trykeyline 0.0.0-stage → 0.1.0

package/plugins/keyline/skills/keyline/glass/motion/assets/useScrollTick.ts

@@ -0,0 +1,183 @@
+import { useEffect, useRef, useState } from "react";
+
+/**
+ * The one scroll shape: a `ticking` flag, one requestAnimationFrame, and a
+ * passive listener. Every scroll-driven behaviour in the system uses it.
+ *
+ * `passive: true` tells the browser the handler will never preventDefault, so
+ * it can begin scrolling without waiting for your JS. Omitting it is the most
+ * common cause of scroll jank.
+ *
+ * The `ticking` flag collapses a burst of scroll events into one measurement
+ * per frame. Don't substitute a time-based throttle — it's either faster than
+ * the frame rate (wasted work) or slower (dropped frames). rAF is
+ * frame-aligned by construction.
+ *
+ * `resize` shares the handler because a viewport change invalidates the same
+ * measurements a scroll does.
+ */
+export function useScrollTick(update: () => void, deps: unknown[] = []) {
+  const fn = useRef(update);
+  fn.current = update;
+
+  useEffect(() => {
+    let ticking = false;
+
+    const onScroll = () => {
+      if (!ticking) {
+        ticking = true;
+        requestAnimationFrame(() => {
+          ticking = false;
+          fn.current();
+        });
+      }
+    };
+
+    // Measure once on mount, so a page loaded already scrolled (a deep link,
+    // a restored scroll position) starts in the right state.
+    fn.current();
+
+    window.addEventListener("scroll", onScroll, { passive: true });
+    window.addEventListener("resize", onScroll);
+    return () => {
+      window.removeEventListener("scroll", onScroll);
+      window.removeEventListener("resize", onScroll);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, deps);
+}
+
+/**
+ * Collapse-on-scroll-down with hysteresis. Returns true while the element
+ * should be collapsed.
+ *
+ * Three things at once:
+ *
+ *   · THRESHOLD px of movement required before the state flips. Without a
+ *     dead zone, a 1px jitter — trackpad, rubber-band bounce, or your own
+ *     state change altering layout — oscillates forever.
+ *
+ *   · A zone at the top where it's always expanded. Landing at the top of a
+ *     page should look the same however you got there.
+ *
+ *   · A bottom zone, so a collapsed element never sits over the footer. The
+ *     `- 2` absorbs subpixel rounding in the height calculation; an exact
+ *     comparison intermittently fails at fractional device pixel ratios.
+ *
+ * The top/bottom overrides are checked FIRST so they beat the direction
+ * logic.
+ *
+ * `hoverOnly` (default true) bails out entirely on touch devices. This
+ * pattern is only safe where a cursor can bring the element back — on a
+ * touch screen there is no hover, so collapsing would strand whatever the
+ * element contains. The capability check belongs at the point where you
+ * decide to HIDE something, not where you reveal it.
+ */
+export function useCollapseOnScroll({
+  threshold = 6,
+  topZone = 24,
+  hoverOnly = true,
+}: { threshold?: number; topZone?: number; hoverOnly?: boolean } = {}) {
+  const [collapsed, setCollapsed] = useState(false);
+
+  useEffect(() => {
+    if (hoverOnly && !window.matchMedia("(hover: hover) and (pointer: fine)").matches) return;
+
+    let last = window.scrollY;
+    let ticking = false;
+
+    const update = () => {
+      ticking = false;
+      const y = window.scrollY;
+      const atBottom =
+        y + window.innerHeight >= document.documentElement.scrollHeight - 2;
+
+      if (y < topZone || atBottom) setCollapsed(false);
+      else if (y > last + threshold) setCollapsed(true);
+      else if (y < last - threshold) setCollapsed(false);
+      last = y;
+    };
+
+    const onScroll = () => {
+      if (!ticking) {
+        ticking = true;
+        requestAnimationFrame(update);
+      }
+    };
+
+    window.addEventListener("scroll", onScroll, { passive: true });
+    return () => window.removeEventListener("scroll", onScroll);
+  }, [threshold, topZone, hoverOnly]);
+
+  return collapsed;
+}
+
+/**
+ * Which of the given section ids the reader is currently in — for a table of
+ * contents that marks its place.
+ *
+ * A reading line, not an IntersectionObserver. An observer tells you WHETHER
+ * an element is visible, which is the wrong question: several sections are
+ * visible at once and the answer changes with element height. A single line
+ * answers the actual question — which heading did I most recently pass?
+ *
+ * Ids must be in document order; the loop breaks at the first section that
+ * hasn't crossed the line.
+ *
+ * IMPORTANT: give every heading a scroll-margin-top just under READING_LINE
+ * (scroll-mt-28 = 112px against 120px here). Without it, a jump scrolls the
+ * heading to y=0 — ABOVE the line — so the section you just jumped to isn't
+ * the active one and the TOC highlights the previous one.
+ */
+const READING_LINE = 120;
+
+export function useActiveSection(ids: string[]): string {
+  const [active, setActive] = useState(ids[0] ?? "");
+
+  // Ids arrive as a fresh array each render, so [ids] would tear down and
+  // rebuild the listener continuously. Key the effect on the contents.
+  const key = ids.join("|");
+
+  useEffect(() => {
+    const list = key ? key.split("|") : [];
+    if (list.length === 0) return;
+
+    let ticking = false;
+
+    const update = () => {
+      ticking = false;
+      let current = list[0];
+      for (const id of list) {
+        const el = document.getElementById(id);
+        if (!el) continue;
+        if (el.getBoundingClientRect().top > READING_LINE) break;
+        current = id;
+      }
+
+      // Without this clamp a short final section can never become active:
+      // you reach the end of the page before its heading crosses the line.
+      const atBottom =
+        window.scrollY + window.innerHeight >= document.documentElement.scrollHeight - 2;
+      if (atBottom) current = list[list.length - 1];
+
+      setActive((prev) => (prev === current ? prev : current));
+    };
+
+    const onScroll = () => {
+      if (!ticking) {
+        ticking = true;
+        requestAnimationFrame(update);
+      }
+    };
+
+    update();
+    window.addEventListener("scroll", onScroll, { passive: true });
+    window.addEventListener("resize", onScroll);
+    return () => {
+      window.removeEventListener("scroll", onScroll);
+      window.removeEventListener("resize", onScroll);
+    };
+  }, [key]);
+
+  return active;
+}

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 {
+  localStorage.setItem(KEY, choice);
+  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,286 @@
+# 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:
+
+- **Opacity-only micro-transitions**: `ease-out` at 100ms.
+- **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): one viewport-sized canvas above the gallery draws the open photo into a screen rect, four numbers in a uniform, no reflow. The wall stays DOM, since a hundred tiles as textures is ~590MB before atlasing; the open photo is `alt=""`, its labels sitting beside it; failure returns `null` and keeps the caller's `<img>`.
+
+**Carry the reading position across**: open the other layout on the tile nearest the viewport centre, measured before React commits it, and give each end its own rect around a shared centre (law 8).
+
+→ The measurement (`centreFrame`) and the WebGL notes: `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
+
+CSS animates; JavaScript only marks an element as arrived:
+
+```css
+.reveal { opacity: 0; transform: translateY(8px);
+          transition: opacity 300ms var(--ease-geist), transform 300ms var(--ease-geist); }
+.reveal[data-in] { opacity: 1; transform: translateY(0); }
+
+@media (prefers-reduced-motion: reduce) {
+  .reveal { opacity: 1; transform: none; transition: none; }
+}
+```
+
+`threshold: 0` with `rootMargin: "0px 0px -40px 0px"`, one-shot, re-run on the pathname. 8px of travel registers without a page of paragraphs seeming to slide. Every guard is law 11 and `domains/motion/guards.md`; the two the site hit:
+
+- **A fractional threshold on a tall element.** Every rendered SKILL.md on the site, eight to thirteen thousand pixels in one `.reveal`, once sat invisible at opacity 0 behind `0.1`.
+- **A class the framework owns.** Tag-filtered rows went blank as the pointer left, when React rewrote a state-dependent `className` and wiped an `in` added with `classList.add`. Hence `data-in`.
+
+The no-JavaScript reset, in the head:
+
+```html
+<noscript>
+  <style>.reveal { opacity: 1 !important; transform: none !important; }</style>
+</noscript>
+```
+
+## 10. Performance: `m` not `motion`
+
+`m.div` inside `<LazyMotion features={domAnimation} strict>`, never a bare `motion.*` (`domains/motion/performance.md`). The menu animates a bare `<m.div>` around the `glass-panel`, so the wrapper scales and the child carries the blur (law 13).
+
+## 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).
+
+The site synthesises a "tok" on hover and click (Web Audio, no asset files): a sine fundamental, a fast-decaying marimba-like 3.9:1 partial, and a lowpassed noise transient for the wooden attack. Hover is quiet and high (1200Hz, 0.09s, 0.05 gain), click lower and louder (900Hz, 0.14s, 0.13 gain); it's gated on the autoplay policy, muteable, and persisted. Dense surfaces opt out of the hover tick with `[data-quiet-hover]`; clicks still sound. The rules for arming and muting are in `domains/motion/patterns.md`, sound.
+
+**Sound can be a phrase, not just an event.** The opening screen's run, a note per photograph, is written out in A major pentatonic, where no two notes clash, so a run cut short by a failed image still resolves; the landing note, the only accented one, sits a fifth *below* the start, closing the phrase rather than adding a step.
+
+Sound is *on* by default here, which is defensible only on a personal site and only if you're confident. → Synthesis walkthrough and delegation pattern: `glass/motion/sound.md`
+
+## 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**: overshoot suits travel, not a fade. 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, plus `ease-out` for opacity-only, 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 §9 of `glass/motion/guide.md`; 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.