Codex instructions — SwayFX Mosaic

These instructions apply to the entire repository. They define the agent's working discipline, not the product specification. If this file conflicts with canonical project documentation, stop and report the conflict; do not silently choose a convenient interpretation.

Mission and communication

Develop only the optional native Mosaic / Spatial Canvas layout for SwayFX. Do not turn the project into a general-purpose SwayFX fork.
Explain plans, findings, test evidence and blockers to the user in French. Follow the existing language/style of each source file and document.
Be evidence-first. Distinguish CURRENT, EXPERIMENTAL, PLANNED, NOT TESTED, BLOCKED, and NOT YET SUPPORTED. Never upgrade a status based on a proposed design, a private spike or a successful compile alone.
Work within the requested scope. Investigations and design proposals do not authorize production implementation, packaging changes or live deployment.

Read before changing anything

git status --short --branch, current branch, recent commits and diff. Preserve pre-existing user changes; do not reset, stash or overwrite them.
docs/README.md (documentation authority and index).
docs/ARCHITECTURE.md, docs/UX.md, docs/KNOWN_LIMITATIONS.md, and docs/ROADMAP.md.
For build/source work: docs/DEVELOPMENT.md and docs/UPSTREAM.md. For packaging: docs/PACKAGING.md.
For STEP20C: all four reports under docs/design/STEP20C_*.md, especially STEP20C_POPUP_OWNERSHIP_PROBE.md.

Canonical architecture/UX/packaging/upstream/development documents govern their own topics. Design documents are proposals or isolated evidence; historical docs/STEP20A.md and docs/STEP20B.md are not current specifications. Resolve contradictory canonical documents before implementing behavior.

Architecture and user-experience invariants

SwayFX's real compositor and tiling tree own runtime order, focus, geometry, camera, transactions, scene, hit testing and IPC. Do not emulate tiling with floating windows or give QuickShell, Session V2 or a daemon parallel authority.
Mosaic is opt-in inside an ordinary Sway workspace. Preserve standard layouts and the workspace-local layout toggle mosaic restoration path.
Runtime Row 0 borrows workspace->tiling; Mosaic state does not own Sway containers. Additional rows currently exist only in the model, not runtime.
Keep logical row order, geometry, viewport/camera and focus distinct. Keep applied rendering and input consistent with the same transaction state.
Super alone must never move windows. Intended external bindings are Super+Alt+L (standard/Mosaic) and Super+Alt+M (Applications); this repository must not install personal bindings, dotfiles or QuickShell configuration.
Preserve ordinary SwayFX floating, fullscreen, scratchpad, popup and IPC behavior unless an explicitly documented, tested Mosaic-specific contract requires a change. Do not invent final cell sizes or animation policy.

Current boundary — STEP20C is a feasibility gate

STEP20A: DONE. STEP20B: EXPERIMENTAL. STEP20C: NEXT, not implemented in production. STEP20D–G: PLANNED. Recheck the roadmap on every new task.
Cross-output viewport clipping is NOT YET SUPPORTED; Mosaic is not validated as a daily-driver compositor. Do not claim otherwise.
The isolated SceneFX subtree clip covered sampled tiled visual/input cases. A later isolated owner-derived root-popup clip covered sampled GTK root and nested popup cases on two horizontal headless outputs. Both are only PARTIALLY_FEASIBLE, not a production dependency decision.
Next evidence required: reproducible valid-serial XDG grabs (distinguish popup dismissal/grab behavior from invisible scene hits), fully hidden popup owner, vertical/negative-origin/scaled/rotated outputs, output migration/resize, transaction-generation consistency, damage/stale pixels, decorations/shadows/blur/saved buffers, and SceneFX/wlroots ABI/package maintenance. Mark any untested matrix cell NOT TESTED.
For popup semantics, compare the modified private compositor against an unmodified headless SwayFX control. Do not promise universal click-through. Offscreen-popup hide/dismiss/reposition UX remains undecided.
Do not merge private SceneFX experiments into the project, create a permanent library fork, alter public ABI, add package dependencies, or claim STEP20C production readiness without an explicit decision and closed feasibility gates. Use disposable private checkouts, libraries, sockets and logs for bounded probes.

Safe development workflow

State the exact scope, accepted contract, expected files and test plan. Prefer one small, reviewable change at a time.
Docs first: change docs/UX.md for user-visible behavior and docs/ARCHITECTURE.md for architecture before implementation. Update Packaging/Upstream/Development when those contracts change; update Known Limitations/Roadmap with actual evidence. Never present a proposal as shipped.
Use existing C, Sway/wlroots/SceneFX conventions. Keep ownership/lifetimes, container identity, popup hierarchy, pending/current state and output coordinates explicit. Add regression tests for changed behavior.
Build and test in isolated build directories; never install, reload, restart or replace the running desktop session. Never operate on the live Sway IPC socket. Headless tests must use their own XDG_RUNTIME_DIR, WAYLAND_DISPLAY and explicit SWAYSOCK / swaymsg -s.
For a normal source change, verify the documented sequence as applicable:
```
meson compile -C build-mosaic -j 8
meson test -C build-mosaic --print-errorlogs
MOSAIC_BINARY="$PWD/build-mosaic/sway/swayfx-mosaic" python tests/headless-ipc.py
git diff --check
```
If the build directory does not exist, set it up as documented in docs/DEVELOPMENT.md. Do not rebuild a supposed upstream baseline in a Mosaic-modified checkout. For documentation-only changes, validate links, consistency, and git diff --check; do not claim runtime tests were run.
For packaging tasks, use DESTDIR staging only and verify the complete manifest contains exactly /usr/bin/swayfx-mosaic. No live install, sudo, pacman, session switch or system library replacement without explicit user authorization.

Package, patch and upstream safety

Pinned base: SwayFX 0.6 at fd71a6bdc061bd633b488ae7b83e8a6981d22f86, wlroots 0.20 and SceneFX 0.5. Never assume an upstream update is compatible.
The ordinary SwayFX package owns /usr/bin/sway; this project may stage only /usr/bin/swayfx-mosaic. No provides, conflicts or replaces against sway/SwayFX. Do not alter or block normal SwayFX upgrades.
Remotes: origin = canonical Forgejo; github = public mirror; upstream = SwayFX fetch-only. Never push Mosaic to upstream.
Production patch: patches/0001-mosaic-layout-viewport.patch, intended as the complete cumulative delta against the pinned pristine upstream commit. Verify forward application on a clean pinned checkout, source equivalence, and the PKGBUILD checksum before treating it as releasable.
tooling/export-patch.sh builds the cumulative delta from the verified pristine SwayFX 0.6 import in a private index. Run its offline regression test, export, review the patch, verify forward application and source equivalence on a clean pinned checkout, then check/update the PKGBUILD checksum. The exporter validates before atomic replacement and must leave the previous artifact intact on failure. Never force-apply hunks.
Do not modify git history, branches, remotes or package version/pins without an explicit scoped reason. No commit or push unless the user requests it.

Required handoff after each task

Report in French: files changed, exact behavior or finding, commands run and PASS/FAIL/NOT RUN results, limitations/risks, and whether anything was committed/pushed. Keep the working tree visible and identify the next smallest justified step. Never conceal failed tests or silently broaden the task into STEP20C production work.

8.2 KiB Raw Blame History Unescape Escape