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. STEP20C nested valid-grab probe: two genuine nested XDG grabs and sampled clipping, dismissal, hidden-owner and standard-layout return evidence; remaining STEP20C gates stay open. Nested-grab source fixture reconstructs the same disposable experiment.
14. STEP20C vertical-output nested-grab probe: sampled vertical popup clipping and pointer evidence with two standard controls and private Mosaic; production gates remain open. Vertical source fixture replays it in a disposable laboratory.
15. STEP20C negative-origin nested-grab probe: sampled signed-coordinate pointer, popup clipping, hidden-owner and standard-layout evidence with real x=-800 headless origin; production gates remain open. Negative-origin source fixture replays it in a disposable laboratory.
16. STEP20C temporal damage probe: repeated XDG cycles, camera transitions, sampled pixel restoration and timed private damage/commit traces at the same negative-origin geometry; frame presentation remains unproven. Temporal source fixture rebuilds the private campaign.
17. STEP20C presentation identity probe: native headless commit/present correlation and sampled applied camera/clip/input evidence; exact committed buffer content remains unproven. Presentation source fixture rebuilds the private instrumentation.
18. STEP20C output buffer identity probe: private GBM/FX buffer readback tied to native commit and headless present, with measured timing perturbation and remaining temporal-coherence gate. Buffer source fixture reconstructs the disposable experiment; it is not production code.
19. STEP20C applied state/input probe: private per-output buffer-reference correction and partial applied-scene epoch tracing through render and pointer paths; no atomic generation is established. Applied-state source fixture rebuilds the disposable experiment.
20. STEP20C mutation coverage probe: source ownership inventory and bounded trace-only camera, popup, client-content and input-region scenarios; output-destroy cleanup sampled, rejected commit still untested. Mutation source fixture replays the disposable matrix without production integration.
21. STEP20C commit/present/input ordering probe: independently replayed headless ordering evidence; 20 applied input-region mutations, no natural commit-to-present interleaving, temporal question INCONCLUSIVE. Ordering source fixture rebuilds the passive private trace.
22. STEP20C event-loop pending-input probe: bounded asynchronous client submission and native callback order; no natural commit-to-present input mutation, INCONCLUSIVE. Pending-input source fixture replays the disposable matrix.
23. STEP20C effects/damage probe: real translucent blur and shadow-overflow pixels compared across standard and private Mosaic layouts; sampled damage and camera returns PARTIALLY_FEASIBLE, optimized blur cache unqualified. Effects/damage source fixture rebuilds the disposable matrix.
24. STEP20C static R90 partial-popup probe: sampled genuine B crossing and input with a completed pristine control; broader STEP20C gates remain open. R90 source fixture preserves the published experimental inputs.
25. STEP20C saved transaction buffer probe: real saved nodes and lifetime evidence, but target partial-overflow geometry NOT EXERCISED; result INCONCLUSIVE. Saved-buffer source fixture preserves the experimental inputs.
26. STEP20C saved target crossing probe: measured saved target crossing and clipped H1 render; H2 reference difference and incomplete timeout/input gate keep it PARTIALLY_FEASIBLE. Target-crossing source fixture remains local and experimental.
27. 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
STEP20C nested valid-grab probe	Experimental evidence	FEASIBLE for sampled two-level grabbed XDG popup cases on horizontal headless outputs; no production qualification
STEP20C vertical-output nested-grab probe	Experimental evidence	FEASIBLE for sampled two-level grabbed XDG popup cases across the horizontal output boundary; no production qualification
STEP20C negative-origin nested-grab probe	Experimental evidence	FEASIBLE for sampled two-level grabbed XDG popup cases with HEADLESS-1 at x=-800; no production qualification
STEP20C temporal damage probe	Experimental evidence	PARTIALLY_FEASIBLE for sampled repeated lifecycle/camera states; damage-to-presented-frame and transaction/input synchronization remain open
STEP20C presentation identity probe	Experimental evidence	PARTIALLY_FEASIBLE; native headless events pair with commits, but buffer pixels and per-frame input identity remain unproven
STEP20C output buffer identity probe	Experimental evidence	PARTIALLY_FEASIBLE; sampled true buffers were read and paired with headless presents; four early releases came from a private cross-output instrumentation defect, while readback perturbs timing and atomic scene/input coherence remains unproven
STEP20C applied state/input probe	Experimental evidence	PARTIALLY_FEASIBLE; per-output holds survive cross-output repaint in the sampled matrix, and applied scene/hit/client streams are observed with a partial experimental epoch
STEP20C mutation coverage probe	Experimental evidence	PARTIALLY_FEASIBLE overall; an input-region change alters the hit at unchanged partial epoch, client recolor changes pixels without geometry, and a held output reference is released on sampled output destruction; cross-time generation contract remains UNDECIDED
STEP20C commit/present/input ordering probe	Experimental, independently replayed evidence	INCONCLUSIVE for the discriminating temporal window; headless input-region commits and hits agree in observed states, but none of 20 applied mutations occurred between a native output commit and its present
STEP20C event-loop pending-input probe	Experimental, independently replayed evidence	INCONCLUSIVE / NOT EXERCISED for natural commit→input mutation→present despite decoupled client submission; the temporal line is closed for this backend/matrix
STEP20C effects/damage probe	Experimental, independent private replay	PARTIALLY_FEASIBLE for visible blur, excluded sampled shadow overflow, settled camera restoration and sampled damage; shadow interior, optimized cache, popup effects and saved buffers remain unqualified
STEP20C static R90 partial-popup probe	Experimental evidence	PARTIALLY_FEASIBLE; sampled B crossing clips under R90, independent A input remains untested
STEP20C saved transaction buffer probe	Experimental, local evidence	INCONCLUSIVE; real saved nodes rendered, target partial crossing not exercised
STEP20C saved target crossing probe	Experimental, local evidence	PARTIALLY_FEASIBLE; target saved node crossed and rendered within H1, but whole-H2 reference and timeout/input evidence 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.

Preserved experimental evidence: fractional scaling probe and source fixture. PARTIALLY_FEASIBLE for the sampled static scale matrix, independently replayed without new camera pairs; no production qualification.

Preserved experimental evidence: dynamic output ownership report and source fixture. PARTIALLY_FEASIBLE for measured stable geometry/ownership, with explicit fixture and unexercised-input limitations. The original temporary evidence manifest was verified before an offline analyzer rerun replaced its bytes; the report records this provenance limit.

Rotated-output probe and fixture: EXPERIMENTAL / PARTIALLY_FEASIBLE for applied geometry, logical PNG/pointer, full-owner hide, sampled damage and return. Pristine R90 capture and a Mosaic popup portion actually crossing the boundary were not exercised; architectural clipping conclusion UNDECIDED. STEP20C remains NEXT; production multi-output remains NOT YET SUPPORTED.

Static R90 partial-popup probe and fixture: EXPERIMENTAL / PARTIALLY_FEASIBLE. Mosaic B crossed x=0 by 72 logical pixels; its H1 pixels and real button remained, while H2 matched its reference and delivered no B button. Both standard controls drew and handled the overflow. Independent clipped-away A input and saved buffers remain open. STEP20C is NEXT; production multi-output is NOT YET SUPPORTED.

Saved transaction buffer probe and source fixture: EXPERIMENTAL / INCONCLUSIVE. Real held XDG configures created nonempty saved scene buffers; private render entries and ACK/timeout removal were observed. The Mosaic target was wholly off H1 after an applied relative camera scroll, so the partial-boundary clipping gate was NOT EXERCISED. STEP20C stays NEXT.

Saved target crossing probe and local source fixture: EXPERIMENTAL / PARTIALLY_FEASIBLE. One calculated camera correction produced a real saved target crossing x=0 with clipped render and retained H1 pixels. H2's target color was absent, but its whole-image reference differed by 253 pixels; Mosaic target timeout and held input remain unqualified. STEP20C stays NEXT and production multi-output remains NOT YET SUPPORTED. The offline freeze audit found an identical filled 11×23 Kitty cursor-color rectangle across pristine and Mosaic captures. Cursor blinking is strongly supported, not causally proven; a static H2 reference is the next gate.