swayfx-mosaic/docs/KNOWN_LIMITATIONS.md

Known limitations

This document describes the development tree at the documentation foundation pass. EXPERIMENTAL means implemented but incompletely validated; PLANNED means absent from runtime; NOT YET SUPPORTED means it must not be presented as ready for general use.

Area	Status	Practical implication
Adjacent-output viewport clipping	NOT YET SUPPORTED	A wider row may render beyond its workspace/output boundary on another output; pointer behavior needs matching validation.
Multiple runtime rows	PLANNED	Model helpers/tests exist, but only Row 0 is wired into the Sway tree, arrangement, scene, and input.
Camera animation	PLANNED	Camera movement is immediate; transaction-safe timing/curve is open.
Cell sizing and grouped containers	EXPERIMENTAL	The 640 px minimum is temporary; nested groups remain one cell. Final sizing/reflow policy is TBD.
Resize and output migration	EXPERIMENTAL	Scroll is clamped after arrangement, but these transitions need broader headless validation.
Floating, fullscreen, scratchpad edge cases	EXPERIMENTAL	Basic transitions are tested; long-running and multi-output combinations are not qualified.
Session V2 Mosaic restore	PLANNED	Mosaic state is not durably restored by Session V2.
QuickShell Mosaic visualization	PLANNED	No Mosaic-specific QuickShell display is supplied here.
Daily-driver deployment	NOT YET SUPPORTED	Build and headless evidence do not amount to a validated live session.
Forward port to a later SwayFX release	PLANNED	The patch is pinned to SwayFX 0.6; a new release requires manual review and validation.
Very wide logical coordinates	NOT YET SUPPORTED	Scene positions use bounded integer coordinates; extremely wide canvases are not qualified.

The STEP20C viewport proposal identifies an additional design feasibility blocker: installed SceneFX 0.5 exposes no generic scene-tree clip. Its proposed Mosaic-only projection requires a disposable headless proof that all relevant nodes, popups, damage and pointer hits respect one viewport boundary. The proposal does not change any current support status.

The later popup ownership probe is PARTIALLY_FEASIBLE. A private owner-derived root-popup clip kept tested root and nested GTK popup pixels and pointer hits inside the Mosaic viewport on two horizontal headless outputs. Valid-serial grabs and fully hidden owners were untested in that probe; other output arrangements, complete damage and effects also remained unqualified. This does not change the current NOT YET SUPPORTED multi-output status.

The valid-grab and hidden-owner follow-up is also PARTIALLY_FEASIBLE. A genuine pointer-button serial produced an interactive grabbed XDG popup in unmodified SwayFX, private standard layout and private Mosaic. The previous owner-derived viewport clip leaked popup pixels and button hits when the owner was fully hidden. A further disposable owner-visibility guard removed that sampled leak while the popup stayed mapped and returned with the camera. This earlier probe did not qualify nested valid grabs; the separate nested-grab probe below covers only a sampled horizontal matrix. Other output arrangements, transaction-generation consistency, complete damage/effect coverage and ABI/package maintenance remain unqualified. Multi-output Mosaic is still NOT YET SUPPORTED.

The retained source fixture permits bounded replay; it does not close these qualification gaps.

The nested valid-grab probe is FEASIBLE for its sampled matrix only. A separate client used real pointer button serials to grab A and then B as A's XDG child. In the disposable guarded compositor, both levels were visible and interactive inside the Mosaic viewport, absent at sampled pixels and hits beyond it, and suppressed while their tiled owner was fully hidden; the mapped surfaces returned with the camera. Closing B left A interactive, and outside clicks dismissed B then A. Control and private splith retained ordinary sampled behavior. Other output geometries, migration/resize, transaction generations, complete damage/effects and dependency/ABI maintenance remain NOT TESTED. Adjacent output Mosaic remains NOT YET SUPPORTED in production.

The vertical-output nested-grab probe is FEASIBLE for its measured matrix only. On two stacked 800×600 headless outputs, the standard controls showed real A/B XDG popup pixels and buttons below y=600, while the disposable guarded Mosaic build clipped sampled lower pixels and hits and left upper popup interaction intact. Hidden-owner and standard-layout return cases also passed at their measured points. This does not qualify tiled-window Y overflow, continuous or complete damage coverage, other output geometries, migrations, transaction generations, effects, or SceneFX ABI/package maintenance. Production adjacent-output Mosaic remains NOT YET SUPPORTED.

The negative-origin nested-grab probe is FEASIBLE for its sampled matrix only. With HEADLESS-1 actually at x=-800, signed global pointer requests reached both outputs, standard controls exposed real A/B popup pixels and hits beyond x=0, and the disposable guarded Mosaic build clipped those measured pixels and hits while preserving visible interactions. Hidden-owner and standard-layout return cases passed at measured points. This does not qualify other output transforms, migration/resize, complete damage/effects, transaction generations or SceneFX ABI/package maintenance. Production adjacent-output Mosaic remains NOT YET SUPPORTED.

The temporal damage probe is PARTIALLY_FEASIBLE at the same fixed negative-origin geometry. Ten open/close cycles per configuration and sampled camera transitions found no residual popup pixels or blocking standard-layout regression. The cycles also delivered a real A button after B closed; one separate hidden-owner click missed the popup surfaces and dismissed them in child-first order. Its timed damage extents covered changed pixels between sampled PNGs, but screenshots did not enumerate presented frames; broad extents and accepted output commits cannot prove per-frame rendering, input/scene synchronization or damage minimality. Popup effects, saved buffers and the SceneFX ABI/package gate remain unqualified. Production multi-output Mosaic is NOT YET SUPPORTED.

The presentation identity probe is PARTIALLY_FEASIBLE in the same fixed headless geometry. A private listener paired 470 headless present callbacks with accepted native output commits; 12 other accepted commits had no observed present and are not classified as presented. Applied scene and clip snapshots at the commit callback covered the measured target transitions, but no exact buffer readback tied those values to the pixels of a particular commit. grim captures, damage extents and pointer delivery cannot fill that missing identity. Headless events are simulated, not evidence for physical DRM presentation. A transient logical/applied camera lag was observed during initial layout setup; no wrong applied clip or invisible hit was reproduced in the targeted matrix. Production multi-output Mosaic remains NOT YET SUPPORTED.

The private output buffer identity probe is PARTIALLY_FEASIBLE at the fixed negative-origin headless geometry. Thirty-two actual output-state buffers were read through SceneFX FX texture readback, paired with native commits and headless present events, and released on present in 28 cases; four were released early when a HEADLESS-2 repaint reached the probe's global release, before their later present events. This private instrumentation scope defect is not evidence of same-output buffer replacement. Three second reads matched their earlier bytes. The direct CPU access method was unavailable for the GBM buffers. Readback added measurable GPU/CPU synchronization and file-copy delay; 29 buffers were not read a second time at present. The observed transient logical camera 1760 versus applied scene/clip 1120 had an identified buffer but no demonstrated wrong pixel or hit. There is still no atomic applied scene/input generation contract, broad effects/damage proof, physical presentation proof or SceneFX ABI/package qualification. Production multi-output Mosaic remains NOT YET SUPPORTED.

The subsequent private applied state/input probe is PARTIALLY_FEASIBLE in the same fixed headless geometry. A per-output hold survived an intervening repaint of the other output; three selected buffers reached matching native presents and matched visible/hidden/returned applied scene samples. Hit-test, seat-notification and client-delivery streams were observed separately for visible, clipped and fully hidden pointer cases. The experimental epoch covers only instrumented popup and transaction arrangements; other scene, effect, damage, animation, client-buffer and output mutations remain outside it. Rejected-commit and output-destroy cleanup were not dynamically triggered. Readback remains intrusive, and neither an atomic scene/render/input generation nor physical presentation is proven. Production multi-output Mosaic remains NOT YET SUPPORTED.

The mutation coverage probe is PARTIALLY_FEASIBLE overall. In the fixed headless matrix, the partial epoch missed a real input-region change that removed a scene hit, while a client recolor changed pixels without a geometry change. Normal private output destruction released one intentionally retained buffer reference exactly once; rejected-commit cleanup passed only a synthetic model and remains NOT TESTED on a real backend. Subsurfaces, effects, animations, output migration and the complete cross-time build/present/hit boundary remain unqualified. The architecture decision is UNDECIDED; physical presentation and production multi-output Mosaic remain NOT YET SUPPORTED.

The independently replayed commit/present/input ordering probe is INCONCLUSIVE for the discriminating temporal case. The headless backend defers present to an idle callback, but none of 20 bounded input-region mutations in private standard/Mosaic fell between a native commit and its matching present. Sampled hits and client receipt followed the applied input state, with unchanged sampled pixels; this is not a demonstrated Mosaic clip defect. Client input-only commits need not cause output redraw. Popup clip changes in that window, physical presentation, rejected backend commit cleanup and broader output/effect paths remain NOT TESTED. Existing ordering sufficiency and any added-generation contract remain UNDECIDED.

The pending-input event-loop follow-up removed the runner's intermediate response waits during five bounded cycles per private mode. It confirmed ten positive client flushes and ten applied target input commits per mode, yet zero natural commit→mutation→present interleavings. The sought same-interval hit and grabbed-popup variant are NOT TESTED. The result remains INCONCLUSIVE for that temporal window; repeat attempts on the same headless matrix are closed. Effects/damage, scaling and resize/migration remain open STEP20C gates.

The effects/damage follow-up is PARTIALLY_FEASIBLE only for the sampled negative-origin private matrix. Both standard controls showed a genuine shadow overflow into 46 neighboring columns; the private Mosaic output showed none. A real translucent blur changed patterned pixels inside Mosaic without changing the neighboring output, and three settled camera returns were pixel-identical to baseline. Sampled private damage extents covered capture-to-capture changes. The Mosaic interior shadow was not independently visible. Optimized blur cache correctness, source sampling outside the viewport, popup effects, saved buffers, intermediate frames and other renderers remain NOT TESTED. The optional trace changed the neighboring reference rendering in Mosaic, so visual claims use the untraced runs. Production multi-output Mosaic remains NOT YET SUPPORTED. The final audit also found that reproduction/trace replays executed 15 camera pairs instead of the requested campaign maximum of three. This protocol deviation is retained with all raw runs and prevents claiming full campaign compliance; the final fixture now enforces the finite budget.

The isolated feasibility probe is PARTIALLY FEASIBLE, not a release qualification. On two horizontal headless outputs, real Mosaic content leaked visually into an empty adjacent output; that earlier disposable candidate also delivered pointer enter from a partly visible client outside its viewport. Negative-origin, scaled and rotated arrangements showed visual leakage in that candidate. Popups, effects, saved buffers and complete damage correctness remain unqualified across the full matrix. The later probes above narrow individual cases without qualifying multi-output Mosaic, which remains NOT YET SUPPORTED.

The later SceneFX subtree clipping spike is also PARTIALLY FEASIBLE. Its private inherited tree clip stopped tested tiled pixels and pointer hits from crossing the output boundary, including a fully hidden cell, but a real GTK XDG popup rendered and received input on the neighboring output because its scene tree lives in the global popup layer. Dedicated subsurface, saved-buffer, nested-popup and complete effect/damage validation remain open. The spike changed no production library or compositor source; multi-output Mosaic remains NOT YET SUPPORTED.

These limits are reflected in UX, architecture, and roadmap. A future step must update those contracts before claiming support.

The preserved fractional scaling probe is PARTIALLY_FEASIBLE for static 1.25 uniform/mixed and 1.5 mixed headless outputs. Actual modes/PNGs and logical pointer motion were calibrated. Sampled root/nested popup and shadow spill disappeared on the neighboring output; visible blur, terminal popup columns, two settled camera returns and available physical damage were consistent. Opaque tiled-overflow controls, permitted interior shadow, restored Mosaic hit, caches and intermediate frames remain unqualified. Ten failed early calibrations and their source-provenance limit are retained. The two-pair global budget was respected. The next distinct gate should test resize/migration of owner/output clips; rotation, saved buffers and ABI/package remain separate. This is evidence only: STEP20C stays NEXT, production multi-output NOT YET SUPPORTED, STEP20D–G PLANNED.

The preserved dynamic output ownership probe is PARTIALLY_FEASIBLE: actual logical resize 800→960→800 and workspace migration H1→H2→H1 retain workspace/tiled identities and update sampled applied tiled/root-popup clips. Vacated outputs show exact background after stabilization. Two standard controls fail final reference calibration through fixture occlusion; Mosaic's corrected calibration passes. Maximum-scroll clamp, migrated clipped popup input, independent opaque tiled spill, effects and intermediate frames remain unqualified. Budgets are exhausted at six reconfigurations and six migrations, with zero additional camera pairs. No production change follows. Rotation is the next separate geometric gate; other open STEP20C gates persist. The original temporary evidence manifest was verified before an offline analyzer rerun replaced it; its exact historical bytes are not retained. STEP20C stays NEXT, multi-output NOT YET SUPPORTED.

The rotation probe established the applied 90° mode/transform and logical PNG/pointer orientation in two private runs, plus sampled fully-hidden owner and damage behavior. Its global result is PARTIALLY_FEASIBLE, architectural partial-clipping conclusion UNDECIDED: pristine R90 capture failed through fixture assertion, and the Mosaic popup stayed wholly inside the viewport despite standard control spill. Scored border hits, rotated shadow/blur/cache and raw buffer readback are NOT TESTED. No production support claim follows.