trykeyline 0.0.0-stage → 0.1.1

package/plugins/keyline/skills/keyline/glass/motion/easing-and-duration.md

@@ -0,0 +1,108 @@
+# Easing and duration
+
+The glass ladder in code, and the reasons behind its values. Why duration tracks area, and why a hover over ~150ms lags across a list, are in `domains/motion/ladder-and-curves.md`; the tiers themselves are in §1 of `glass/motion/guide.md`.
+
+## The 100ms tier
+
+```tsx
+className="transition-opacity duration-100 ease-out hover:opacity-60"
+```
+
+Text links fade to 60% opacity in 100ms with `ease-out`, not the house curve: opacity clamps at 1, so the overshoot is a wasted tail (law 5). 100ms is at the edge of perceptible, which is the point: a hover response should feel like it *already happened*.
+
+## The 150ms tier does most of the work
+
+Colour, background, small transforms, icon swaps, the marker that grows in a table of contents:
+
+```tsx
+"transition-colors duration-150 ease-geist"
+"transition-[width,background-color] duration-150 ease-geist"
+"transition-[color,background-color,box-shadow,transform] duration-150 ease-geist"
+```
+
+Every property enumerated, never `transition-all` (law 13).
+
+## Where 200ms is right
+
+The gap between 150 and 200 maps to *whether other things move too*:
+
+- A chevron rotating 180° in a disclosure: the rotation is small, but the panel opening below it isn't.
+- A hover card scaling in: a new object with content, appearing over existing content.
+- The menu glyph's two bars rotating into a cross: two elements moving in opposition read as one compound gesture.
+- A hover wash across a whole card or panel: the 100ms that suits a link reads as a cut over that much area, and a pointer settles on a card rather than sweeping a column of them.
+
+## Why route transitions are 260ms
+
+```css
+.route-fade { animation: routeFade 260ms var(--ease-geist) both; }
+@keyframes routeFade { from { opacity: 0 } to { opacity: 1 } }
+```
+
+260ms is the shortest crossfade that still reads as intentional; below ~200ms a full-viewport opacity change looks like a rendering artefact (law 3 caps it). Opacity only, because a directional transition implies a spatial relationship between routes, and the site map (home, experience, writing, playground) is flat.
+
+Keying the wrapper on the pathname replays the CSS animation on every navigation:
+
+```tsx
+<div key={pathname} className="route-fade">
+```
+
+`both` on the fill mode holds the `from` state before the animation starts, preventing a one-frame flash of fully opaque content.
+
+## Why the theme crossfade breaks both rules
+
+```css
+@media (prefers-reduced-motion: no-preference) {
+  :root.theme-transition,
+  :root.theme-transition *,
+  :root.theme-transition *::before,
+  :root.theme-transition *::after {
+    transition: background-color 400ms ease, color 400ms ease, border-color 400ms ease,
+      fill 400ms ease, stroke 400ms ease, box-shadow 400ms ease !important;
+  }
+}
+```
+
+**400ms, longest on the ladder**: every surface, text colour, border, icon fill and shadow at once. At 150ms it reads as a jarring flash; at 400ms, as the lights coming up. **Plain `ease`, not the house curve**, because colour has no mass (law 5).
+
+The class is applied only on an explicit toggle, then removed:
+
+```ts
+export function setThemeChoice(choice: ThemeChoice): void {
+  try { localStorage.setItem(KEY, choice); } catch { /* won't persist */ }
+  const root = document.documentElement;
+  root.classList.add("theme-transition");
+  applyTheme(choice);
+  window.setTimeout(() => root.classList.remove("theme-transition"), 440);
+}
+```
+
+It exists for ~440ms, the duration plus a 40ms margin, and its `!important` beats every component's own `transition-colors duration-150` for that window. Why it's scoped this way is in `domains/motion/patterns.md`, theme cross-fade.
+
+## The overshoot in the house curve
+
+```
+cubic-bezier(0.175, 0.885, 0.32, 1.1)
+```
+
+The `1.1` in the final control point takes the value past its target near the end and back: a small (~10%), brief overshoot. That number makes 150ms colour transitions feel like something *happened* rather than was *set*. Character beyond it belongs to springs (law 5).
+
+## The filter curve
+
+The class of properties the house curve can't have, and why, is law 5. Glass's monotone curve:
+
+```ts
+// Lines staggering in behind a blur: filter: blur(4px) → blur(0px).
+// --ease-geist would pass through a NEGATIVE radius to settle back.
+const EASE = [0.16, 1, 0.3, 1] as const;   // expo-out: decelerates hard, never exceeds 1
+```
+
+## Durations that legitimately sit off the ladder
+
+The pair that shows the discipline, from one gallery component (§1 of `glass/motion/guide.md`):
+
+```ts
+const DISSOLVE = 0.62;  // stepping between photographs — the subject
+const FLIGHT   = 0.42;  // the same photo moving between layouts — a state change
+```
+
+The dissolve is the content being watched, so it gets 620ms to read as a dissolve rather than a cut; the flight only has to be *followable*, with the photograph on screen at both ends, so it stays inside the overlay tier. The greeting's gating is §14 of the guide.

package/plugins/keyline/skills/keyline/glass/motion/guide.md

@@ -0,0 +1,255 @@
+# Glass motion
+
+> **Glass preset.** The motion system running on [modimihir.com](https://modimihir.com), with its real values, meant to be copied whole. Read it beside `domains/motion/guide.md`: the laws live there, and this guide holds only what glass sets — its durations, curve, springs and tokens, its recipes and code, and the decisions behind them. Under any other preset it is only a worked example.
+
+State is CSS transitions; springs and presence use [Motion](https://motion.dev). "Law" below means a motion law in the domain guide.
+
+## 1. The duration ladder
+
+Tiers by area, not importance (law 2):
+
+| Tier | Duration | What moves | Easing |
+|---|---|---|---|
+| Instant | 0ms | Press feedback, focus rings | none |
+| Micro | 100ms | Link opacity on hover | `ease-out` |
+| State | **150ms** | Colour, background, small transforms, icon swaps | the house curve |
+| Popover | **200ms** | A disclosure chevron, a hover card, a menu glyph | the house curve |
+| Overlay | **300ms** | Reveal-on-scroll, a collapsing region | the house curve |
+| Route | 260ms | An incoming page fading in | the house curve |
+| Theme | 400ms | Every colour on the page at once | plain `ease` |
+
+Three numbers carry almost everything: **150 / 200 / 300**. **Route is 260ms**, not 300: 260 is the shortest crossfade on the critical path that doesn't read as a flicker. **Theme is 400ms with plain `ease`**, the largest change on the longest duration, and colour gets no overshoot. Nothing on the ladder exceeds 400ms.
+
+**Hover takes its tier by area:** a link's opacity 100ms, a wash across a whole card 200ms.
+
+### Two things that sit off the ladder
+
+Glass uses two of law 4's classes:
+
+**The subject of the moment.** Stepping between gallery photographs dissolves over **620ms**: the photograph *is* the content, and a noise-thresholded dissolve needs time to read as a dissolve rather than a cut. The same photo's flight between two layouts stays at 420ms, in the overlay tier, because that *is* a state change with the photo on screen at both ends. **Same component, two durations, decided by whether the motion is the subject or the report.**
+
+**A once-a-session set piece.** The opening screen runs 560ms in, holds 1400ms, about 2.5 seconds in all, defensible only because it plays once per tab (§14).
+
+## 2. One easing curve
+
+```css
+--ease-geist: cubic-bezier(0.175, 0.885, 0.32, 1.1);
+```
+
+One curve for the whole site. The `1.1` end control point overshoots slightly and settles back, physical but not bouncy. The exceptions:
+
+- **100ms opacity hovers and icon fills** (§13): `ease-out`. Opacity entrances (`.reveal`, the route fade) keep the house curve on purpose: on opacity the overshoot clamps at 1.
+- **The theme crossfade**: plain `ease`.
+- **Anything spring-driven**: no bezier at all.
+- **Any track that also drives a filter**, or any property floored at zero (law 5): expo-out, `cubic-bezier(0.16, 1, 0.3, 1)`, which never exceeds 1. It is the same intent in a curve legal for the property, not a second character.
+
+→ The tiers in code, the theme crossfade, and the overshoot: `glass/motion/easing-and-duration.md`
+
+## 3. Springs, tuned by character
+
+Three springs, each with a job (law 6), plus the close:
+
+```ts
+// Highlight or tooltip re-targeting: moving, not arriving — almost no bounce.
+const SLIDE = { type: "spring", bounce: 0.2, duration: 0.4,
+                opacity: { duration: 0.16, ease: "easeOut" } } as const;
+
+// Cards rising out of a folder. Playful on purpose — the only place that is.
+const LIFT = { type: "spring", bounce: 0.28, duration: 0.5 } as const;
+
+// Opening a menu: two springs that DISAGREE (§4).
+const GROW  = { type: "spring", stiffness: 620, damping: 19, mass: 0.85 } as const;
+const CROSS = { type: "spring", stiffness: 380, damping: 30 } as const;
+
+// Closing: flat and quick.
+const CLOSE = { duration: 0.13, ease: "easeIn" } as const;
+```
+
+Opacity is split out of every spring, as `SLIDE` does (law 6).
+
+→ How these numbers were arrived at: `glass/motion/springs.md`
+
+## 4. Squash and stretch, out of physics
+
+The best motion detail in the system, in four lines of config. A menu scales open from its anchored edge: `GROW` is light and underdamped, and sails past its final size; `CROSS` is heavily damped and arrives late. Through the overshoot the panel is briefly **taller and narrower** than it ends up.
+
+```tsx
+transition={{
+  scaleY: GROW,   // the grow axis overshoots
+  y:      GROW,   // travel rides the same spring, so they stay locked
+  scaleX: CROSS,  // the cross axis lags
+  opacity: { duration: 0.14, ease: "easeOut" },
+}}
+```
+
+→ The principle: `domains/motion/ladder-and-curves.md`, squash and stretch. The component: `glass/motion/assets/DropMenu.tsx`
+
+## 5. Asymmetric open and close
+
+| Direction | Character | Duration |
+|---|---|---|
+| Open | spring, overshoots | ~400ms effective |
+| Close | tween, `easeIn`, flat | 130ms |
+
+Why exits get out of the way is law 7. The exit offsets are smaller too: open starts from `scaleY: 0.82, scaleX: 0.94`, exit only goes to `scaleY: 0.9, scaleX: 0.97`.
+
+## 6. Shared elements
+
+In the dock and in lists, **one** highlight and **one** tooltip animate their `x / y / width / height` to whichever item is hovered (law 8):
+
+```tsx
+// One element. It re-targets. It does not remount.
+<m.div
+  aria-hidden
+  className="pointer-events-none absolute left-0 top-0 -z-10 rounded-[12px] bg-highlight"
+  initial={false}
+  animate={hovered
+    ? { x: hovered.x, y: hovered.y, width: hovered.w, height: hovered.h, opacity: 1 }
+    : { opacity: 0 }}
+  transition={SLIDE}
+/>
+```
+
+The details that keep it from flickering are in `domains/motion/patterns.md`, the shared highlight; in Tailwind they are `isolate` on the container and `-z-10` on the highlight.
+
+→ The tooltip and vertical-list variants, and the active state: `glass/motion/shared-element.md`
+
+### When the DOM element isn't enough
+
+A *photograph* travelling between layouts escalates to the GPU (law 13), opening on the tile nearest the viewport centre (law 8): `glass/motion/shared-element.md`, escalating to the GPU
+
+## 7. Reduced motion
+
+Every animated component takes its own branch (law 10):
+
+```tsx
+const reduce = useReducedMotion();
+const tween = reduce ? { duration: 0.15 } : SLIDE;
+```
+
+The glass substitutes: a spring slide becomes a 150ms tween; the squash-and-stretch open becomes a plain fade.
+
+```tsx
+// No elastic scaling, but you still see it appear.
+initial={reduce ? { opacity: 0 } : { opacity: 0, scaleY: 0.82, scaleX: 0.94, y: 4 }}
+```
+
+Imperative APIs get the preference passed in: `scrollIntoView({ behavior: reduce ? "auto" : "smooth" })`. Reduced transparency and high contrast are §8 of `glass/depth/guide.md`.
+
+→ Every glass substitute: `glass/motion/reduced-motion.md`
+
+## 8. Scroll
+
+One passive listener and one rAF per behaviour (law 12; the shape is in `domains/motion/performance.md`).
+
+**The dock's dead zone** is 6px of intent either way, and it is always open within 24px of the top or at the bottom. **It collapses only where `(hover: hover) and (pointer: fine)` matches**, so a hover can reopen it.
+
+→ Scroll spy, `scroll-mt` alignment, the grid collapse: `glass/motion/scroll-performance.md`
+
+## 9. Reveal on scroll
+
+300ms on the house curve, 8px of travel, `threshold: 0`, `rootMargin: "0px 0px -40px 0px"`, marked by `data-in`; the guards are law 11, whose two bugs are this site's. → `glass/motion/assets/motion-tokens.css`, `glass/motion/assets/useReveal.ts`
+
+## 10. Performance: `m` not `motion`
+
+`m.div` inside `<LazyMotion features={domAnimation} strict>`, never a bare `motion.*` (`domains/motion/performance.md`). The menu's wrapper scales and its `glass-panel` child carries the blur (law 13; `glass/depth/guide.md` §3).
+
+## 11. Hover intent
+
+A 100ms grace period on close (law 14):
+
+```ts
+const closeBoxSoon = () => {
+  clearTimeout(closeTimer.current);
+  closeTimer.current = window.setTimeout(() => setConfigOpen(false), 100);
+};
+```
+
+The hover bridge here is `pt-2.5` of wrapper padding between a button and the pill below it.
+
+**Hover is a wash, never a translate-up** (law 1). The folder's rising cards (`LIFT`) are the one exception, and being the only one is the point (`glass/motion/springs.md`).
+
+## 12. Press and sound
+
+```
+active:scale-[0.92]   /* 8% — felt, not seen */
+```
+
+On `pointerdown` (law 3).
+
+Sound is *on* by default here, defensible only on a personal site: a synthesised "tok" on hover and click, muteable; `[data-quiet-hover]` silences hover on dense surfaces. → `glass/motion/sound.md`; the rules: `domains/motion/patterns.md`, sound
+
+## 13. Fill means chosen
+
+Law 9, in glass's mechanism: the filled variant is the outline with its interior painted, layered *over* the stroke at the same coordinates, so the layers cross-fade in place.
+
+```tsx
+export const fillFade = (on: boolean) =>
+  `transition-opacity duration-200 ease-out motion-reduce:transition-none ${on ? "opacity-100" : "opacity-0"}`;
+
+// The inverse, for interior lines the fill swallows (a briefcase's divider).
+export const detailFade = (on: boolean) =>
+  `transition-opacity duration-200 ease-out motion-reduce:transition-none ${on ? "opacity-0" : "opacity-100"}`;
+```
+
+**200ms `ease-out`, not the house curve** (§2). The knockout mask for interior lines is in `domains/motion/patterns.md`, fill means chosen.
+
+**How the marks that can't fill signal instead:**
+
+| Mark | Why fill is wrong | What it does instead |
+|---|---|---|
+| Brand marks — socials, a tech stack | Official solid silhouettes; an outline is an off-brand redrawing | Colour: quiet at rest, full on hover |
+| Open strokes — chevrons, arrows, checks, menu bars | No interior to paint | A stroke-weight ladder by role |
+| A mark on static content, or a lone toggle | Never hovered, never current — or the only mark on screen | Stays in the default state |
+
+## 14. Set pieces play once
+
+Two set pieces, each once a session (law 15): the opening screen, and a summary panel's first reveal.
+
+```ts
+// Once a session, per item. The theatre is a welcome; a re-run is a delay.
+const seenKey = (slug: string) => `short-version:${slug}`;
+```
+
+The inline gate's glass condition:
+
+```js
+// Home page, first landing, not a deep link (/#work), never under reduced motion.
+document.documentElement.dataset.intro = "on";
+```
+
+The summary panel's lines branch the transition, never the style, on the client-only flag:
+
+```tsx
+variants={{
+  shut: { opacity: 0, y: 6, filter: "blur(4px)" },   // constant, both renders
+  open: { opacity: 1, y: 0, filter: "blur(0px)",
+          transition: { duration: reduce ? 0 : theatre ? 0.34 : 0.16, ease: EASE } },
+}}
+```
+
+"Seen" is recorded in `onAnimationComplete`, which also makes a second open in one visit as quiet as a second visit. The gate, the hydration rule and the "seen" bookkeeping are in `domains/motion/guards.md`.
+
+Collapsibles animate height and stay mounted (law 11), so the content stays in the served HTML for a crawler or an `llms.txt`.
+
+## Assets
+
+- `glass/motion/assets/motion-tokens.css` — easing curve, duration ladder, `.reveal`, route fade, theme crossfade.
+- `glass/motion/assets/motion-presets.ts` — every spring and tween above, plus reduced-motion substitutes.
+- `glass/motion/assets/DropMenu.tsx` — the squash-and-stretch menu.
+- `glass/motion/assets/useScrollTick.ts` — rAF-throttled scroll with hysteresis.
+- `glass/motion/assets/useReveal.ts` — the IntersectionObserver hook and its guards.
+
+## Checklist
+
+The domain checklist first; then glass's values:
+
+- [ ] Every duration on the ladder: no 250ms, 500ms or 1s.
+- [ ] Off-ladder timing is the subject of the moment (the 620ms dissolve) or a once-a-session set piece, and says which.
+- [ ] `--ease-geist` everywhere, opacity entrances included, plus `ease-out` for 100ms opacity hovers and icon fills, plain `ease` for the theme fade, and expo-out on any track driving a filter.
+- [ ] Menus open on the `GROW`/`CROSS` pair and close on `CLOSE`.
+- [ ] Hover timed by area: a link 100ms, a card-sized wash 200ms.
+- [ ] No translate on hover, bar the folder's rising cards.
+- [ ] Icon fills cross-fade at 200ms `ease-out`.
+- [ ] `LazyMotion` + `m` + `strict`; no bare `motion.*`.
+- [ ] Dense hover surfaces carry `data-quiet-hover`.

package/plugins/keyline/skills/keyline/glass/motion/reduced-motion.md

@@ -0,0 +1,81 @@
+# Reduced motion
+
+Glass's substitutes and the code that takes them. The principle, the full substitution table, imperative APIs and testing are law 10 and `domains/motion/guards.md`; reduced transparency and high contrast are §8 of `glass/depth/guide.md`.
+
+## The glass substitutes
+
+The rows where glass sets a value or has a component the domain table doesn't name; every other row is as `domains/motion/guards.md`.
+
+| Original | Reduced-motion path | Reasoning |
+|---|---|---|
+| Spring slide (highlight, tooltip) | 150ms tween | The state change is the message; physics is decoration. |
+| Squash-and-stretch open | Plain 150ms fade | Presence still communicated, no scaling. |
+| Card lift on hover | No hover variant at all | Motion is the whole interaction; static is correct. |
+| Press scale | **Keep it** | 8% on a 40px button, 0ms: below any threshold of concern. |
+| First-open theatre (staggered lines) | Same open, zero-length transitions | The disclosure opens; the choreography doesn't run. |
+| A GPU dissolve between images | Fall back to the plain `<img>` | The no-WebGL path, already built. |
+| Icon fill crossfade | Instant swap (`motion-reduce:transition-none`) | The state is the message; the 200ms fade isn't. |
+
+## In JavaScript
+
+`useReducedMotion()` from Motion; branch the *transition*, keep the animation: `reduce ? { duration: 0.15 } : SLIDE`.
+
+Where motion is the whole point of a variant-driven interaction, drop the trigger, on focus as well as hover:
+
+```tsx
+<m.div
+  variants={container}
+  initial="rest"
+  animate="rest"
+  whileHover={reduce ? undefined : "hover"}
+  whileFocus={reduce ? undefined : "hover"}
+>
+```
+
+For presence, branch the offsets themselves:
+
+```tsx
+initial={reduce ? { opacity: 0 } : { opacity: 0, scaleY: 0.82, scaleX: 0.94, y: away }}
+animate={reduce ? { opacity: 1 } : { opacity: 1, scaleY: 1, scaleX: 1, y: 0 }}
+exit={reduce
+  ? { opacity: 0, transition: CLOSE }
+  : { opacity: 0, scaleY: 0.9, scaleX: 0.97, y: away, transition: CLOSE }}
+```
+
+The exit keeps `CLOSE` in both branches: 130ms `easeIn` is already flat, so it needs no substitute.
+
+## The blur crossfade
+
+```tsx
+const blur = reduce ? "blur(0px)" : "blur(4px)";
+
+<m.span
+  initial={{ opacity: 0, filter: blur }}
+  animate={{ opacity: 1, filter: "blur(0px)", transition: { duration: 0.28, ease: "easeOut" } }}
+  exit={{ opacity: 0, filter: blur, transition: { duration: 0.18, ease: "easeIn" } }}
+>
+```
+
+One variable turns a blur-crossfade into a plain crossfade; `blur(0px)` → `blur(0px)` is a no-op the browser optimises away, so there's no second code path. Note the asymmetry: 280ms in, 180ms out.
+
+## In CSS
+
+The `.reveal` rule is in `glass/motion/assets/motion-tokens.css`; the theme crossfade's opt-in block is in `glass/motion/easing-and-duration.md`. The route fade:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  .route-fade { animation: none; }
+}
+```
+
+### Tailwind's `motion-reduce:` variant
+
+```tsx
+className="transition-transform duration-200 ease-geist motion-reduce:transition-none"
+```
+
+Apply it to every `transition-*` that moves something. Colour-only ones don't strictly need it (a 150ms colour fade isn't a vestibular trigger), but consistency costs nothing.
+
+## Set pieces
+
+The greeting never plays under reduced motion, decided in its inline gate (§14 of the guide). **The `?intro` replay override, for development, does not defeat the preference**: it's a preference, not a cache. The "seen" flag is still written.

package/plugins/keyline/skills/keyline/glass/motion/scroll-performance.md

@@ -0,0 +1,58 @@
+# Scroll and performance
+
+Glass's values for the scroll and compositor rules. The scroll shape, hysteresis, the touch gate, scroll spies and what to animate are laws 12 and 13 and `domains/motion/performance.md`; the React hooks are in `glass/motion/assets/useScrollTick.ts`.
+
+## The dock
+
+The dock (`useCollapseOnScroll`) collapses on scroll-down with the domain's dead zone — 6px of intent either way, always expanded within 24px of the top and at `scrollHeight - 2`. It collapses only where `(hover: hover) and (pointer: fine)` matches; touch gets its own presentation (the Glass layout guide, `glass/layout/guide.md`, on adaptive presentations).
+
+## Scroll spy
+
+The spy is `useActiveSection`. Its reading line sits 120px below the viewport top (`READING_LINE = 120`), with the bottom clamp.
+
+### Matching `scroll-mt`
+
+```tsx
+const ANCHOR = "scroll-mt-28";   // 112px — matched to READING_LINE = 120
+```
+
+Every heading carries `scroll-mt-28`, so a jump lands it 112px below the viewport top, just above the 120px line.
+
+### Deep links without the router
+
+```tsx
+el.scrollIntoView({ behavior: reduce ? "auto" : "smooth", block: "start" });
+window.history.replaceState(null, "", `#${id}`);
+```
+
+The URL stays copyable without a second scroll fighting the first.
+
+## The `1fr` ↔ `0fr` grid trick, in Tailwind
+
+Collapsing a region to zero width without animating `width`:
+
+```tsx
+<li
+  className="grid transition-[grid-template-columns] duration-300 ease-geist motion-reduce:transition-none"
+  style={{ gridTemplateColumns: expanded ? "1fr" : "0fr" }}
+>
+  <div className="flex min-w-0 items-center overflow-hidden">{children}</div>
+</li>
+```
+
+`min-w-0` on the child is required (flex children default to `min-width: auto` and won't shrink below their content); `overflow-hidden` clips during the collapse.
+
+## `backdrop-filter` and transforms
+
+The animating wrapper and the glass surface are different elements (law 13):
+
+```tsx
+<DropMenu open={open}>            {/* animates scale + y */}
+  <ul className="glass-panel …">  {/* carries the blur, never transformed */}
+```
+
+Where the panel itself must animate, carry more of the effect in the tint than the blur: `glass-panel` sits at 97% opacity because its blur is compromised while it animates.
+
+## Timers
+
+The hover-intent timer is `closeTimer`, cleared on unmount and reset on `pathname` (law 14, `domains/motion/patterns.md`).

package/plugins/keyline/skills/keyline/glass/motion/shared-element.md

@@ -0,0 +1,161 @@
+# The shared-element highlight
+
+The signature interaction of this system: one highlight rectangle and one tooltip per container, animating position and size to whichever child is hovered or focused. Why it beats per-item backgrounds, and when it's the wrong tool, is law 8; the details that keep it from flickering are in `domains/motion/patterns.md`, the shared highlight.
+
+## The implementation
+
+```tsx
+type Hover = { x: number; y: number; w: number; h: number; cx: number; label: string };
+
+const [hovered, setHovered] = useState<Hover | null>(null);
+
+const enter = (el: HTMLElement, label: string) =>
+  setHovered({
+    x: el.offsetLeft,
+    y: el.offsetTop,
+    w: el.offsetWidth,
+    h: el.offsetHeight,
+    cx: el.offsetLeft + el.offsetWidth / 2,  // centre, for the tooltip
+    label,
+  });
+```
+
+```tsx
+<ul className="relative isolate flex items-center …" onMouseLeave={() => setHovered(null)}>
+
+  {/* The highlight — behind the icons, inside its own stacking context */}
+  <m.div
+    aria-hidden
+    className="pointer-events-none absolute left-0 top-0 -z-10 rounded-[12px] bg-highlight"
+    initial={false}
+    animate={hovered
+      ? { x: hovered.x, y: hovered.y, width: hovered.w, height: hovered.h, opacity: 1 }
+      : { opacity: 0 }}
+    transition={tween}
+  />
+
+  {items.map((item) => (
+    <a
+      key={item.label}
+      onMouseEnter={(e) => enter(e.currentTarget, item.label)}
+      onFocus={(e) => enter(e.currentTarget, item.label)}
+      …
+    />
+  ))}
+</ul>
+```
+
+Pair `onFocus` with `onBlur` where the list can lose focus without the pointer leaving.
+
+## The tooltip variant
+
+Same state, same spring, one axis:
+
+```tsx
+<m.div
+  aria-hidden
+  className="pointer-events-none absolute bottom-full left-0 mb-2"
+  initial={false}
+  animate={hovered ? { x: hovered.cx, opacity: 1 } : { opacity: 0 }}
+  transition={tween}
+>
+  <div className="-translate-x-1/2 whitespace-nowrap rounded-md bg-gray-1000 px-2 py-1
+                  text-[11px] leading-none text-background-100
+                  shadow-[0_4px_10px_-4px_rgba(0,0,0,0.3)]">
+    {hovered?.label}
+  </div>
+</m.div>
+```
+
+`bottom-full mb-2` places it above the container at any height; flip to `top-full mt-2` when the container is itself a dropdown, so the tooltip doesn't cover what opened it. It's `aria-hidden` because every item already carries an `aria-label` with the same text.
+
+## The vertical list variant
+
+For rows rather than icons only the container class changes: items carry the padding, so the bar is the same box everywhere, and a negative horizontal margin lets it bleed past the text column:
+
+```tsx
+<HighlightList
+  className="reveal -mx-3 flex flex-col text-[14px] leading-[1.55]"
+  itemClassName="group relative flex gap-10 px-3 py-2.5"
+  items={…}
+/>
+```
+
+`-mx-3` against `px-3` on each item: the bar extends 12px past the measure on both sides while the text sits exactly on it.
+
+Here the bar uses `bg-gray-100` rather than `bg-highlight`: in a list on the page surface the subtle-surface token is right; in floating glass chrome, the elevated one.
+
+## Interaction with active state
+
+The active item shows a static background and drops it while the dock is hovered (`domains/motion/patterns.md`, current versus hovered):
+
+```tsx
+isActive
+  ? `text-gray-1000 ${dockHover ? "" : "bg-highlight shadow-[0_2px_2px_rgba(0,0,0,0.04)]"}`
+  : "text-gray-600 hover:text-gray-1000"
+```
+
+The glyph fills both when current and when hovered (§13 of `glass/motion/guide.md`), and the chip tells the two apart when both are on screen.
+
+## Escalating to the GPU
+
+What broke the DOM approach: a gallery with a masonry wall of ~100 tiles and a "roll" with one photo open above a filmstrip, the same photograph travelling between them. Three things break at once:
+
+1. **Aspect ratios differ.** Consecutive photographs are 1:1 then 16:9; one `<img>` animated between the boxes distorts for the whole trip.
+2. **The wall is expensive to re-lay-out.** Layout on 100 tiles is not a per-frame budget.
+3. **The endpoints exist at different moments.** One rect is measurable only while the outgoing layout is rendered, the other only after the incoming one commits.
+
+One viewport-sized canvas above the gallery draws a single photo into an arbitrary screen rect, so the trip is four numbers in a uniform and costs no reflow at any size:
+
+```ts
+export type Rect = { x: number; y: number; width: number; height: number };
+
+/** Straight-line interpolation. Equal-aspect endpoints keep their aspect throughout. */
+export function lerpRect(a: Rect, b: Rect, t: number): Rect { /* … */ }
+```
+
+The rules are law 13 and `domains/motion/performance.md`, escalating to the GPU. Here the wall stays DOM, since a hundred tiles as textures is ~590MB before atlasing, and the open photo is `alt=""`, its labels in the strip beside it.
+
+**Failing returns `null`:**
+
+```ts
+export function createPhotoStage(canvas: HTMLCanvasElement): PhotoStage | null {
+  try {
+    /* … */
+    // A failed shader link only warns in some libraries; the throw lands on the
+    // first draw. Check the artefact that proves setup completed.
+    if (!program.uniformLocations) return null;
+    /* … */
+  } catch {
+    return null; // No WebGL, or a context that can't be set up.
+  }
+}
+```
+
+**Carry the reading position across** (law 8). Before the switch, find the tile nearest the viewport centre and open the other layout on *that* item, from *that* rect:
+
+```ts
+// Read while the OUTGOING layout is still rendered — from the layout store's
+// synchronous subscriber, before React commits the incoming one.
+export function centreFrame(): { id: string; rect: Rect } | null {
+  const midX = window.innerWidth / 2, midY = window.innerHeight / 2;
+  let best = null;
+  for (const el of document.querySelectorAll<HTMLImageElement>("img[data-frame]")) {
+    const r = el.getBoundingClientRect();
+    if (r.width <= 0 || r.bottom <= 0 || r.top >= window.innerHeight) continue;
+    const d = Math.hypot(r.left + r.width / 2 - midX, r.top + r.height / 2 - midY);
+    if (!best || d < best.d) best = { id: el.dataset.frame!, rect: r, d };
+  }
+  return best;
+}
+```
+
+**Each end keeps its own shape**: two rects around a shared centre, each keeping its aspect through the linear lerp. The GPU path then matches the `<img>` fallback exactly: two absolutely-centred images, each at its own aspect, crossfading.
+
+### Implementation notes that cost real time to find
+
+**Mipmaps.** A 2000px photo in a 355px tile samples one texel in five, so without a mip chain it shimmers as the rect moves sub-pixel. Use trilinear (`LINEAR_MIPMAP_LINEAR`) so crossing mip levels as the photo grows doesn't step.
+
+**Fade the last pixel of the edge** with one `smoothstep` across a pixel's width, fading *alpha only* on a non-premultiplied context, or the edge darkens toward black instead of disappearing.
+
+**Don't call `WEBGL_lose_context` on teardown.** React reuses the node across a remount (StrictMode does on every mount), and the next context silently fails to compile its shaders. Drop the textures and references; the context goes with the element.