Merge branch 'flow/m3te/P16.1' into m3te-plan

README.md

@@ -214,6 +214,32 @@ env SIMCTL_CHILD_M3TE_ANIM_TIME=0 SIMCTL_CHILD_M3TE_SELECT=27 \
 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).
+
 ## Audio bank (P10) — final model
 
 The SFX bank (`audio.sx`) is a purely additive layer over iOS **System Sound

board_view.sx

@@ -415,7 +415,11 @@ BoardView :: struct {
 
         p : f32 = ---;
         if mv.legal {
-            p = ease_out_cubic(t);
+            // Overshoot-and-settle: the two gems shoot a touch PAST their target
+            // cells, then settle exactly onto them, instead of decelerating flatly
+            // into place. ease_out_back pins f(0)=0 and f(1)=1, so t==0 is the rest
+            // pose and t==1 lands byte-on-cell — the swap stays purely visual.
+            p = ease_out_back(t);
         } else if t < 0.5 {
             p = ease_out_cubic(t * 2.0);
         } else {