swayfx-mosaic/AGENTS.md

# 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

1. `git status --short --branch`, current branch, recent commits and diff.
   Preserve pre-existing user changes; do not reset, stash or overwrite them.
2. `docs/README.md` (documentation authority and index).
3. `docs/ARCHITECTURE.md`, `docs/UX.md`,
   `docs/KNOWN_LIMITATIONS.md`, and `docs/ROADMAP.md`.
4. For build/source work: `docs/DEVELOPMENT.md` and `docs/UPSTREAM.md`.
   For packaging: `docs/PACKAGING.md`.
5. 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

1. State the exact scope, accepted contract, expected files and test plan.
   Prefer one small, reviewable change at a time.
2. **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.
3. 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.
4. 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`.
5. For a normal source change, verify the documented sequence as applicable:

   ```sh
   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.
6. 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.