trykeyline 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,195 @@
+# 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
+// 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.

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.

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

@@ -0,0 +1,268 @@
+/**
+ * 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:
+ *
+ *   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.
+ */
+
+import { Fragment, type ReactNode } from "react";
+
+export type Block =
+  | { type: "p" | "lead" | "keyline" | "note"; text: string }
+  | { type: "h2"; text: string }
+  | { type: "quote"; text: string; cite?: string }
+  | { type: "figure"; src: string; alt: string; caption: string; aspect?: string }
+  | { type: "ul" | "ol"; items: string[] };
+
+export function Prose({ blocks }: { blocks: Block[] }) {
+  return (
+    <div className="text-[14px] leading-[1.75] text-gray-1000">
+      {blocks.map((b, i) => {
+        switch (b.type) {
+          /* The opening paragraph. Same size as the body; the 1.9 leading is
+             the entire difference, and it's what stops a piece reading as one
+             undifferentiated block from the first screen. */
+          case "lead":
+            return (
+              <p key={i} className="reveal mb-8 text-[14px] leading-[1.9] text-gray-1000">
+                {renderInline(b.text)}
+              </p>
+            );
+
+          case "p":
+            return (
+              <p key={i} className="reveal mb-6">
+                {renderInline(b.text)}
+              </p>
+            );
+
+          /* The one sentence a section is for. Authored by promoting a
+             sentence out of a paragraph and DELETING it from the paragraph —
+             a section that gains a keyline gets shorter. One per section.
+             Everything that makes it a landmark comes from weight and from
+             the 36px of air, so it can never outrank the heading above it. */
+          case "keyline":
+            return (
+              <p
+                key={i}
+                className="reveal my-9 text-[14px] font-medium leading-[1.6] text-gray-1000"
+              >
+                {renderInline(b.text)}
+              </p>
+            );
+
+          /* An aside set outside the argument — a caveat, a scope limit, a
+             piece of provenance. Its rule is 1px against the quote's 3px and
+             its type is four steps down, so two indented rules on one page
+             can't be mistaken for each other. */
+          case "note":
+            return (
+              <p
+                key={i}
+                className="reveal my-7 border-l border-gray-alpha-300 pl-4 text-[13px] leading-[1.6] text-faint"
+              >
+                {renderInline(b.text)}
+              </p>
+            );
+
+          /* 16px against 14px body — one step, and the weight, the tight
+             leading and the 40px above do the real work. This is the same
+             size as the page's own title, separated by position alone. */
+          case "h2":
+            return (
+              <h2
+                key={i}
+                className="reveal mt-10 mb-3 text-[16px] font-medium leading-[1.2] tracking-[-0.015em] text-gray-1000"
+              >
+                {renderInline(b.text)}
+              </h2>
+            );
+
+          /* The type is identical to the body around it, so THE BAR IS THE
+             ENTIRE SIGNAL — which is why it's a real one. It used to be a 2px
+             alpha-300 border, ten percent black, near enough invisible on a
+             white page; survivable only while the quote was also two steps
+             larger than the body. When you remove one signal, audit the ones
+             you left in.
+
+             A flex child rather than a border-left, because a border can't be
+             rounded on its own and a squared-off bar reads as a table rule.
+             No vertical margin on it, so flex's default `stretch` runs it the
+             full height of the quote including the citation. */
+          case "quote":
+            return (
+              <blockquote key={i} className="reveal my-9 flex gap-4">
+                <span aria-hidden className="w-[3px] shrink-0 rounded-full bg-gray-500" />
+                <div className="text-[14px] leading-[1.75] text-gray-1000">
+                  {renderInline(b.text)}
+                  {/* not-italic is required — <cite> carries UA italics that the
+                      global `em, i { font-style: normal }` rule doesn't reach. */}
+                  {b.cite && (
+                    <cite className="mt-2 block text-[13px] not-italic text-quiet">— {b.cite}</cite>
+                  )}
+                </div>
+              </blockquote>
+            );
+
+          /* Aspect ratio declared on a wrapper so the box is reserved before
+             the image loads and nothing shifts. `ring-1` rather than a border,
+             so the outline doesn't participate in the box model and the corner
+             radius stays exact.
+
+             The caption is the point of the figure, not a label on it — what
+             the thing was for, and which constraint shaped it. Set at the note
+             tier so it reads as apparatus; at body size it would compete with
+             the paragraph after it. */
+          case "figure":
+            return (
+              <figure key={i} className="reveal my-9">
+                <div className="overflow-hidden rounded-[10px] bg-gray-100 ring-1 ring-gray-alpha-300">
+                  <div style={{ aspectRatio: b.aspect ?? "16 / 9" }}>
+                    <img
+                      src={b.src}
+                      alt={b.alt}
+                      loading="lazy"
+                      decoding="async"
+                      className="h-full w-full object-cover"
+                    />
+                  </div>
+                </div>
+                <figcaption className="mt-2.5 text-[13px] leading-[1.55] text-faint">
+                  {renderInline(b.caption)}
+                </figcaption>
+              </figure>
+            );
+
+          /* marker: drops the bullets to the quiet tier. At the text colour
+             they read as a column of dark dots pulling the eye down the left
+             edge; quiet, they read as structure. space-y-2 inside vs mb-6
+             below — items belong to each other more than to what follows. */
+          case "ul":
+            return (
+              <ul key={i} className="reveal mb-6 list-disc space-y-2 pl-5 marker:text-gray-500">
+                {b.items.map((it, j) => (
+                  <li key={j}>{renderInline(it)}</li>
+                ))}
+              </ul>
+            );
+          case "ol":
+            return (
+              <ol key={i} className="reveal mb-6 list-decimal space-y-2 pl-5 marker:text-gray-500">
+                {b.items.map((it, j) => (
+                  <li key={j}>{renderInline(it)}</li>
+                ))}
+              </ol>
+            );
+
+          default:
+            return null;
+        }
+      })}
+    </div>
+  );
+}
+
+/**
+ * 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.
+ */
+const TOKENS = /(\*\*[^*]+\*\*|\*[^*]+\*|\[[^\]]+\]\([^)\s]+\))/g;
+const LINK = /^\[([^\]]+)\]\(([^)\s]+)\)$/;
+
+const LINK_CLASS =
+  "underline decoration-gray-alpha-500 decoration-1 underline-offset-[3px] " +
+  "transition-[opacity,text-decoration-color] duration-150 ease-geist " +
+  "hover:decoration-gray-1000 hover:opacity-70";
+
+export function renderInline(text: string): ReactNode {
+  const tokens = text.split(TOKENS).filter(Boolean);
+  return (
+    <>
+      {tokens.map((tok, i) => {
+        if (tok.startsWith("**") && tok.endsWith("**")) {
+          return (
+            <strong key={i} className="font-medium text-gray-1000">
+              {tok.slice(2, -2)}
+            </strong>
+          );
+        }
+
+        const link = LINK.exec(tok);
+        if (link) {
+          const [, label, href] = link;
+          // In-app paths route through the framework's Link; everything else
+          // (mailto:, other origins, files) is a plain anchor, and an http(s)
+          // one opens away from the site.
+          const external = /^https?:/.test(href);
+          return (
+            <a
+              key={i}
+              href={href}
+              className={LINK_CLASS}
+              {...(external ? { target: "_blank", rel: "noopener" } : {})}
+            >
+              {label}
+            </a>
+          );
+        }
+
+        if (tok.startsWith("*") && tok.endsWith("*")) {
+          return (
+            <em key={i} className="text-muted">
+              {tok.slice(1, -1)}
+            </em>
+          );
+        }
+        return <Fragment key={i}>{tok}</Fragment>;
+      })}
+    </>
+  );
+}
+
+/** The same string with its markers removed — for titles, meta and plain text. */
+export function stripInlineMarkup(text: string): string {
+  return text
+    .replace(/\[([^\]]+)\]\([^)\s]+\)/g, "$1")
+    .replace(/\*\*([^*]+)\*\*/g, "$1")
+    .replace(/\*([^*]+)\*/g, "$1");
+}