trykeyline 0.0.0-stage → 0.1.0

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 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.

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

@@ -0,0 +1,192 @@
+# UI sound
+
+The most optional thing in the system: "if you're going to do it, here's how", not a recommendation. Whether a preset allows sound, and the rules for arming, hover, dense surfaces and mute, are in `domains/motion/patterns.md`, sound; this file is glass's synthesis and the decisions behind it.
+
+## Synthesise, don't ship files
+
+The whole sound design is ~100 lines of Web Audio, no assets: two sounds, generated on demand. Tuning is editing numbers, not re-exporting audio.
+
+## The "tok"
+
+A woody marimba-like tick: a sine fundamental, a fast-decaying partial, and a noise transient for the attack.
+
+```ts
+function tok(base: number, duration: number, volume: number): void {
+  if (muted) return;
+  const c = getCtx();
+  if (!c || c.state !== "running") return;
+  const now = c.currentTime;
+
+  // Fundamental + a 3.9:1 partial that decays faster than the body.
+  const tones: [number, number, number][] = [
+    [1, 1, duration],
+    [3.9, 0.32, duration * 0.45],
+  ];
+  for (const [ratio, vmul, dur] of tones) {
+    const osc = c.createOscillator();
+    osc.type = "sine";
+    osc.frequency.value = base * ratio;
+    const gain = c.createGain();
+    gain.gain.setValueAtTime(0.0001, now);
+    gain.gain.exponentialRampToValueAtTime(volume * vmul, now + 0.002);
+    gain.gain.exponentialRampToValueAtTime(0.0001, now + dur);
+    osc.connect(gain).connect(c.destination);
+    osc.start(now);
+    osc.stop(now + dur + 0.02);
+  }
+
+  // Wooden contact tick: short lowpassed noise for the "k".
+  const transient = 0.012;
+  const noise = c.createBufferSource();
+  noise.buffer = getNoise(c);
+  const lp = c.createBiquadFilter();
+  lp.type = "lowpass";
+  lp.frequency.value = 2600;
+  const noiseGain = c.createGain();
+  noiseGain.gain.setValueAtTime(volume * 0.7, now);
+  noiseGain.gain.exponentialRampToValueAtTime(0.0001, now + transient);
+  noise.connect(lp).connect(noiseGain).connect(c.destination);
+  noise.start(now);
+  noise.stop(now + transient + 0.01);
+}
+
+export const playHover = () => tok(1200, 0.09, 0.05);
+export const playClick = () => tok(900, 0.14, 0.13);
+```
+
+### Why each piece is there
+
+**The 3.9:1 partial.** A pure sine reads as a test tone. Struck wooden bars have a strong inharmonic partial near the 4th, and slightly *off* 4.0 reads as physical rather than as a musical interval. It's quieter (0.32×) and decays in 45% of the time, as a real bar's overtones die first.
+
+**The noise transient.** 12ms of lowpassed white noise at the attack is the "k" in "tok", the contact before the note's body: without it a pitched beep, with it something *struck*. Lowpassed at 2600Hz so it's a thud, not a click.
+
+**Exponential ramps, not linear.** Loudness perception is logarithmic, so a linear ramp seems to decay too fast and then hang. `exponentialRampToValueAtTime` matches perception, and can't target zero, hence `0.0001` at both ends.
+
+**The 2ms attack** avoids the click of a discontinuity while still feeling instantaneous.
+
+### Hover vs click
+
+|  | Hover | Click |
+|---|---|---|
+| Base | 1200Hz | 900Hz |
+| Duration | 90ms | 140ms |
+| Gain | 0.05 | 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
+
+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.
+
+```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();
+```
+
+One attribute on the container quiets the subtree on hover while clicks stay audible. It's a rate limit, not "this surface is unimportant".
+
+## Sound as a phrase
+
+Occasionally you want a *run*: the reference implementation plays one note per photograph as they flick past in the opening screen, then a landing note as the real mark arrives.
+
+```ts
+/* An A major pentatonic run, written out rather than computed from an
+   interval: five notes want to BE a phrase, and pentatonic is the scale
+   where no two of them can sound wrong together. */
+const RIFFLE = [880, 990, 1100, 1320, 1467];
+
+export function playRiffleStep(i: number): void {
+  tok(RIFFLE[Math.min(Math.max(i | 0, 0), RIFFLE.length - 1)], 0.1, 0.06);
+}
+
+/** The mark arriving last, and the run resolving onto it. */
+export const playLanding = () => tok(587, 0.26, 0.16);
+```
+
+- **Pentatonic, because the phrase can be truncated.** A photograph that fails to load drops its turn and the run comes up short; with no dissonant pair in the scale, it still sounds finished.
+- **Quieter than a click** (0.06 against 0.13). Five notes inside a second should read as a flutter, not a drum fill.
+- **The landing note resolves *downward*.** It sits a fifth below where the run started and is the only accented note. Landing above the run sounds like one more step, not an ending.
+
+It's still a set piece, not a texture — once a session. See §14 of `glass/motion/guide.md`.
+
+## Mute, and persistence
+
+```ts
+let muted = localStorage.getItem("ui-sound") === "off";
+
+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.

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

@@ -0,0 +1,51 @@
+# Springs
+
+How glass's springs were arrived at. The two vocabularies, tuning by symptom and where springs are wrong are in `domains/motion/ladder-and-curves.md` and law 6.
+
+## SLIDE — a shared element re-targeting
+
+```ts
+const SLIDE = {
+  type: "spring", bounce: 0.2, duration: 0.4,
+  opacity: { duration: 0.16, ease: "easeOut" },
+} as const;
+```
+
+`bounce: 0.2` sits near the floor of "perceptibly springy", as a highlight should (`spring.snappy` in the domain reference).
+
+`duration: 0.4` is longer than it sounds: the spring covers most of the distance in the first ~150ms and spends the tail settling, landing about as fast as a 200ms tween while staying re-targetable. The 160ms `easeOut` opacity outpaces the position spring, so the element is fully visible while it settles, which makes the settle readable.
+
+## LIFT — cards rising out of a folder
+
+```ts
+const LIFT = { type: "spring", bounce: 0.28, duration: 0.5 } as const;
+```
+
+The one playful moment: hovering a folder on the home page lifts four preview cards out of a frosted pocket, a delight beat with 40% more bounce and 25% more duration than anything else. Being the *only* one is why it works.
+
+## GROW / CROSS — the disagreeing pair
+
+```ts
+const GROW  = { type: "spring", stiffness: 620, damping: 19, mass: 0.85 } as const;
+const CROSS = { type: "spring", stiffness: 380, damping: 30 } as const;
+```
+
+|  | GROW | CROSS | Effect |
+|---|---|---|---|
+| stiffness | 620 | 380 | GROW pulls harder → moves sooner |
+| damping | 19 | 30 | GROW resists less → overshoots |
+| mass | 0.85 | 1 (default) | GROW is lighter → accelerates faster |
+
+All three push the same way — GROW fast and loose, CROSS slow and controlled — so on `scaleY` and `scaleX` of one panel it's briefly **taller and narrower** than at rest, then settles. `y` rides `GROW` alongside `scaleY` (§4 of `glass/motion/guide.md`).
+
+## CLOSE — a tween, not a spring
+
+```ts
+const CLOSE = { duration: 0.13, ease: "easeIn" } as const;
+```
+
+130ms, under the state tier, on `easeIn` (law 7).
+
+## Reduced-motion substitutes
+
+Every spring has a flat replacement at the state-tier duration: 150ms, default easing, no overshoot. See `reduced-motion.md` for the complete set.