trykeyline 0.0.0-stage → 0.1.0

package/plugins/keyline/skills/keyline/domains/motion/ladder-and-curves.md

@@ -0,0 +1,139 @@
+# Ladder, curves and springs
+
+The numbers behind the `## Dials` table, the reasoning that sets them, and how to derive a project's ladder from what it already ships.
+
+## Why area, not importance
+
+The eye needs time in proportion to the distance it travels and the area it re-reads: a background colour changing under a 40px button is one fixation, a panel sliding in is a new region to parse, and the whole page changing colour is a re-read of everything.
+
+| Area changing | Role | editorial | product | expressive |
+|---|---|---|---|---|
+| A pressed element's own fill or scale | `duration.instant` | 0 | 0 | 0 |
+| One property, no position | `duration.micro` | 100ms | 80ms | 120ms |
+| One small element | `duration.state` | 150ms | 100ms | 200ms |
+| A small element and its surroundings | `duration.popover` | 200ms | 150ms | 280ms |
+| A large region entering or collapsing | `duration.overlay` | 300ms | 200ms | 450ms |
+| The viewport, on the critical path | `duration.route` | 250ms | — | 400ms |
+| Everything, at once | `duration.theme` | 400ms | 250ms | 600ms |
+
+`duration.route` sits below `duration.overlay` because law 3 caps it: a page transition is latency the user blames on the product. Below ~200ms a full-viewport fade looks like a rendering glitch, so `product` drops it rather than shortening it.
+
+**If unsure which tier, it's `duration.state`**, which does most of the work in every preset. `product` is shortest because its user is fluent and repeats everything; `expressive` is longest on entrances because they are usually seen once.
+
+**Above ~150ms on a hover state**, a fast pointer across a list or a dense table leaves a visible trail. That caps `duration.micro` and `duration.state` for anything hovered in bulk, in any preset, so `expressive` spends its longer `duration.state` on entrances and single controls and keeps list-row hovers at `duration.micro`. Above ~200ms, `editorial`'s `duration.state` makes reading chrome feel heavy.
+
+**A large surface is the opposite case.** A row is a thin strip the pointer crosses; a card on a board is an area the eye rests on, and the same 80ms colour change across it looks instant, not smooth. The area sets the tier here as everywhere, so a card's wash takes about 200ms in and a slower 250ms out: the pointer has already left, the fade blocks nothing, and a sweep across the board fades behind it instead of strobing. Name only `background-color` (and `border-color` if it moves), never `transform` or `box-shadow`: in `product` a card that rises or darkens its shadow under the pointer claims it can be picked up. `expressive` lets primary navigation lift, because there the travel is the invitation.
+
+## Exits
+
+An exit runs at about two-thirds of its entrance, on `ease.exit` (an `ease-in`, accelerating away, so the element reads as leaving rather than deleted), and travels about half the entrance's offset.
+
+| Entrance | editorial exit | product exit | expressive exit |
+|---|---|---|---|
+| A menu or popover | 130ms | 100ms | 180ms |
+| A sheet or panel | 200ms | 130ms | 280ms |
+
+## Curves
+
+| Role | editorial | product | expressive |
+|---|---|---|---|
+| `ease.standard` | `cubic-bezier(0.22, 1, 0.36, 1)` | `cubic-bezier(0.2, 0, 0, 1)` | `cubic-bezier(0.34, 1.2, 0.64, 1)` |
+| `ease.colour` | `ease` | `ease-out` | `ease` |
+| `ease.exit` | `ease-in` | `ease-in` | `ease-in` |
+
+`editorial`'s curve decelerates hard and never leaves [0, 1], so it is legal on every property. `product`'s front-loads even more, so a 100ms transition has visibly arrived by 50ms, and doesn't overshoot either. `expressive`'s end control point above 1 overshoots slightly — physical on a transform, never a bounce — which costs law 5's floor check on every track.
+
+**Where `ease.standard` overshoots, find every track carrying a floored property** — `blur()`, `brightness()`, `saturate()` toward 0, a radius toward 0, a scale that must not invert — and give it a monotone curve. `cubic-bezier(0.16, 1, 0.3, 1)` arrives as decisively without passing its target: the same intent, legal for the property, not a second character. Record it in `DESIGN.md` as a proposed role, `ease.floor`, if needed.
+
+A theme cross-fade is always monotone too: it is the largest change available, and overshoot on colour is a wobble in the light.
+
+### Library equivalents
+
+| | CSS | Motion | GSAP |
+|---|---|---|---|
+| A bezier | `cubic-bezier(a, b, c, d)` | `ease: [a, b, c, d]` | `CustomEase.create("standard", "a,b,c,d")` |
+| `ease-in` | `ease-in` | `"easeIn"` | `"power1.in"` |
+| `ease-out` | `ease-out` | `"easeOut"` | `"power1.out"` |
+
+React Spring is physics-only; use a spring config, or its `easings` with a `duration` for the colour track.
+
+## Springs
+
+Two vocabularies describe the same physics:
+
+- **`bounce` + `duration`** (Motion): `bounce` 0 is critically damped and `duration` is roughly the settle time, so arrival is predictable beside a bezier.
+- **`stiffness` + `damping` + `mass`** (Motion; React Spring's `tension` / `friction` / `mass`): needed when the relationship between two springs is the point, as in squash and stretch.
+
+For intuition rather than conversion, damping ratio ζ = damping ÷ (2 · √(stiffness · mass)), and bounce ≈ 1 − ζ. Tune each spring in one vocabulary.
+
+| Character | Used for | editorial | product | expressive |
+|---|---|---|---|---|
+| `spring.snappy` | A shared element re-targeting; a dragged item released | bounce 0.15, 0.35s · 400 / 34 | bounce 0, 0.25s · 600 / 49 | bounce 0.2, 0.4s · 380 / 31 |
+| `spring.soft` | A panel or card entering | bounce 0.2, 0.45s · 260 / 26 | — (tween) | bounce 0.3, 0.6s · 180 / 19 |
+| `spring.playful` | The one delight beat | bounce 0.3, 0.5s · 300 / 24, once | — | bounce 0.45, 0.7s · 220 / 16 |
+
+Stiffness / damping pairs assume mass 1. `snappy` stays near the floor of "perceptibly springy": a highlight is a thing moving, not arriving, and one that settles at every stop draws attention to itself instead of what it marks. `product` keeps springs to real momentum — a dragged card, a thrown sheet — because a fluent user notices a spring's variable settle time. `editorial`'s one `playful` spring is one delight beat: against restraint, one exuberant interaction reads as craft, three as a template.
+
+```ts
+// Motion
+const snappy = { type: "spring", bounce: 0.15, duration: 0.35 };
+// Opacity always split out as its own short tween (in GSAP, a separate tween beside the move)
+transition={{ ...<spring.snappy>, opacity: { duration: <duration.micro>, ease: <ease.colour> } }}
+// React Spring
+const snappy = { tension: 400, friction: 34 };
+// GSAP has no spring solver; to re-target use gsap.quickTo(el, "x", { duration: 0.35, ease: "power3.out" }),
+// which re-targets smoothly from the current value.
+// CSS: linear() can sample a spring's curve but can't re-target mid-flight — entrances only.
+```
+
+### Tuning by symptom
+
+Change one control at a time.
+
+| Symptom | Fix |
+|---|---|
+| Floaty, slow to commit | ↑ stiffness, or ↓ duration |
+| Wobbles too many times | ↑ damping, or ↓ bounce |
+| Snaps, feels mechanical | ↓ damping slightly |
+| Slow to start moving | ↓ mass |
+| Too eager, no weight | ↑ mass |
+| Flickers at the end of a fade | opacity is still on the spring — split it out |
+| Takes over a second across a long distance | raise stiffness with distance, or use a tween |
+
+### Squash and stretch
+
+A light, underdamped spring on the grow axis (high stiffness, low damping, mass below 1) and a stiffer, heavily damped one on the cross axis: through the overshoot the element is briefly taller and narrower, then settles — the animation principle from physics, interruptible for free, with deformation reading as mass. Travel on the grow axis rides the same spring as its scale, or the anchored edge detaches from the trigger mid-flight. In the Glass preset the pair is 620 / 19 / 0.85 against 380 / 30. `editorial` may spend this once; `product` never; `expressive` may use it on menus throughout.
+
+## Emitting tokens
+
+A fictional project, *Ledgerline* — bookkeeping software on `product`, with `app/(site)/**` on `expressive`. The app's tokens, in its existing `--motion-*` style:
+
+```css
+:root {
+  --motion-micro: 80ms;     /* duration.micro   — row opacity on hover */
+  --motion-state: 100ms;    /* duration.state   — cell colour, icon swaps */
+  --motion-popover: 150ms;  /* duration.popover — menus, date picker */
+  --motion-overlay: 200ms;  /* duration.overlay — inspector panel, sheets */
+  --motion-theme: 250ms;    /* duration.theme */
+  --motion-exit: 100ms;     /* duration.exit    — ease-in, flat */
+  --motion-ease: cubic-bezier(0.2, 0, 0, 1);  /* ease.standard */
+  --motion-ease-colour: ease-out;              /* ease.colour */
+  --motion-travel: 12px;    /* a sheet's slide as it fades in */
+}
+@media (prefers-reduced-motion: reduce) {
+  :root { --motion-travel: 0px; }  /* still fades, no longer slides */
+}
+```
+
+In Tailwind v4, `--ease-*` in `@theme` generates `ease-*` utilities; durations have no theme namespace, so use `duration-(--motion-state)`. A v3 config extends `transitionDuration` and `transitionTimingFunction`; a JS theme object carries `motion.duration.state` and `motion.spring.snappy` beside its colours.
+
+## Deriving a project's ladder from its code
+
+A worked case: a codebase with 31 distinct durations.
+
+1. **Cluster by value and by what moves.** 150ms, 160ms and 175ms are all hover colours: one tier. 300ms and 350ms are both drawers: one tier. A lone 1200ms is a toast's auto-dismiss, a timer rather than motion, so out of scope.
+2. **Name each cluster's role** by the area it changes, not its name in code: a `--slow` token on every tooltip is `duration.popover`.
+3. **Compare with the preset.** A consistent cluster within ~20ms of the dial keeps its value, recorded, because users already know its rhythm; a scattered one snaps to the dial.
+4. **Check the ordering.** Tooltips (popover) that outrun drawers (overlay) put the ladder upside down: an open issue whatever the numbers.
+5. **Class what's left** under law 4 or list it as a stray; nothing remains unclassed. One component can hold both: in a Glass preset gallery, a photograph dissolving to the next is the subject, but the same photograph moving between layouts is state, in the overlay tier.
+6. **Write it to `DESIGN.md`** with the counts: *"`duration.state` → `--dur-fast` 150ms; 42 uses; 9 strays at 160–180ms snapped."*

package/plugins/keyline/skills/keyline/domains/motion/patterns.md

@@ -0,0 +1,196 @@
+# Patterns
+
+Code uses role placeholders (`<duration.state>`) and generic custom properties; swap in the names `DESIGN.md` maps them to.
+
+## The shared highlight
+
+One highlight per group, animating its position and size to whichever item is hovered or focused. It never remounts.
+
+```tsx
+// Motion. The same shape works with GSAP quickTo or React Spring's useSpring.
+const [hover, setHover] = useState<{ x: number; y: number; w: number; h: number } | null>(null);
+const enter = (el: HTMLElement) =>
+  setHover({ x: el.offsetLeft, y: el.offsetTop, w: el.offsetWidth, h: el.offsetHeight });
+
+<ul className="group-shell" onPointerLeave={() => setHover(null)}>  {/* position: relative; isolation: isolate */}
+  <m.div
+    aria-hidden
+    className="highlight"                                       /* absolute; z-index: -1; pointer-events: none */
+    initial={false}
+    animate={hover ? { x: hover.x, y: hover.y, width: hover.w, height: hover.h, opacity: 1 } : { opacity: 0 }}
+    transition={reduce ? { duration: <duration.state> } : { ...<spring.snappy>, opacity: { duration: <duration.micro> } }}
+  />
+  {items.map((it) => (
+    <a key={it.id} onPointerEnter={(e) => enter(e.currentTarget)} onFocus={(e) => enter(e.currentTarget)} … />
+  ))}
+</ul>
+```
+
+Six details, each a bug without it:
+
+- **`initial={false}`** (outside Motion, set the first position with no transition), or the highlight flies in from the corner on first paint.
+- **Offsets, not `getBoundingClientRect()`.** `offsetLeft` / `offsetTop` are relative to the positioned parent the highlight lives in; viewport rectangles need subtraction and break if the page scrolls between measure and render.
+- **`isolation: isolate` on the group, `z-index: -1` on the highlight**: behind the items but inside the group's stacking context, so it can't drop behind the group's own surface.
+- **`pointer-events: none`**: the highlight sits under the pointer by definition, and would otherwise steal the enter event and oscillate.
+- **Focus alongside hover**, so keyboard users get the same feedback.
+- **Leave on the group, not the items**: per-item leave fires in the gaps and blanks the highlight between items.
+
+A tooltip rides the same state on one axis: an outer element animates `x` to the item's centre; an inner one is statically `translate: -50% 0`. A plain coordinate animates cleanly; `calc(centre - 50%)` asks the library to interpolate mixed units.
+
+**Current versus hovered.** The current item's static surface drops while the group is hovered, so the travelling highlight owns the surface; two at once make the selection ambiguous. The current item keeps its label colour (colour law 7) throughout, so its place is never lost.
+
+## Layout switches and page-level shared elements
+
+For an element that persists across a DOM change — a card becoming a detail view, a thumbnail becoming the open image:
+
+```css
+/* CSS View Transitions — same-document via document.startViewTransition(update),
+   cross-document via @view-transition { navigation: auto; } */
+.card-image { view-transition-name: var(--vt-name); }  /* unique per element, e.g. set inline per card */
+::view-transition-group(*) { animation-duration: <duration.overlay>; animation-timing-function: <ease.standard>; }
+@media (prefers-reduced-motion: reduce) {
+  ::view-transition-group(*), ::view-transition-old(*), ::view-transition-new(*) { animation: none; }
+}
+```
+
+- **Motion:** give both ends the same `layoutId`; the library measures and travels between them.
+- **GSAP:** `const state = Flip.getState(els); /* change the DOM */ Flip.from(state, { duration, ease });`
+
+Whichever tool, **measure the reading position while the outgoing layout is still rendered** — the item nearest the viewport's centre — and open the incoming layout on it. Where the ends differ in aspect ratio, cross-fade two elements, each at its own aspect and sharing a centre, rather than stretching one into the other's box.
+
+## Presence: open and close
+
+```css
+/* CSS only: a popover or dialog entering from display: none */
+.menu {
+  transition: opacity <duration.popover> <ease.colour>, translate <duration.popover> <ease.standard>,
+              display <duration.popover> allow-discrete, overlay <duration.popover> allow-discrete;
+  opacity: 1; translate: 0 0;
+}
+@starting-style { .menu:popover-open { opacity: 0; translate: 0 calc(var(--motion-travel) * -1); } }
+.menu:not(:popover-open) {
+  opacity: 0; translate: 0 calc(var(--motion-travel) * -0.5);   /* the exit travels half as far */
+  transition-duration: var(--motion-exit); transition-timing-function: <ease.exit>;
+}
+```
+
+```tsx
+// Motion: AnimatePresence keeps the element mounted for its exit.
+<AnimatePresence>
+  {open && (
+    <m.div
+      initial={reduce ? { opacity: 0 } : { opacity: 0, scale: 0.96, y: -4 }}
+      animate={{ opacity: 1, scale: 1, y: 0, transition: reduce ? { duration: <duration.state> } : <spring.soft> }}
+      exit={{ opacity: 0, ...(reduce ? {} : { scale: 0.98, y: -2 }), transition: { duration: <exit>, ease: <ease.exit> } }}
+    />
+  )}
+</AnimatePresence>
+```
+
+Scale from the edge the element is anchored to (`transform-origin` at the trigger): a menu growing from its own middle seems to come from nowhere. The wrapper moves; a child carries the translucent material.
+
+## Fill means chosen, in code
+
+The filled state is a second layer over the outline, at the same coordinates, cross-fading in place:
+
+```css
+.icon .fill   { opacity: 0; transition: opacity <duration.popover> <ease.colour>; }
+.icon .detail { opacity: 1; transition: opacity <duration.popover> <ease.colour>; }  /* interior lines a solid shape swallows */
+.is-current .icon .fill,   .item:hover .icon .fill   { opacity: 1; }
+.is-current .icon .detail, .item:hover .icon .detail { opacity: 0; }
+@media (prefers-reduced-motion: reduce) { .icon .fill, .icon .detail { transition: none; } }
+```
+
+Where the solid shape would swallow an interior line, knock it out with a mask rather than deleting it: the silhouette in white (fill and stroke, matching the outline exactly), the interior lines in black at the outline's stroke width. A solid chip chosen instead of fill follows the same rule: one treatment, one meaning.
+
+## Hover intent
+
+```ts
+const closeSoon = () => {
+  clearTimeout(timer.current);
+  timer.current = window.setTimeout(() => setOpen(false), 100);
+};
+const cancelClose = () => clearTimeout(timer.current);
+useEffect(() => () => clearTimeout(timer.current), []);   // unmount
+useEffect(() => setOpen(false), [pathname]);              // navigation
+```
+
+Bind `closeSoon` to leaving the trigger *and* the panel, `cancelClose` to entering either. Any `setTimeout` driving UI state is cleared on unmount and reset on navigation, or a menu opened on one page reappears 100ms into the next. Where they're adjacent, a hover bridge is cheaper: padding on the wrapper spanning the visual gap, so the pointer never leaves the hover region.
+
+## Hover on a card
+
+A wash, with the leave on the resting rule and the arrival on the hovered one, so each direction takes its own time:
+
+```css
+.card       { transition: background-color <hover out> <ease.colour>; }   /* the leave */
+.card:hover { background-color: var(--surface-hover); transition-duration: <hover in>; }
+```
+
+No `translate`, no shadow change, one named property; the bundle stays where the depth guide put it. Rows keep `duration.micro` both ways.
+
+## Press
+
+`transform: scale(<press>)` on `:active`, `transition-duration: 0` in and `duration.state` back out, on `pointerdown`, not `click`. In `product`, prefer the `surface.pressed` step: a toolbar of twenty shrinking buttons is noise. Anything wider than about 200px presses with `scale(0.98)` or a 1px `translate` instead: at 0.92–0.95 a full-width button loses about 15px and reads as collapsing, not pressed.
+
+## Live indicators
+
+An indicator that reports a live state — level bars while recording, a stroke travelling round a card while something is generated — moves only while the state does, and turns into its action on demand.
+
+```css
+.live .bars span  { animation: level 900ms <ease.standard> infinite alternate; }
+.live[data-paused] .bars span { animation: none; transform: scaleY(0.25); }   /* settle low, don't freeze mid-peak */
+.live .stop, .live .bars { transition: opacity <duration.state> <ease.colour>; }
+.live .stop { opacity: 0; }
+.live:is(:hover, :focus-visible) .stop  { opacity: 1; }
+.live:is(:hover, :focus-visible) .bars  { opacity: 0; }
+@media (prefers-reduced-motion: reduce) { .live .bars span { animation: none; } }
+```
+
+- **Paused settles, it doesn't freeze.** A loop stopped mid-cycle leaves a peak that looks like a glitch; hold a low resting frame, or stop a travelling stroke and dim its glow. Bars driven by a real input level fall on their own; a decorative loop has to be told.
+- **The morph is in place.** Bars and stop square share one box and cross-fade, so the control never moves under the pointer.
+- **The name is the action throughout** — a button named "Stop recording" — because on touch nothing hovers and the tap is the stop.
+
+## Theme cross-fade
+
+A universal colour transition left in the stylesheet makes every hover on the site `duration.theme` and sluggish. Apply it only for the toggle:
+
+```ts
+root.classList.add("theme-transition");
+applyTheme(choice);
+setTimeout(() => root.classList.remove("theme-transition"), THEME_MS + 40);
+```
+
+```css
+@media (prefers-reduced-motion: no-preference) {
+  :root.theme-transition, :root.theme-transition *, :root.theme-transition *::before, :root.theme-transition *::after {
+    transition: background-color <duration.theme> <ease.colour>, color <duration.theme> <ease.colour>,
+                border-color <duration.theme> <ease.colour>, fill <duration.theme> <ease.colour>,
+                stroke <duration.theme> <ease.colour> !important;
+  }
+}
+```
+
+The `!important` beats each component's own transition for that window; removing the class stops it poisoning everything after. Pseudo-elements are listed because `*` doesn't match them, and decoration built with them would snap. The curve is `ease.colour`, never one that overshoots: an overshooting colour passes its target and returns. `duration.theme` runs only under this class, when the page itself switches.
+
+A theme that follows the OS by media query changes with no toggle to hook, and every control carrying its own colour transition fades at its own duration while the page around it snaps. So everyday colour transitions never include the page background, and a theme change suspends them: listen for the query's `change` and hold a class for one frame.
+
+```ts
+matchMedia("(prefers-color-scheme: dark)").addEventListener("change", (e) => {
+  if (readChoice() !== "system") return;   // the reader chose a theme: the OS doesn't override it
+  root.classList.add("theme-instant");   /* :root.theme-instant * { transition: none !important; } */
+  applyTheme(e.matches ? "dark" : "light");
+  requestAnimationFrame(() => requestAnimationFrame(() => root.classList.remove("theme-instant")));
+});
+```
+
+The theme mechanism and flash-free first paint belong to the colour guide.
+
+## Sound, if the preset allows it
+
+Sound is off wherever the user didn't choose to be there. Where it exists, synthesise it with Web Audio rather than shipping files — no request, no decode latency, so it lands with the input — and, non-negotiably:
+
+- **Arm the context on every activation gesture:** `pointerdown`, `keydown` and `touchstart`. Hover is activation in no engine, and a keyboard Enter dispatches `click`, not `pointerdown`, so a pointer-only unlock leaves keyboard users in silence for ever. `wheel` activates nothing; leave it out.
+- **Hover sounds for `pointerType === "mouse"` only**, deduplicated per element: a touch tap fires `pointerover` just before `click`, and plays both.
+- **Dense surfaces opt out of hover sound** with an attribute on the container; above about three ticks a second it stops being feedback.
+- **A visible, persisted mute**, checked at the top of playback rather than at the listener, so it applies to in-flight input; storage access wrapped so it can't throw.
+- **Two sounds is a texture; five is a soundtrack.** Press and, at most, hover.

package/plugins/keyline/skills/keyline/domains/motion/performance.md

@@ -0,0 +1,121 @@
+# Performance
+
+## The one scroll shape
+
+Every scroll-driven behaviour uses one structure. At its smallest, with `update` clearing the flag:
+
+```ts
+let ticking = false;
+const onScroll = () => { if (!ticking) { ticking = true; requestAnimationFrame(update); } };
+window.addEventListener("scroll", onScroll, { passive: true });
+```
+
+In full, with teardown:
+
+```ts
+function onScrollFrame(update: () => void): () => void {
+  let ticking = false;
+  const run = () => { ticking = false; update(); };
+  const onScroll = () => { if (!ticking) { ticking = true; requestAnimationFrame(run); } };
+  update();                                                   // correct on a page loaded already scrolled
+  window.addEventListener("scroll", onScroll, { passive: true });
+  window.addEventListener("resize", onScroll);                // a resize invalidates the same measurements
+  return () => {
+    window.removeEventListener("scroll", onScroll);
+    window.removeEventListener("resize", onScroll);
+  };
+}
+```
+
+- **`passive: true`**, as the handler never calls `preventDefault()`; without it every scroll event blocks on your JavaScript, the commonest cause of scroll jank.
+- **The `ticking` flag** makes a burst of events (a high-resolution trackpad fires many per frame) one measurement per painted frame.
+- **No `throttle` or `debounce`.** A time-based throttle is faster than the frame rate, wasting work, or slower, dropping frames.
+- **One listener per behaviour**, torn down on unmount. In a component, make the effect's dependency a value, not a fresh array — `ids.join("|")` — or the listener rebuilds every render.
+
+A purely visual effect can use CSS scroll-driven animations (`animation-timeline: scroll()` or `view()`), off the main thread with no listener, behind `@supports (animation-timeline: scroll())` with a static fallback and inside `prefers-reduced-motion: no-preference`.
+
+## Hysteresis
+
+Anything toggled by scroll *direction* needs a dead zone, or a pixel of jitter — trackpad noise, a rubber-band bounce, your own layout change — flips it for ever.
+
+```ts
+const update = () => {
+  const y = window.scrollY;
+  const atBottom = y + window.innerHeight >= document.documentElement.scrollHeight - 2;
+  if (y < 24 || atBottom) setCollapsed(false);   // always expanded at either end — checked first
+  else if (y > last + 6) setCollapsed(true);     // 6px of downward intent
+  else if (y < last - 6) setCollapsed(false);    // 6px of upward intent
+  last = y;
+};
+```
+
+The end zones come first, or a small upward scroll near the foot leaves a collapsed bar over the footer. The `- 2` absorbs sub-pixel rounding on fractional device pixel ratios.
+
+## Never hide an affordance where it can't come back
+
+Gate the effect before attaching anything — layout law 8, with the code in `domains/layout/forks-gating-and-disclosures.md`.
+
+## Scroll spies
+
+Tracking the section being read, for a contents rail:
+
+```ts
+const READING_LINE = 120;   // px below the viewport top
+const update = () => {
+  let current = ids[0];
+  for (const id of ids) {
+    const el = document.getElementById(id);
+    if (!el) continue;
+    if (el.getBoundingClientRect().top > READING_LINE) break;   // document order: stop at the first not yet passed
+    current = id;
+  }
+  if (window.scrollY + window.innerHeight >= document.documentElement.scrollHeight - 2) current = ids.at(-1)!;
+  setActive((prev) => (prev === current ? prev : current));
+};
+```
+
+- **A reading line, not an `IntersectionObserver`**, because several sections are visible at once and the question is *which heading did I last pass?*
+- **The bottom clamp.** A short final section never crosses the line before the page ends, so the rail would mark the one before it.
+- **Match `scroll-margin-top` to the line**, a little smaller, within ~10px. A contents link that scrolls its heading to y = 0 puts it above the line, and the rail highlights the previous section.
+- **`history.replaceState` for the hash**, not router navigation, which runs the app's own scroll handling and cuts the smooth scroll short.
+
+## What to animate
+
+`width`, `height`, `top`, `left`, `margin` and `padding` lay out on every frame, for the element and possibly its siblings; `transform` and `opacity` don't.
+
+**Name every property.** `transition: all` picks up properties you never intended, including layout ones a parent adds later. The explicit list — `transition: color, background-color, translate` — also makes a hover's *leave* predictable: exactly the listed properties transition out.
+
+**A justified exception** looks like the shared highlight: one absolutely positioned, `pointer-events: none` element outside the flow, whose size change reflows nothing. If you can't say that about an element, scale it instead.
+
+**Animating to auto** without measuring:
+
+```css
+.region { display: grid; grid-template-rows: 0fr; transition: grid-template-rows <duration.overlay> <ease.standard>; }
+.region[data-open] { grid-template-rows: 1fr; }
+.region > * { min-height: 0; overflow: hidden; }
+```
+
+The same works on columns with `min-width: 0`. Where supported, `interpolate-size: allow-keywords` lets `height: auto` transition directly.
+
+**Transforms and `backdrop-filter`.** A transform on an ancestor creates a new containing block and weakens or breaks the blur beneath it, so the moving wrapper and the translucent surface are different elements; the depth guide covers how much the tint carries while it animates.
+
+**`will-change`** only on an element about to animate, removed after; left on everything, it pins memory for layers that never move.
+
+## Escalating to the GPU
+
+Some shared-element trips can't be done in the DOM: the ends differ in aspect ratio, so one image distorts all the way, or the view is too large to re-lay-out per frame. Then draw one element on a canvas above the view and animate four numbers — a rectangle — in a uniform.
+
+- **One decorative element, never the view.** A hundred tiles as textures costs hundreds of megabytes, and the tiles carry keyboard and screen-reader semantics a canvas can't. The drawn element has none of its own (`alt=""`, labels elsewhere).
+- **Setup returns `null`, never throws.** Inside an effect, an exception takes the view down instead of falling back. Check for the artefact that proves setup completed — a linked program — rather than trusting the constructor.
+- **`null` is the ordinary path:** the caller keeps its `<img>`, which also serves reduced motion, no WebGL, and a context lost later.
+- **Mipmaps, trilinear filtering**, or a large image drawn small shimmers as it moves sub-pixel.
+- **Soften the last pixel of the edge**, or a rectangle on fractional pixels crawls column by column. Fade alpha only, on a non-premultiplied context.
+- **Don't force-lose the context on teardown.** Frameworks reuse the canvas node across remounts, and a force-lost context silently poisons it.
+
+## Keeping the motion code small
+
+- **Motion:** `LazyMotion` with `domAnimation` and the `m` component; `strict` makes a stray full `motion.*` import a build error. Scope a `domMax` island to the one component that needs layout animations.
+- **GSAP:** register only the plugins in use; import `Flip` or `ScrollTrigger` where they're used, not in a global setup file.
+- **React Spring:** import from `@react-spring/web` only.
+- **CSS first.** A hover, a colour change, a reveal and most presence animations need no library; reach for one when something re-targets, is dragged, or must exit after unmounting.
+