reze-engine 0.43.0 → 0.50.1

package/src/shaders/cast-api.ts

@@ -0,0 +1,123 @@
+// The cast, as data — the sibling of the audio and score interfaces, and shaped
+// like them: one shared buffer, read through accessors, never touched directly.
+//
+// WHY THIS FILE EXISTS. There were two of these. The field, grid and lightEmit
+// modules read the cast through one implementation; the particle and trail
+// modules read the SAME BUFFER through another, written separately, and the
+// particle one had no rzAnchor at all — so a particle effect could ask where a
+// trail had been but not where a wrist is. Neither was wrong; they had simply
+// never been the same code, and the split was invisible until an effect used a
+// mount from each family and its own file stopped compiling in one of them.
+//
+// The two differed only in how the layout reached them: one baked the engine's
+// constants, the other took them as a CastLayout. Every caller of that layout
+// passed the same five constants, so the parameterisation described a freedom
+// that did not exist. Baking them makes this a constant string, which is what
+// lets both families share it without either one deciding the shape.
+//
+// WHAT A HOST MUST SUPPLY. Three names, and deliberately only three:
+//
+//   _rzCast          the buffer, at whatever binding the module puts it on
+//   _rzSlot(i)       the effect's local slot → the scene's, from its alias
+//   rzSubjectCount() how many subjects are live
+//
+// The last is a host's because the two families genuinely disagree on it: the
+// field module reads a count the engine wrote into the view uniform, and the
+// particle module scans the buffer, because it has no view uniform to read.
+// They agree in value. Unifying them would be a behaviour change to every
+// shipped effect for no gain, so the seam stays and is named here instead.
+
+import { EFFECT_ANCHORS, EFFECT_SUBJECTS, EFFECT_TRAIL_BASE, EFFECT_TRAIL_SAMPLES } from "./cast-layout"
+
+export const CAST_API = /* wgsl */ `
+const RZ_SUBJECTS: i32 = ${EFFECT_SUBJECTS};
+const RZ_SAMPLES: i32 = ${EFFECT_TRAIL_SAMPLES};
+/** The anchor ADDRESS SPACE — how many an effect may declare, not how many it
+ *  did. RZ_TRAIL_SLOTS is the per-effect number and is not this one; the two
+ *  being one number was the old trail bug. */
+const RZ_MAX_ANCHORS: i32 = ${EFFECT_ANCHORS};
+const RZ_TRAIL_SAMPLES: i32 = ${EFFECT_TRAIL_SAMPLES};
+
+struct RzSubject {
+  /** On the FLOOR, under the body — where a ring or a magic circle belongs. */
+  root: vec3f,
+  /** At the hips, the middle of the body — where an aura belongs. */
+  center: vec3f,
+  /** Bounding sphere: xyz centre, w radius. Deliberately generous — cull with it. */
+  bounds: vec4f,
+  /** False past the end of the cast, and every field is then zero. */
+  valid: bool,
+}
+
+struct RzAnchor {
+  pos: vec3f,
+  /** World units per second, from the previous frame. Direction for a trail,
+   *  magnitude for anything that should react to how hard someone is moving. */
+  vel: vec3f,
+  /** The bone's forward axis — which way a foot points, where a head looks. */
+  fwd: vec3f,
+  /** False when this rig has no such bone. Check it: the alternative is drawing
+   *  a hand effect at the world origin on every model that spells it differently. */
+  valid: bool,
+}
+
+/** Which model this is, stable across a scene — for per-subject variation. */
+fn rzSubjectId(i: i32) -> u32 {
+  if (i < 0 || i >= rzSubjectCount()) { return 0u; }
+  return u32(_rzCast[i * 3 + 1].w);
+}
+
+fn rzSubject(i: i32) -> RzSubject {
+  var s: RzSubject;
+  s.valid = i >= 0 && i < rzSubjectCount();
+  if (!s.valid) { return s; }
+  let b = i * 3;
+  s.root = _rzCast[b].xyz;
+  s.center = _rzCast[b + 1].xyz;
+  s.bounds = _rzCast[b + 2];
+  return s;
+}
+
+/**
+ * Where a named bone is, this frame.
+ *
+ * The slot is the author's own: the Nth @anchor in their file, in the order
+ * they wrote them. _rzSlot turns that into the scene's address, which is what
+ * keeps two effects that both anchor to a wrist from reading each other's.
+ */
+fn rzAnchor(subject: i32, slot: i32) -> RzAnchor {
+  var a: RzAnchor;
+  a.valid = false;
+  let g = _rzSlot(slot);
+  if (subject < 0 || subject >= rzSubjectCount() || g < 0 || g >= RZ_MAX_ANCHORS) { return a; }
+  let b = ${EFFECT_SUBJECTS * 3} + (g * ${EFFECT_SUBJECTS} + subject) * 3;
+  a.valid = _rzCast[b].w > 0.5;
+  a.pos = _rzCast[b].xyz;
+  a.vel = _rzCast[b + 1].xyz;
+  a.fwd = _rzCast[b + 2].xyz;
+  return a;
+}
+
+/**
+ * How many samples of a path are recorded — 0 for an anchor that asked for no
+ * trail, and for one that has not moved yet.
+ *
+ * Bounded by the anchor cap, NOT by how many anchors asked for a trail. Those
+ * are different index spaces: storage is addressed by anchor slot, so an
+ * untrailed @anchor followed by a trailed one put the trail at index 1 with a
+ * bound of 1 and rzTrail returned zero — a ribbon that silently did not draw.
+ */
+fn rzTrailCount(subject: i32, slot: i32) -> i32 {
+  let g = _rzSlot(slot);
+  if (subject < 0 || subject >= rzSubjectCount() || g < 0 || g >= RZ_MAX_ANCHORS) { return 0; }
+  return i32(_rzCast[${EFFECT_SUBJECTS * 3} + (g * ${EFFECT_SUBJECTS} + subject) * 3 + 2].w);
+}
+
+/** Sample i of a path: xyz where it was, w how many seconds ago. i = 0 is now. */
+fn rzTrail(subject: i32, slot: i32, i: i32) -> vec4f {
+  let n = rzTrailCount(subject, slot);
+  if (i < 0 || i >= n) { return vec4f(0.0); }
+  let base = ${EFFECT_TRAIL_BASE} + (_rzSlot(slot) * ${EFFECT_SUBJECTS} + subject) * RZ_TRAIL_SAMPLES;
+  return _rzCast[base + i];
+}
+`

package/src/shaders/cast-layout.ts

@@ -0,0 +1,20 @@
+/**
+ * The caps the cast buffer is built to, shared by every shader that reads it and
+ * by the engine that fills it. Interpolated into the WGSL rather than written
+ * twice: the layout arithmetic on both sides has to agree exactly, and two
+ * literals that must match are two literals that eventually will not.
+ *
+ * All three are MINIMUMS. Raising one breaks nothing, because effects read
+ * through accessors and loop to the count functions; lowering one does.
+ *
+ * THEIR OWN FILE, and it imports nothing: cast-api.ts needs them to write the
+ * accessors, composite.ts needs them for the rest of its module, and cast-api
+ * is spliced into composite. Left where they were, that is an import cycle,
+ * and the first thing to touch the cycle throws ReferenceError at module load —
+ * the whole engine failing to start on an import order nobody chose.
+ */
+export const EFFECT_SUBJECTS = 4
+export const EFFECT_ANCHORS = 8
+export const EFFECT_TRAIL_SAMPLES = 128
+/** vec4 slot where the trails begin — after the subjects and the anchors. */
+export const EFFECT_TRAIL_BASE = EFFECT_SUBJECTS * 3 + EFFECT_ANCHORS * EFFECT_SUBJECTS * 3

package/src/shaders/lights.ts

@@ -0,0 +1,280 @@
+// Positional lights, as data — the sibling of the cast, audio and score
+// interfaces, and shaped like them: one shared buffer, read through accessors,
+// never touched directly.
+//
+// WHAT THIS IS NOT. The sun is still the ONE key light and it still owns the
+// toon ramp. These are an ADDITIVE layer on top of whatever the material's
+// graph decided, and they deliberately do not re-ramp: two ramped terminators
+// crossing a cheek read as plastic, which is the failure every stylised
+// renderer that bolted a second key light onto a toon shader has shipped. A
+// light here brightens; it does not restate the shading.
+//
+// So there are no per-light shadows, no area lights and no clustering. At this
+// count a flat loop in the fragment shader is cheaper than anything that would
+// avoid it, and the cap is what keeps that true.
+//
+// LAYOUT. A 4-float header (count, then padding that keeps the records
+// vec4-aligned), then MAX_LIGHTS records of 8 floats:
+//
+//   [0..2] position, world space      [3] radius
+//   [4..6] colour PREMULTIPLIED by intensity   [7] type
+//
+// Colour carries intensity because nothing reads them apart: every use is the
+// product, and storing two numbers that are only ever multiplied is two numbers
+// that can disagree. `type` is reserved — every light is a point light today
+// and the loop does not branch on it, so it is honest padding rather than a
+// switch with one case.
+
+import { audioApi } from "./audio-api"
+import { midiApi } from "./midi-api"
+import { lyricsApi } from "./lyrics-api"
+import { clockApi, trailSlotsApi, viewportApi } from "./passes/hosted-api"
+
+/** Floats before the first record. One is the count; the rest keep the records
+ *  vec4-aligned, which is what lets a future pass read them as vec4s. */
+export const LIGHT_HEADER = 4
+/** Floats per light — see the layout above. */
+export const LIGHT_STRIDE = 8
+/**
+ * The cap, and it is a real one: the loop below runs per fragment, so this is
+ * the number that decides whether lights are free or a cost. Sixteen is the
+ * bounded middle tier the design settled on — enough for a stage rig, far below
+ * the point where clustering would start to pay for itself.
+ */
+export const MAX_LIGHTS = 16
+/** Floats in the whole buffer. */
+export const LIGHTS_FLOATS = LIGHT_HEADER + MAX_LIGHTS * LIGHT_STRIDE
+
+/**
+ * `// @lights 3` — how many lights this effect emits.
+ *
+ * Declared, like every other mount: what the file says is what gets allocated,
+ * so an effect that emits none costs no slots and nobody pays for a cap they
+ * did not ask for. Clamped rather than rejected, the same choice `@particles`
+ * makes — an author asking for a hundred gets the most the engine will give and
+ * a scene that still runs.
+ */
+export function parseLightCount(wgsl: string, max: number): number {
+  const m = /^\s*\/\/\s*@lights\s+(\d+)\s*$/m.exec(wgsl)
+  if (!m) return 0
+  return Math.max(1, Math.min(max, parseInt(m[1], 10)))
+}
+
+/**
+ * The RzLight struct, declared in EVERY module a user's source is spliced into.
+ *
+ * One effect file goes into every module it has a mount in, so a foreground
+ * effect that also emits lights compiles its lightEmit inside the FIELD shader
+ * too — where nothing calls it, but it still has to resolve. Leaving the struct
+ * out of those modules is a compile error on a function the author was right to
+ * write, which is the same trap the grid's step-only half documents.
+ */
+export const RZ_LIGHT_STRUCT_WGSL = /* wgsl */ `
+/** What an effect returns for one of its lights. */
+struct RzLight {
+  pos: vec3f,
+  color: vec3f,
+  intensity: f32,
+  radius: f32,
+}
+`
+
+/**
+ * The world's light at a surface facing n — the flat colour, or the installed
+ * HDRI's irradiance (sh[0].w = 1), evaluated from folded SH coefficients (see
+ * ibl.ts for the folding; the shader is a plain polynomial in the normal).
+ *
+ * One string included by every module that declares LightUniforms with the sh
+ * block — the hosted-api lesson: a helper defined in some modules and not
+ * others is a compile error waiting for the first file that crosses them.
+ */
+export const WORLD_AMBIENT_WGSL = /* wgsl */ `
+fn rzWorldAmbient(n: vec3f) -> vec3f {
+  if (light.sh[0].w < 0.5) { return light.ambientColor.xyz; }
+  let x = n.x;
+  let y = n.y;
+  let z = n.z;
+  let c = light.sh[0].xyz
+    + light.sh[1].xyz * y + light.sh[2].xyz * z + light.sh[3].xyz * x
+    + light.sh[4].xyz * (x * y) + light.sh[5].xyz * (y * z)
+    + light.sh[6].xyz * (3.0 * z * z - 1.0) + light.sh[7].xyz * (x * z)
+    + light.sh[8].xyz * (x * x - y * y);
+  return max(c, vec3f(0.0));
+}
+`
+
+/** Does this source define the emit mount? */
+export function hasLightEmit(wgsl: string): boolean {
+  return /\bfn\s+lightEmit\s*\(/.test(wgsl)
+}
+
+/**
+ * The compute module that runs an effect's lightEmit once per light per frame.
+ *
+ *     fn lightEmit(i: u32, time: f32) -> RzLight
+ *
+ * A COMPUTE stage rather than a CPU callback, and that is the whole point:
+ * Fireworks knows where its bursts are as a closed form in WGSL, and mirroring
+ * that on the CPU to place a light would be two derivations of one trajectory
+ * that drift apart. Emitting in the shader means the light is wherever the
+ * effect says it is, on the scene clock — which is also what makes it survive
+ * an offline export frame-stepped at a different rate.
+ *
+ * The author writes local index 0..n-1 and never learns the global one, the
+ * same aliasing the anchor table uses — so installing another effect ahead of
+ * this one moves its lights without touching its source.
+ *
+ * The base arrives in the UNIFORM rather than baked into the text. Baking it
+ * would mean recompiling every emitting effect the moment a scene gained or
+ * lost a document light, because that is what shifts the slots underneath
+ * them — a shader rebuild triggered by moving a lamp.
+ *
+ * The scene API arrives as a STRING rather than being imported, so this module
+ * depends on nothing that depends on it. That API is what lets a lamp aim at
+ * someone: Stage Lights points its beams at rzSubject().root, and a light that
+ * did not know where she was could only sit where the fixture hangs. It also
+ * brings RzLight, which is why this builder does not declare it again.
+ */
+export function buildLightEmitShader(
+  wgsl: string,
+  sceneApi: string,
+  cast: { trailCount: number },
+): string {
+  return /* wgsl */ `
+// read_write HERE and read-only in the material shaders. Different passes, so
+// the two never coexist: this compute runs before the scene pass that reads it.
+@group(0) @binding(0) var<storage, read_write> _rzLightsOut: array<f32>;
+// (time, base slot, count, _) — see buildLightEmitShader on why the base is
+// here and not in the text.
+@group(0) @binding(1) var<uniform> _rzLightU: vec4f;
+// The camera block and the cast — the two buffers the scene API reads. Same
+// contents the field and grid modules bind, so an effect's lightEmit sees the
+// scene exactly as its drawing half does.
+@group(0) @binding(2) var<uniform> viewU: array<vec4<f32>, 15>;
+@group(0) @binding(3) var<storage, read> _rzCast: array<vec4f>;
+${sceneApi}
+// Audio and score at 4 and 5, the same bindings the particle and trail modules
+// put them on. A lamp that pulses on the beat or lights on a note is the whole
+// point of a light an effect owns rather than one the document places, so this
+// is not compile-safety padding — it is the mount's reason to exist.
+${audioApi(0, 4)}
+${midiApi(0, 5)}
+${lyricsApi(0, 6)}
+// The rest of the hosted API. Every one of these is here because the AUTHOR'S
+// WHOLE FILE lands below, not because lightEmit needs it: a trail effect that
+// grows a lamp at its tip compiles its ribbon code in this module too. The math
+// helpers and the Particle struct are NOT repeated — they arrive with the scene
+// API above, and a second copy is a redefinition error in engine code.
+${clockApi("_rzLightU.x", "0.0")}
+// Canvas height — the same number the drawing modules read out of their camera
+// struct, both written from canvas.height, so this name means ONE value in
+// every module. Verified against the writers, not assumed: cameraMatrixData[35]
+// and viewU[6].w have the same source.
+${viewportApi("viewU[6].w")}
+${trailSlotsApi(cast.trailCount)}
+${wgsl}
+
+@compute @workgroup_size(64)
+fn lightEmitMain(@builtin(global_invocation_id) gid: vec3u) {
+  let i = gid.x;
+  // The dispatch is sized to the count, but a workgroup is 64 wide and the
+  // count rarely is — the tail must not write into the next effect's slots.
+  if (i >= u32(_rzLightU.z)) { return; }
+  // Time is a PARAMETER, not an rzTime() call: this same source compiles
+  // inside the field, particle, trail and grid modules, and those already
+  // define rzTime differently or not at all. A parameter needs nothing from
+  // the module it lands in, which is why the field mounts take theirs too.
+  let l = lightEmit(i, _rzLightU.x);
+  // SANITIZED at the one write site, because lightEmit is HOSTED USER CODE and
+  // this buffer feeds every fragment of every material: one NaN position would
+  // poison the whole frame, and WGSL leaves max(NaN, 0) indeterminate, so it
+  // would not even fail the same way on every GPU. A light that fails the
+  // check writes zeros — radius 0 is off. Colour is clamped at zero on top:
+  // this layer is ADDITIVE, and a negative channel would darken what it lands
+  // on and can push HDR negative into bloom.
+  let finite = l.pos.x == l.pos.x && l.pos.y == l.pos.y && l.pos.z == l.pos.z &&
+    l.radius == l.radius && l.intensity == l.intensity &&
+    l.color.x == l.color.x && l.color.y == l.color.y && l.color.z == l.color.z;
+  let c = select(vec3f(0.0), max(l.color * l.intensity, vec3f(0.0)), finite);
+  let b = ${LIGHT_HEADER}u + (u32(_rzLightU.y) + i) * ${LIGHT_STRIDE}u;
+  _rzLightsOut[b] = select(0.0, l.pos.x, finite);
+  _rzLightsOut[b + 1u] = select(0.0, l.pos.y, finite);
+  _rzLightsOut[b + 2u] = select(0.0, l.pos.z, finite);
+  _rzLightsOut[b + 3u] = select(0.0, max(l.radius, 0.0), finite);
+  // Colour carries intensity, exactly as the CPU writer stores it — one product,
+  // one place, so the two producers cannot disagree about what a slot means.
+  _rzLightsOut[b + 4u] = c.x;
+  _rzLightsOut[b + 5u] = c.y;
+  _rzLightsOut[b + 6u] = c.z;
+}
+`
+}
+
+/** The rz*Light accessors, with the buffer declared at the given binding. */
+export function lightsApi(group: number, binding: number): string {
+  return /* wgsl */ `
+@group(${group}) @binding(${binding}) var<storage, read> _rzLights: array<f32>;
+
+const RZ_MAX_LIGHTS: u32 = ${MAX_LIGHTS}u;
+
+/** How many positional lights the scene has. Zero is the ordinary case. */
+fn rzLightCount() -> u32 { return min(u32(_rzLights[0]), RZ_MAX_LIGHTS); }
+
+/** Light i's world position. */
+fn rzLightPos(i: u32) -> vec3f {
+  let b = ${LIGHT_HEADER}u + i * ${LIGHT_STRIDE}u;
+  return vec3f(_rzLights[b], _rzLights[b + 1u], _rzLights[b + 2u]);
+}
+
+/** How far light i reaches. Its falloff is zero AT this distance, not merely
+ *  small, so the light has a bound a cull can be derived from later. */
+fn rzLightRadius(i: u32) -> f32 { return _rzLights[${LIGHT_HEADER}u + i * ${LIGHT_STRIDE}u + 3u]; }
+
+/** Light i's colour, already multiplied by its intensity. */
+fn rzLightColor(i: u32) -> vec3f {
+  let b = ${LIGHT_HEADER}u + i * ${LIGHT_STRIDE}u + 4u;
+  return vec3f(_rzLights[b], _rzLights[b + 1u], _rzLights[b + 2u]);
+}
+
+/**
+ * Every positional light's contribution at a surface point, as light — not as a
+ * finished colour. Multiply by whatever the surface's albedo is.
+ *
+ * WITH NO LIGHTS THIS RETURNS EXACTLY ZERO and the loop never runs, so a scene
+ * that declares none is arithmetically identical to one compiled before lights
+ * existed. That is the property the whole feature is gated on: adding this to
+ * every material must cost nothing until someone asks for a light.
+ *
+ * FALLOFF IS RELATIVE TO THE RADIUS, and deliberately not physical.
+ *
+ * The first version windowed a real inverse-square, and it was unusable: 1/d²
+ * is measured in world units, an MMD character is about 18 of them tall, so a
+ * lamp two metres off her shoulder divided by 37 and an intensity of 4 landed
+ * as 0.06 — invisible. Radius and intensity were fighting, and intensity had no
+ * scale a person could learn.
+ *
+ * So: intensity is the brightness AT the light, radius is where it reaches
+ * zero, and the curve between them is the same shape whatever the scene's
+ * scale. Both dials now mean what they say, which for a composer beats being
+ * right about photons. (1 - t²)² — smooth at both ends, exactly 0 at the
+ * radius, so the bound a cull could be derived from is still real.
+ */
+fn rzLightsDiffuse(p: vec3f, n: vec3f) -> vec3f {
+  var acc = vec3f(0.0);
+  let count = rzLightCount();
+  for (var i = 0u; i < count; i = i + 1u) {
+    let d = rzLightPos(i) - p;
+    let dist = length(d);
+    // Facing the light, and nothing behind it. No wrap or half-lambert: this
+    // layer adds light, and a wrapped term would lift the shadow side, which is
+    // the ramp's business and not this one's.
+    let ndl = max(dot(n, d / max(dist, 1e-4)), 0.0);
+    if (ndl <= 0.0) { continue; }
+    let t = clamp(dist / max(rzLightRadius(i), 1e-4), 0.0, 1.0);
+    let falloff = 1.0 - t * t;
+    acc = acc + rzLightColor(i) * (ndl * falloff * falloff);
+  }
+  return acc;
+}
+`
+}

package/src/shaders/lyrics-api.ts

@@ -0,0 +1,202 @@
+// Lyrics, as data — the fourth timing interface beside audio, the score and
+// the lights, and shaped like them: one shared buffer, read through accessors,
+// never touched directly.
+//
+// An effect gets the TIMING of the words — which line is live at the scene
+// clock, how far through it is — and, in the field module, the words
+// themselves: the host rasterises each line once (Canvas2D; CJK rules out
+// glyph atlases) into a fixed atlas the effect samples through rzLyricText.
+// The look — fill, outline, wipe, motion — is the effect author's, in WGSL.
+//
+// LAYOUT. A 4-float header (count, then padding that keeps the records
+// vec4-aligned), then LYRIC_LINES_MAX records of 8 floats:
+//
+//   [0] start s   [1] end s   [2] character count   [3] reserved
+//   [4..7] atlas rect: u0, vTop, u1, vBottom
+//
+// FIXED SIZE, unlike the score: a song carries tens of lines, not thousands
+// of notes, so capping at 256 costs 8 KB and buys the property that setLyrics
+// is a buffer write — the buffer identity never changes, so nothing ever has
+// to re-bind for lyrics arriving late. The atlas holds the same property by
+// being allocated once at a fixed size (LYRIC_ATLAS_W × LYRIC_ATLAS_H).
+
+export const LYRIC_LINES_MAX = 256
+export const LYRIC_HEADER = 4
+export const LYRIC_STRIDE = 8
+export const LYRICS_FLOATS = LYRIC_HEADER + LYRIC_LINES_MAX * LYRIC_STRIDE
+
+/** Bounds on the line atlas the host packs rasterised lines into. It is sized
+ *  to the track that arrives rather than allocated at the maximum: a scene with
+ *  no lyrics carries a 1×1 placeholder, and a song's atlas is as tall as its
+ *  own lines need. 8192 is the smallest texture dimension WebGPU guarantees. */
+export const LYRIC_ATLAS_MAX_W = 2048
+export const LYRIC_ATLAS_MAX_H = 8192
+
+export type LyricLine = {
+  /** Seconds on the scene clock. */
+  start: number
+  /** Seconds; a parser that has no better answer uses the next line's start. */
+  end: number
+  text: string
+}
+
+/** Where a rasterised line sits in the atlas: u0, vTop, u1, vBottom, in 0..1. */
+export type LyricRect = [number, number, number, number]
+
+/**
+ * Parse an .lrc file: `[mm:ss.xx]` tags (several per line share the text),
+ * an optional `[offset:±ms]` tag, blank-text tags kept as instrumental gaps'
+ * end markers. Lines come out sorted; each line's end is the next line's
+ * start, and the last line gets a ten-second hold. The offset follows the
+ * LRC convention: positive shows lines EARLIER — the knob to turn when the
+ * words feel late against this particular rip.
+ */
+export function parseLRC(source: string): LyricLine[] {
+  let offset = 0
+  const stamped: { start: number; text: string }[] = []
+  for (const raw of source.split(/\r?\n/)) {
+    const off = /^\s*\[offset:\s*([+-]?\d+)\s*\]/i.exec(raw)
+    if (off) {
+      offset = parseInt(off[1], 10) / 1000
+      continue
+    }
+    const tags = [...raw.matchAll(/\[(\d+):(\d{1,2})(?:[.:](\d{1,3}))?\]/g)]
+    if (tags.length === 0) continue
+    const text = raw.slice(tags[tags.length - 1].index! + tags[tags.length - 1][0].length).trim()
+    for (const t of tags) {
+      const frac = t[3] ? parseInt(t[3], 10) / 10 ** t[3].length : 0
+      stamped.push({ start: Math.max(0, parseInt(t[1], 10) * 60 + parseInt(t[2], 10) + frac - offset), text })
+    }
+  }
+  stamped.sort((a, b) => a.start - b.start)
+  const lines: LyricLine[] = []
+  for (let i = 0; i < stamped.length; i++) {
+    // An empty-text stamp is an .lrc idiom for "the previous line ends here";
+    // it closes its predecessor and is not a line of its own.
+    if (stamped[i].text === "") continue
+    const next = stamped[i + 1]
+    lines.push({
+      start: stamped[i].start,
+      end: next ? next.start : stamped[i].start + 10,
+      text: stamped[i].text,
+    })
+  }
+  return lines
+}
+
+/** Fill the shared buffer's floats from parsed lines, clamped to the cap. */
+export function packLyrics(lines: LyricLine[], rects?: LyricRect[]): Float32Array<ArrayBuffer> {
+  const out = new Float32Array(new ArrayBuffer(LYRICS_FLOATS * 4))
+  const n = Math.min(lines.length, LYRIC_LINES_MAX)
+  out[0] = n
+  for (let i = 0; i < n; i++) {
+    const b = LYRIC_HEADER + i * LYRIC_STRIDE
+    out[b] = lines[i].start
+    out[b + 1] = lines[i].end
+    out[b + 2] = lines[i].text.length
+    const r = rects?.[i]
+    if (r) {
+      out[b + 4] = r[0]
+      out[b + 5] = r[1]
+      out[b + 6] = r[2]
+      out[b + 7] = r[3]
+    }
+  }
+  return out
+}
+
+/** The rzLyric* timing accessors, with the buffer declared at the given binding. */
+export function lyricsApi(group: number, binding: number): string {
+  return /* wgsl */ `
+@group(${group}) @binding(${binding}) var<storage, read> _rzLyrics: array<f32>;
+
+/** Lines in the lyric track; 0 when none is loaded, which every accessor
+ *  below tolerates by answering zero rather than reading past the end. */
+fn rzLyricCount() -> i32 { return i32(_rzLyrics[0]); }
+
+fn rzLyricStart(i: i32) -> f32 {
+  if (i < 0 || i >= rzLyricCount()) { return 0.0; }
+  return _rzLyrics[${LYRIC_HEADER} + i * ${LYRIC_STRIDE}];
+}
+
+fn rzLyricEnd(i: i32) -> f32 {
+  if (i < 0 || i >= rzLyricCount()) { return 0.0; }
+  return _rzLyrics[${LYRIC_HEADER} + i * ${LYRIC_STRIDE} + 1];
+}
+
+/** Characters in line i — the number a per-character sweep divides by. */
+fn rzLyricChars(i: i32) -> f32 {
+  if (i < 0 || i >= rzLyricCount()) { return 0.0; }
+  return _rzLyrics[${LYRIC_HEADER} + i * ${LYRIC_STRIDE} + 2];
+}
+
+/** Where line i sits in the lyric atlas: u0, vTop, u1, vBottom. Zero when the
+ *  host never rasterised text — check with rzLyricHasText. */
+fn rzLyricRect(i: i32) -> vec4f {
+  if (i < 0 || i >= rzLyricCount()) { return vec4f(0.0); }
+  let b = ${LYRIC_HEADER} + i * ${LYRIC_STRIDE};
+  return vec4f(_rzLyrics[b + 4], _rzLyrics[b + 5], _rzLyrics[b + 6], _rzLyrics[b + 7]);
+}
+
+fn rzLyricHasText(i: i32) -> bool {
+  let r = rzLyricRect(i);
+  return r.z > r.x;
+}
+
+/** The line live at time t, or -1 between lines and outside the track. */
+fn rzLyricIndex(t: f32) -> i32 {
+  let n = rzLyricCount();
+  for (var i = 0; i < n; i = i + 1) {
+    if (t >= rzLyricStart(i) && t < rzLyricEnd(i)) { return i; }
+  }
+  return -1;
+}
+
+/** How far through line i the clock is, 0..1 — the karaoke sweep. */
+fn rzLyricProgress(i: i32, t: f32) -> f32 {
+  let s = rzLyricStart(i);
+  let e = rzLyricEnd(i);
+  if (e <= s) { return 0.0; }
+  return clamp((t - s) / (e - s), 0.0, 1.0);
+}
+`
+}
+
+/**
+ * The text half — field module only, where the atlas is bound. uv is 0..1
+ * across LINE i's own box, y-up like everything else; the return is glyph
+ * coverage. textureSampleLevel, so it is legal after any branch.
+ */
+export function lyricsTextApi(group: number, texBinding: number, samplerName: string): string {
+  return /* wgsl */ `
+@group(${group}) @binding(${texBinding}) var _rzLyricTex: texture_2d<f32>;
+
+fn rzLyricText(i: i32, uv: vec2f) -> f32 {
+  let r = rzLyricRect(i);
+  if (r.z <= r.x || uv.x < 0.0 || uv.x > 1.0 || uv.y < 0.0 || uv.y > 1.0) { return 0.0; }
+  let at = vec2f(mix(r.x, r.z, uv.x), mix(r.w, r.y, uv.y));
+  return textureSampleLevel(_rzLyricTex, ${samplerName}, at, 0.0).r;
+}
+
+/** Line i's width over its height as rasterised — size a box with it so the
+ *  glyphs keep their proportions on any canvas. */
+fn rzLyricAspect(i: i32) -> f32 {
+  let r = rzLyricRect(i);
+  let h = r.w - r.y;
+  if (h <= 0.0) { return 1.0; }
+  let dim = vec2f(textureDimensions(_rzLyricTex));
+  return ((r.z - r.x) * dim.x) / (h * dim.y);
+}
+
+/**
+ * Line i's box in ATLAS TEXELS. Divide by the size you draw it at to learn
+ * whether you are magnifying or minifying, which is what an edge-sharpening
+ * step needs to know — and the honest way to get it, since a derivative
+ * builtin is illegal after the branches an effect of this kind opens with.
+ */
+fn rzLyricPixels(i: i32) -> vec2f {
+  let r = rzLyricRect(i);
+  return vec2f(r.z - r.x, r.w - r.y) * vec2f(textureDimensions(_rzLyricTex));
+}
+`
+}