Motion flavours, and Lift is shadow, rim or auto: auto on a dark page recedes the other panes (InactiveDim)

Motion off|crisp|smooth|bouncy|playful is one parameter set (animation.Motion)
every fx animation reads. One focus spring per pane drives both the lift and
the dim, at the flavour's pace; a grid snaps.

Lift drops glow and surface. A shadow falls on pane bodies and rails only,
capped so text and the selection keep min(contrast, 4.5); rim is a hairline
along the focused tag's top. auto is a shadow on a light page; on a dark page
the core recedes the unfocused panes' text (InactiveDim, ported from 2e4d97f,
default 30 under auto) with the same floor. Tests: focused text contrast is
never below unfocused in any style, dim or theme; the focused pane's cells and
tag are untouched by a dim.

Shared files: src/config.zig, src/builtins.zig, src/ninep/ctl.zig,
src/surface.zig, src/detached/wire.zig, docs/config.md,
test/snapshots/builtins.snap (one more wheel for the longer help).

2 files changed, 63 insertions, 6 deletions

diff --git a/docs/config.md b/docs/config.md
index 16fd59e5..83fbd0eb 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -527,6 +527,21 @@ the chain empty the pass is bypassed. CRT works in linear light with restrained
 scanlines, mask, bloom and vignette, and no curvature, so clicks land where
 they are drawn.
 
+The focused pane can stand off the page (SDL GUI, off by default):
+
+```text
+Lift shadow      a soft drop shadow, on the other panes' bodies only
+Lift rim         a hairline just above the focused tag (light, or shade on a light page)
+Lift auto        a shadow on a light page; on a dark one the others recede
+Lift off
+InactiveDim 30   the unfocused panes' text fades 30% toward its ground
+Motion smooth    off, crisp, smooth, bouncy or playful
+```
+
+`InactiveDim` works everywhere (a grid shows it at once) and never takes a
+pair below its own contrast or 4.5. Under `Lift auto` on a dark page it is 30
+while unset. `Motion` sets how every such effect moves: see docs/effects.md.
+
 `EffectCode PanelAscii` or `EffectCode Crt` lists the current backend's
 build-embedded source paths under `/virtual`. Look opens each full file;
 no checkout is needed, but the build must carry them (`-Dembed-sources=true`,
diff --git a/docs/effects.md b/docs/effects.md
index 44f3e949..fec2d13b 100644
--- a/docs/effects.md
+++ b/docs/effects.md
@@ -1,5 +1,15 @@
 # Effects: feel reviews
 
+**The rule above all the others:** no effect may alter or cover a focus
+indicator (the focused pane's tag colour, its grip, the cursor, the
+selection) or reduce its contrast. The effects are sugar; the indicators are
+how a person knows where they are. Every G stage is reviewed against this.
+Lift, for one, falls only on pane bodies and rails, never on a tag, a grip or
+a header, and its strength is capped so text and the selection keep min(their
+contrast, 4.5) (tests in src/gui/gui.zig). A dim touches only the unfocused
+panes, with the same floor, and the focused pane's text is never at less
+contrast than theirs (tests in src/draw.zig).
+
 Each effect of docs/render-pipeline.md §9 lands behind its own switch, off,
 and is kept only after a feel review (§8.4): a frame series on the virtual
 clock, a recording, and a verdict — keep, polish or drop — with one line of
@@ -9,10 +19,42 @@ why. The verdict is the user's.
 |---|---|---|---|---|
 | Crt (bundled post pass) | `Crt 0..3` | kept, rewritten (no barrel) | fx-compare stills, live window | kept at the user's live look |
 | Ripple, Glitch | — | removed | live window | dropped by the user after a live look |
-| G1 soft elevation shadows | `Lift` (off) | opt-in until the focus-lift default is decided | frame series + mp4 per theme (forge, acme, dusk): Lift on, a focus switch, a run of quick switches, a notice, Lift off | pending |
+| G1 lift | `Lift shadow\|rim\|auto` (off), `InactiveDim <percent>` | opt-in until the focus-lift default is decided | lift-shots-2 (off, shadow, rim, auto on acme, dusk, forge); frame series + mp4 per Motion flavour | shadow on acme: keep as is. Round 1 dropped glow and surface (surface lowered the focused text's contrast) and made rim a hairline just above the focused tag (light on a dark page, shade on a light one). auto on a dark page recedes the others (InactiveDim 30) |
+
+## Motion flavours
+
+`Motion off|crisp|smooth|bouncy|playful` (default smooth) is one parameter set
+(animation.Motion) every fx animation reads, so a flavour is data, not a
+branch in each effect. Input is never blocked, and a new target always
+retargets from the current position and velocity.
+
+| flavour | timing (ω) | follow-through (ζ) | anticipation | squash/stretch | secondary lag | arcs |
+|---|---|---|---|---|---|---|
+| off | instant | — | — | — | — | — |
+| crisp | 44 | 1 (none) | — | — | in step | — |
+| smooth | 26 | 1 (none) | — | — | 0.85 | 0.04 |
+| bouncy | 30 | 0.55 (overshoots ~12%) | — | 0.12 | 0.8 | 0.08 |
+| playful | 24 | 0.42 (overshoots ~23%) | 0.08 of the move | 0.25 | 0.7 | 0.15 |
+
+Which principles each motion uses:
+
+- **Lift** (G1): timing, slow in / slow out (the spring), follow-through
+  (bouncy and playful lift past full and settle back), anticipation (playful
+  dips before it rises; below zero nothing is drawn, so it reads as a beat
+  before the lift), staging (only the focused pane lifts; nothing else moves
+  with a focus change). Squash, stretch, arcs and secondary lag have nothing
+  to act on in a lift.
+- **Cursor** (G3, next): designed around the same set: glide on the spring,
+  stretch along the path, an arc on long jumps, the trailing corners as the
+  secondary action.
+
 
-Notes on G1: the lift runs on a critically damped spring (§7.2) that settles
-in about 240 ms and keeps its velocity when a quick run of switches retargets
-it; a notice floats on a lift of 1 while Lift is on. The series are the core's
-frames: core animation steps at 62.5 Hz on any display (§7.1), so a 144 Hz
-display shows the same frames, each held for two or three refreshes.
+Notes on G1: the lift and the dim run on one focus spring per pane, at the
+Motion flavour's pace, sampled at each frame's own time; while it moves the
+GUI draws at the display's rate, and a grid snaps. A notice floats on a lift
+of 1 while a shadow or rim is on. InactiveDim under `Lift auto` defaults to
+30. The fade is in linear light, so on a dark page it is gentle: at 30
+forge's text goes from 15.5:1 to 11.2:1 and dusk's from 6.4:1 to 4.8:1,
+plainly quieter and still easy reading; at 10 forge barely moves (14.1:1).
+On a light page the same percent bites far harder (acme: 7.0:1 at 10, the
+4.5 floor at 30), which is why `auto` shades there instead of dimming.