reze-engine 0.43.0 → 0.50.1

package/src/midi-loader.ts

@@ -0,0 +1,246 @@
+// Standard MIDI File → MidiNote[], for setMidiNotes.
+//
+// The engine already parses PMX and VMD; this is the third loader and the
+// smallest, because a score needs four numbers per note and a .mid carries far
+// more than that. Everything not needed to place a note in TIME is skipped:
+// instruments, controllers, pitch bend, lyrics, key signatures.
+//
+// THE TEMPO MAP IS THE WHOLE JOB. A MIDI file measures time in ticks against a
+// tempo that changes as often as the music does — the piano transcription this
+// was written against has 89 tempo changes across four minutes, because rubato
+// is what makes it sound played rather than sequenced. Divide by a single
+// average and every note after the first change lands at the wrong moment, and
+// the drift compounds. So tempo changes are collected across ALL tracks first
+// (format 1 puts them in track 0, but nothing requires that), then ticks are
+// integrated through them segment by segment.
+
+import type { MidiNote } from "./engine"
+
+/** A tempo change: from this tick onward, one quarter note lasts this long. */
+type Tempo = { tick: number; usPerQuarter: number }
+
+/** 120 bpm — what the spec says to assume when a file states nothing. */
+const DEFAULT_US_PER_QUARTER = 500000
+
+class Reader {
+  offset = 0
+  constructor(private readonly d: DataView) {}
+  get remaining(): number {
+    return this.d.byteLength - this.offset
+  }
+  u8(): number {
+    return this.d.getUint8(this.offset++)
+  }
+  u16(): number {
+    const v = this.d.getUint16(this.offset)
+    this.offset += 2
+    return v
+  }
+  u32(): number {
+    const v = this.d.getUint32(this.offset)
+    this.offset += 4
+    return v
+  }
+  bytes(n: number): number {
+    // Big-endian integer of n bytes — tempo is three of them.
+    let v = 0
+    for (let i = 0; i < n; i++) v = (v << 8) | this.u8()
+    return v
+  }
+  /** Variable-length quantity: seven bits per byte, high bit continues. */
+  vlq(): number {
+    let v = 0
+    for (;;) {
+      const b = this.u8()
+      v = (v << 7) | (b & 0x7f)
+      if ((b & 0x80) === 0) return v
+    }
+  }
+  tag(): string {
+    return String.fromCharCode(this.u8(), this.u8(), this.u8(), this.u8())
+  }
+}
+
+/** One note-on waiting for its note-off, keyed by channel and pitch. */
+type Pending = { tick: number; velocity: number }
+
+/**
+ * Parse a Standard MIDI File into notes on the scene clock, sorted by onset.
+ *
+ * Throws only on a file that is not a MIDI file at all; a truncated or partly
+ * unreadable track yields the notes it managed rather than nothing, because a
+ * score that plays most of a piece is worth more than an exception.
+ */
+export function parseMidi(data: ArrayBuffer): MidiNote[] {
+  const r = new Reader(new DataView(data))
+  if (r.remaining < 14 || r.tag() !== "MThd") throw new Error("not a MIDI file (no MThd header)")
+  const headerLength = r.u32()
+  const headerEnd = r.offset + headerLength
+  r.u16() // format: 0, 1 and 2 all parse the same way here — every track is read
+  const trackCount = r.u16()
+  const division = r.u16()
+  r.offset = headerEnd
+
+  if (division & 0x8000) {
+    // SMPTE: ticks are absolute frames, so there is no tempo map to apply.
+    // Vanishingly rare for music files and it would silently mis-time
+    // everything, so say so rather than pretend.
+    throw new Error("SMPTE time division is not supported — export the file with a tick-based division")
+  }
+  const ticksPerQuarter = division || 480
+
+  const tempos: Tempo[] = []
+  const raw: { tick: number; on: boolean; pitch: number; velocity: number; channel: number }[] = []
+
+  for (let t = 0; t < trackCount && r.remaining >= 8; t++) {
+    if (r.tag() !== "MTrk") break
+    const length = r.u32()
+    const end = Math.min(r.offset + length, r.offset + r.remaining)
+    let tick = 0
+    // Running status: an event may omit its status byte and inherit the last
+    // one. Dropping this reads the file as garbage from the first omission on.
+    let status = 0
+    while (r.offset < end) {
+      tick += r.vlq()
+      let b = r.u8()
+      if (b & 0x80) {
+        status = b
+        b = r.offset < end ? r.u8() : 0
+      }
+      const kind = status & 0xf0
+      if (status === 0xff) {
+        const meta = b
+        const len = r.vlq()
+        if (meta === 0x51 && len === 3) tempos.push({ tick, usPerQuarter: r.bytes(3) })
+        else r.offset += len
+      } else if (status === 0xf0 || status === 0xf7) {
+        // A sysex length was already consumed into `b` above only if the status
+        // byte was present; re-read defensively from the current position.
+        r.offset -= 1
+        r.offset += r.vlq()
+      } else if (kind === 0xc0 || kind === 0xd0) {
+        // Program change / channel pressure: one data byte, already in `b`.
+      } else if (kind === 0x80 || kind === 0x90) {
+        const velocity = r.offset < end ? r.u8() : 0
+        // Note-on at velocity 0 IS a note-off — the common encoding, because it
+        // lets a run of notes share one running status byte.
+        const on = kind === 0x90 && velocity > 0
+        raw.push({ tick, on, pitch: b, velocity, channel: status & 0x0f })
+      } else {
+        // Everything else with two data bytes: controller, pitch bend, aftertouch.
+        if (r.offset < end) r.u8()
+      }
+    }
+    r.offset = end
+  }
+
+  tempos.sort((a, b) => a.tick - b.tick)
+  // Ticks → seconds, integrating the tempo map. Walked once in tick order
+  // rather than searched per note: the events are already sorted, so this is
+  // linear where a per-note scan would be quadratic on a 1500-note file.
+  const toSeconds = makeTickClock(tempos, ticksPerQuarter)
+
+  raw.sort((a, b) => a.tick - b.tick || (a.on ? 1 : 0) - (b.on ? 1 : 0))
+  const pending = new Map<number, Pending[]>()
+  /**
+   * Note-offs that found nothing to close, by key, in the order they were read.
+   *
+   * At the same tick the sort above puts every off AHEAD of every on, which is
+   * what makes a restrike pair correctly — the release of the held note is read
+   * before the strike that follows it. The cost is a note whose off is at its
+   * own onset tick: genuinely zero-length, and its off arrives before the on
+   * exists to be closed. Dropping it here left the on unpaired, so the note
+   * hung to the end of the file — the one case where the ordering that fixes
+   * restrikes creates a note nothing wrote.
+   *
+   * Kept rather than discarded so the flush below can look again. An off at any
+   * OTHER tick really is stray and stays dropped.
+   */
+  const orphanOffs = new Map<number, number[]>()
+  const notes: MidiNote[] = []
+  for (const e of raw) {
+    const key = e.channel * 128 + e.pitch
+    if (e.on) {
+      const list = pending.get(key)
+      if (list) list.push({ tick: e.tick, velocity: e.velocity })
+      else pending.set(key, [{ tick: e.tick, velocity: e.velocity }])
+      continue
+    }
+    // FIFO against the same key: a pedalled passage can restrike a pitch before
+    // releasing it, and pairing the newest would leave the older one hanging
+    // forever — the note would last the rest of the piece.
+    const list = pending.get(key)
+    const start = list?.shift()
+    if (!start) {
+      const seen = orphanOffs.get(key)
+      if (seen) seen.push(e.tick)
+      else orphanOffs.set(key, [e.tick])
+      continue
+    }
+    const t0 = toSeconds(start.tick)
+    notes.push({
+      start: t0,
+      duration: Math.max(0, toSeconds(e.tick) - t0),
+      pitch: e.pitch,
+      velocity: start.velocity / 127,
+    })
+  }
+  // Anything still held at the end of the file gets the file's own length, so a
+  // missing note-off shows as a long note rather than as a lost one.
+  const lastTick = raw.length ? raw[raw.length - 1].tick : 0
+  for (const [key, list] of pending) {
+    // The pitch comes back out of the map key. Writing a literal 0 here — as
+    // this did — does not lose the note, it MOVES it: every hanging note lands
+    // on C-1, which then drags the score's reported pitch range down to it and
+    // lays every keyboard out against an octave nothing plays in.
+    const pitch = key % 128
+    const orphans = orphanOffs.get(key)
+    for (const p of list) {
+      const t0 = toSeconds(p.tick)
+      // The second look: an off read at this note's OWN tick is its off, seen
+      // early because same-tick offs sort first. One off closes one note, so it
+      // is consumed — two zero-length strikes of a pitch need two offs.
+      const i = orphans ? orphans.indexOf(p.tick) : -1
+      if (i >= 0) {
+        orphans!.splice(i, 1)
+        notes.push({ start: t0, duration: 0, pitch, velocity: p.velocity / 127 })
+        continue
+      }
+      notes.push({ start: t0, duration: Math.max(0, toSeconds(lastTick) - t0), pitch, velocity: p.velocity / 127 })
+    }
+  }
+
+  notes.sort((a, b) => a.start - b.start)
+  return notes
+}
+
+/** Tick → seconds through the tempo map, as a closure over the segments. */
+function makeTickClock(tempos: Tempo[], ticksPerQuarter: number): (tick: number) => number {
+  // Precompute the elapsed seconds at each tempo change, so a lookup is a walk
+  // over segments rather than a re-integration from zero.
+  const marks: { tick: number; seconds: number; usPerQuarter: number }[] = []
+  let seconds = 0
+  let lastTick = 0
+  let us = tempos.length && tempos[0].tick === 0 ? tempos[0].usPerQuarter : DEFAULT_US_PER_QUARTER
+  marks.push({ tick: 0, seconds: 0, usPerQuarter: us })
+  for (const t of tempos) {
+    if (t.tick > lastTick) {
+      seconds += ((t.tick - lastTick) * us) / ticksPerQuarter / 1e6
+      lastTick = t.tick
+    }
+    us = t.usPerQuarter
+    marks.push({ tick: t.tick, seconds, usPerQuarter: us })
+  }
+  return (tick: number): number => {
+    // Binary search for the last mark at or before `tick`.
+    let lo = 0
+    let hi = marks.length - 1
+    while (lo < hi) {
+      const mid = (lo + hi + 1) >> 1
+      if (marks[mid].tick <= tick) lo = mid
+      else hi = mid - 1
+    }
+    const m = marks[lo]
+    return m.seconds + ((tick - m.tick) * m.usPerQuarter) / ticksPerQuarter / 1e6
+  }
+}

package/src/model.ts

@@ -17,6 +17,7 @@ import {
   IkKeyframe,
   MorphKeyframe,
   interpolateControlPoints,
+  retiredMorphs,
   rawInterpolationToBoneInterpolation,
 } from "./animation"
 
@@ -207,7 +208,7 @@ export interface Morphing {
 }
 
 // CSR inversion of vertex-morph offsets for the GPU compute pass (built once at load).
-export interface MorphComputeData {
+interface MorphComputeData {
   basePositions: Float32Array // vertexCount * 3
   rowStart: Uint32Array // vertexCount + 1 (prefix offsets into the entry arrays)
   colMorph: Uint32Array // entryCount (morph index per entry)
@@ -218,7 +219,7 @@ export interface MorphComputeData {
 }
 
 // Runtime skeleton pose state (updated each frame)
-export interface SkeletonRuntime {
+interface SkeletonRuntime {
   nameIndex: Record<string, number> // Cached lookup: bone name -> bone index (built on initialization)
   localRotations: Quat[] // quat per bone
   localTranslations: Vec3[] // vec3 per bone
@@ -228,7 +229,7 @@ export interface SkeletonRuntime {
 }
 
 // Runtime morph state
-export interface MorphRuntime {
+interface MorphRuntime {
   nameIndex: Record<string, number> // Cached lookup: morph name -> morph index
   weights: Float32Array // One weight per morph (0.0 to 1.0)
 }
@@ -1549,7 +1550,17 @@ export class Model {
     return { boneTracks, morphTracks, frameCount: maxFrame }
   }
 
-  loadVmd(name: string, urlOrRelative: string): Promise<void> {
+  /**
+   * Load a VMD as the clip called `name`.
+   *
+   * `tracks: "morphs"` takes only the expression half and lays it over whatever
+   * clip `name` already holds — see AnimationState.setMorphTracks for why an
+   * morph file overwrites rather than merges. Everything else about the
+   * load is identical, which is the reason it is an option here rather than a
+   * second method: the path resolution below (site fetch, blob, or a folder
+   * upload's asset reader) is the part nobody should own twice.
+   */
+  loadVmd(name: string, urlOrRelative: string, options?: { tracks?: "all" | "morphs" }): Promise<void> {
     const loadBuffer = (): Promise<ArrayBuffer> => {
       const u = urlOrRelative.trim()
       const useSiteFetch =
@@ -1575,6 +1586,13 @@ export class Model {
     return loadBuffer().then((buf) => {
       const vmdKeyFrames = VMDLoader.loadFromBuffer(buf)
       const clip = this.buildClipFromVmdKeyFrames(vmdKeyFrames)
+      if (options?.tracks === "morphs") {
+        this.clearRetiredMorphs(name, clip.morphTracks)
+        this.animationState.setMorphTracks(name, clip.morphTracks, clip.frameCount)
+        return
+      }
+      // A whole new clip retires the old one's morphs for the same reason.
+      this.clearRetiredMorphs(name, clip.morphTracks)
       // The IK block lives past every other section, so it is read separately
       // rather than threaded through the keyframe grouping.
       const ikFrames = VMDLoader.loadIkFromBuffer(buf)
@@ -1594,6 +1612,18 @@ export class Model {
     })
   }
 
+  /** Zero the morphs a replaced track set drove and the new one does not, so
+   *  the face it left behind does not sit frozen under the new morphs.
+   *  See retiredMorphs for why nothing else clears them. */
+  private clearRetiredMorphs(name: string, next: Map<string, MorphKeyframe[]>): void {
+    for (const morphName of retiredMorphs(this.animationState.getAnimationClip(name), next)) {
+      const idx = this.runtimeMorph.nameIndex[morphName]
+      if (idx === undefined) continue
+      this.runtimeMorph.weights[idx] = 0
+      this.morphsDirty = true
+    }
+  }
+
   loadClip(name: string, clip: AnimationClip): void {
     this.animationState.loadAnimation(name, clip)
   }

package/src/param-track.ts

@@ -0,0 +1,83 @@
+/**
+ * A material parameter over time.
+ *
+ * The other half of step 5: dissolve, teleport, a look that changes on a beat.
+ * The per-material channel already exists — setStyleParam writes straight into
+ * the style uniform — so what was missing was only a way to drive it from the
+ * scene clock rather than from whenever a caller happened to fire.
+ *
+ * WHY THE SAMPLING LIVES HERE, alone in its own file: everything else in this
+ * feature needs a GPU, and this does not. Keeping it pure is what lets the
+ * interpolation be tested exhaustively in a headless suite, which matters
+ * because it is the part with edge cases — the ends, a single key, keys at the
+ * same instant.
+ *
+ * NOT bezier. Bone animation has curves because a VMD carries them and a body
+ * needs ease; a material parameter is a dial, and a dial that needs shaping can
+ * be shaped by placing more keys. If eased segments are ever wanted, they
+ * belong as a property ON a key, not as a second sampler.
+ *
+ * DETERMINISTIC BY CONSTRUCTION: the value is a pure function of the scene
+ * clock, so an offline export stepping frame by frame produces exactly what
+ * playback did. Anything read from wall time would not, which is the same rule
+ * the score and audio interfaces already follow.
+ */
+
+/** A parameter value: a scalar, or a vector for the vec3 params. */
+export type ParamValue = number | [number, number, number]
+
+export type ParamKey = {
+  /** Seconds on the SCENE clock — the same clock an export steps. */
+  t: number
+  v: ParamValue
+}
+
+const lerp = (a: number, b: number, k: number): number => a + (b - a) * k
+
+/**
+ * The value at `t`.
+ *
+ * Outside the track it HOLDS rather than extrapolating: a parameter that ran
+ * off the end of its keys and kept going would leave the scene somewhere its
+ * author never described, and the last key is the last thing they said.
+ *
+ * Keys must be sorted by `t` — setStyleParamTrack sorts on the way in, so this
+ * can binary-search rather than scan, and a track with a thousand keys costs
+ * the same per frame as one with four.
+ */
+export function sampleParamTrack(keys: ParamKey[], t: number): ParamValue | null {
+  if (keys.length === 0) return null
+  if (keys.length === 1 || t <= keys[0].t) return keys[0].v
+  const last = keys[keys.length - 1]
+  if (t >= last.t) return last.v
+
+  // The last key at or before t.
+  let lo = 0
+  let hi = keys.length - 1
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >> 1
+    if (keys[mid].t <= t) lo = mid
+    else hi = mid - 1
+  }
+  const a = keys[lo]
+  const b = keys[lo + 1]
+  const span = b.t - a.t
+  // Two keys at the same instant are a STEP, and the later one wins. Dividing
+  // by the zero span would be a NaN written into a uniform every frame.
+  if (span <= 0) return b.v
+  const k = (t - a.t) / span
+  if (typeof a.v === "number" && typeof b.v === "number") return lerp(a.v, b.v, k)
+  // Mixed scalar and vector keys are an authoring mistake, not something to
+  // guess at: hold the segment's start rather than inventing a conversion.
+  if (typeof a.v === "number" || typeof b.v === "number") return a.v
+  return [lerp(a.v[0], b.v[0], k), lerp(a.v[1], b.v[1], k), lerp(a.v[2], b.v[2], k)]
+}
+
+/** Whether a freshly sampled value differs from the last one written. Tracks are
+ *  evaluated every frame and most of them are flat most of the time, so this is
+ *  what keeps a still scene from writing a uniform per parameter per frame. */
+export function paramChanged(a: ParamValue | null, b: ParamValue | null): boolean {
+  if (a === null || b === null) return a !== b
+  if (typeof a === "number" || typeof b === "number") return a !== b
+  return a[0] !== b[0] || a[1] !== b[1] || a[2] !== b[2]
+}

package/src/physics/types.ts

@@ -14,7 +14,10 @@ export enum RigidbodyShape {
 export enum RigidbodyType {
   Static = 0, // follows bone (anchor)
   Dynamic = 1,
-  Kinematic = 2, // follows bone (legacy alias; loader no longer emits it)
+  // The loader no longer emits this — it maps mode 2 to Dynamic, which is the
+  // fix above. The member stays because the physics step still names it when
+  // asking "does this body follow its bone", and a host may set it directly.
+  Kinematic = 2,
 }
 
 export interface Rigidbody {

package/src/reflection.ts

@@ -0,0 +1,94 @@
+// The mirror camera, as arithmetic — pure and headlessly testable, the
+// shadow-cascades precedent.
+//
+// A planar reflection is not a second camera aimed by hand; it is the SAME
+// camera with the world reflected about the floor plane. Fold the reflection
+// into the view matrix and everything downstream is untouched: world positions
+// stay TRUE world positions, so sun, shadows and positional lights evaluate at
+// the unmirrored point — which is exactly what a mirror shows, an object lit
+// as it is, seen from a mirrored eye. The only other value that must mirror is
+// the eye itself, because specular reads the view direction from it.
+//
+// Winding: a reflection has determinant -1, so triangle orientation flips.
+// Every scene-pass pipeline that draws into the mirror culls "none", which is
+// what makes this legal without a flipped-frontFace pipeline set. The OUTLINE
+// culls "back" and is therefore skipped in the mirror — its hull would face
+// the wrong way and ink over the model.
+
+/**
+ * The debug view: the reflection target drawn over the finished frame — the
+ * only way to SEE whether the mirror pass is right before anything consumes
+ * it, the same instrument discipline as setIdDebug. The target is HDR linear;
+ * a Reinhard fold plus a square-root keeps highlights readable without
+ * involving the real view transform, which a diagnostic does not need.
+ */
+export const REFLECTION_DEBUG_WGSL = /* wgsl */ `
+@group(0) @binding(0) var t: texture_2d<f32>;
+@group(0) @binding(1) var s: sampler;
+
+struct VSOut { @builtin(position) pos: vec4f, @location(0) uv: vec2f, };
+
+@vertex fn vs(@builtin(vertex_index) i: u32) -> VSOut {
+  var out: VSOut;
+  let x = f32(i32(i / 2u) * 4 - 1);
+  let y = f32(i32(i % 2u) * 4 - 1);
+  out.pos = vec4f(x, y, 0.0, 1.0);
+  out.uv = vec2f(x * 0.5 + 0.5, 0.5 - y * 0.5);
+  return out;
+}
+
+@fragment fn fs(in: VSOut) -> @location(0) vec4f {
+  let c = textureSample(t, s, in.uv).rgb;
+  return vec4f(sqrt(c / (vec3f(1.0) + c)), 1.0);
+}
+`
+
+/**
+ * Reflection about the horizontal plane y = h, column-major.
+ *
+ *   p' = (x, 2h - y, z)
+ */
+export function reflectionAboutY(h: number): Float32Array {
+  // prettier-ignore
+  return new Float32Array([
+    1, 0, 0, 0,
+    0, -1, 0, 0,
+    0, 0, 1, 0,
+    0, 2 * h, 0, 1,
+  ])
+}
+
+/**
+ * Fill a camera-uniform block for the mirror pass from the live one.
+ *
+ * Layout is the material CameraUniforms: view at 0, projection at 16, eye at
+ * 32, render-target height at 35 — the same 36 floats the main camera writes,
+ * copied rather than re-derived so the two cannot disagree about anything but
+ * the reflection.
+ *
+ * view' = view × R (column-vector convention, matching `projection * view *
+ * pos` in the vertex shaders); projection unchanged; eye reflected.
+ */
+export function buildMirrorCamera(camera: Float32Array, planeY: number, out: Float32Array): Float32Array {
+  const v = camera
+  const h = planeY
+  // view × R where R = reflectionAboutY(h). R only touches column 1 (scaled by
+  // -1) and adds 2h·col1 to the translation — write the product directly
+  // rather than through a generic multiply, so the arithmetic is exact and the
+  // cost is a handful of ops.
+  for (let i = 0; i < 16; i++) out[i] = v[i]
+  out[4] = -v[4]
+  out[5] = -v[5]
+  out[6] = -v[6]
+  out[7] = -v[7]
+  out[12] = v[12] + 2 * h * v[4]
+  out[13] = v[13] + 2 * h * v[5]
+  out[14] = v[14] + 2 * h * v[6]
+  out[15] = v[15] + 2 * h * v[7]
+  for (let i = 16; i < 32; i++) out[i] = v[i]
+  out[32] = v[32]
+  out[33] = 2 * h - v[33]
+  out[34] = v[34]
+  out[35] = v[35]
+  return out
+}

package/src/shaders/anchor-table.ts

@@ -0,0 +1,147 @@
+// The scene's anchor table: one deduplicated set of bones for every effect in
+// the scene, plus the per-effect alias that maps an author's slot onto it.
+//
+// THE PROBLEM IT SOLVES. A slot number is currently two things at once: the
+// author's name for a bone, and its storage address in the cast buffer. Those
+// coincide only while one effect exists. Install two and slot 0 means a
+// different bone to each of them, so whichever wrote last wins and the other
+// silently reads someone else's hand.
+//
+// The fix is to stop conflating them. Bones are allocated ONCE for the scene,
+// deduplicated, and each effect is spliced a private `_rzSlot(local) -> global`
+// that the accessors route through. Author source is untouched — a published
+// effect keeps compiling and keeps its line numbers, which matters because line
+// numbers are what an author debugs against.
+//
+// Three things fall out of it beyond fixing the clash:
+//   · two effects wanting the same trail SHARE one ring, and trails are the
+//     expensive resource — 128 samples × 4 subjects each;
+//   · the cap becomes 8 distinct bones per SCENE rather than per file;
+//   · it is the same indirection the skeleton data interface needs later, so
+//     this is a bridge rather than a detour.
+
+interface AnchorRequest {
+  bone: string
+  trail: boolean
+}
+
+/** The empty table — a scene with no effect installed asks for no bones. */
+export const EMPTY_ANCHOR_TABLE: AnchorTable = { entries: [], alias: [], dropped: [] }
+
+export interface AnchorTable {
+  /** The scene's bones, deduplicated, in allocation order. Storage addresses. */
+  entries: AnchorRequest[]
+  /** Per effect, local slot → global slot; -1 for a request the cap refused. */
+  alias: number[][]
+  /** What the cap refused, so an install can say so instead of going quiet. */
+  dropped: { effect: number; bone: string }[]
+}
+
+/**
+ * Allocate the scene's anchors from what each effect asked for.
+ *
+ * Deduplicated by BONE, not by (bone, trail): a request for a trail and a
+ * request for the bare position are the same bone, and one entry with the trail
+ * turned on satisfies both. Keying on the pair would spend two of eight slots
+ * describing one wrist.
+ *
+ * Order is first-come, so a single effect gets the identity alias and the whole
+ * mechanism is a no-op until a second effect exists — which is what makes this
+ * safe to land before setEffects does.
+ */
+export function buildAnchorTable(requests: AnchorRequest[][], max: number): AnchorTable {
+  const entries: AnchorRequest[] = []
+  const index = new Map<string, number>()
+  const alias: number[][] = []
+  const dropped: { effect: number; bone: string }[] = []
+
+  for (let e = 0; e < requests.length; e++) {
+    const local: number[] = []
+    for (const req of requests[e]) {
+      let g = index.get(req.bone)
+      if (g === undefined) {
+        if (entries.length >= max) {
+          // Refused, and the effect still installs: an effect that loses one of
+          // its anchors draws that one wrong, where refusing the install would
+          // lose the whole scene's visuals over a bone.
+          dropped.push({ effect: e, bone: req.bone })
+          local.push(-1)
+          continue
+        }
+        g = entries.length
+        index.set(req.bone, g)
+        entries.push({ bone: req.bone, trail: req.trail })
+      } else if (req.trail) {
+        // A later request for the same bone can only ever ADD the trail — the
+        // ring is shared, and turning it on for one reader turns it on for all.
+        entries[g].trail = true
+      }
+      local.push(g)
+    }
+    alias.push(local)
+  }
+
+  return { entries, alias, dropped }
+}
+
+/**
+ * Ribbon index → LOCAL anchor slot, for the trail draw.
+ *
+ * A THIRD index space, and the one that bit. The trail pass draws one ribbon per
+ * TRAILED anchor, so its instance index counts 0,1,2… over trailed anchors only
+ * — while the cast buffer is addressed by DECLARATION slot. Those coincide
+ * exactly when every anchor is trailed, which is true of all 14 library effects
+ * and is why this stayed latent: declare `@anchor 頭` then `@anchor 左手首 trail`
+ * and ribbon 0 asked for the trail of 頭, which has none, so the ribbon silently
+ * did not draw.
+ *
+ * Feeding this into _rzSlot afterwards is what makes the chain complete:
+ * ribbon → local slot → scene slot.
+ */
+export function ribbonSlotWgsl(localSlots: number[]): string {
+  const identity = localSlots.every((s, i) => s === i)
+  if (identity) {
+    return `
+/** Ribbon index → local anchor slot. Identity: every anchor is trailed. */
+fn _rzRibbonSlot(ribbon: i32) -> i32 { return ribbon; }
+`
+  }
+  const cases = localSlots.map((s, i) => `    case ${i}: { return ${s}; }`).join("\n")
+  return `
+/** Ribbon index → local anchor slot, skipping the anchors with no trail. */
+fn _rzRibbonSlot(ribbon: i32) -> i32 {
+  switch ribbon {
+${cases}
+    default: { return -1; }
+  }
+}
+`
+}
+
+/**
+ * The alias as WGSL, spliced into each effect's module.
+ *
+ * A switch rather than an array because a const array indexed by a runtime value
+ * lowers badly on the Metal backend — the same reason the filmic curve became a
+ * texture. With one effect this compiles to `return local`, which every backend
+ * folds away.
+ */
+export function anchorAliasWgsl(alias: number[]): string {
+  const identity = alias.every((g, i) => g === i)
+  if (identity) {
+    return `
+/** Local slot → scene slot. Identity here: this effect owns the table. */
+fn _rzSlot(local: i32) -> i32 { return local; }
+`
+  }
+  const cases = alias.map((g, i) => `    case ${i}: { return ${g}; }`).join("\n")
+  return `
+/** Local slot → scene slot, from the deduplicated table this effect shares. */
+fn _rzSlot(local: i32) -> i32 {
+  switch local {
+${cases}
+    default: { return -1; }
+  }
+}
+`
+}