trykeyline 0.1.1 → 0.1.2

package/plugins/keyline/skills/keyline/glass/motion/assets/motion-tokens.css

@@ -1,56 +1,20 @@
 /* ─────────────────────────────────────────────────────────────────────────
    Interface motion — tokens and CSS-driven effects
    Drop-in for Tailwind v4 (@theme) or plain CSS (the :root fallback below).
+   The ladder and the reasons for each value: glass/motion/guide.md §1–2.
    ───────────────────────────────────────────────────────────────────────── */
 
 @theme {
-  /* ── One curve for the whole system ─────────────────────────────────────
-     The 1.1 end control point overshoots ~10% and settles back — enough to
-     feel physical, not enough to read as bounce. A single shared curve is
-     why unrelated elements moving at once still feel like one mechanism.
-
-     Do NOT add a second bezier "because this needs a different feel." If an
-     element needs distinct character it needs a spring — that's the axis
-     where character belongs without fragmenting the system. */
+  /* One curve for the whole system; the 1.1 overshoots ~10% and settles.
+     Character beyond it belongs to springs, never a second bezier. */
   --ease-geist: cubic-bezier(0.175, 0.885, 0.32, 1.1);
 
-  /* ── Duration ladder ────────────────────────────────────────────────────
-     Set by how much of the screen changes, not by how important the element
-     feels. Three numbers carry almost everything: 150 / 200 / 300. */
-  --duration-micro: 100ms;    /* one property, no position — link opacity  */
-  --duration-state: 150ms;    /* colour, background, small transform, icon */
-  --duration-popover: 200ms;  /* chevron, hover card, compound glyph       */
-  --duration-route: 260ms;    /* whole viewport, on the critical path      */
-  --duration-overlay: 300ms;  /* large region entering or collapsing       */
-  --duration-theme: 400ms;    /* literally everything, at once            */
-
-  /* ── Off the ladder, deliberately ───────────────────────────────────────
-     The ladder is for STATE. Two things aren't state, and squeezing them
-     onto it makes them worse rather than tighter.
-
-     THE SUBJECT OF THE MOMENT — the thing animating IS the content, so the
-     user is looking directly at it and the motion has to read in its own
-     right. Note the pair: the dissolve is the subject, the flight is a
-     report about it, so the flight stays inside the overlay tier. */
-  --duration-dissolve: 620ms; /* stepping between images                   */
-  --duration-flight: 420ms;   /* one image moving between two layouts      */
-
-  /* A SET PIECE earns its budget by never appearing again — once per tab,
-     never blocking a deep link, never played under reduced motion. */
-  --duration-setpiece-in: 560ms;
-  --duration-setpiece-out: 320ms;
-
-  /* ── The curve for a track that also drives a filter ────────────────────
-     NOT --ease-geist. The house curve overshoots past 1, and a blur
-     animating to 0px would have to pass through a NEGATIVE radius to settle
-     back. Browsers clamp rather than crash, so the symptom is a value stuck
-     at zero for the tail of the transition — which reads as the animation
-     stalling right at the end, and is very hard to attribute.
-
-     Applies to any property with a hard floor: blur, brightness, a radius
-     going to 0, a scale you've promised won't invert. Expo-out has the same
-     "arrives decisively" character without ever leaving [0, 1]. */
-  --ease-filter: cubic-bezier(0.16, 1, 0.3, 1);
+  /* The state tiers these rules use. The full ladder, and the off-ladder
+     subject and set-piece timings, are in the guide. */
+  --duration-state: 150ms;
+  --duration-route: 260ms;
+  --duration-overlay: 300ms;
+  --duration-theme: 400ms;
 }
 
 /* Plain-CSS fallback if you're not on Tailwind v4. */
@@ -60,24 +24,20 @@
 
 @layer components {
   /* ── Reveal on scroll ────────────────────────────────────────────────────
-     CSS animates; JS only sets `data-in` (see useReveal.ts). 8px of travel —
-     enough to register, small enough that a page of revealing paragraphs
-     doesn't feel like it's sliding around. */
+     CSS animates; JS only sets `data-in` (useReveal.ts, which also holds the
+     <noscript> reset this needs). 8px of travel. */
   .reveal {
     opacity: 0;
     transform: translateY(8px);
     transition: opacity var(--duration-overlay) var(--ease-geist),
                 transform var(--duration-overlay) var(--ease-geist);
   }
-  /* An attribute, not a class — see useReveal.ts for why a class can't survive. */
   .reveal[data-in] {
     opacity: 1;
     transform: translateY(0);
   }
 
-  /* Off entirely — the animation IS the effect, so there's nothing to
-     degrade to. Note it resolves to opacity: 1; the danger with any
-     reveal-on-scroll is leaving content stuck at opacity: 0. */
+  /* Resolves to opacity: 1 — never leave reveal content stuck at 0. */
   @media (prefers-reduced-motion: reduce) {
     .reveal {
       opacity: 1;
@@ -86,8 +46,8 @@
     }
   }
 
-  /* Print is a real presentation, and scroll-triggered content prints blank
-     without this. The most-forgotten line in the file. */
+  /* Scroll-triggered content prints blank without this. The one copy of the
+     print reset; layout-tokens.css's print block relies on it. */
   @media print {
     .reveal {
       opacity: 1;
@@ -95,29 +55,9 @@
     }
   }
 
-  /* THE THIRD GUARD IS NOT CSS. A feature check can't catch "JavaScript
-     never ran at all": the rules above ship, `.reveal` applies, and nothing
-     arrives to add `.in`. The reader gets a correct document they cannot
-     see — a blank page rather than a plain one. Put this in the head:
-
-       <noscript>
-         <style>.reveal { opacity: 1 !important; transform: none !important; }</style>
-       </noscript>
-
-     The general rule: any CSS that hides content pending JavaScript needs a
-     <noscript> reset. */
-
   /* ── Route transition ───────────────────────────────────────────────────
-     Opacity only — no slide, no scale. Directional motion implies a spatial
-     relationship between routes; in a flat site map there isn't one.
-
-     260ms rather than 300: a page transition sits directly between "I
-     clicked" and "I can read," and that latency reads as the site being
-     slow. 260 is the shortest crossfade that isn't mistaken for a flicker.
-
-     `both` holds the from-state before the animation starts, preventing a
-     one-frame flash of opaque content. Key the wrapper on the pathname to
-     replay it on each navigation. */
+     Opacity only, 260ms; `both` holds the from-state so there's no one-frame
+     flash. Key the wrapper on the pathname (glass/motion/easing-and-duration.md). */
   .route-fade {
     animation: routeFade var(--duration-route) var(--ease-geist) both;
   }
@@ -130,21 +70,10 @@
   }
 
   /* ── Theme crossfade ────────────────────────────────────────────────────
-     Added by the theme setter for ~440ms on an explicit toggle only, then
-     removed. Left in permanently it would make EVERY hover state on the site
-     400ms and sluggish — the !important is what lets it beat each
-     component's own duration-150 for those 440ms, and the removal is what
-     stops it poisoning everything else.
-
-     400ms because this is the largest possible change: every surface, text
-     colour, border, icon fill and shadow simultaneously.
-
-     Plain `ease`, not the house curve — overshoot on a position is momentum;
-     overshoot on a colour interpolation means the background travels past
-     its target and comes back, which reads as a wobble in the light.
-
-     The whole rule sits inside no-preference, so it's opt-in. Reduced-motion
-     users still get the theme change, just instantly. */
+     setThemeChoice (glass/color/assets/theme.ts) adds the class on an
+     explicit toggle for ~440ms, then removes it; the !important beats every
+     component's own duration for that window only. Plain `ease`, and opt-in
+     under no-preference. Why: glass/motion/easing-and-duration.md. */
   @media (prefers-reduced-motion: no-preference) {
     :root.theme-transition,
     :root.theme-transition *,
@@ -159,18 +88,5 @@
     }
   }
 
-  /* ── Skip link ──────────────────────────────────────────────────────────
-     Parked off-screen with a transform (not display:none, which would take
-     it out of the tab order) and slid in on focus at the state tier. */
-  .skip {
-    position: absolute;
-    left: 16px;
-    top: 16px;
-    z-index: 100;
-    transform: translateY(-200%);
-    transition: transform var(--duration-state) var(--ease-geist);
-  }
-  .skip:focus {
-    transform: translateY(0);
-  }
+  /* The skip link lives in glass/layout/assets/layout-tokens.css. */
 }

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

@@ -33,12 +33,7 @@ The gap between 150 and 200 maps to *whether other things move too*:
 
 ## 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.
+The rule is `.route-fade` in `glass/motion/assets/motion-tokens.css`. 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:
 
@@ -50,33 +45,9 @@ Keying the wrapper on the pathname replays the CSS animation on every navigation
 
 ## 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 `.theme-transition` rule is in `glass/motion/assets/motion-tokens.css`; `setThemeChoice` in `glass/color/assets/theme.ts` adds it only on an explicit toggle and removes it after ~440ms, the duration plus a 40ms margin, so its `!important` beats every component's own `transition-colors duration-150` for that window only. Why it's scoped this way is in `domains/motion/patterns.md`, theme cross-fade.
 
 ## The overshoot in the house curve
 

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

@@ -204,7 +204,7 @@ export const detailFade = (on: boolean) =>
 
 ## 14. Set pieces play once
 
-Two set pieces, each once a session (law 15): the opening screen, and a summary panel's first reveal.
+Two set pieces, each once a session (law 15): the opening screen, and a summary panel's first reveal. The first open runs each line at 340ms, its children staggered 90ms after a 60ms delay; every later open runs 160ms with no stagger, and reduced motion runs none.
 
 ```ts
 // Once a session, per item. The theatre is a welcome; a re-run is a delay.
@@ -234,8 +234,8 @@ Collapsibles animate height and stay mounted (law 11), so the content stays in t
 
 ## 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/motion-tokens.css` — easing curve, state durations, `.reveal`, route fade, theme crossfade.
+- `glass/motion/assets/motion-presets.ts` — the springs, the close and the icon-fill fades.
 - `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.

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

@@ -60,13 +60,7 @@ One variable turns a blur-crossfade into a plain crossfade; `blur(0px)` → `blu
 
 ## 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; }
-}
-```
+The `.reveal` reset, the route fade's `animation: none` and the theme crossfade's `no-preference` opt-in are all in `glass/motion/assets/motion-tokens.css`.
 
 ### Tailwind's `motion-reduce:` variant
 

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

@@ -18,40 +18,11 @@ 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
+Deep links scroll with `scrollIntoView({ behavior: reduce ? "auto" : "smooth" })` and set the hash with `history.replaceState` (`domains/motion/performance.md`, scroll spies).
 
-```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 */}
-```
+## The dock's collapse
 
-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.
+The dock's icon row collapses on `grid-template-columns` `1fr` ↔ `0fr`, 300ms on the house curve, with `min-w-0 overflow-hidden` on the child (the technique: `domains/motion/performance.md`, what to animate). The menu's wrapper/surface split is §3 of `glass/depth/guide.md`.
 
 ## Timers
 

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

@@ -74,73 +74,20 @@ export const playClick = () => tok(900, 0.14, 0.13);
 
 Hover is higher, shorter and **2.6× quieter**: you cross dozens of links moving around a page, and hover at click volume is intolerable within seconds. Click, a completed action, is louder and lower, since lower pitch reads as more consequential. Roughly a fourth apart, they sound pleasant when a click follows a hover.
 
-## The autoplay policy
+## Wiring
 
-An `AudioContext` starts `suspended` and resumes only from a user gesture, so hover sounds stay silent until the reader's first real interaction unlocks it, permanently.
+The rules — arm on every activation gesture, mouse-only and deduplicated hover, a dense-surface opt-out, a persisted mute checked at playback — are `domains/motion/patterns.md`, sound. Glass's values for them:
 
 ```ts
-export function unlockAudio(): void {
-  const c = getCtx();
-  if (c && c.state === "suspended") void c.resume();
-}
-```
-
-Every playback path checks state rather than assuming:
-
-```ts
-if (!c || c.state !== "running") return;
-```
-
-That's a feature, not a workaround: a page you've merely scrolled past makes no sound. Fail silently; never surface an error for this.
-
-### Arm it on every activation gesture
-
-```ts
-const UNLOCK_EVENTS = ["pointerdown", "keydown", "touchstart"] as const;
-
-/* Idempotent — resume() on a running context is a no-op, which is cheaper
-   than the bookkeeping to detach these after the first one lands. */
-const onUnlock = () => unlockAudio();
-for (const type of UNLOCK_EVENTS) {
-  document.addEventListener(type, onUnlock, { passive: true });
-}
-```
-
-The reference implementation shipped `pointerdown` alone for months. A reader who only moved the mouse across the dock heard nothing — *the hover was the interaction* — which hid because testers click something within seconds; and keyboard-only readers never heard the site. `keydown` is the fix that matters most: the affected group is the one least able to work around it.
-
-## Delegation, not per-element wiring
-
-One set of document listeners covers every link and button on the site.
-
-```ts
-const SELECTOR = "a, button, [role='button'], summary";
-
-const onOver = (e: PointerEvent) => {
-  // Mouse only — touch has no hover, and we don't want a tick on tap.
-  if (e.pointerType && e.pointerType !== "mouse") return;
-  const el = (e.target as Element | null)?.closest?.(SELECTOR) ?? null;
-  if (el === lastHover) return;   // don't re-fire while moving within one element
-  lastHover = el;
-  if (el) playHover();
-};
-
-document.addEventListener("pointerover", onOver);
-document.addEventListener("click", onClick);
-```
-
-- **`pointerType !== "mouse"` bails out**, or every tap plays both sounds 15ms apart, like a stutter.
-- **`lastHover` deduplication.** `pointerover` fires for descendants too, so an icon *inside* a button would re-trigger without the identity check.
-- **`closest(SELECTOR)`** covers anything interactive, including elements added later, with no per-component wiring. `summary` is in it because a `<details>` disclosure is a real control that should feel like one.
-
-### Dense surfaces opt out of the hover tick
-
-```ts
-// Surfaces of a hundred small targets (an image wall, a filmstrip) opt out with
-// data-quiet-hover: a tick per tile is a machine gun. Clicks still tick.
-if (el && !el.closest("[data-quiet-hover]")) playHover();
+const UNLOCK_EVENTS = ["pointerdown", "keydown", "touchstart"] as const;  // resume() is idempotent
+const SELECTOR = "a, button, [role='button'], summary";                  // one delegated listener set
+if (el && !el.closest("[data-quiet-hover]")) playHover();                 // image wall, filmstrip
 ```
 
-One attribute on the container quiets the subtree on hover while clicks stay audible. It's a rate limit, not "this surface is unimportant".
+- Every playback path checks `c.state !== "running"` and fails silently, so a page merely scrolled past makes no sound.
+- The site shipped `pointerdown` alone for months; mouse-only readers and keyboard readers heard nothing, and testers, who click within seconds, never noticed.
+- `summary` is in the selector because a `<details>` disclosure is a real control.
+- Mute persists as `localStorage["ui-sound"] = "off" | "on"`, from an `aria-pressed` control in the nav's settings box beside the theme toggle.
 
 ## Sound as a phrase
 
@@ -166,30 +113,10 @@ export const playLanding = () => tok(587, 0.26, 0.16);
 
 It's still a set piece, not a texture — once a session. See §14 of `glass/motion/guide.md`.
 
-## Mute, and persistence
-
-```ts
-// Every storage access is guarded: it throws in some private modes.
-let muted = (() => {
-  try { return localStorage.getItem("ui-sound") === "off"; } catch { return false; }
-})();
-
-export function setMuted(value: boolean): void {
-  muted = value;
-  try { localStorage.setItem("ui-sound", value ? "off" : "on"); } catch {}
-}
-```
-
-The mute control sits in the nav's settings box beside the theme toggle, with an `aria-pressed` state and a label.
-
 ## Should the default be on?
 
 Arguable. On a personal site where sound is part of the character, on is defensible — the only way most people will discover it, and it's quiet, short and muteable. On anything the user didn't choose to visit (a tool, an app, a client site), default to off. If it's on, the mute control must be *findable within seconds*; that's the price.
 
 ## What's deliberately absent
 
-**Haptics.** `navigator.vibrate()` isn't implemented: Safari on iOS lacks it, so it would fire only on Android, and a feedback channel on one platform is worse than none. If you add it, keep it under 10ms and tie it to the same mute preference.
-
-**Sounds for anything but hover, click and the one greeting phrase** — no navigation, reveal or error sounds. The riffle earns its place by playing once per tab.
-
-**Pitch variation** by element type or position. It turns an ambient texture into something the user starts trying to interpret.
+**Haptics**: `navigator.vibrate()` would fire only on Android, and a feedback channel on one platform is worse than none. **Pitch variation** by element type or position, which turns an ambient texture into something the user tries to interpret. And no sound beyond hover, click and the one greeting phrase.

package/plugins/keyline/skills/keyline/glass/type/assets/prose.tsx

@@ -1,33 +1,12 @@
 /**
  * Long-form prose renderer — the reading half of the type system.
  *
- * The reading column is TWO SIZES: 16px for headings, 14px for everything a
- * reader reads. Which means size does no work below the headings, and the
- * blocks sharing 14px have to separate on other axes — each on a different
- * one, or they collide:
+ * Two sizes: 16px headings, 14px for everything read, so the 14px blocks
+ * each separate on a different axis (the table in glass/type/long-form-prose.md).
  *
- *   lead     leading, 1.9 against the body's 1.75
- *   keyline  weight 500, and 36px of air on both sides
- *   body     1.75 — the baseline the others are read against
- *   quote    a 3px rounded bar and a 16px indent
- *   note     13px, the faint tier, and a 1px rule
- *
- * The rule that produced this: A TIER MUST NEVER OUTRANK THE HEADING IT SITS
- * UNDER. An earlier pass ran the keyline at 17px, above the 16px heading it
- * belonged to, and the page read as though the paragraphs were shouting over
- * the titles. Pulling everything to one size removes any chance of that
- * returning.
- *
- * Spacing is deliberately asymmetric around headings: 40px above, 12px below,
- * so a heading belongs to the paragraph that follows it rather than floating
- * between two sections. The keyline is the one symmetric block, because it
- * belongs to neither neighbour.
- *
- * Colour comes from the Glass colour guide (`glass/color/guide.md`): `gray-1000`/`gray-900` for
- * the two upper text tiers, and the `muted`/`quiet`/`faint` tokens below them
- * (which are deliberately NOT ramp steps — 500–800 are border values and fail
- * as text in a light theme). `gray-500` stays on decorative marks, which carry
- * no text. `reveal` comes from glass/motion.
+ * Spacing: 40px above a heading, 12px below; the keyline is the one
+ * symmetric block (glass/type/long-form-prose.md). Text tiers come from
+ * glass/color/guide.md; `reveal` from glass/motion.
  */
 
 import { Fragment, type ReactNode } from "react";
@@ -188,23 +167,9 @@ export function Prose({ blocks }: { blocks: Block[] }) {
 }
 
 /**
- * Inline markdown for **strong**, *em* and [links](/there), mapped onto the
- * system's two axes instead of bold and italic:
- *
- *   **strong** → weight 500 + primary colour   (advances)
- *   *em*       → muted colour, no slant        (recedes)
- *
- * This gives genuinely two-directional emphasis, which a bold-only system
- * can't express. The semantic tags stay — screen readers still announce them.
- *
- * One caution specific to a two-size reading column: <strong> and the keyline
- * are now the same weight at the same size, so a paragraph with a long bolded
- * clause reads as a keyline that failed to get its own line. Keep strong
- * emphasis to a few words; anything longer wants to BE a keyline.
- *
- * Links are here because the strongest sentences often live in data rather
- * than JSX, and a claim that can't carry a link to its own evidence is just an
- * assertion. One link treatment everywhere prose carries one.
+ * Inline markdown for **strong** (500 + primary), *em* (muted, no slant) and
+ * [links](/there) — §5 of glass/type/guide.md. Keep strong to a few words:
+ * at this size it is the keyline's weight.
  */
 const TOKENS = /(\*\*[^*]+\*\*|\*[^*]+\*|\[[^\]]+\]\([^)\s]+\))/g;
 const LINK = /^\[([^\]]+)\]\(([^)\s]+)\)$/;