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.

The subsequent static R90 partial-popup probe closed the missing B geometry challenge for one legal XDG placement: Mosaic B crossed by 72 logical pixels; sampled H1 visual/button input survived and H2 matched its prior reference with no B delivery. Its overall status is PARTIALLY_FEASIBLE. The A root popup also crossed, but independent input on its forbidden portion remains NOT TESTED. Saved buffers, optimized blur caches, inner shadows, intermediate frames, atomic generation and SceneFX/wlroots ABI/package remain unqualified. Multi-output stays NOT YET SUPPORTED.

The saved transaction buffer probe is INCONCLUSIVE for the intended partial-overflow gate. The target snapshot was outside H1 because its applied camera differed from the fixture's assumed initial position. Other saved nodes rendered in the private scene; ACK and natural timeout removed sampled trees. Target pixels, clipped input, transaction-scoped damage, destruction while pending and reference lifetime after texture conversion remain unqualified. One private-standard episode failed through fixture timing. STEP20C remains NEXT and production multi-output NOT YET SUPPORTED.

The new target-crossing probe is PARTIALLY_FEASIBLE for one real saved target that crossed x=0 and rendered only its permitted H1 portion in the sampled ACK episode. H2 had no target-color pixels but differed from its whole-image reference by 253 pixels of unproven cause, also seen in pristine controls. A stale fixture pointer stopped Mosaic E2 before natural timeout; target input, complete damage and GPU reference lifetime are unqualified. STEP20C remains NEXT and production multi-output NOT YET SUPPORTED.

Offline RGB analysis found the same filled 11×23 #F5E0DC→#303038 rectangle in pristine and Mosaic H2 comparisons. Kitty's recorded local block-cursor color and blink setting strongly support a dynamic reference, but no effective cursor phase was logged. Whole-H2 equality is still unproven; the new timeout probe must use a static reference.

The subsequent static-reference saved-target timeout gate is PARTIALLY_FEASIBLE. In one private horizontal Mosaic run, all four full H2 RGB captures matched exactly; the actual crossing saved target rendered its permitted H1 pixels, remained absent on H2 and its saved tree was removed after a natural timeout with the configure withheld. Two pointer points showed no invisible H2 target hit. Full frame-by-frame damage, unmeasured input paths, seat notification for the saved node and complete GPU/texture reference lifetime remain NOT TESTED. The old Kitty cursor explanation remains strongly probable, not causally proven. STEP20C remains NEXT and production multi-output Mosaic 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 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 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.

Approved private STEP20C static candidate — 2026-10-13

The user approved four decisions for documentation and private prototypes only: private static SceneFX; separate complete notices under /usr/share/licenses/swayfx-mosaic/; project responsibility for embedded SceneFX maintenance; and qualification of each exact SceneFX/wlroots pair. See the decision register and bounded runtime gate. The current PKGBUILD, system SceneFX dependency, one-binary package, production sources and cumulative patch remain unchanged. The future private stage may contain only /usr/bin/swayfx-mosaic and justified regular notice files below the license directory. No private shared library, session, service, config or Sway symlink is allowed. No real installation is authorized.

Mosaic owns monitoring, impact review, rebuild and requalification of embedded SceneFX fixes, including renderer/shaders/dependencies/ABI/buffer lifetime/clip/ damage changes. Before public distribution, a release maintainer and security reviewer must be designated; no names or SLA are assigned. Preserve exact source, patch, compiler/options/dependency, notice, test and artifact manifests. A new relevant dependency build requires header/symbol/shared-layout inspection, rebuild, relocation/model/staging/headless checks and graphical requalification of relevant paths, then a separate publication decision. No automatic update subsystem is added. Ordinary SwayFX upgrades remain independent and standard SwayFX remains the fallback. All other pairs are NOT QUALIFIED.

These decisions do not settle popup UX or close STEP20C production gates. STEP20A DONE; STEP20B EXPERIMENTAL; STEP20C NEXT; STEP20D–G PLANNED. Production multi-output remains NOT YET SUPPORTED.

The private static runtime gate is EXPERIMENTAL / PARTIALLY_FEASIBLE, architecture UNDECIDED. Real /usr static build/model/stage/notices/loaded-library identity/headless startup pass. Sampled H1 target pixels survive with zero target colors on H2, but whole-H2 reference equality fails through a focus/decor mismatch; input and splith return are NOT TESTED after the single run stopped. No rerun or algorithm modification occurred. Distribution notice closure, named release/security roles and broader ABI/graphics gates remain open. STEP20C NEXT, multi-output NOT YET SUPPORTED.

The static focus/input/standard follow-up is EXPERIMENTAL / INCONCLUSIVE, architecture UNDECIDED. One run reused the exact static binary, verified loaded wlroots/output geometry, calculated camera and observed the applied clip. A fixture incorrectly required stored current_border_width=0 under border none; actual IPC retained thickness 2 with empty decoration and full-size client rectangles. The run stopped before any PNG, click or splith transition. Those gates are NOT TESTED; no clipping defect or need for an algorithm change is demonstrated. No retry/build/production change occurred. A separately authorized corrected-fixture gate is required. STEP20C stays NEXT; production multi-output remains NOT YET SUPPORTED.