22 KiB
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.
- STEP20C popup ownership probe: isolated owner-derived root/nested popup evidence and remaining grab, damage and packaging gates.
- 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.
- 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.
- 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.
- STEP20C negative-origin nested-grab probe: sampled signed-coordinate pointer, popup clipping, hidden-owner and standard-layout evidence with real
x=-800headless origin; production gates remain open. Negative-origin source fixture replays it in a disposable laboratory. - 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
Saved target natural timeout and input gate and local source fixture: EXPERIMENTAL / PARTIALLY_FEASIBLE. A static SHM H2 reference stayed pixel-identical before, during and after one held Mosaic transaction. The crossing target saved node rendered inside H1 and was removed after a real timeout with the XDG client alive; sampled H2 input reached the reference. Complete damage and GPU lifetime remain open. STEP20C stays NEXT and production multi-output remains NOT YET SUPPORTED.
The preserved optimized blur cache probe is PARTIALLY_FEASIBLE, architecture UNDECIDED. A real background layer under blur_tree triggered natural output-specific cache reconstruction and fresh central A/B/A filtered pixels in private splith and Mosaic. Sampled final tiled drawing excluded H2, whose whole RGB remained identical; output damage extents covered stabilized differences and sampled cache/FBO teardown completed. Shared boundary differences up to six RGB levels remain unresolved. Pristine C0 failed before captures through a duplicate configure fixture; its second initial image was reserved only after observation. No numerical budget was exceeded or run repeated. Instrumentation neutrality, whole-cache equivalence and intermediate frames remain unqualified. A separate pristine/untraced boundary-sampling gate should precede ABI/package qualification. This evidence freeze changes no production or UX contract. STEP20C stays NEXT, multi-output NOT YET SUPPORTED.
The preserved optimized edge causality gate is PARTIALLY_FEASIBLE, architecture UNDECIDED. Four completed fixed negative-origin runs qualify pristine/private splith and same-binary Mosaic OPT-off/on controls. Pristine/private full images and Mosaic trace-off/on full images are exact at six homologous states; common glass across layouts is also exact. Historical right/bottom differences persist without new traces, with max RGB delta 6, fresh central pixels and stable whole H2. Native FBO history causality remains unproved despite source/model support. R3 damage extents cover stabilized differences only. No clipping regression or required invariant violation is established. A separate SceneFX ABI/package audit is now justified, retaining this shared rendering limitation; optional selective GPU observation requires a new scoped ticket. This evidence is preserved without a production change. STEP20C stays NEXT, production multi-output NOT YET SUPPORTED.
The preserved edge source fixture records pinned reconstruction, offline checks and the exhausted four-slot ledger.
The preserved SceneFX ABI/package audit is PARTIALLY_FEASIBLE, architecture SCENEFX_ABI_PACKAGE_REQUIRES_ARCHITECTURAL_DECISION. The unchanged current package builds with stock SceneFX and stages exactly /usr/bin/swayfx-mosaic. The shared experimental binary needs two clip exports absent from stock despite the same SONAME. Static embedding builds and resolves without a SceneFX shared dependency, but shared wlroots interposition, updates, security maintenance and license notices remain gates. A distinct private shared library would require a new file-ownership decision; upstream API acceptance is unknown. No integration or packaging contract is approved. The historical audit is frozen as evidence; STEP20C stays NEXT, production multi-output NOT YET SUPPORTED.
The ABI/package source fixture records build-only reconstruction and non-graphical diagnostic commands.
The preserved static distribution contract dossier
is EXPERIMENTAL / PARTIALLY_FEASIBLE, conclusion
STATIC_DISTRIBUTION_REQUIRES_CONTRACT_DECISION. One private Meson DESTDIR
stage of the hash-qualified static executable contains exactly
/usr/bin/swayfx-mosaic; this proves file shape only. The 85 overlapping
exports and 31/34 wlroots scene bindings into the executable remain explicit
paired-version constraints, not automatically defects. Only the pinned
SceneFX 0.5 / observed wlroots 0.20.2 pair has non-graphical evidence.
Notices (including generated protocols), security ownership, upgrades, rollback
and graphical semantics remain gates. A disposable notice-section extraction
passes mechanically; legal distribution compliance is not approved.
The upstream API dossier is preserved and not submitted. Production strategy:
NONE — USER DECISION REQUIRED. Packaging/UX contracts are unchanged;
STEP20C stays NEXT and production multi-output NOT YET SUPPORTED.
The static-contract source fixture preserves the bounded audit/staging procedure; all generated results stay external.