swayfx-mosaic/docs/design/STEP20C_EFFECTS_DAMAGE_PROBE.md

STEP20C SceneFX effects and damage probe

Status: EXPERIMENTAL / PARTIALLY_FEASIBLE for the sampled matrix. STEP20C stays NEXT, STEP20B EXPERIMENTAL, and production multi-output Mosaic NOT YET SUPPORTED. This is a bounded private feasibility measurement, not a UX, ABI, package or production decision.

Question and current evidence

The private inherited clip and owner-derived popup guard passed sampled tiled, nested popup, grab and negative-origin cases. The earlier SceneFX spike accepted shadows enable and blur enable and showed a sampled shadow boundary, but did not prove a distinct translucent blur, optimized blur cache correctness or effect-specific damage. This probe requires an effect to be created and enabled, geometrically placed and measurably visible in both standard controls before its Mosaic clipping can pass.

The viewport is HEADLESS-1 (-800,0,800,600) beside HEADLESS-2 (0,0,800,600), both scale 1 and normal transform. Mosaic's applied Row 0 clip should prevent tiled-owner content, including its shadow and blur draw regions, from writing outside the workspace viewport. An effect must remain visible in its permitted interior. The ordinary client on HEADLESS-2 must retain its own pixels. A blur shader may sample outside its draw region; source sampling, visible influence and a contract violation are distinct claims. No policy forbidding a particular shader source sample has yet been accepted, so T3 cannot be called a leak on sample reach alone.

Source audit and working hypotheses

Pinned inputs: private Mosaic base cd550382b311efdbfe3ed892f4e1d281d852e754, SceneFX 37ccd723bef49e6891156ffafce8f549f01446cc, wlroots 0.20.2. The preserved private clip patch is layered on these bases. In SceneFX types/scene/wlr_scene.c, scene_node_intersect_clip intersects ancestor tree clips for each leaf. scene_node_update_iterator intersects node->visible; scene_node_bounds intersects new bounds; and scene_node_update damages old and new visibility. The render-list constructor rejects empty visible intersections. scene_entry_render passes node->visible ∩ output damage as the draw clip for buffer, rect, shadow and blur entries. This demonstrates a route for all four node types through the inherited draw clip, not proven shader sampling bounds. scene_output_damage maps logical damage into the output buffer and queues repaint. Its extents can exceed changed pixels and cannot prove every intermediate frame or optimality.

SwayFX creates a shadow and blur under each container scene_tree; their geometry and enabled state are updated in sway/desktop/transaction.c; output_configure_scene additionally configures blur selection, strength and corner radii using the closest container. A tiled container should inherit its tiling tree clip. Layer-shell surfaces have their own effect nodes, with different ownership. Root XDG popups are globally parented and receive the separate owner-derived private guard; no popup effect is assumed without observed node creation. Each output creates an optimized_blur node under staging, outside the tiled owner's tree. mark_dirty sets its dirty flag only while enabled; scene rendering clears it after a successful optimized blur pass. SwayFX marks it dirty on selected blur/layer changes. Camera movement alone is not yet proven to invalidate all relevant optimized caches. Thus the ordinary inherited clip does not directly own the output optimized node. The optimized cache pass itself uses its output-sized destination box; it does not receive the tiled descendant's render_region draw clip. The final ordinary blur texture draw does receive that clip. These two operations must be audited separately.

The box-shadow node can extend by its configured sigma and offset beyond the view's rectangle. scene_entry_render supplies a clipped draw region, while shader/filter sampling may use a wider source footprint. The apply_blur_region path expands damage for blur sampling; actual output pixels and damage must be measured. Saved transaction buffers are distinct from client SHM buffers, output buffers and optimized blur caches. No saved buffer claim is valid without an observed controlled creation/use path.

These source answers are hypotheses until real effects are activated. A successful IPC command, compiled shader, enabled flag or nonempty render list alone is insufficient visual evidence. The renderer, EGL/GLES version, headless backend, buffer formats and linked SceneFX/wlroots versions must be recorded for each private run; WLR_RENDERER=pixman is a request, not proof of the renderer actually used.

Fixture and comparisons

Rebuild from a full Git clone into a private temporary lab. Preserve the same deterministic SHM clients and effect settings in three modes: unmodified SwayFX splith, private splith, private mosaic. Use explicit private runtime and IPC socket, bounded process groups, timeouts and captures; never address the daily session. The visual client will supply a documented high-contrast striped/damier background, a translucent surface, an opaque surface, and a stable ordinary reference on HEADLESS-2. Record all SHM sizes, colors, alpha values, geometry and mapping. Disable dynamic content and animations where the normal compositor allows it. Fix pixel regions of interest before inspecting anomalies: interior effect, boundary band on each output, unchanged reference and exposed/old-owner regions. PNG coordinates are output-local; Wayland/Mosaic global coordinates are signed.

Separate FX0 (shadow/blur off), FX1 (shadow only), FX2 (blur on translucent patterned background), FX3 (optimized blur only if a real enabled node and dirty/cache transition can be observed), and FX4 (combined only after independent FX1/FX2 proof). For each effect require: accepted configuration, observed enabled node and size/position, a preselected pixel ROI changing against FX0, and both standard controls visibly exercising it. An unavailable effect is NOT TESTED; visible but inseparable effects are INCONCLUSIVE.

Bounded scenarios

• T1 shadow boundary: standard controls visibly draw a shadow across global x=0; Mosaic retains its permitted interior and excludes its forbidden right-output pixels. If controls do not overflow, no clipping claim follows.
• T2 translucent blur boundary: demonstrate blur distinct from alpha compositing with effect off/on ROIs, then compare the three modes.
• T3 hidden sampling influence: keep inside-viewport sources fixed, alter only an outside pattern, and test visible blurred pixels. Record draw clip and sampling evidence separately; classify contract legitimacy conservatively.
• T4/T5 hidden owner and return: at most three scroll_x 400→1280→400 pairs, with right-output reference, enabled nodes, cache state, settled pixels and old/new damage checked. Do not accidentally dismiss popups.
• T6 effect toggle and close: disable/re-enable by normal commands, then close the relevant surface and compare discovered regions.
• T7 standard-layout return: switch to splith while surfaces remain open; ordinary effects must return without Mosaic clip leakage.

Only after main cases are valid, consider one bounded real-serial nested popup hierarchy. First audit whether that hierarchy owns any applicable effect node. No positive popup effect is invented. A horizontal regression is allowed only if it distinguishes an observed anomaly. No scale, rotation, migration or saved-buffer animation is silently added.

Pixel, damage and classification rules

Record per capture output, dimensions, phase, monotonic capture window, SHA-256, fixed ROIs, reference colors, pixel difference count and bounding box, plus color-distance summaries for blur. Use lossless PNG. Compare FX1 and FX2 separately against FX0 with identical clients/geometry. Never mask an anomalous area after seeing it. Verify actual enabled nodes and renderer before interpreting equal pixels.

The fixed output-local ROIs for the 800×600 images are: left effect interior (300,100,700,500), left boundary (720,50,800,550), right boundary (0,50,80,550), and right reference (250,250,550,500). Whole-image differences are retained as well. The striped wallpaper alternates #f5f5f5 and #0f192d every 8 pixels horizontally; the test client's translucent top buffer is premultiplied ARGB 0x88442010. The first FX1 capture showed no pixel difference from FX0, so shadow visibility must be established by an amended, documented fixture before T1 can pass.

Retain SPIKE_DAMAGE, TEMPORAL_DAMAGE, accepted output commits and native headless presents when present in the private chain. For each transition, compare changed-pixel boxes with the union of observed damage extents on the same output, and inspect restored/old regions. Damage coverage is a bounded observation: it is not minimum damage, every-frame correctness, or submitted-buffer identity. Mark cache dirty and pass events with passive private traces only if existing logs are insufficient. Never alter the clip algorithm, shaders, public ABI or backend scheduler to obtain a pass.

FEASIBLE requires visibly active relevant effects in both standards, permitted interior pixels in Mosaic, no prohibited adjacent-output writes, correct settled restoration and damage evidence supporting each claim. PARTIALLY_FEASIBLE means some effects pass but other effect/cache/damage paths remain unproven. INCONCLUSIVE means visibility or origin cannot be established. BLOCKED requires a reproducible pixel leak, stale cache, crash or standard-layout regression, with a minimal retained reproducer. Stop the affected scenario on a concrete leak; do not implement an algorithmic repair in this ticket. Even FEASIBLE here does not qualify all renderers, scaling, rotation, migration, saved buffers or SceneFX packaging.

Keep source patches and fixture code under tooling/probes/step20c-effects-damage/; keep binaries, builds, logs, PNGs, protocol-generated files and sockets outside Git. Source and complete raw evidence manifests must be checked separately. Synchronize canonical Architecture, Known Limitations, Roadmap, index and Changelog to observed results, without changing UX. This protocol is updated with actual evidence before the final local handoff; phase B is never committed in this ticket.

Executed matrix and evidence

Final verification amendment: reuse the preserved step20c-presentation-identity/presentation-events.patch in the private Mosaic copy to retain native commit/present identities. The neighboring wev reference keeps its natural floating size rather than receiving a late resize request; its position stays (250,250). Run the supplemental effect/native-event control with zero camera pairs. The three already measured camera pairs remain the restoration evidence; do not increase that repetition count to obtain a preferred timing result.

Protocol deviation discovered at final audit: the default runner repeated three camera pairs in each exploratory/reproduction/trace Mosaic run. Across five such runs, 15 pairs actually ran, exceeding the ticket's global maximum of three. The final native supplement used zero pairs, but that does not repair the earlier excess. All 15 retained runs and 342 PNGs are retained and included in the final raw manifest. Numerical pixel claims use named comparable runs; selecting them does not make the whole campaign compliant. The final runner locks a lab campaign and reserves a persisted three-pair budget before launch, including failed attempts. Its budget rejection was verified without creating another run. No further compositor experiment was executed after discovery of the deviation.

The independent full clone at /tmp/step20c-effects-clone contains the frozen repository commit 542d9b9c945b22cf9134a4a643c8dc763b34607d plus the local source fixture. The private build and all selected evidence are in /tmp/swayfx-mosaic-nested-grab-OIWBj9xM/. Its headless backend actually loaded the SceneFX FX renderer with OpenGL ES 3.2 Mesa 26.2.4-arch1.1 on AMD Radeon 780M (radeonsi); output GBM buffers were XR24 and XB24. WLR_RENDERER=pixman did not imply Pixman rendering. Output IPC confirms HEADLESS-1 (-800,0) and HEADLESS-2 (0,0), each 800×600, scale 1, normal transform. The translucent client supplied a real ARGB buffer; the wallpaper used the documented eight-pixel alternating stripes.

The comparable, untraced three-run matrix finished without fixture failure: ordinary splith 18 captures/3.822 s, private splith 18 captures/3.800 s, and private Mosaic 32 captures/5.762 s. The Mosaic run included exactly three hide/return pairs. effects-damage-results/ pixel-analysis.json retains every capture hash, monotonic capture window, whole-image/ROI difference and sampled transition damage comparison.

Mode	FX1 shadow pixels on right output	FX2 blur pixels on left output	FX2 pixels on right output
Ordinary splith	27,594, columns 0–45	112,308	0
Private splith	27,594, columns 0–45	112,308	0
Private Mosaic	0	319,734	0

The ordinary and private-standard shadow screenshots and differential pixels show a genuine spill across global x=0. The corresponding Mosaic right screenshot remains byte-identical to FX0, so the tested overflow is excluded. Private passive trace later observed an enabled shadow render entry on HEADLESS-1 with a draw region clipped at local x=800. However, Mosaic FX1 changed zero sampled pixels on HEADLESS-1 even after gaps inner 24; a visible authorized interior shadow was not established. T1 therefore proves exclusion of the sampled right-output spill but does not fully qualify shadow rendering inside the clip.

FX2 is a real filtered blur, not merely alpha compositing. At y=300, the standard owner's stripe luminance standard deviation fell from about 50.32 (FX0) to 1.37 (FX2), and its mean adjacent-column contrast from 12.37 to 0.88. Mosaic's corresponding preselected strip fell from about 50.33 to 0.69 and 12.61 to 0.74. Enabled regular-blur render entries were also observed in the private trace. The right output had zero FX2 changes in all three modes. T2 is FEASIBLE for these sampled draw boundaries. T3 source-sampling influence is NOT TESTED: no outside-only pattern mutation with an unchanged interior was executed, and the viewport contract does not yet prohibit a shader reading neighbors outside its draw clip.

For T4/T5, the three hidden captures were mutually pixel-identical; each return was pixel-identical to the pre-hide FX4 reference on both outputs. Thus no residual pixel was measured at the settled return. There is no matched effects-off hidden-state reference, so absence of every effect pixel in the hidden state is not established by repeat equality. T6 normal effect disable/re-enable changed 112,308 left-output pixels after layout return, then the owner closed and the exposed area was repainted. T7 layout splith succeeded while the owner remained mapped; its tree geometry reverted to standard tiling and the subsequent enabled/disabled effect toggles remained observable. Closure changes the exposed pixels, but a fresh, identically arranged owner-absent reference was not captured; complete left-output ghost exclusion after closure remains unqualified. No grabbed XDG popup was opened, so popup-effect ownership and dismissal remain NOT TESTED.

Private TEMPORAL_DAMAGE supplied 681 events in standard layout and 715 in Mosaic. For the sampled settled capture transitions, no changed pixel fell outside the union of same-output damage extents between capture windows; the uninstrumented ordinary control supplies no native damage claim. These extents are often broad. This measurement does not prove minimum damage, exact intermediate frames or output-buffer identity. The initial matrix observed private output commits. A final supplemental zero-camera-pair matrix reused the preserved native presentation listener: private standard observed 82 commits / 80 presentations, private Mosaic 95 / 93, with matching (output, commit_seq) identities. The two initial commits of sequence 2 per private mode remain UNEXPLAINED / NO PRESENT OBSERVED. This listener also confirms applied tiled clip/scene geometry and removal on standard-layout return. The supplement uses the natural-size neighboring reference and reproduces the same shadow/blur difference counts as the original controls.

The optional effect-trace.patch is a passive private SceneFX patch, base 37ccd723bef49e6891156ffafce8f549f01446cc plus the preserved historical patches. It records enabled shadow (type 3), optimized-blur (type 4), and regular-blur (type 5) render entries, draw regions and the optimized dirty flag. SHA-256: 32056bd03177ad9b73e1f821bacd121dd39c3b8c078d96a8367f3b1ecc90bc01. That compiled variant is retained outside Git in effects-preparation-logs/effect-trace-compiled.patch. The preserved fixture adds WHY/CONTRACT/INVARIANT comments only, with final SHA-256 6a89142afe2b019262033c7397d4c4593e1b7d0e63b0d620a546a2aa8ee29df7. The optimized entries included dirty=1 and dirty=0, but FX3 PNGs exactly equaled FX2. Source inspection explains a limit of this comparison: output_configure_scene already selects bottom-layer optimized blur for tiled, non-overlapping containers, even with blur_xray disabled. The regular blur node passes that selection through use_optimized_blur. Therefore FX2 cannot be labeled a guaranteed non-optimized control, and FX3 equality is not evidence that optimized blur was unavailable. Node presence and dirty states were observed, but independent optimized-cache invalidation correctness and a stale-cache test remain NOT TESTED.

The trace had a measurable fixture limitation. All 18 private-standard PNGs matched the untraced run; 17/32 private-Mosaic PNGs matched. The remaining 15 differed only in the right reference rectangle, where the traced run's wev tree node was mapped but its checker did not appear. Durations were 3.825 versus 3.800 seconds and 5.772 versus 5.762 seconds; output commit counts were 80 versus 78 and 113 versus 112. Thus perfect instrumentation neutrality is not claimed. The untraced matrix is authoritative for pixel conclusions; the trace establishes node-path presence only. No rendering algorithm, shader, scheduler or ABI changed.

The final raw manifest covers 890 files / 342 PNGs, totaling 26,817,110 bytes: all contents of the 15 retained runs, including exploratory and excluded reference variants (configs, IPC, client/compositor logs, captures, output states, exits and events), the wallpaper, generated runner, preparation logs, compiled trace patch, source manifest, library metadata and structured pixel analysis. Its SHA-256 is 5fbe12b0312f2d82b3c5414251ae57345db8d25a83cfc018947308d40e752b42; all 890 entries verified. The structured analysis measures 174 PNGs in eight named comparable/control runs; metadata identifies each role. The separate 29-entry source manifest, including the preparer chain, pinned patches, protocol inputs, clients and private SceneFX/Mosaic sources, has SHA-256 8fbd0cf927e3e2690a77aeaf2288072c183ef1dbe8f856cb63e0442454614d95; all 29 entries verified. The client patch SHA-256 is 49070bb13ffc96a58e35693b34f1d25c60f824aba69507061211a44ecaeb8087. Exploratory runs remain excluded from selected numerical claims while included in the complete raw manifest and the campaign repetition count.

Verdict: PARTIALLY_FEASIBLE. The tested inherited draw clip excludes the demonstrated ordinary shadow spill, and the genuinely visible blur stays within the sampled Mosaic output with exact settled camera returns. Authorized interior shadow pixels, optimized cache behavior, outside-only shader sampling, popup effects, saved buffers and intermediate frames are unqualified. No concrete leak or standard-layout regression requires a SceneFX redesign on these observations. The next independent STEP20C gate should test scaling first, since this entire effects matrix uses scale 1 and normal transform; rotation, resize/migration, saved buffers and ABI/package maintenance remain subsequent gates. STEP20C stays NEXT and production multi-output Mosaic stays NOT YET SUPPORTED.

Final technical validation and retained incidents

Shell syntax, Python AST, C17 client compilation, patch applicability, private SceneFX/Mosaic builds, the Meson mosaic-model test (1/1), local Markdown links and git diff --check passed. Native presentation callbacks were later than their matching commit callbacks and reported presented buffers; no relation is assigned to the two unmatched startup commits. The actual private library linkage resolves libscenefx-0.5.so inside the lab, wlroots 0.20.2 and Wayland 1.26.0 system libraries without replacement. The preparer creates source hashes automatically; the analyzer creates the complete chosen-run evidence manifest. No build/binary/capture is tracked.

Retained fixture incidents: the initial hand-written client patch failed applicability before any experiment and the preparation trap removed only its own failed lab; the corrected patch subsequently applied and compiled. The late-resize neighboring-reference variant differed between untraced and traced Mosaic and is excluded from perfect-neutrality claims. A source manifest made during edits became stale when the analyzer was updated; the final manifest was regenerated and every entry now passes. None is silently converted into a compositor defect. The private build also retains the existing upstream libinput enumeration warning; it compiled successfully.

All 15 run-specific runtimes created in this lab were removed. No lab process or socket remained at validation. Production source, historical patches, cumulative patch, PKGBUILD and UX are unchanged; phase B remains local and uncommitted. The overall architectural conclusion is UNDECIDED: the tested blur draw boundary is viable, but unexercised cache/sampling, interior-shadow and buffer paths prevent a complete effects contract.

Effects freeze V1 audit plan (2026-10-12)

Reverify the historical 890-entry evidence and 29-entry source manifests without rewriting them. Audit the eight budget cases offline, including launch failure, concurrency and interruption. Rebuild in a new full clone with the pinned inputs and replay the three controls: zero camera pairs in ordinary/private standard, one pair in Mosaic. The new reproduction has a single three-pair campaign ceiling; no second lab is used to reset it. Keep its manifest and results separate from the nonconforming historical campaign. Audit mapped reference geometry and client events before assigning any cause to the traced wev anomaly. No production or UX change is authorized.

Independent audit of the historical reference incident

The retained FX0 IPC trees show wev as floating_con, visible=true, at global (250,250) in each selected run. The untraced Mosaic reference is actually 640×480; the traced Mosaic reference is 300×250. Both event streams include floating enable, resize 300×250 and move 250,250, but the client logs differ: only the traced variant receives the later 300×250 configure (serials 59/60); the untraced variant retains 640×480 (57/58). The common runner maps wev on workspace 2 before mapping the owner on workspace 1, then applies the floating/resize adaptation. FX_TRACE is present in the traced compositor log. Mapping/IPC visibility is insufficient to prove the checker was rendered. The anomalous 15 captures remain in the historical manifest; no screenshot was removed. Geometry/configure timing is a demonstrated confounder, not a proven cause. Logging causality and perfect instrumentation neutrality remain unqualified. Main pixel claims retain the untraced matrix as their reference.

The reservation block passed isolated executable tests of reservation before launch, nonblocking exclusive flock, a launch returning failure, SIGINT interruption, refusal after exhaustion, zero-pair operation with an exhausted budget, and historical retained captures exceeding the limit. The JSON reservation survives failure/interruption. Existing capture counts are combined with the persisted count using max, not reset. These are local process interruption tests, not a power-loss durability guarantee. An initial audit harness failed before executing the reservation block because its synthetic script path had insufficient parent components; the corrected harness passed. No compositor or camera pair ran in that harness.

Freeze V1 independent replay result

New full clone: /tmp/step20c-effects-freeze-v1-clone, HEAD 542d9b9c945b22cf9134a4a643c8dc763b34607d, with the source-only fixture copied in before preparation. New lab: /tmp/swayfx-mosaic-nested-grab-xbAPurbe. Preparation reconstructed pinned SceneFX/Mosaic, checked each historical patch before application, rebuilt private libraries/compositor and compiled the adapted C17 client. No historical lab or binary was used as the reproduction source. The ordinary control uses installed unmodified /usr/bin/sway, as the historical fixture does; exact package-source byte identity is not claimed.

The three runs used --camera-pairs 0, 0, 1 respectively; 18/18/24 captures, failure=null, compositor exit 0 and client exit 0. Helpers were terminated by the runner (SIGTERM where recorded). FX1 right-output counts are again 27,594 / 27,594 / 0; FX2 left counts 112,308 / 112,308 / 319,734, with zero right changes in all modes. Mosaic's FX1 left remains zero; interior shadow is still INCONCLUSIVE. The single camera return is pixel-identical to FX4 on both outputs. Available sampled private damage contains no changed pixel outside the recorded union; ordinary control has no such native damage claim. Renderer again reports SceneFX FX, GLES 3.2 Mesa 26.2.4-arch1.1, AMD Radeon 780M/radeonsi, wlroots 0.20.2.

The separate new 164-entry evidence manifest SHA-256 is 46ac42d414a63ccf5f6f02e6d616fadb72b5533fa8a1b8f56687fdb9600e36c6; new 29-entry build-source manifest: 3693b3be887a8781b3010f330ddeed2c1b69228228f0d579b13b847ccded0bde. Every entry verifies. The persisted budget is consumed=1; actual captured pairs=1. Historical manifests separately verify 890/890 and 29/29 at their original announced hashes. Historical patches, including the distinct compiled trace provenance, are unchanged. The new source manifest records the build inputs before subsequent documentation amendments; it is not represented as a final-publication source manifest.

Shell syntax, Python AST, controlled patch application, C17 compilation, private builds, model test 1/1, local links, unchanged production paths and git diff --check pass. A Pillow getdata deprecation warning is retained; it did not invalidate current analysis. No runtime was left by the three runs. Verdict remains PARTIALLY_FEASIBLE. The historical 15 pairs remain supplementary measurements outside the authorized original protocol; this new conforming reproduction does not retroactively authorize them or erase the instrumentation-neutrality limitation.