reze-engine 0.42.3 → 0.50.0

package/dist/shaders/lights.js

@@ -0,0 +1,269 @@
+// 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, max) {
+    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) {
+    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, sceneApi, cast) {
+    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, binding) {
+    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/dist/shaders/lyrics-api.d.ts

@@ -0,0 +1,39 @@
+export declare const LYRIC_LINES_MAX = 256;
+export declare const LYRIC_HEADER = 4;
+export declare const LYRIC_STRIDE = 8;
+export declare const LYRICS_FLOATS: number;
+/** 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 declare const LYRIC_ATLAS_MAX_W = 2048;
+export declare 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 declare function parseLRC(source: string): LyricLine[];
+/** Fill the shared buffer's floats from parsed lines, clamped to the cap. */
+export declare function packLyrics(lines: LyricLine[], rects?: LyricRect[]): Float32Array<ArrayBuffer>;
+/** The rzLyric* timing accessors, with the buffer declared at the given binding. */
+export declare function lyricsApi(group: number, binding: number): string;
+/**
+ * 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 declare function lyricsTextApi(group: number, texBinding: number, samplerName: string): string;
+//# sourceMappingURL=lyrics-api.d.ts.map

package/dist/shaders/lyrics-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lyrics-api.d.ts","sourceRoot":"","sources":["../../src/shaders/lyrics-api.ts"],"names":[],"mappings":"AAsBA,eAAO,MAAM,eAAe,MAAM,CAAA;AAClC,eAAO,MAAM,YAAY,IAAI,CAAA;AAC7B,eAAO,MAAM,YAAY,IAAI,CAAA;AAC7B,eAAO,MAAM,aAAa,QAAgD,CAAA;AAE1E;;;gFAGgF;AAChF,eAAO,MAAM,iBAAiB,OAAO,CAAA;AACrC,eAAO,MAAM,iBAAiB,OAAO,CAAA;AAErC,MAAM,MAAM,SAAS,GAAG;IACtB,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAA;IACb,8EAA8E;IAC9E,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED,iFAAiF;AACjF,MAAM,MAAM,SAAS,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;AAExD;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,CA+BpD;AAED,6EAA6E;AAC7E,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,KAAK,CAAC,EAAE,SAAS,EAAE,GAAG,YAAY,CAAC,WAAW,CAAC,CAkB7F;AAED,oFAAoF;AACpF,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAsDhE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAgC5F"}

package/dist/shaders/lyrics-api.js

@@ -0,0 +1,187 @@
+// 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;
+/**
+ * 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) {
+    let offset = 0;
+    const stamped = [];
+    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 = [];
+    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, rects) {
+    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, binding) {
+    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, texBinding, samplerName) {
+    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));
+}
+`;
+}

package/dist/shaders/materials/common.d.ts

@@ -1,6 +1,4 @@
-export declare const COMMON_BINDINGS_WGSL = "\n\nstruct CameraUniforms {\n  view: mat4x4f,\n  projection: mat4x4f,\n  viewPos: vec3f,\n  _padding: f32,\n};\n\nstruct Light {\n  direction: vec4f,\n  color: vec4f,\n};\n\nstruct LightUniforms {\n  ambientColor: vec4f,\n  lights: array<Light, 4>,\n};\n\n// Per-material uniforms. Every material binds this layout even if it ignores fields;\n// the engine keeps one bind group layout across all material pipelines. The PMX\n// classic-material fields (ambient/specular/shininess) are carried for graph nodes that\n// want them; most graphs read only diffuseColor + alpha.\nstruct MaterialUniforms {\n  diffuseColor: vec3f,   // PMX diffuse rgb \u2014 the material_diffuse node reads this\n  alpha: f32,            // 0 \u2192 discard; <1 \u2192 transparent draw call\n  ambient: vec3f,        // PMX ambient rgb\n  shininess: f32,        // PMX specular power\n  specular: vec3f,       // PMX specular rgb\n  sphereMode: f32,       // 0 none \u00B7 1 multiply (sph) \u00B7 2 add (spa)\n  // Skeleton index of the \u982D (head) bone, or -1. Lets the eye shader gate\n  // the post-alpha-eye stencil by camera-vs-face hemisphere.\n  headBoneIndex: f32,\n  _pad0: f32,\n  _pad1: f32,\n  _pad2: f32,\n};\n\nstruct VertexOutput {\n  @builtin(position) position: vec4f,\n  @location(0) normal: vec3f,\n  @location(1) uv: vec2f,\n  @location(2) worldPos: vec3f,\n  // Bind-pose object-space position (the raw pre-skin vertex attribute). Procedural\n  // textures (noise bump, sparkle, Generated-coord gradients) key off this instead of\n  // worldPos so the pattern rides with the surface \u2014 otherwise the mesh swims through a\n  // world-static noise field under any skinning deformation or root (\u30BB\u30F3\u30BF\u30FC) motion.\n  // At rest skinMats are identity so restPos == worldPos, which is why existing noise-\n  // scale constants stay valid without retuning.\n  @location(3) restPos: vec3f,\n};\n\nstruct LightVP { viewProj: mat4x4f, };\n\n@group(0) @binding(0) var<uniform> camera: CameraUniforms;\n@group(0) @binding(1) var<uniform> light: LightUniforms;\n@group(0) @binding(2) var diffuseSampler: sampler;\n@group(0) @binding(3) var shadowMap: texture_depth_2d;\n@group(0) @binding(4) var shadowSampler: sampler_comparison;\n@group(0) @binding(5) var<uniform> lightVP: LightVP;\n// binding(9) brdfLut is declared inside NODES_WGSL (nodes.ts).\n@group(1) @binding(0) var<storage, read> skinMats: array<mat4x4f>;\n@group(2) @binding(0) var diffuseTexture: texture_2d<f32>;\n@group(2) @binding(1) var<uniform> material: MaterialUniforms;\n// Reserved for future sphere/toon graph nodes; graphs that don't read them get the\n// 1\u00D71 white fallback bound here.\n@group(2) @binding(2) var toonTexture: texture_2d<f32>;\n@group(2) @binding(3) var sphereTexture: texture_2d<f32>;\n// Extra maps supplied by the STYLE GROUP rather than by the PMX \u2014 the lightmap /\n// ILM / ramp textures a Blender-authored look is built on. A PMX material carries\n// exactly one image, and this whole family of shading encodes shadow thresholds,\n// specular masks and material IDs in the channels of a second and third. Unset\n// slots get the 1\u00D71 white fallback, so a graph reading one that was never\n// supplied sees white rather than garbage.\n@group(2) @binding(5) var groupTexture0: texture_2d<f32>;\n@group(2) @binding(6) var groupTexture1: texture_2d<f32>;\n@group(2) @binding(7) var groupTexture2: texture_2d<f32>;\n@group(2) @binding(8) var groupTexture3: texture_2d<f32>;\n\n// Four-bone blended normals can cancel to ~zero on physics-driven parts\n// (opposing bone rotations at 50/50 weights) \u2014 normalize(0) is 0/0 = NaN,\n// which poisons the whole shading stack and flashes through bloom. Fall\n// back to up for degenerate normals instead.\nfn safe_normal(nIn: vec3f) -> vec3f {\n  let l2 = dot(nIn, nIn);\n  if (l2 < 1e-12) { return vec3f(0.0, 1.0, 0.0); }\n  return nIn * inverseSqrt(l2);\n}\n\n";
-export declare const SAMPLE_SHADOW_WGSL = "\n\nfn sampleShadow(worldPos: vec3f, n: vec3f) -> f32 {\n  if (dot(n, -light.lights[0].direction.xyz) <= 0.0) { return 0.0; }\n  let biasedPos = worldPos + n * 0.08;\n  let lclip = lightVP.viewProj * vec4f(biasedPos, 1.0);\n  let ndc = lclip.xyz / max(lclip.w, 1e-6);\n  let suv = vec2f(ndc.x * 0.5 + 0.5, 0.5 - ndc.y * 0.5);\n  let cmpZ = ndc.z - 0.001;\n  let ts = 1.0 / 4096.0;\n  let s00 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f(-ts, -ts), cmpZ);\n  let s10 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f(0.0, -ts), cmpZ);\n  let s20 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f( ts, -ts), cmpZ);\n  let s01 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f(-ts, 0.0), cmpZ);\n  let s11 = textureSampleCompareLevel(shadowMap, shadowSampler, suv, cmpZ);\n  let s21 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f( ts, 0.0), cmpZ);\n  let s02 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f(-ts,  ts), cmpZ);\n  let s12 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f(0.0,  ts), cmpZ);\n  let s22 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f( ts,  ts), cmpZ);\n  return (s00 + s10 + s20 + s01 + s11 + s21 + s02 + s12 + s22) * (1.0 / 9.0);\n}\n\n";
-export declare const COMMON_VS_WGSL = "\n\n@vertex fn vs(\n  @location(0) position: vec3f,\n  @location(1) normal: vec3f,\n  @location(2) uv: vec2f,\n  @location(3) joints0: vec4<u32>,\n  @location(4) weights0: vec4<f32>\n) -> VertexOutput {\n  var output: VertexOutput;\n  let pos4 = vec4f(position, 1.0);\n  let weightSum = weights0.x + weights0.y + weights0.z + weights0.w;\n  let invWeightSum = select(1.0, 1.0 / weightSum, weightSum > 0.0001);\n  let nw = select(vec4f(1.0, 0.0, 0.0, 0.0), weights0 * invWeightSum, weightSum > 0.0001);\n  var skinnedPos = vec4f(0.0);\n  var skinnedNrm = vec3f(0.0);\n  for (var i = 0u; i < 4u; i++) {\n    let m = skinMats[joints0[i]];\n    let w = nw[i];\n    skinnedPos += (m * pos4) * w;\n    skinnedNrm += (mat3x3f(m[0].xyz, m[1].xyz, m[2].xyz) * normal) * w;\n  }\n  output.position = camera.projection * camera.view * vec4f(skinnedPos.xyz, 1.0);\n  output.normal = skinnedNrm;\n  output.uv = uv;\n  output.worldPos = skinnedPos.xyz;\n  output.restPos = position;\n  return output;\n}\n\n";
-export declare const COMMON_FS_OUT_WGSL = "\n\nstruct FSOut {\n  @location(0) color: vec4f,\n  @location(1) mask: vec4f,\n};\n\n";
+export declare const COMMON_BINDINGS_WGSL: string;
+export declare function commonFsOutWgsl(): string;
 export declare const COMMON_MATERIAL_PRELUDE_WGSL: string;
 //# sourceMappingURL=common.d.ts.map

package/dist/shaders/materials/common.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../../src/shaders/materials/common.ts"],"names":[],"mappings":"AAsBA,eAAO,MAAM,oBAAoB,w1HAyFhC,CAAC;AASF,eAAO,MAAM,kBAAkB,4xCAsB9B,CAAC;AAQF,eAAO,MAAM,cAAc,s+BA8B1B,CAAC;AAsBF,eAAO,MAAM,kBAAkB,0FAO9B,CAAC;AAMF,eAAO,MAAM,4BAA4B,QACwC,CAAA"}
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../../src/shaders/materials/common.ts"],"names":[],"mappings":"AA2BA,eAAO,MAAM,oBAAoB,QAwGhC,CAAC;AAgIF,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAQD,eAAO,MAAM,4BAA4B,QAC0D,CAAA"}