Documentation
Documentation is a first-class project artifact. Architecture and UX contracts are updated before implementation when behavior changes.
The root README is the public summary. For a specific topic, use the canonical document below. Within its own subject, a canonical document takes precedence over a historical STEP report. If two canonical documents disagree, resolve the conflict before implementation; do not silently choose one.
Source-of-truth order
- Architecture: compositor ownership and technical invariants.
- UX contract: user-visible behavior and interaction invariants.
- Packaging: binary and package coexistence.
- Upstream maintenance: provenance and forward ports.
- Development: reproducible workflow.
- Known limitations: current support boundary.
- Roadmap: ordered future work, not proof of implementation.
- STEP20C viewport proposal: proposed design, subordinate to accepted canonical contracts.
- STEP20C feasibility probe: isolated technical evidence and an unresolved multi-output gate.
- STEP20C SceneFX subtree spike: isolated clipping, popup and packaging evidence; production gate remains open.
- STEP20A and STEP20B: historical evidence.
Project
| Document |
Role |
Purpose |
| README |
Summary |
Public landing page and current status |
| Contributing |
Normative |
Scope, docs-first flow, checks |
| Changelog |
Historical |
Repository evolution |
| Notice |
Normative |
Attribution boundary |
Architecture and user experience
| Document |
Role |
Purpose |
| Architecture |
Normative |
Runtime model, ownership, IPC, transactions, scene |
| UX contract |
Normative |
Interaction rules, row behavior, undecided choices |
| Known limitations |
Planning/current evidence |
Unsupported and unvalidated paths |
Development, packaging, and upstream
| Document |
Role |
Purpose |
| Development |
Normative |
Build, test, staging, patch workflow |
| Packaging |
Normative |
File ownership, versioning, fallback |
| Upstream maintenance |
Normative |
SwayFX relationship, pinned base, forward ports |
Design proposals
| Document |
Role |
Purpose |
| STEP20C viewport design |
Proposed, not yet accepted |
Source audit, clipping alternatives, test plan, feasibility gate |
| STEP20C feasibility probe |
Experimental evidence |
PARTIALLY FEASIBLE; visual and input boundary failed in a two-output headless candidate |
| STEP20C SceneFX subtree spike |
Experimental evidence |
PARTIALLY FEASIBLE; tiled clip worked privately, global popup leaked pixels and input |
A proposal does not supersede accepted canonical contracts or assert implementation status. Its open feasibility items must be resolved before implementation.
Roadmap and historical reports
| Document |
Role |
Purpose |
| Roadmap |
Planning |
Step goals, exit criteria, required documentation |
| STEP20A |
Historical |
Native foundation implementation evidence |
| STEP20B |
Historical |
First scrollable-row implementation evidence |
STEP reports record what was observed and decided at the time. They are not the canonical source for current behavior. When a STEP report conflicts with current canonical documentation, the canonical documentation wins. The original French reports are preserved as historical artifacts; their opening notices point here.
