m3te/README.md

# m3te

A match-3 game written entirely in the **sx** language, targeting **iOS** first.

- Game logic, rendering, input, and UI are all authored in sx.
- Art (palettes, sprite sheets) is produced as real assets.
- Verification gate: sx logic tests pass AND the iOS app builds & launches in the Simulator.

Development is driven by the multi-agent `flow` (Product Owner → Worker → Reviewer → Observer).

## Verification gate

The gate has two halves. Both must pass. The sx compiler used below lives at
`/Users/agra/projects/sx/zig-out/bin/sx` (override the runner's binary with the
`SX` env var). Run everything from the repo root.

### 1. Logic tests

Pure-sx logic tests run under `sx` and have their stdout + exit code diffed
against committed snapshots in `tests/expected/`. A failed assertion exits the
process non-zero, so it fails the runner (and the gate).

```bash
bash tools/run_tests.sh
```

- A test is any `tests/<name>.sx` that has a `tests/expected/<name>.exit`
  marker; `tests/test.sx` (the `expect` assert helper) has no marker, so it is
  not itself run.
- Regenerate snapshots after an intentional change: `bash tools/run_tests.sh --update`.

### 2. iOS Simulator build + launch

Build the app for the simulator, then install/launch it on an available device
and screenshot the rendered scene — the brighter **candy** match-3 board: a soft
pink→lavender→blue gradient background, an 8×8 grid of glossy candy gems on cream
cell tiles, and a grape candy HUD card (score / moves) above the grid.

```bash
# Build the .app bundle (sx-out/ios/M3te.app):
/Users/agra/projects/sx/zig-out/bin/sx build --target ios-sim main.sx

# Discover an available simulator — do NOT hardcode a udid:
xcrun simctl list devices available
# e.g. capture the first available device's UDID into $udid:
udid=$(xcrun simctl list devices available | grep -Eo '[0-9A-Fa-f-]{36}' | head -1)

# Boot it (skip if already "Booted") and bring the Simulator window up:
xcrun simctl boot "$udid" || true
open -a Simulator

# Install, launch (bundle id co.swipelab.m3te), and screenshot:
xcrun simctl install booted sx-out/ios/M3te.app
xcrun simctl launch booted co.swipelab.m3te
xcrun simctl io booted screenshot /tmp/m3te.png
```

The screenshot should match `goldens/p6_idle_t0.png` (the resting candy board),
modulo the status-bar clock — pixel-exact equality is not required; compare the
board + HUD region, not the top status strip. A tap selects a cell; a swipe
between two adjacent gems commits a swap (legal swaps cascade + score, illegal
ones ping back). The deterministic capture hooks below pin a chosen scene so each
golden reproduces from a clean checkout.

> The earlier `p0_*` goldens (a pre-board orange quad over a blue clear, from the
> P0 foundation slice) were removed in P13.1: the app no longer renders that
> scene, so they could only ever mislead.

### Deterministic animation capture (P6.3)

The per-gem idle loop (`gem_anim.sx`) is always-on, so a plain screenshot is
time-dependent. Two environment variables pin the visual state so the board can
be captured reproducibly. The simulator forwards any `SIMCTL_CHILD_*` variable to
the launched app, so prefix them on the `simctl launch`:

- `M3TE_ANIM_TIME=<seconds>` freezes the animation clock at that phase. **`t=0`
  is the resting board** — every gem sits at its static pose, so the pre-P6.3
  goldens reproduce unchanged. A larger `t` (e.g. `1.0`) shows the mid-breath
  idle deformation. The select/land reactions read this same pinned phase.
- `M3TE_SELECT=<cellIndex 0..63>` (= `row*8 + col`) force-selects a cell at
  startup, so the selection highlight + pop can be captured without a tap.

> **Every `M3TE_*` pin is read once, at app startup.** A `simctl launch` against
> an already-running copy just foregrounds the existing process (the launch prints
> the *same* PID) and the new `SIMCTL_CHILD_*` value is ignored. So every
> multi-launch recipe below passes `--terminate-running-process` on each pinned
> launch — it kills the running copy first, so the fresh process re-reads the new
> pin. (`xcrun simctl terminate booted co.swipelab.m3te` before each relaunch does
> the same.) A *changed* PID between launches confirms the new pin took.

```bash
# Resting board (idle at rest): goldens/p6_idle_t0.png
SIMCTL_CHILD_M3TE_ANIM_TIME=0   xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
# Mid-breath idle: goldens/p6_idle_mid.png
SIMCTL_CHILD_M3TE_ANIM_TIME=1.0 xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
# Selection pop on cell (3,3): goldens/p6_select.png
env SIMCTL_CHILD_M3TE_ANIM_TIME=0.17 SIMCTL_CHILD_M3TE_SELECT=27 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
```

With no variable set the game runs fully live (the clock advances by
`delta_time`). `tests/gem_pose.sx` locks the `t==0`-rest invariant headlessly.

### Level-state capture (P7.2)

The win/lose banner and restart button are driven by the model's `level_status`
(score vs. goal vs. move budget). Three more env hooks force a terminal status
(or a restart) so the banner / restart states can be screenshot deterministically
without scripting a winning swipe — combine them with `M3TE_ANIM_TIME` to pin the
idle clock:

- `M3TE_TARGET=<n>` overrides the per-level score goal. `0` makes the fresh board
  read **won** immediately (`score 0 ≥ goal 0`).
- `M3TE_MOVE_LIMIT=<n>` overrides the move budget. `0` makes it read **lost**
  (budget spent below the goal).
- `M3TE_RESTART=<non-zero>` runs `board.restart` after the overrides, capturing
  the fresh `in_progress` board the restart button produces.

```bash
# Win banner + restart over the board: goldens/p7_win.png
env SIMCTL_CHILD_M3TE_TARGET=0 SIMCTL_CHILD_M3TE_ANIM_TIME=0 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
# Lose banner ("OUT OF MOVES") + restart: goldens/p7_lose.png
env SIMCTL_CHILD_M3TE_MOVE_LIMIT=0 SIMCTL_CHILD_M3TE_ANIM_TIME=0 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
# Fresh in_progress board after restart: goldens/p7_restart.png
env SIMCTL_CHILD_M3TE_TARGET=0 SIMCTL_CHILD_M3TE_RESTART=1 SIMCTL_CHILD_M3TE_ANIM_TIME=0 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
```

While a banner is up the board freezes (only the restart button is live, per
P7.1's finished-level rule); `tests/banner_layout.sx` locks the restart button's
rect ↔ hit-test round-trip headlessly.

### Match-FX capture (P11.1)

The match bursts + score popup (`board_fx.sx`) only spawn off a *committed* move,
which the simulator can't script (there is no public touch injection). One more
env hook forces a representative match at startup so the FX can be screenshot
deterministically — combine it with `M3TE_ANIM_TIME` to freeze the phase:

- `M3TE_FX=<n>` commits the **n-th currently-legal swap** (1-based, clamped; `=1`
  is the first) through the normal `plan_and_commit` path, then begins the move
  timeline + its burst/popup FX. While `M3TE_ANIM_TIME` is set the move/FX
  timelines are pinned at that phase (the frame loop holds them frozen), so the
  burst and floating `+points` render identically every run. A larger
  `M3TE_ANIM_TIME` lands past the timeline, capturing the settled board with the
  FX fully pruned. Startup-only and guarded by the var, so normal play is
  untouched.

The legal-swap order is the fixed enumeration in `tests/expected/swap_legality.stdout`
(row-major, right-before-down). For seed 1337, `M3TE_FX=3` is the vertical red
3-match used by the golden, and `M3TE_FX=11` is a **depth-5 cascade** (the deepest
on this seed) used to capture the escalated combo emphasis (next section).

```bash
# Punchy match burst + "+30" popup, pinned mid-clear: goldens/p6_fx_match.png
env SIMCTL_CHILD_M3TE_FX=3 SIMCTL_CHILD_M3TE_ANIM_TIME=0.22 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
# Same match, later phase — FX fully gone over the settled board (no golden):
env SIMCTL_CHILD_M3TE_FX=3 SIMCTL_CHILD_M3TE_ANIM_TIME=2.0 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
```

### Escalating combo emphasis (P11.2)

The combo FX escalates with cascade depth (`mv.rounds.len`), the SAME depth the
cascade SFX (`play_cascade`) steps up on: a deeper cascade gets a bigger, hotter-
gold `+points` popup topped by a `COMBO xN` label, and bursts that grow from the
first round. The depth→emphasis clamp (`fx_combo_level`) mirrors the cascade cue's
`cascade_cue_index` exactly (depth ≤ 1 → floor, depth ≥ 5 → ceiling); the
equivalence is locked headlessly by `tests/fx_combo.sx`.

Capture it with the same `M3TE_FX` hook — `M3TE_FX=11` is a depth-5 cascade on
seed 1337, contrasted against the depth-1 single clear `M3TE_FX=3`:

```bash
# Escalated COMBO x5 + gold "+1050" + bigger burst: goldens/p11_combo_deep.png
env SIMCTL_CHILD_M3TE_FX=11 SIMCTL_CHILD_M3TE_ANIM_TIME=0.22 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
# Single clear for contrast — plain white "+30", no COMBO label (goldens/p6_fx_match.png):
env SIMCTL_CHILD_M3TE_FX=3 SIMCTL_CHILD_M3TE_ANIM_TIME=0.22 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
# Deep cascade at a later phase — all combo FX gone over the settled board (no golden):
env SIMCTL_CHILD_M3TE_FX=11 SIMCTL_CHILD_M3TE_ANIM_TIME=3.0 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
```

The combo emphasis is purely visual and self-pruning: it never gates input
(`BoardAnim.active` owns gating) and never touches board / score / move state.

### Glossier gem & selection feel (P11.3)

The selection highlight (`board_view.sx` `render_selection`) is a candy-glossier
overlay: two concentric stroked rings fake a soft outward glow, a warm wash tints
the cell, a bright rim is doubled by a thin inner highlight for a glassy edge, and
a wet sheen rides the selected gem's live pose. The engine can't tint a texture at
draw time (issue 0002), so every layer is a rect/overlay — never a gem-texture
tint. The selection-pop motion still comes from `gem_anim`, so the **t==0 idle
pose is byte-identical to the static sprite** (locked by `tests/gem_pose.sx`); the
gloss is selection-only, so the resting board (no selection) is unchanged.

Capture it with the same P6.3 hooks — no new env var:

```bash
# Glossy candy selection on cell (3,3), pinned mid-pop: goldens/p6_select.png
env SIMCTL_CHILD_M3TE_ANIM_TIME=0.17 SIMCTL_CHILD_M3TE_SELECT=27 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
# Same selection at exact rest (no pop) — isolates the overlay:
env SIMCTL_CHILD_M3TE_ANIM_TIME=0 SIMCTL_CHILD_M3TE_SELECT=27 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
```

The selection gloss is purely visual: it never gates input (`BoardAnim.active`
owns gating) and never touches board / score / move state.

### Organic swap motion (P16.1)

A legal swap no longer slides flatly into place: `render_swap` drives the two
gems with `ease_out_back` (the P15.1 overshoot curve), so they shoot a touch PAST
their target cells then settle exactly onto them. The curve pins `f(0)=0` and
`f(1)=1`, so the swap stays purely visual — `t==0` is the rest pose and `t==1`
lands byte-on-cell; the committed move and final board are unchanged. The reused
`SWAP_ANIM_DUR` (0.16 s) is untouched, so the cascade-cue timing snapshots
(`tests/cascade_rounds.sx` / `cascade_cue.sx`) don't churn.

Capture the overshoot with the same `M3TE_FX` hook, pinned near the peak
(swap-phase `t ≈ 0.625`, where the gems are ~10 % past target):

```bash
# Swapped gems caught PAST their target cells (overshoot): goldens/p16_swap.png
env SIMCTL_CHILD_M3TE_FX=3 SIMCTL_CHILD_M3TE_ANIM_TIME=0.10 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
# Same swap at exact rest (t=0) — gems sit dead-on their pre-swap cells:
env SIMCTL_CHILD_M3TE_FX=3 SIMCTL_CHILD_M3TE_ANIM_TIME=0 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
```

`M3TE_FX=3` is the top-row swap `(5,0)↔(6,0)` that completes the vertical red
3-match in column 5; at `M3TE_ANIM_TIME=0.10` the red lands ~8 % left of col-5
and the green ~12 % right of col-6 (every unswapped gem stays centered).

### Organic illegal swap (P16.2)

A *rejected* swap no longer pings flatly out and back: `render_swap` now drives the
two gems with `bad_swap_bounce` (a P15.1 `spring`-based envelope), so they lunge
toward each other then spring home, overshooting rest by a bounded amount before
settling. The curve pins `f(0)=0` and `f(1)=0`, so the move stays purely visual —
both `t=0` and `t=1` are the rest pose, the board is byte-identical to pre-swap, no
move or score is spent. The envelope (endpoints, single lunge peak + location,
damped settle) is locked headlessly by `tests/easing.sx`.

The bounce only plays for an *illegal* swap, which the sim can't script, so one more
env hook forces a known rejected pair at startup — combine it with `M3TE_ANIM_TIME`
to freeze the phase:

- `M3TE_BADSWAP=<n>` commits the **n-th currently-ILLEGAL orthogonally-adjacent
  pair** — the complement of `legal_swaps`, enumerated in the SAME stable row-major
  order (right-before-down), 1-based + clamped — through the normal `plan_and_commit`
  path (which reverts the illegal swap), then begins the move timeline so the
  swap-segment bounce can be screenshot. No FX begins (a rejected swap clears
  nothing). Startup-only and guarded by the var, so normal play is byte-identical
  with it unset.

The lunge peak is at swap-phase `t = BADSWAP_LUNGE_T (0.36)`, i.e. animation time
`0.36 × SWAP_ANIM_DUR (0.16) ≈ 0.0576 s`. For seed 1337, `M3TE_BADSWAP=41` is the
mid-board horizontal pair `(2,3)↔(3,3)`:

```bash
# Springy lunge caught at its extreme (gems nudged toward each other): goldens/p16_badswap.png
env SIMCTL_CHILD_M3TE_BADSWAP=41 SIMCTL_CHILD_M3TE_ANIM_TIME=0.0576 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
# Same rejected pair at exact rest (t=0) — gems sit dead-on their pre-swap cells:
env SIMCTL_CHILD_M3TE_BADSWAP=41 SIMCTL_CHILD_M3TE_ANIM_TIME=0 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
```

### Organic fall — gravity accel (P17.1)

Falling gems no longer *decelerate* into place: `render_fall` now drives the
per-round drop with `ease_in_cubic` (the P15.1 accelerate-from-rest curve) instead
of `ease_out_cubic`, so gems start slow and accelerate down like gravity. The curve
pins `f(0)=0` and `f(1)=1`, so each gem still lands EXACTLY on its destination cell
at the segment's end — the seam to the next round / settled board stays invisible
and `move.final` is untouched (`tests/anim_plan.sx` contiguity stays green).
`FALL_ANIM_DUR` (0.22 s) is unchanged, so the per-round cascade-cue timing
snapshots (`tests/cascade_rounds.sx` / `cascade_cue.sx`) don't churn.

The visual tell of the accel: pinned mid-fall, gems are bunched HIGH near their
sources (little distance covered) rather than spread out near landing. Capture it
with the `M3TE_FX` hook; `M3TE_FX=11` is the depth-5 cascade on seed 1337, pinned
inside **round 3's fall window** `[1.38, 1.60)` s — at `1.51` we are ~59 % through
that segment in time, yet `ease_in_cubic(0.59) ≈ 0.20`, so the gems have covered
only ~20 % of their drop and hang caught in the upper rows over the filled lower
board (the old `ease_out_cubic(0.59) ≈ 0.93` would have them ~93 % down, all but
landed):

```bash
# Gems caught bunched-high mid-fall under gravity accel: goldens/p17_fall.png
env SIMCTL_CHILD_M3TE_FX=11 SIMCTL_CHILD_M3TE_ANIM_TIME=1.51 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
# Same cascade past the timeline — fully settled board (no golden):
env SIMCTL_CHILD_M3TE_FX=11 SIMCTL_CHILD_M3TE_ANIM_TIME=3.0 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
```

The round-k fall window is `[0.30 + 0.36·k, 0.52 + 0.36·k)` s on the
swap→(clear,fall)\* timeline (swap 0.16, then clear 0.14 + fall 0.22 per round), so
`1.51` lands squarely in round 3's fall. The change is render-only — no `board.sx`
model change, and normal play is byte-identical apart from the fall's motion curve.

### Organic fall — per-column stagger (P17.2)

The fall no longer drops a whole row in lockstep: `render_fall` offsets each
COLUMN's drop START by a small bounded delay (`fall_stagger_t`), so a refilled row
pours in as a left-to-right cascade. Column `col` waits `FALL_STAGGER_MAX·col/7`
(`FALL_STAGGER_MAX = 0.30`) of the fall window, then falls over the remaining
`1 - 0.30`, feeding that local progress through `ease_in_cubic` so each column still
accelerates under gravity within its own window. The LAST column lands EXACTLY at
`t=1` and every earlier column strictly before it, so NO gem is ever left mid-air at
the segment end — the seam to the next round / settled board stays invisible and
`move.final` is untouched (`tests/anim_plan.sx` contiguity stays green;
`tests/easing.sx` pins `fall_stagger_t`'s `f(0)=0`, `f(1)=1`, monotonicity, and the
mid-fall cascade ordering). `FALL_ANIM_DUR` (0.22 s) is unchanged, so the per-round
cascade-cue snapshots don't churn.

The cleanest tell is a round where several adjacent columns refill the SAME
distance: in lockstep their gems share one height (a flat row); staggered, they
form a diagonal. On seed 1337, `M3TE_FX=11` **round 4** refills columns 2–7 by one
cell each (its fall window `[1.74, 1.96)` s); at `1.91` the leading column has just
landed while the trailing column is still ~⅔ cell high, so the top row reads as a
left-to-right staircase instead of a flat band:

```bash
# Refilled row pouring in as a staggered cascade: goldens/p17_stagger.png
env SIMCTL_CHILD_M3TE_FX=11 SIMCTL_CHILD_M3TE_ANIM_TIME=1.91 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
# Same cascade past the timeline — every gem landed exactly on the model board:
env SIMCTL_CHILD_M3TE_FX=11 SIMCTL_CHILD_M3TE_ANIM_TIME=3.0 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
```

The change is render-only — no `board.sx` model change, and normal play is
byte-identical apart from the fall's per-column timing.

### Organic fall — landing squash-&-settle (P17.3)

Each landing gem now flattens **wide-and-short on impact then wobbles back to rest**
(P15.1's `squash_envelope`), applied WITHIN the fall so EVERY cascade round bounces,
staggered per column — not only the final whole-move settle as before. `render_fall`
ages a per-column bounce from each column's touch-down instant (`fall_landing_frac` ·
`FALL_ANIM_DUR`), so a gem still in the air is drawn unsquashed and only a gem that
has reached its cell flattens; the squash carries across the fall→clear seam
(`render_clear` continues the previous round's bounce) and across the final
render_anim → render_gems seam (the settle stamp is **back-dated** per column so
`land_squash` resumes exactly where the fall left it — ONE bounce, no double-pop).
`land_squash` is now `LAND_SQUASH_A · squash_envelope(tl/LAND_DUR)`, so the per-round
fall bounce and the settle bounce are the same single envelope; amplitude is the
tasteful ~13 % peak (`LAND_SQUASH_A = 0.18`). Durations are unchanged, so the
cascade-cue snapshots don't churn; `M3TE_ANIM_TIME=0` still reproduces
`goldens/p6_idle_t0.png` exactly (a resting board carries no landing stamp).

The visual tell: pin a round's fall just before it ends and the leading columns sit
landed-and-squashed (wide-short) while the trailing columns are still airborne — a
staggered squash wave. On seed 1337, `M3TE_FX=11` **round 4** (the refill round) at
`1.94` shows columns 2–4 landed and flattened with columns 5–7 still pouring in
(every round behaves identically — round 2 `[1.02,1.24)` at `1.21` and round 3
`[1.38,1.60)` near `1.58` bounce the same way, so the bounce is NOT limited to the
last settle):

```bash
# Staggered landing squash mid-pour (leading cols flattened, trailing airborne):
#   goldens/p17_land.png
env SIMCTL_CHILD_M3TE_FX=11 SIMCTL_CHILD_M3TE_ANIM_TIME=1.94 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
# Same cascade past the timeline — fully settled, bounce decayed to rest (no golden):
env SIMCTL_CHILD_M3TE_FX=11 SIMCTL_CHILD_M3TE_ANIM_TIME=3.0 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
```

All three fall goldens were re-captured in P19.2 to the final, fully-merged fall
motion (gravity accel + per-column stagger + landing squash), each pinned to
foreground a different tell of it: `goldens/p17_fall.png` (round 3 at `1.51`) catches
the columns bunched HIGH under the gravity accel before any has landed (so it carries
no squash); `goldens/p17_stagger.png` (round 4 at `1.91`) catches the left-to-right
staircase as the leading column just touches down; and this golden (round 4 at `1.94`)
catches the squash wave once the leading columns have landed-and-flattened while the
trailing ones still pour in. The change is render-only — no `board.sx` model change,
and a resting board is untouched.

### Organic combine — anticipation pop on clear (P18.1)

Matched gems no longer just pop-then-shrink flatly: `clear_pop_scale` now shapes the
clear as a candy pop in three beats over its local `0..1` — a tiny anticipation
squash dip (a "gather" ~8 % below rest), a snappy overshoot up to ~1.40× via P15.1's
`ease_out_back`, then an accelerating collapse to nothing (`ease_in_quad`). The
endpoints stay LOCKED — `t==0 → 1.0` (rest) and `t==1 → 0.0` (gone) — so the seam to
the model board is clean and `M3TE_ANIM_TIME=0` still reproduces the resting board;
the soft particle burst / `+points` popup (`board_fx.sx`) compose on top.
`tests/gem_pose.sx` pins the new envelope (locked rest endpoints, the anticipation
dip below rest, the overshoot above 1, and the strictly monotonic post-peak
collapse). `CLEAR_ANIM_DUR` (0.14 s) is unchanged, so the per-round cascade-cue
timing snapshots (`tests/cascade_rounds.sx` / `cascade_cue.sx`) don't churn.

The pop peaks at clear-phase local `t ≈ 0.37`; for `M3TE_FX=3` (the seed-1337
vertical red 3-match in column 5, rows 0–2) the clear window is `[0.16, 0.30)` s.
Because P18.2 staggers each matched gem's pop START (see below), the `0.21` capture
no longer catches the three gems together at this shared peak — it catches them at
DIFFERENT points on this same curve, a ripple: the top gem collapsing, the middle
rising toward its overshoot, and the bottom still at rest (full size), all composed
with the burst and "+30" popup:

```bash
# Per-gem candy-pop shape, staggered across the match by P18.2 (composed w/ burst):
#   goldens/p18_pop.png
env SIMCTL_CHILD_M3TE_FX=3 SIMCTL_CHILD_M3TE_ANIM_TIME=0.21 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
# Same match at exact rest (t=0) — board sits at its resting pose, no pop:
env SIMCTL_CHILD_M3TE_FX=3 SIMCTL_CHILD_M3TE_ANIM_TIME=0 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
```

`goldens/p6_fx_match.png` (the P11.1 burst+popup reference, pinned at `0.22`) was
refreshed for the new pop shape (and re-refreshed in P18.2 for the stagger — pinned
mid-clear, the committed frame now shows the ripple, not a uniform pop). This step is
the per-gem pop SHAPE only; the per-gem STAGGER of the explosions follows in P18.2.
The change is render-only — no `board.sx` model change, and normal play is
byte-identical apart from the clear's pop curve.

### Organic combine — staggered clear ripple (P18.2)

The matched gems no longer all explode at once: within a clearing round each gem's
pop (and its burst) START is offset by a small BOUNDED delay so the cells detonate
as a RIPPLE. `clear_ripple_t(t, u)` mirrors `fall_stagger_t`'s `(t-delay)/window`:
a gem's normalized rank `u ∈ [0,1]` (its diagonal `col+row` position within the
round's matched cells, lowest = `0`) delays its pop START by `CLEAR_STAGGER_MAX·u`
(`0.45` of the clear window), then plays the P18.1 `clear_pop_scale` curve over the
remaining `1 − CLEAR_STAGGER_MAX`. The rank is normalized PER ROUND (not across the
board) so even a 3-match ripples across the full stagger budget. It is BOUNDED:
every matched gem still reaches local `1` (scale `0`, fully cleared) by the clear
segment's end — the last-to-start gem (`u=1`) lands exactly at `t==1` — so no gem is
left mid-pop at the seam to the fall. The bursts (`board_fx.sx`) carry the SAME
per-gem delay so they ripple in lockstep with the pops. `tests/easing.sx` pins the
envelope (locked `f(0,·)=0` / `f(1,·)=1` endpoints, bounded completion by `t==1`,
monotonicity, and the rank ordering).

INTRA-ROUND VISUAL ONLY: the per-round cascade audio (P10.10) is untouched — one
ascending cue per round at the round's clear, NOT per gem — and the model is
unchanged (same cells cleared, same final board). `CLEAR_ANIM_DUR` (`0.14` s) is
unchanged, so the cascade-cue snapshots (`tests/cascade_rounds.sx` / `cascade_cue.sx`)
don't churn and `M3TE_ANIM_TIME=0` still reproduces the resting board.

For `M3TE_FX=3` (the seed-1337 vertical red 3-match in column 5, rows 0–2) the clear
window is `[0.16, 0.30)` s; at `M3TE_ANIM_TIME=0.22` the ripple is at its clearest —
the TOP gem is collapsing, the MIDDLE is mid-burst, and the BOTTOM is still full-size
(not yet started):

```bash
# Staggered clear ripple (top collapsing / middle bursting / bottom not yet):
#   goldens/p18_stagger.png
env SIMCTL_CHILD_M3TE_FX=3 SIMCTL_CHILD_M3TE_ANIM_TIME=0.22 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
# Past the timeline — all three cells cleared per the model, board continues:
env SIMCTL_CHILD_M3TE_FX=3 SIMCTL_CHILD_M3TE_ANIM_TIME=2.0 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
```

`goldens/p18_pop.png` (`M3TE_FX=3` at `0.21`), `goldens/p6_fx_match.png` (`M3TE_FX=3`
at `0.22`), and `goldens/p11_combo_deep.png` (`M3TE_FX=11` at `0.22`) were refreshed
— each was pinned mid-clear, so each now shows the staggered ripple instead of the
prior simultaneous pop.

### FPS counter — dev overlay (P20.1)

A small FPS readout for gauging frame cost while tuning the animations. It is a
**dev overlay, OFF by default**: only the `M3TE_FPS` env pin turns it on, so default
play and every committed golden stay byte-identical (with `M3TE_FPS` unset the
rendered scene is unchanged — `goldens/p6_idle_t0.png` reproduces exactly).

- `M3TE_FPS=<non-zero>` renders the FPS counter in the **top-left corner** (inside
  the safe area, clear of the centered notch / Dynamic Island and the centered HUD).
  The rate is computed from the per-frame `delta_time` as an exponential moving
  average (`FPS_DT_SMOOTH = 0.9`) so the digits don't jitter. Read once at startup
  like every other `M3TE_*` pin; `=0` or unset leaves it off. Purely a render
  overlay — no board / score / move / animation state changes, and it never gates
  input. `delta_time` is real wall-clock even when `M3TE_ANIM_TIME` pins the
  animation, so the counter stays live while the rest of the scene is frozen.

```bash
# FPS counter over the resting board: goldens/p20_fps.png
# (the FPS digits are DYNAMIC — only the FPS text varies run-to-run; the rest of the
#  scene is pinned at M3TE_ANIM_TIME=0, byte-identical to goldens/p6_idle_t0.png)
env SIMCTL_CHILD_M3TE_FPS=1 SIMCTL_CHILD_M3TE_ANIM_TIME=0 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
# On device, pass the same flag through devicectl's environment instead:
#   xcrun devicectl device process launch --environment M3TE_FPS=1 ... co.swipelab.m3te
```

`goldens/p20_fps.png` is the only golden that captures this overlay; because the FPS
digits are dynamic, compare the FPS text's PRESENCE in the top-left corner, not its
exact value. Every other golden is captured with `M3TE_FPS` unset and is unaffected.

### Move-timeline frame goldens (P6.1 / P6.2)

The board-motion timeline (`board_anim.sx`: swap slide → matched-gem clear →
collapse/refill fall) and the match-FX layer (`board_fx.sx`) were first locked by a
set of frame goldens captured off ONE committed move. They use the same `M3TE_FX`
hook as the FX captures above — `M3TE_FX=3` is the seed-1337 vertical red 3-match (a
single round) — each pinned with `M3TE_ANIM_TIME` to a phase of the swap→clear→fall→
settled timeline. Re-captured in P19.2 so each now shows the **organic** motion merged
in P16–P18 (swap overshoot, anticipation-pop clear ripple, gravity-accel fall); the
canonical per-feature organic goldens live in the P16/P17/P18 sections above, and
these are the generic timeline frames at their segment midpoints.

```bash
# Swap segment midpoint — the swapped gems caught PAST target (ease_out_back
# overshoot): goldens/p6_anim_swap.png
env SIMCTL_CHILD_M3TE_FX=3 SIMCTL_CHILD_M3TE_ANIM_TIME=0.08 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
# Clear segment midpoint — matched gems mid pop-ripple, composed with the burst and
# "+30" popup. The SAME committed-move frame backs all three of:
#   goldens/p6_anim_clear.png == goldens/p6_fx.png == goldens/p6_inputlock_board.png
env SIMCTL_CHILD_M3TE_FX=3 SIMCTL_CHILD_M3TE_ANIM_TIME=0.23 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
# Fall segment midpoint — the refilled column caught bunched high under gravity
# accel: goldens/p6_anim_fall.png
env SIMCTL_CHILD_M3TE_FX=3 SIMCTL_CHILD_M3TE_ANIM_TIME=0.41 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
# Settled board past the timeline — FX fully pruned, the move's final board. The
# SAME settled frame backs all three of:
#   goldens/p6_anim_after.png == goldens/p5_swap_after.png == goldens/p6_fx_after.png
env SIMCTL_CHILD_M3TE_FX=3 SIMCTL_CHILD_M3TE_ANIM_TIME=2.0 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
```

`p6_anim_clear` / `p6_fx` / `p6_inputlock_board` are one and the same frame — the
timeline's clear segment, the burst/popup FX, and the input-locked in-flight board
are all the same committed-move moment — as are the three settled `*_after` goldens.

The resting-board goldens — `goldens/p4_board.png`, `goldens/p4_hud.png`,
`goldens/p9_polish.png`, and `goldens/p5_swap_before.png` (the swap's start pose) —
are the seed-1337 board at rest, captured with no move committed:

```bash
# Resting candy board / HUD (no move): p4_board.png, p4_hud.png, p9_polish.png,
# p5_swap_before.png
SIMCTL_CHILD_M3TE_ANIM_TIME=0 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
```

They match `goldens/p6_idle_t0.png` over the board+HUD region (the `t==0` rest
invariant, `tests/gem_pose.sx`); only the status-bar clock and the bottom
home-indicator chrome vary per grab, never the board or HUD.

## Audio bank (P10) — final model

The SFX bank (`audio.sx`) is a purely additive layer over iOS **System Sound
Services** (AudioToolbox, reached by `#foreign` FFI exactly as the platform reaches
UIKit/Metal). Each cue is loaded once at startup into its own `SystemSoundID`;
playback is a single C call. The bank only plays when *every* cue loaded (`loaded`
gate), so a partial/failed bank mutes rather than playing a stale id. It never
reads or mutates score / board / move state — `board_view` and the frame loop just
tell it an event happened.

### Provenance — the user-provided "Triple Treat SFX" pack

The nine shipped cues are best-fit selections from the user-supplied **Triple Treat
SFX** pack (`Triple_Treat_SFX.zip`, ~30 MB, 280 Unity-style files). The pack itself
is **not committed** — only the selected, converted cues live in `assets/audio/`;
the source archive is kept outside the repo (in `~/Downloads`). Full per-cue notes
are in `assets/audio/LICENSE.txt`. The shipped game never re-synthesizes anything;
it only loads the finished WAVs.

| cue          | game event                         | pack source (under `Triple Treat SFX/`) |
|--------------|------------------------------------|------------------------------------------|
| `swap.wav`   | every committed swipe (subtle)     | `Transition SFX/Swipe FX 1-RCM.wav`      |
| `match.wav`  | first clear of a legal move (pop)  | `Pop:Bubble SFX/Pop FX 5-RCM.wav`        |
| `combo1.wav` | cascade round 1 (dullest)          | `Match SFX/Match FX 2-RCM.wav` (~1.7 kHz)|
| `combo2.wav` | cascade round 2                    | `Match SFX/Match FX 4-RCM.wav` (~2.1 kHz)|
| `combo3.wav` | cascade round 3                    | `Match SFX/Match FX 6-RCM.wav` (~3.2 kHz)|
| `combo4.wav` | cascade round 4                    | `Match SFX/Match FX 7-RCM.wav` (~4.7 kHz)|
| `combo5.wav` | cascade round ≥5 (brightest)       | `Match SFX/Match FX 3-RCM.wav` (~6.8 kHz)|
| `win.wav`    | level won (stinger)                | `Success:Power-Up SFX/Power Up FX 1-RCM.wav` |
| `lose.wav`   | level lost (stinger)               | `Fail SFX/Fail FX 2-RCM.wav`             |

The Match-FX set does not cleanly pitch-ascend, so `combo1..5` are ordered by
ascending **spectral brightness** (centroid 1.68 < 2.09 < 3.18 < 4.70 < 6.77 kHz)
so a deeper cascade reads as more exciting.

### Per-round ascending cascade

The cascade plays **one ascending cue per cascade round** — round 1 → `combo1`,
round 2 → `combo2`, … clamped at `combo5` — *not* a single end-of-move sound. Each
cue fires on the move's animation timeline, edge-triggered as that round's clear
begins: the frame loop (`main.sx`) diffs `cascade_rounds_started(elapsed, rounds)`
against `BoardAnim.cascade_fired` and plays the next combo cue per newly-cleared
round (`sfx_cascade`). The depth→index clamp (`cascade_cue_index`: depth ≤ 1 → 0,
depth ≥ 5 → 4) is pure + headless, snapshot-tested by `tests/cascade_cue.sx` and
`tests/cascade_rounds.sx`. A single match (one round) plays only the `match` pop —
no combo cue. The `swap` cue plays for any committed gesture (legal or the reverted
ping-back); a legal move adds the `match` pop on its first clearing round; the
`win`/`lose` stinger fires once, edge-triggered, as the banner comes up.

### Format / level spec

Every cue is delivered in exactly the form System Sound Services loads directly:
**WAVE / mono / 44100 Hz / signed-16-bit PCM**. The pack sources are 24-bit /
48 kHz / stereo; each was down-mixed to mono, trimmed to its punchy window, eased
in with a short fade, rounded out with a cosine fade-out tail, and **peak-normalized
to a gentle −15 dBFS** (the user rejected aggressive SFX twice). The candy character
of the pack is preserved — the cues are not re-synthesized.

### Capturing the cue ordering

Every play is `NSLog`'d, so a playthrough's cue order is readable from the device
log. The deep cascade (`M3TE_FX=11`, depth-5 on seed 1337) must be launched **live**
(no `M3TE_ANIM_TIME` pin) so the timeline advances and the per-round cues fire in
sequence:

```bash
# Deep cascade, live — fires combo1..combo5 one per round on the timeline:
SIMCTL_CHILD_M3TE_FX=11 xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
xcrun simctl spawn booted log show --last 20s \
    --predicate 'eventMessage CONTAINS "[sx] audio"' --style compact
# Win / lose stingers (also live so the banner edge-triggers the cue). Each pinned
# launch passes --terminate-running-process: the M3TE_* pins are read only at
# startup, so relaunching a still-running copy reuses its PID and the new pin is
# ignored — without it the lose launch reuses the win process and only `cue win`
# ever prints. A changed PID between the two launches confirms each pin took:
SIMCTL_CHILD_M3TE_TARGET=0     xcrun simctl launch --terminate-running-process booted co.swipelab.m3te   # cue win
SIMCTL_CHILD_M3TE_MOVE_LIMIT=0 xcrun simctl launch --terminate-running-process booted co.swipelab.m3te   # cue lose
```

## Asset regeneration

The shipped game only loads finished assets; the steps below rebuild them and are
never run at play time. Refresh any affected `goldens/` after an art change.

### Audio (the SFX bank)

The shipped cues are **not synthesized** — each is a real **Triple Treat SFX** pack
clip selected per game event (per-cue source in `assets/audio/LICENSE.txt`). To
re-derive a cue from the pack, take its source file and apply the same DSP the
shipped bank used: down-mix to mono, trim to the punchy onset window (≤ ~600 ms),
ease in with a short fade, round out with a cosine fade-out tail, peak-normalize to
a gentle **−15 dBFS**, then re-wrap to the canonical container with `afconvert`
(`afconvert -f WAVE -d LEI16@44100 -c 1 in.wav out.wav` → WAVE / `LEI16` / 44100 /
mono). The combo ladder is five real **Match FX** cues ordered by ascending spectral
brightness (P10.9, `combo1`→`combo5`); the cascade plays one cue per round on the
animation timeline (P10.10). Verify the result read-only with `tools/measure_pitch.py`
(it never writes a WAV) — it prints each clip's dominant frequency, and `clear.wav`'s
~784 Hz CC0 reference is the documented baseline. The 30 MB pack and its `.meta` /
`__MACOSX` cruft are not committed.

> There is intentionally **no procedural-synthesis regeneration script**: the cues
> are the curated pack clips, so the original P10.1 note-frequency synthesizer
> (`tools/synth_audio.py`) was removed — running it would have clobbered the curated
> WAVs with synthetic audio.

### Image art

Real art is produced with codex's built-in **`imagegen`** tool through `codex exec`,
then `sips`-normalized to each asset's exact dimensions and source format:

| asset                       | dims (px) | format | role                              |
|-----------------------------|-----------|--------|-----------------------------------|
| `assets/board/background.png` | 863×1822  | PNG    | full-view candy gradient backdrop |
| `assets/board/cell.png`       | 128×128   | PNG    | one grid cell tile                |
| `assets/gems/gems.png`        | 768×128   | PNG    | 6 gem columns (a gem's UV column = its index) |
| `assets/fx/particle.png`      | 256×256   | PNG    | soft match-burst sprite (tinted per gem) |

```bash
# 1. Generate (codex's imagegen tool, driven non-interactively):
codex exec "use the imagegen tool to render <prompt for the asset>"
# 2. Normalize to the exact per-asset dims + format, e.g. the gem sheet:
sips -z 128 768 --setProperty format png <generated>.png --out assets/gems/gems.png
```

After any art change, re-capture the affected goldens with the deterministic hooks
above (`M3TE_ANIM_TIME` / `M3TE_SELECT` / `M3TE_FX` / `M3TE_BADSWAP` / `M3TE_TARGET` /
`M3TE_MOVE_LIMIT` / `M3TE_RESTART` / `M3TE_FPS`) and state per golden whether it was refreshed,
left unchanged, or removed.