ThreadSketch: cue-driven weave for 滚谱的扎法

RuitingMa · claude · RuitingMa · commit c935121b3c13 · 2026-05-05T01:30:51.000+10:00
A horizontal field of threads (max 8 slots) that lerps between cue
presets as the reading-line observer in EssayLayout fires stage:cue.
Each preset pairs with a structural insight in the prose:

  empty     — one thread drifting alone.
  strip     — same thread laid flat.
  pipeline  — same thread but zone-colored (accent → fg-dim → accent).
  layers    — eight threads in three loose vertical groups.
  lifecycle — five threads visible through a traveling window mask.
  ticking   — six threads + two phase-offset accent sweep bars.
  recap     — full weave, gentle breathing.

Implementation notes:
- Y positions stored as normalized [0..1] so resize doesn't strand
  threads at stale pixel coords; multiply by current h at draw time.
  Initial render relies on a ResizeObserver since the sticky stage's
  100vh resolves after the ctor's first resize() call.
- Tint reading: scoped tint classes (.tint-dune etc) live on the
  article, not :root — so we read CSS vars from the tinted article
  when present, otherwise fall back to documentElement defaults.
- Lerp half-life ≈ 250ms; transitions feel confident without snapping.

Wired into the STAGES registry as `thread`. 滚谱的扎法 opts in via
its frontmatter `stage: thread`.

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/src/components/ThreadSketch.astro b/src/components/ThreadSketch.astro
@@ -0,0 +1,345 @@
+---
+/*
+ * Thread sketch — 扎 / a horizontal weave that responds to cues.
+ *
+ * Stage for engineering essays whose prose moves through structural
+ * states. Listens for `stage:cue` events from EssayLayout's reading-
+ * line observer and shifts a field of horizontal threads through
+ * preset configurations. Each cue's visual state pairs with a
+ * structural insight in the prose:
+ *
+ *   empty     — one thread drifting; the "before" state.
+ *   strip     — the thread lays flat across the canvas.
+ *   pipeline  — the thread colored in three zones (raw → done).
+ *   layers    — eight threads arranged in three stacked groups.
+ *   lifecycle — threads visible only through a moving window mask.
+ *   ticking   — two perpendicular pulse bars sweep with phase offset.
+ *   recap     — full weave, gentle breathing.
+ *
+ * Per-frame: lerp current params toward target (cue-driven), draw
+ * threads as sine-wobbled polylines, optionally apply a window mask
+ * or sweep bars. Threads have stable random phase + amplitude
+ * multipliers so transitions look organic rather than synced.
+ *
+ * Lifecycle: see src/lib/sketch-lifecycle.ts.
+ */
+---
+
+<canvas id="thread"></canvas>
+
+<script>
+  import { mountSketch } from '../lib/sketch-lifecycle';
+
+  mountSketch(() => {
+    const canvas = document.getElementById('thread') as HTMLCanvasElement | null;
+    if (!canvas) return;
+    const ctx = canvas.getContext('2d');
+    if (!ctx) return;
+
+    const dpr = Math.min(window.devicePixelRatio || 1, 1.5);
+    let w = 0, h = 0;
+
+    function resize() {
+      const rect = canvas!.getBoundingClientRect();
+      w = rect.width;
+      h = rect.height;
+      canvas!.width = w * dpr;
+      canvas!.height = h * dpr;
+      ctx!.setTransform(dpr, 0, 0, dpr, 0, 0);
+    }
+    resize();
+
+    // Read CSS variables once at mount. Tint classes are scoped to the
+    // article (e.g. `.tint-dune`), not :root — so reading from
+    // documentElement gives us the un-tinted defaults (--accent === --fg,
+    // i.e. nearly white). Read from the tinted article when present so
+    // pulses and zone gradients pick up the page's accent. We're torn
+    // down + remounted on SPA swap so any tint change arrives fresh.
+    const tinted = document.querySelector('article[class*="tint-"]') ?? document.documentElement;
+    const cs = getComputedStyle(tinted);
+    const fgDim = (cs.getPropertyValue('--fg-dim').trim() || '#aaa');
+    const accent = (cs.getPropertyValue('--accent').trim() || '#b6a078');
+
+    // Eight thread slots. Each slot is always processed each frame; its
+    // alpha + y are driven by the active preset. Empty cues just hide
+    // most slots by lerping their alpha to 0.
+    const SLOTS = 8;
+    interface Slot {
+      phase: number;
+      freqMult: number;
+      ampMult: number;
+    }
+    const slots: Slot[] = Array.from({ length: SLOTS }, () => ({
+      phase: Math.random() * Math.PI * 2,
+      freqMult: 0.85 + Math.random() * 0.3,
+      ampMult: 0.85 + Math.random() * 0.3,
+    }));
+
+    // A preset is "what target state a cue maps to". yNorm is normalized
+    // [0,1] vertical position; visible booleans become alpha targets.
+    interface Preset {
+      visible: boolean[];
+      yNorm: number[];
+      amplitude: number;
+      freq: number;
+      zoned: number;          // 0..1 — strength of 3-zone gradient
+      pulses: number;         // 0..2 — number of sweep bars
+      lifecycleMask: number;  // 0..1 — strength of traveling window
+      baseAlpha: number;
+    }
+
+    const PRESETS: Record<string, Preset> = {
+      // One thread, alone, drifting more loosely.
+      empty: {
+        visible: [false, false, false, true, false, false, false, false],
+        yNorm:   [0.30,  0.35,  0.40,  0.50, 0.60,  0.65,  0.70,  0.75],
+        amplitude: 8, freq: 0.45, zoned: 0, pulses: 0, lifecycleMask: 0, baseAlpha: 0.35,
+      },
+      // Same single thread, calmed down. The "lays flat" pose.
+      strip: {
+        visible: [false, false, false, true, false, false, false, false],
+        yNorm:   [0.30,  0.35,  0.40,  0.50, 0.60,  0.65,  0.70,  0.75],
+        amplitude: 1.5, freq: 0.30, zoned: 0, pulses: 0, lifecycleMask: 0, baseAlpha: 0.75,
+      },
+      // Same thread but now zone-colored: 3 segments, accent → fg-dim → accent.
+      pipeline: {
+        visible: [false, false, false, true, false, false, false, false],
+        yNorm:   [0.30,  0.35,  0.40,  0.50, 0.60,  0.65,  0.70,  0.75],
+        amplitude: 2, freq: 0.40, zoned: 1, pulses: 0, lifecycleMask: 0, baseAlpha: 0.85,
+      },
+      // Eight threads in three loose bands. Top group, middle group,
+      // bottom group — visually echoes pan / chrome / staff-lines.
+      layers: {
+        visible: [true, true, true,  true, true, true,  true, true],
+        yNorm:   [0.22, 0.28, 0.34,  0.46, 0.52, 0.58,  0.70, 0.76],
+        amplitude: 4, freq: 0.50, zoned: 0, pulses: 0, lifecycleMask: 0, baseAlpha: 0.7,
+      },
+      // Five threads in the middle, but rendered through a moving window.
+      lifecycle: {
+        visible: [false, true, true, true, true, true, false, false],
+        yNorm:   [0.25,  0.36, 0.43, 0.50, 0.57, 0.64, 0.72,  0.80],
+        amplitude: 3, freq: 0.50, zoned: 0, pulses: 0, lifecycleMask: 1, baseAlpha: 0.65,
+      },
+      // Six threads in two groups; two pulses sweep with phase offset.
+      ticking: {
+        visible: [true, true, true,  false, false, true, true, true],
+        yNorm:   [0.30, 0.36, 0.42,  0.50,  0.50,  0.58, 0.64, 0.70],
+        amplitude: 2, freq: 0.40, zoned: 0, pulses: 2, lifecycleMask: 0, baseAlpha: 0.75,
+      },
+      // Full weave, gentle breathing — every slot active.
+      recap: {
+        visible: [true, true, true, true, true, true, true, true],
+        yNorm:   [0.22, 0.30, 0.38, 0.46, 0.54, 0.62, 0.70, 0.78],
+        amplitude: 3, freq: 0.45, zoned: 0, pulses: 0, lifecycleMask: 0, baseAlpha: 0.85,
+      },
+    };
+
+    // Initial state — start at "empty" so a fresh page reads as a held
+    // breath even before the first cue fires (compute in EssayLayout
+    // primes a cue immediately, but rAF may render a frame first).
+    //
+    // y is stored as a *normalized* fraction (0..1) so a resize doesn't
+    // strand thread positions in stale pixel coordinates; we multiply
+    // by current h at draw time. Amplitude stays in pixels — wobble
+    // height should feel the same regardless of canvas height.
+    type AnimState = {
+      alpha: number[];     // per slot 0..1
+      yNorm: number[];     // per slot 0..1
+      amplitude: number;
+      freq: number;
+      zoned: number;
+      pulses: number;
+      lifecycleMask: number;
+      baseAlpha: number;
+    };
+
+    function fromPreset(p: Preset): AnimState {
+      return {
+        alpha: p.visible.map((v) => (v ? 1 : 0)),
+        yNorm: [...p.yNorm],
+        amplitude: p.amplitude,
+        freq: p.freq,
+        zoned: p.zoned,
+        pulses: p.pulses,
+        lifecycleMask: p.lifecycleMask,
+        baseAlpha: p.baseAlpha,
+      };
+    }
+
+    let cur: AnimState = fromPreset(PRESETS.empty);
+    let target: AnimState = fromPreset(PRESETS.empty);
+
+    function setCue(name: string) {
+      const p = PRESETS[name];
+      if (!p) return;
+      target = fromPreset(p);
+    }
+
+    function lerp(a: number, b: number, t: number) { return a + (b - a) * t; }
+    function lerpArr(a: number[], b: number[], t: number) {
+      const out = new Array(a.length);
+      for (let i = 0; i < a.length; i++) out[i] = lerp(a[i], b[i], t);
+      return out;
+    }
+
+    let paused = false;
+    function onPause(e: Event) {
+      paused = !!(e as CustomEvent).detail?.paused;
+    }
+    function onCue(e: Event) {
+      const cue = (e as CustomEvent).detail?.cue;
+      if (typeof cue === 'string') setCue(cue);
+    }
+    window.addEventListener('stage:cue', onCue);
+    window.addEventListener('stage:pause', onPause);
+
+    // ResizeObserver picks up the canvas's actual layout size — the
+    // sticky stage may resolve its 100vh after our initial resize()
+    // runs, and pure window.resize doesn't fire on layout settles.
+    const ro = new ResizeObserver(() => resize());
+    ro.observe(canvas);
+
+    function drawThread(slot: Slot, baseY: number, amplitude: number, freq: number, time: number, alpha: number, zoned: number) {
+      if (alpha < 0.01) return;
+      const STEP = 6;
+      ctx!.beginPath();
+      for (let x = 0; x <= w; x += STEP) {
+        const wave = amplitude * slot.ampMult * Math.sin(slot.freqMult * freq * (x / w) * Math.PI * 4 + slot.phase + time * 0.0006);
+        const y = baseY + wave;
+        if (x === 0) ctx!.moveTo(x, y);
+        else ctx!.lineTo(x, y);
+      }
+      if (zoned > 0.01) {
+        // Three-zone gradient: accent → fg-dim → accent. Mix toward
+        // pure fg-dim as zoned decreases so the transition lerps
+        // smoothly between zoned and unzoned states.
+        const grad = ctx!.createLinearGradient(0, 0, w, 0);
+        grad.addColorStop(0, accent);
+        grad.addColorStop(0.32, accent);
+        grad.addColorStop(0.34, fgDim);
+        grad.addColorStop(0.66, fgDim);
+        grad.addColorStop(0.68, accent);
+        grad.addColorStop(1, accent);
+        ctx!.strokeStyle = grad;
+        ctx!.globalAlpha = alpha * (0.35 + 0.5 * zoned);
+      } else {
+        ctx!.strokeStyle = fgDim;
+        ctx!.globalAlpha = alpha;
+      }
+      ctx!.lineWidth = 1.0;
+      ctx!.stroke();
+    }
+
+    let aborted = false;
+    let rafId = 0;
+    let last = performance.now();
+
+    function frame(time: number) {
+      if (aborted) return;
+      const dt = Math.min(time - last, 64);
+      last = time;
+      if (!paused) {
+        // ~250ms half-life feels confident without snapping.
+        const k = 1 - Math.exp(-dt / 250);
+        cur.alpha = lerpArr(cur.alpha, target.alpha, k);
+        cur.yNorm = lerpArr(cur.yNorm, target.yNorm, k);
+        cur.amplitude = lerp(cur.amplitude, target.amplitude, k);
+        cur.freq = lerp(cur.freq, target.freq, k);
+        cur.zoned = lerp(cur.zoned, target.zoned, k);
+        cur.pulses = lerp(cur.pulses, target.pulses, k);
+        cur.lifecycleMask = lerp(cur.lifecycleMask, target.lifecycleMask, k);
+        cur.baseAlpha = lerp(cur.baseAlpha, target.baseAlpha, k);
+      }
+
+      ctx!.clearRect(0, 0, w, h);
+      ctx!.globalCompositeOperation = 'source-over';
+
+      // Draw threads. yNorm * h resolves to current pixel position so
+      // resize-time changes carry through automatically.
+      for (let i = 0; i < SLOTS; i++) {
+        drawThread(slots[i], cur.yNorm[i] * h, cur.amplitude, cur.freq, time, cur.alpha[i] * cur.baseAlpha, cur.zoned);
+      }
+      ctx!.globalAlpha = 1;
+
+      // Lifecycle window mask: keep only what's inside a feathered
+      // band that travels left → right. After it exits the right, a
+      // brief gap, then it re-enters from the left. Reads as: "things
+      // mount, drift across, unmount."
+      if (cur.lifecycleMask > 0.01) {
+        const period = 5200;
+        const t = (time % period) / period;            // 0..1
+        const winCx = -0.25 * w + t * (1.5 * w);       // sweep -25%..125%
+        const winHalf = w * 0.18;
+        const feather = w * 0.10;
+        ctx!.globalCompositeOperation = 'destination-in';
+        const grad = ctx!.createLinearGradient(0, 0, w, 0);
+        const stops: [number, string][] = [
+          [0, 'rgba(0,0,0,0)'],
+          [Math.max(0, (winCx - winHalf - feather) / w), 'rgba(0,0,0,0)'],
+          [Math.max(0, (winCx - winHalf) / w), `rgba(0,0,0,${cur.lifecycleMask})`],
+          [Math.min(1, (winCx + winHalf) / w), `rgba(0,0,0,${cur.lifecycleMask})`],
+          [Math.min(1, (winCx + winHalf + feather) / w), 'rgba(0,0,0,0)'],
+          [1, 'rgba(0,0,0,0)'],
+        ];
+        // Sort by stop position (Math.max/min may have produced unsorted)
+        stops.sort((a, b) => a[0] - b[0]);
+        for (const [stop, color] of stops) {
+          if (stop >= 0 && stop <= 1) grad.addColorStop(stop, color);
+        }
+        ctx!.fillStyle = grad;
+        ctx!.fillRect(0, 0, w, h);
+
+        // Outside the mask we want full transparency (1 - lifecycleMask
+        // gives a pass-through during transitions so the threads aren't
+        // erased mid-fade between cues).
+        ctx!.globalCompositeOperation = 'destination-over';
+        ctx!.fillStyle = `rgba(0,0,0,${1 - cur.lifecycleMask})`;
+        ctx!.fillRect(0, 0, w, h);
+        ctx!.globalCompositeOperation = 'source-over';
+      }
+
+      // Pulse bars (ticking cue). Two slim accent-colored sweeps, second
+      // offset by a small phase so they read as not-quite-synced — the
+      // visual analog of rAF vs AudioContext.
+      const pulseCount = Math.round(cur.pulses);
+      if (pulseCount > 0) {
+        const period = 3800;
+        const bandTop = h * 0.18;
+        const bandH = h * 0.64;
+        for (let p = 0; p < pulseCount; p++) {
+          const phaseOffset = p * 0.16;
+          const t = (((time / period) + phaseOffset) % 1 + 1) % 1;
+          const x = t * w;
+          const half = 22;
+          const grad = ctx!.createLinearGradient(x - half, 0, x + half, 0);
+          grad.addColorStop(0, 'rgba(0,0,0,0)');
+          grad.addColorStop(0.5, accent);
+          grad.addColorStop(1, 'rgba(0,0,0,0)');
+          ctx!.globalAlpha = 0.55 * (cur.pulses / pulseCount);
+          ctx!.fillStyle = grad;
+          ctx!.fillRect(x - half, bandTop, half * 2, bandH);
+        }
+        ctx!.globalAlpha = 1;
+      }
+
+      rafId = requestAnimationFrame(frame);
+    }
+    rafId = requestAnimationFrame(frame);
+
+    return () => {
+      aborted = true;
+      cancelAnimationFrame(rafId);
+      window.removeEventListener('stage:cue', onCue);
+      window.removeEventListener('stage:pause', onPause);
+      ro.disconnect();
+    };
+  });
+</script>
+
+<style>
+  canvas#thread {
+    display: block;
+    width: 100%;
+    height: 100%;
+  }
+</style>
diff --git a/src/content/essays/gun-pu-de-zha-fa.mdx b/src/content/essays/gun-pu-de-zha-fa.mdx
@@ -4,6 +4,7 @@ date: "2026-05-04"
 kind: ESSAY
 summary: 一份能在网页里横向滚动、声音同步的乐谱组件，从 MEI 到 DOM 怎么一步步扎起来的。
 tint: dune
+stage: thread
 ---
 
 import Score from '../../components/Score.astro';
diff --git a/src/pages/essays/[...slug].astro b/src/pages/essays/[...slug].astro
@@ -2,6 +2,7 @@
 import { getCollection, render } from 'astro:content';
 import EssayLayout from '../../layouts/EssayLayout.astro';
 import BeginSketch from '../../components/BeginSketch.astro';
+import ThreadSketch from '../../components/ThreadSketch.astro';
 
 export async function getStaticPaths() {
   const essays = await getCollection('essays', (e) => import.meta.env.DEV || e.data.published);
@@ -17,6 +18,7 @@ export async function getStaticPaths() {
 // per voice, not one per essay.
 const STAGES = {
   begin: BeginSketch,
+  thread: ThreadSketch,
 } as const;
 type StageKey = keyof typeof STAGES;
 
