swayfx-mosaic/docs/DEVELOPMENT.md

# Development workflow

For the new experimental CORE-C V2 only, use the
[versioned source-only kit](../tooling/probes/step20c-corec-v2/README.md), its
[private build recipe](../tooling/probes/step20c-corec-v2/BUILD_RECIPE.md) and
[decision/evidence dossier](design/STEP20C_COREC_V2_INTEGRATION_DECISION.md).
Fresh Git-archive reproduction checks complete bytes and modes for new CORE,
OOM and GPU trees; it does not recover historical binaries or prove binary
bit reproducibility. Three private couples/stages and one H1 sanitizer
campaign were consumed; no full-compositor sanitizer H2. Keep generated data
outside HOME, redirect temp/cache with the private wrapper, use separate
sockets, and preserve the LAB. The documented selective purge is NOT EXECUTED.
No new run, production build dependency, installation or live-session action
is authorized by reproduction instructions.

Use separate build directories and headless compositor tests. Ordinary development does not install into `/usr`, reload Sway, or change the active desktop session. The current package is experimental; see [Packaging](PACKAGING.md) for the file-ownership contract.

## Repository and remotes

| Remote | Role | Push policy |
| --- | --- | --- |
| `origin` | Canonical Forgejo project | Project changes |
| `github` | Public GitHub mirror | Same reviewed project commits |
| `upstream` | SwayFX source | Fetch only; never push Mosaic changes |

`main` contains the project's public history: imported SwayFX 0.6 base plus Mosaic commits. The external `upstream` remote retains SwayFX history. Public instructions must not depend on a private local branch. Make focused development branches from `main`; merge or publish only after the source delta, tests, docs, and patch agree.

## Base and prerequisites

The pinned base is SwayFX tag `0.6`, commit `fd71a6bdc061bd633b488ae7b83e8a6981d22f86`, using wlroots 0.20 and SceneFX 0.5. Meson, Ninja, the base build dependencies, Python, and the headless test dependencies (`kitty`, `grim`) are needed for the respective checks. Review [Upstream](UPSTREAM.md) before changing the pin. The exact older local Arch package build source is not reconstructible; do not claim byte-identical provenance.

## Pristine baseline build

Use a pristine checkout of the pinned upstream commit for baseline validation, or an already-retained baseline build known to come from that commit. Do not treat a Mosaic-modified tree as an upstream baseline.

```sh
meson setup build-baseline -Dwerror=false -Dsd-bus-provider=libsystemd
meson compile -C build-baseline -j 8
meson test -C build-baseline --print-errorlogs
```

The historical upstream baseline had no Meson tests. A fresh baseline build is especially important for an upstream update. The command above assumes the current working tree is the pristine baseline; use a separate checkout so the Mosaic tree is not altered.

## Mosaic build and headless tests

From the project development tree:

```sh
meson setup build-mosaic \
  -Dwerror=false -Dsd-bus-provider=libsystemd \
  -Dmosaic-package=true -Dprefix=/usr -Dbindir=bin \
  -Dswaybar=false -Dswaynag=false \
  -Dman-pages=disabled -Ddefault-wallpaper=false
meson compile -C build-mosaic -j 8
meson test -C build-mosaic --print-errorlogs
python tests/headless-ipc.py
git diff --check
```

The headless script starts its own compositor socket; use its documented `MOSAIC_BINARY` environment variable for a nondefault build path. Do not send test commands to the running desktop's IPC socket. Record compiler/test failures, not only passes.

## Preserved STEP20C experimental fixture

The [valid-grab source fixture](../tooling/probes/step20c-valid-grab/README.md)
records the exact private patch bases, hashes, dependencies and temporary
headless replay commands for the [bounded probe](design/STEP20C_VALID_GRAB_HIDDEN_OWNER_PROBE.md).
These source files are experimental evidence. Rebuild in a new temporary
laboratory; leave generated protocol files, private libraries, compositor
binaries, sockets, logs and screenshots outside Git. This fixture is not part
of the ordinary Mosaic build, cumulative production patch or Arch package.

## Staging and package checks

```sh
meson install -C build-mosaic --destdir /tmp/swayfx-mosaic-stage
find /tmp/swayfx-mosaic-stage -type f -print
makepkg --printsrcinfo
makepkg --verifysource
```

Inspect the staging manifest. With `mosaic-package=true`, the expected installed file is `/usr/bin/swayfx-mosaic` under the staging root. This is staging, not live installation. A full `makepkg` build is required before a release, with its own build/test output and manifest review.

## Patch export

The development tree contains full SwayFX source for editing. `patches/0001-mosaic-layout-viewport.patch` is the complete production delta against the imported pristine SwayFX 0.6 commit `a57e3f2c4d88f258c2f038343a398c6d5be1fb59` (whose relevant source matches pinned upstream `fd71a6bdc061bd633b488ae7b83e8a6981d22f86`). Run the regression test before export:

```sh
PYTHONDONTWRITEBYTECODE=1 python -m unittest -v tests/test_export_patch.py
sh -n tooling/export-patch.sh
tooling/export-patch.sh
sha256sum patches/0001-mosaic-layout-viewport.patch
git diff --check
```

The exporter uses a separate temporary Git index and object directory and includes staged, unstaged, added and deleted package source under `include/`, `sway/`, `meson.build`, `meson_options.txt` and `tests/mosaic-model.c`. It refuses unresolved conflicts in those paths and does not change the real index or object database. Before atomic replacement, it requires a nonempty patch, reverse applicability to the current tree, forward applicability to a pristine archive of the imported base, and equivalence of source contents, file modes and links. Failure leaves the prior patch intact. Review the resulting patch and update the checksum in `PKGBUILD` whenever its bytes change.

For an independent release check when the pinned upstream commit is available locally, use a disposable archive of that exact commit:

```sh
(
  set -eu
  upstream=fd71a6bdc061bd633b488ae7b83e8a6981d22f86
  imported=a57e3f2c4d88f258c2f038343a398c6d5be1fb59
  patch_file="$PWD/patches/0001-mosaic-layout-viewport.patch"
  git diff --exit-code "$upstream" "$imported" -- \
    include meson.build meson_options.txt sway tests/mosaic-model.c
  pristine=$(mktemp -d)
  trap 'rm -rf "$pristine"' 0
  git archive "$upstream" > "$pristine/base.tar"
  mkdir "$pristine/source"
  tar -xf "$pristine/base.tar" -C "$pristine/source"
  (cd "$pristine/source" && git apply --check "$patch_file" && git apply "$patch_file")
  for source in include sway meson.build meson_options.txt tests/mosaic-model.c; do
    git diff --no-index --exit-code -- "$pristine/source/$source" "$source"
  done
)
```

Then review the patch and run the package checks in [Packaging](PACKAGING.md). `git apply --check` in an already-patched development tree is not a valid forward-application check. These exporter checks do not qualify the package without a full `makepkg` build and staged manifest inspection.

## Upstream update branch

1. Fetch `upstream` and identify the exact new release commit.
2. Create a dedicated branch/checkout for the new base; inspect SwayFX changes in affected files.
3. Update Architecture, UX, Packaging, Upstream, and limitations for any changed contract before implementing the forward port.
4. Adapt the Mosaic delta manually if the patch conflicts. Never force or silently skip hunks.
5. Build and test the pristine new base, then Mosaic and standard layouts on that base.
6. Run model/headless IPC/rendering tests, stage the package, inspect file ownership, and update the pin, version, patch, and checksums together.
7. Publish only after the new base is validated. The normal SwayFX package continues updating independently.

See [Packaging](PACKAGING.md) and [Upstream](UPSTREAM.md) for release invariants. Desktop key bindings belong to user dotfiles and are not installed here.

## 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](design/STEP20C_STATIC_RUNTIME_AND_PACKAGE_CONTRACT.md).
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.

## Preserved overnight experimental reproduction

The [annotated rebuild/private-stage report](design/STEP20C_ANNOTATED_REBUILD_AND_PRIVATE_STAGE.md)
and [source-only qualification index](../tooling/probes/step20c-overnight/qualification/README.md)
record exact pins, ordered patches, private Meson options, local ABI checks,
staging manifests and an immutable 18-run budget outcome. Reproduce only in a
new disposable LAB with verified retained inputs and a separately authorized
budget; the original budget is exhausted and no retry is authorized. Private
patches, source archives and future recipe remain local references, not a
self-contained publicly distributed build kit. Build/model/ELF/stage passed
locally; makepkg metadata/source verification/full build was NOT RUN. No binary
bit-reproducibility or distribution readiness is claimed. Experimental helper
fixtures do not add a production dependency. See the dossier for transport,
cleanup and unexercised-case limits before interpreting runtime results.