reze-engine 0.42.3 → 0.50.0

package/dist/reflection.js

@@ -0,0 +1,93 @@
+// 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) {
+    // 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, planeY, out) {
+    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/dist/shaders/anchor-table.d.ts

@@ -0,0 +1,56 @@
+interface AnchorRequest {
+    bone: string;
+    trail: boolean;
+}
+/** The empty table — a scene with no effect installed asks for no bones. */
+export declare const EMPTY_ANCHOR_TABLE: AnchorTable;
+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 declare function buildAnchorTable(requests: AnchorRequest[][], max: number): AnchorTable;
+/**
+ * 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 declare function ribbonSlotWgsl(localSlots: number[]): string;
+/**
+ * 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 declare function anchorAliasWgsl(alias: number[]): string;
+export {};
+//# sourceMappingURL=anchor-table.d.ts.map

package/dist/shaders/anchor-table.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anchor-table.d.ts","sourceRoot":"","sources":["../../src/shaders/anchor-table.ts"],"names":[],"mappings":"AAsBA,UAAU,aAAa;IACrB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,OAAO,CAAA;CACf;AAED,4EAA4E;AAC5E,eAAO,MAAM,kBAAkB,EAAE,WAAqD,CAAA;AAEtF,MAAM,WAAW,WAAW;IAC1B,+EAA+E;IAC/E,OAAO,EAAE,aAAa,EAAE,CAAA;IACxB,8EAA8E;IAC9E,KAAK,EAAE,MAAM,EAAE,EAAE,CAAA;IACjB,6EAA6E;IAC7E,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;CAC5C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,aAAa,EAAE,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,WAAW,CAiCtF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,MAAM,CAkB3D;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAkBvD"}

package/dist/shaders/anchor-table.js

@@ -0,0 +1,128 @@
+// 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.
+/** The empty table — a scene with no effect installed asks for no bones. */
+export const EMPTY_ANCHOR_TABLE = { entries: [], alias: [], dropped: [] };
+/**
+ * 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, max) {
+    const entries = [];
+    const index = new Map();
+    const alias = [];
+    const dropped = [];
+    for (let e = 0; e < requests.length; e++) {
+        const local = [];
+        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) {
+    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) {
+    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; }
+  }
+}
+`;
+}

package/dist/shaders/audio-api.d.ts

@@ -0,0 +1,3 @@
+/** The rzAudio* accessors, with the buffer declared at the given binding. */
+export declare function audioApi(group: number, binding: number): string;
+//# sourceMappingURL=audio-api.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"audio-api.d.ts","sourceRoot":"","sources":["../../src/shaders/audio-api.ts"],"names":[],"mappings":"AAgBA,6EAA6E;AAC7E,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAgE/D"}

package/dist/shaders/audio-api.js

@@ -0,0 +1,81 @@
+// The audio data interface, as WGSL — shared verbatim by every effect module.
+//
+// The buffer is PRECOMPUTED for the whole track and sampled by time, never fed
+// live from an AnalyserNode. That is not an optimisation: an export steps the
+// engine frame by frame instead of playing in real time, so a live analyser
+// would return silence during a render and every audio-reactive effect would
+// quietly vanish from the exported video — the same class of bug the scene
+// clock exists to prevent. Layout: an 8-float header [frames, bands,
+// secondsPerFrame, audioTime, playing, 3 spare] then per frame
+// [level, onset, band0..bandN-1]. audioTime and playing are rewritten every frame by
+// whoever owns playback — the editor's audio clock, the viewer's, or the export
+// loop — so "now" is always the clock that is actually running.
+//
+// Every module binds the SAME buffer, so a spawn rule in a particle effect and
+// a bar in a background read identical numbers for the same instant.
+/** The rzAudio* accessors, with the buffer declared at the given binding. */
+export function audioApi(group, binding) {
+    return /* wgsl */ `
+@group(${group}) @binding(${binding}) var<storage, read> _rzAudio: array<f32>;
+
+/** Frames of analysis available; 0 when the scene has no audio. */
+fn rzAudioFrames() -> i32 { return i32(_rzAudio[0]); }
+/** 1 while the track is actually PLAYING, 0 paused or absent — so an effect can
+ *  go calm instead of oscillating over a frozen spectrum. */
+fn rzAudioPlaying() -> f32 { return select(0.0, _rzAudio[4], i32(_rzAudio[0]) > 0); }
+/** Where the track is NOW, in seconds — the clock rzAudioLevelAt offsets hang
+ *  from. An effect that detects an onset k seconds back can anchor a ring to
+ *  the ABSOLUTE moment of the hit and age it continuously. */
+fn rzAudioTime() -> f32 { return _rzAudio[3]; }
+/** Bands per frame — log-spaced, bass first. */
+fn rzAudioBandCount() -> i32 { return i32(_rzAudio[1]); }
+
+fn _rzAudioFrameAt(offset: f32) -> i32 {
+  let frames = i32(_rzAudio[0]);
+  let t = _rzAudio[3] + offset;
+  return clamp(i32(t / max(_rzAudio[2], 1e-5)), 0, frames - 1);
+}
+
+/**
+ * Loudness at now + offset seconds, 0..1.
+ *
+ * The offset is what makes a WAVEFORM drawable: a column at x samples the
+ * envelope at (x - 0.5) * window seconds, and the playhead is the centre of the
+ * screen by construction. Offsets past either end clamp to the track's edges.
+ */
+fn rzAudioLevelAt(offset: f32) -> f32 {
+  let frames = i32(_rzAudio[0]);
+  if (frames <= 0) { return 0.0; }
+  let bands = i32(_rzAudio[1]);
+  return _rzAudio[8 + _rzAudioFrameAt(offset) * (bands + 2)];
+}
+
+/**
+ * The KICK track: how hard the bass is rising at now + offset, 0..1 —
+ * precomputed, so a beat-triggered effect is one comparison instead of a
+ * per-pixel history scan. Scan a short window of NEGATIVE offsets to find
+ * recent hits and age things from them (quantise the hit to the analysis grid
+ * so ages stay continuous).
+ */
+fn rzAudioOnsetAt(offset: f32) -> f32 {
+  let frames = i32(_rzAudio[0]);
+  if (frames <= 0) { return 0.0; }
+  let bands = i32(_rzAudio[1]);
+  return _rzAudio[8 + _rzAudioFrameAt(offset) * (bands + 2) + 1];
+}
+fn rzAudioOnset() -> f32 { return rzAudioOnsetAt(0.0); }
+/** Loudness now, 0..1. */
+fn rzAudioLevel() -> f32 { return rzAudioLevelAt(0.0); }
+
+/** Band i at now + offset seconds, 0..1. Band 0 is the deepest bass. */
+fn rzAudioBandAt(i: i32, offset: f32) -> f32 {
+  let frames = i32(_rzAudio[0]);
+  if (frames <= 0) { return 0.0; }
+  let bands = i32(_rzAudio[1]);
+  if (i < 0 || i >= bands) { return 0.0; }
+  return _rzAudio[8 + _rzAudioFrameAt(offset) * (bands + 2) + 2 + i];
+}
+/** Band i now — the visualiser call. */
+fn rzAudioBand(i: i32) -> f32 { return rzAudioBandAt(i, 0.0); }
+`;
+}

package/dist/shaders/cast-api.d.ts

@@ -0,0 +1,2 @@
+export declare const CAST_API = "\nconst RZ_SUBJECTS: i32 = 4;\nconst RZ_SAMPLES: i32 = 128;\n/** The anchor ADDRESS SPACE \u2014 how many an effect may declare, not how many it\n *  did. RZ_TRAIL_SLOTS is the per-effect number and is not this one; the two\n *  being one number was the old trail bug. */\nconst RZ_MAX_ANCHORS: i32 = 8;\nconst RZ_TRAIL_SAMPLES: i32 = 128;\n\nstruct RzSubject {\n  /** On the FLOOR, under the body \u2014 where a ring or a magic circle belongs. */\n  root: vec3f,\n  /** At the hips, the middle of the body \u2014 where an aura belongs. */\n  center: vec3f,\n  /** Bounding sphere: xyz centre, w radius. Deliberately generous \u2014 cull with it. */\n  bounds: vec4f,\n  /** False past the end of the cast, and every field is then zero. */\n  valid: bool,\n}\n\nstruct RzAnchor {\n  pos: vec3f,\n  /** World units per second, from the previous frame. Direction for a trail,\n   *  magnitude for anything that should react to how hard someone is moving. */\n  vel: vec3f,\n  /** The bone's forward axis \u2014 which way a foot points, where a head looks. */\n  fwd: vec3f,\n  /** False when this rig has no such bone. Check it: the alternative is drawing\n   *  a hand effect at the world origin on every model that spells it differently. */\n  valid: bool,\n}\n\n/** Which model this is, stable across a scene \u2014 for per-subject variation. */\nfn rzSubjectId(i: i32) -> u32 {\n  if (i < 0 || i >= rzSubjectCount()) { return 0u; }\n  return u32(_rzCast[i * 3 + 1].w);\n}\n\nfn rzSubject(i: i32) -> RzSubject {\n  var s: RzSubject;\n  s.valid = i >= 0 && i < rzSubjectCount();\n  if (!s.valid) { return s; }\n  let b = i * 3;\n  s.root = _rzCast[b].xyz;\n  s.center = _rzCast[b + 1].xyz;\n  s.bounds = _rzCast[b + 2];\n  return s;\n}\n\n/**\n * Where a named bone is, this frame.\n *\n * The slot is the author's own: the Nth @anchor in their file, in the order\n * they wrote them. _rzSlot turns that into the scene's address, which is what\n * keeps two effects that both anchor to a wrist from reading each other's.\n */\nfn rzAnchor(subject: i32, slot: i32) -> RzAnchor {\n  var a: RzAnchor;\n  a.valid = false;\n  let g = _rzSlot(slot);\n  if (subject < 0 || subject >= rzSubjectCount() || g < 0 || g >= RZ_MAX_ANCHORS) { return a; }\n  let b = 12 + (g * 4 + subject) * 3;\n  a.valid = _rzCast[b].w > 0.5;\n  a.pos = _rzCast[b].xyz;\n  a.vel = _rzCast[b + 1].xyz;\n  a.fwd = _rzCast[b + 2].xyz;\n  return a;\n}\n\n/**\n * How many samples of a path are recorded \u2014 0 for an anchor that asked for no\n * trail, and for one that has not moved yet.\n *\n * Bounded by the anchor cap, NOT by how many anchors asked for a trail. Those\n * are different index spaces: storage is addressed by anchor slot, so an\n * untrailed @anchor followed by a trailed one put the trail at index 1 with a\n * bound of 1 and rzTrail returned zero \u2014 a ribbon that silently did not draw.\n */\nfn rzTrailCount(subject: i32, slot: i32) -> i32 {\n  let g = _rzSlot(slot);\n  if (subject < 0 || subject >= rzSubjectCount() || g < 0 || g >= RZ_MAX_ANCHORS) { return 0; }\n  return i32(_rzCast[12 + (g * 4 + subject) * 3 + 2].w);\n}\n\n/** Sample i of a path: xyz where it was, w how many seconds ago. i = 0 is now. */\nfn rzTrail(subject: i32, slot: i32, i: i32) -> vec4f {\n  let n = rzTrailCount(subject, slot);\n  if (i < 0 || i >= n) { return vec4f(0.0); }\n  let base = 108 + (_rzSlot(slot) * 4 + subject) * RZ_TRAIL_SAMPLES;\n  return _rzCast[base + i];\n}\n";
+//# sourceMappingURL=cast-api.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cast-api.d.ts","sourceRoot":"","sources":["../../src/shaders/cast-api.ts"],"names":[],"mappings":"AA+BA,eAAO,MAAM,QAAQ,k4GA2FpB,CAAA"}

package/dist/shaders/cast-api.js

@@ -0,0 +1,121 @@
+// 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/dist/shaders/cast-layout.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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 declare const EFFECT_SUBJECTS = 4;
+export declare const EFFECT_ANCHORS = 8;
+export declare const EFFECT_TRAIL_SAMPLES = 128;
+/** vec4 slot where the trails begin — after the subjects and the anchors. */
+export declare const EFFECT_TRAIL_BASE: number;
+//# sourceMappingURL=cast-layout.d.ts.map

package/dist/shaders/cast-layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cast-layout.d.ts","sourceRoot":"","sources":["../../src/shaders/cast-layout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,eAAe,IAAI,CAAA;AAChC,eAAO,MAAM,cAAc,IAAI,CAAA;AAC/B,eAAO,MAAM,oBAAoB,MAAM,CAAA;AACvC,6EAA6E;AAC7E,eAAO,MAAM,iBAAiB,QAA6D,CAAA"}

package/dist/shaders/cast-layout.js

@@ -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/dist/shaders/lights.d.ts

@@ -0,0 +1,79 @@
+/** 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 declare const LIGHT_HEADER = 4;
+/** Floats per light — see the layout above. */
+export declare 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 declare const MAX_LIGHTS = 16;
+/** Floats in the whole buffer. */
+export declare const LIGHTS_FLOATS: number;
+/**
+ * `// @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 declare function parseLightCount(wgsl: string, max: number): number;
+/**
+ * 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 declare const RZ_LIGHT_STRUCT_WGSL = "\n/** What an effect returns for one of its lights. */\nstruct RzLight {\n  pos: vec3f,\n  color: vec3f,\n  intensity: f32,\n  radius: f32,\n}\n";
+/**
+ * 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 declare const WORLD_AMBIENT_WGSL = "\nfn rzWorldAmbient(n: vec3f) -> vec3f {\n  if (light.sh[0].w < 0.5) { return light.ambientColor.xyz; }\n  let x = n.x;\n  let y = n.y;\n  let z = n.z;\n  let c = light.sh[0].xyz\n    + light.sh[1].xyz * y + light.sh[2].xyz * z + light.sh[3].xyz * x\n    + light.sh[4].xyz * (x * y) + light.sh[5].xyz * (y * z)\n    + light.sh[6].xyz * (3.0 * z * z - 1.0) + light.sh[7].xyz * (x * z)\n    + light.sh[8].xyz * (x * x - y * y);\n  return max(c, vec3f(0.0));\n}\n";
+/** Does this source define the emit mount? */
+export declare function hasLightEmit(wgsl: string): boolean;
+/**
+ * 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 declare function buildLightEmitShader(wgsl: string, sceneApi: string, cast: {
+    trailCount: number;
+}): string;
+/** The rz*Light accessors, with the buffer declared at the given binding. */
+export declare function lightsApi(group: number, binding: number): string;
+//# sourceMappingURL=lights.d.ts.map

package/dist/shaders/lights.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lights.d.ts","sourceRoot":"","sources":["../../src/shaders/lights.ts"],"names":[],"mappings":"AAgCA;yEACyE;AACzE,eAAO,MAAM,YAAY,IAAI,CAAA;AAC7B,+CAA+C;AAC/C,eAAO,MAAM,YAAY,IAAI,CAAA;AAC7B;;;;;GAKG;AACH,eAAO,MAAM,UAAU,KAAK,CAAA;AAC5B,kCAAkC;AAClC,eAAO,MAAM,aAAa,QAA2C,CAAA;AAErE;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAIjE;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,qJAQhC,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,idAa9B,CAAA;AAED,8CAA8C;AAC9C,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAElD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,GAC3B,MAAM,CAqER;AAED,6EAA6E;AAC7E,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAkEhE"}