swayfx-mosaic/docs

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

1. Architecture: compositor ownership and technical invariants.
2. UX contract: user-visible behavior and interaction invariants.
3. Packaging: binary and package coexistence.
4. Upstream maintenance: provenance and forward ports.
5. Development: reproducible workflow.
6. Known limitations: current support boundary.
7. Roadmap: ordered future work, not proof of implementation.
8. STEP20C viewport proposal: proposed design, subordinate to accepted canonical contracts.
9. STEP20C feasibility probe: isolated technical evidence and an unresolved multi-output gate.
10. STEP20C SceneFX subtree spike: isolated clipping, popup and packaging evidence; production gate remains open.
11. STEP20C popup ownership probe: isolated owner-derived root/nested popup evidence and remaining grab, damage and packaging gates.
12. STEP20C valid-grab and hidden-owner probe: isolated valid-serial XDG grab comparison, fully hidden owner leak and private guard evidence; production gates remain open. Preserved source fixtures record exact inputs and a disposable replay procedure.
13. 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
STEP20C popup ownership probe	Experimental evidence	PARTIALLY_FEASIBLE; owner-derived root/nested popup clipping worked in a horizontal private headless case, with grab/damage/output gates open
STEP20C valid-grab and hidden-owner probe	Experimental evidence	PARTIALLY_FEASIBLE; valid-serial popup grab measured, hidden-owner leak found and closed only in a private guard; broader STEP20C gates remain open

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.