@woosh/meep-engine 3.14.4 → 3.14.5

package/src/engine/network/sim/ActionRecordCursor.js

@@ -0,0 +1,120 @@
+/**
+ * Forward cursor over the records of one closed {@link ActionLog} frame.
+ *
+ * The record layout is self-describing (see {@link ActionLog}), so any reader
+ * can walk it — and five did, each with its own copy of the header parse: the
+ * replicator's scope scan and action copy, the rewind engine's boundary pass,
+ * and the rollback server's history read and retransmission check. This is
+ * that parse in one place. {@link next} reads one record's header and exposes
+ * the layout as positions into the frame's buffer; what a reader does with the
+ * prior-state entries or the action payload is its own business.
+ *
+ * Allocation-free after construction: a reader owns one cursor and re-opens
+ * it per frame. After `next` returns true the buffer's `position` is at the
+ * END of the record, so a reader that wants the prior-state entries sets
+ * `position = prior_start` and reads `prior_count` of them; `next` seeks from
+ * `record_end` regardless of where the reader left the position.
+ *
+ * ```
+ *   cursor.open(action_log, frame);
+ *   while (cursor.next()) {
+ *       // cursor.action_type_id, cursor.sender_id,
+ *       // cursor.buffer.raw_bytes[cursor.payload_start .. + cursor.payload_len]
+ *   }
+ * ```
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ActionRecordCursor {
+    /**
+     * The open frame's buffer, positioned at {@link record_end} after each
+     * successful {@link next}.
+     * @type {BinaryBuffer|null}
+     */
+    buffer = null;
+
+    /** @type {number} first byte of the current record */
+    record_start = 0;
+
+    /** @type {number} prior-state entries in the current record */
+    prior_count = 0;
+
+    /**
+     * First byte of the first prior-state entry. Each entry is
+     * `varint entity_id, uint8 component_type_id, uint32 len, bytes[len]`.
+     * @type {number}
+     */
+    prior_start = 0;
+
+    /** @type {number} */
+    action_type_id = 0;
+
+    /**
+     * The record's provenance byte: a peer id, `SENDER_LOCAL` or
+     * `SENDER_DERIVED` (see {@link SimActionExecutor}).
+     * @type {number}
+     */
+    sender_id = 0;
+
+    /** @type {number} first byte of the action payload */
+    payload_start = 0;
+
+    /** @type {number} */
+    payload_len = 0;
+
+    /**
+     * One past the last byte of the current record — and so the first byte of
+     * the next, which is where {@link next} resumes. `0` before the first
+     * record.
+     * @type {number}
+     */
+    record_end = 0;
+
+    /** @type {number} one past the last byte of the frame */
+    #end = 0;
+
+    /**
+     * Position the cursor before the first record of `frame`, which must be
+     * closed and present in the log (see {@link ActionLog#buffer_for}).
+     *
+     * @param {ActionLog} action_log
+     * @param {number} frame
+     */
+    open(action_log, frame) {
+        this.buffer = action_log.buffer_for(frame); // rewinds to 0
+        this.#end = action_log.write_end_for(frame);
+        this.record_end = 0;
+    }
+
+    /**
+     * Advance to the next record. Returns false once the frame is exhausted,
+     * leaving the fields as they were.
+     *
+     * @returns {boolean}
+     */
+    next() {
+        if (this.record_end >= this.#end) return false;
+
+        const buffer = this.buffer;
+        buffer.position = this.record_end;
+
+        this.record_start = buffer.position;
+        this.prior_count = buffer.readUintVar();
+        this.prior_start = buffer.position;
+        for (let i = 0; i < this.prior_count; i++) {
+            buffer.readUintVar();                   // entity_id
+            buffer.readUint8();                     // component_type_id
+            const prior_len = buffer.readUint32();
+            buffer.position += prior_len;           // prior payload
+        }
+        this.action_type_id = buffer.readUint8();
+        this.sender_id = buffer.readUint8();
+        this.payload_len = buffer.readUint32();
+        this.payload_start = buffer.position;
+        this.record_end = this.payload_start + this.payload_len;
+        buffer.position = this.record_end;
+
+        return true;
+    }
+}

package/src/engine/network/sim/RewindEngine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RewindEngine.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/sim/RewindEngine.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAQI;;;;;;OAMG;IACH,uDANW;QACV,UAAc,YAAY;QAC1B,KAAS,yBAAyB;QAClC,kBAAsB,8BAA8B;KACjD,EAiBH;IAdG;;OAEG;IACH,sBAA4B;IAE5B;;OAEG;IACH,8BAAkB;IAElB;;OAEG;IACH,gDAA4C;IAGhD;;;;;OAKG;IACH,kBAFW,MAAM,QA2BhB;IAED;;;;;;;;;OASG;IACH,yBAHW,MAAM,gBACN,MAAM,QAWhB;;CAwEJ"}
+{"version":3,"file":"RewindEngine.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/sim/RewindEngine.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAeI;;;;;;OAMG;IACH,uDANW;QACV,UAAc,YAAY;QAC1B,KAAS,yBAAyB;QAClC,kBAAsB,8BAA8B;KACjD,EAiBH;IAdG;;OAEG;IACH,sBAA4B;IAE5B;;OAEG;IACH,8BAAkB;IAElB;;OAEG;IACH,gDAA4C;IAGhD;;;;;OAKG;IACH,kBAFW,MAAM,QA0BhB;IAED;;;;;;;;;OASG;IACH,yBAHW,MAAM,gBACN,MAAM,QAWhB;;CAiDJ"}

package/src/engine/network/sim/RewindEngine.js

@@ -1,4 +1,5 @@
 import { assert } from "../../../core/assert.js";
+import { ActionRecordCursor } from "./ActionRecordCursor.js";
 
 /**
  * Walks the {@link ActionLog} backwards to restore prior component state.
@@ -28,6 +29,13 @@ export class RewindEngine {
      */
     #record_starts = new Int32Array(64);
 
+    /**
+     * Walks a frame's records to find where each starts.
+     * @type {ActionRecordCursor}
+     * @private
+     */
+    #cursor = new ActionRecordCursor();
+
     /**
      * @param {{
      *   action_log: ActionLog,
@@ -64,20 +72,19 @@ export class RewindEngine {
             throw new Error(`RewindEngine.undo_frame: frame ${frame} is not present in the action log`);
         }
 
-        const buffer = this.action_log.buffer_for(frame);
-        const end = this.action_log.write_end_for(frame);
-
         // 1. First pass: walk forward to find record boundaries.
+        const cursor = this.#cursor;
+        cursor.open(this.action_log, frame);
         let record_count = 0;
-        while (buffer.position < end) {
+        while (cursor.next()) {
             if (record_count >= this.#record_starts.length) {
                 this.#grow_record_starts();
             }
-            this.#record_starts[record_count++] = buffer.position;
-            this.#skip_record(buffer);
+            this.#record_starts[record_count++] = cursor.record_start;
         }
 
         // 2. Second pass: iterate records in reverse, restoring prior state.
+        const buffer = cursor.buffer;
         for (let i = record_count - 1; i >= 0; i--) {
             buffer.position = this.#record_starts[i];
             this.#restore_prior_state(buffer);
@@ -106,29 +113,6 @@ export class RewindEngine {
         }
     }
 
-    /**
-     * Walk past a single record without restoring anything. Buffer position
-     * advances to the start of the next record (or to `end` if this was the last).
-     *
-     * @param {BinaryBuffer} buffer
-     * @private
-     */
-    #skip_record(buffer) {
-        // Skip prior_state entries.
-        const prior_count = buffer.readUintVar();
-        for (let i = 0; i < prior_count; i++) {
-            buffer.readUintVar();           // entity_id
-            buffer.readUint8();             // component_type_id
-            const len = buffer.readUint32();
-            buffer.position += len;         // skip prior payload
-        }
-        // Skip action.
-        buffer.readUint8();                 // action_type_id
-        buffer.readUint8();                 // sender_id
-        const action_len = buffer.readUint32();
-        buffer.position += action_len;      // skip action payload
-    }
-
     /**
      * Read the prior_state entries of the record at the buffer's current position
      * and write them back into the live components. Buffer position advances past

package/src/engine/network/sim/SimActionExecutor.d.ts

@@ -122,8 +122,7 @@ export class SimActionExecutor {
      *
      * Set by a rollback orchestrator for the span in which the frame's local
      * sim runs (see `ServerAuthoritativeServer.__replay_frame`) and cleared
-     * immediately after, so it covers nested `execute` calls made from an
-     * action's `apply` during that span. Everything else — arrived input,
+     * immediately after. Everything outside that span — arrived input,
      * locally-authored actions — is left with its real sender.
      *
      * Only the RECORDED byte changes. `sender_id` still drives the
@@ -192,7 +191,7 @@ export class SimActionExecutor {
      * @param {SimAction} action
      * @param {number} [sender_id] peer that originated this action.
      *   Defaults to {@link SENDER_LOCAL} for locally-originated actions.
-     *   Must be in `[0, 254]` for remote-originated actions.
+     *   Must be in `[0, MAX_PEER_ID]` for remote-originated actions.
      * @returns {boolean} true if the action was applied; false if it was
      *   rejected by the {@link authorize} gate (and therefore not applied or
      *   logged).

package/src/engine/network/sim/SimActionExecutor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SimActionExecutor.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/sim/SimActionExecutor.js"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,2BAFU,MAAM,CAEiB;AAEjC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,6BAFU,MAAM,CAEmB;AAEnC;;;;;GAKG;AACH,0BAFU,MAAM,CAEgB;AAEhC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IA4DI;;;;;;;;;OASG;IACH,sGATW;QACV,KAAS,yBAAyB;QAClC,UAAc,YAAY;QAC1B,eAAmB,oBAAoB;QACvC,kBAAsB,8BAA8B;QACpD,UAAc,uBAAuB;QACrC,gBAAoB,CAAC,mBAAmB;KACrC,EAyFH;IAxJD;;;;;;;;;OASG;IACH,gBAFU,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAEP;IAEtB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,uBAFuB,MAAM,aAAa,MAAM,wBAAwB,OAAO,CAE9D;IAEjB;;;;;;;;;;;;;;;;OAgBG;IACH,UAFU,OAAO,CAEA;IAab;;OAEG;IACH,8BAAkB;IAElB;;OAEG;IACH,sBAA4B;IAE5B;;OAEG;IACH,mCAAsC;IAEtC;;OAEG;IACH,gDAA4C;IAE5C;;;;OAIG;IACH,iCAA4B;IAE5B;;;;;;;;;;;OAWG;IACH,kBAFU,mBAAiB,IAAI,CAES;IA4BxC;;;;;;;OAOG;IACH,mBAFU,MAAM,CAEqB;IAErC;;;;;;;OAOG;IACH,kBAFU,MAAM,CAEoB;IAGxC;;;;;;;;;;OAUG;IACH,uCAPW,MAAM,GAGJ,OAAO,CAgJnB;;CACJ;mBA5XkB,uCAAuC"}
+{"version":3,"file":"SimActionExecutor.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/sim/SimActionExecutor.js"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,2BAFU,MAAM,CAEiB;AAEjC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,6BAFU,MAAM,CAEmB;AAEnC;;;;;GAKG;AACH,0BAFU,MAAM,CAEgB;AAEhC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IA2DI;;;;;;;;;OASG;IACH,sGATW;QACV,KAAS,yBAAyB;QAClC,UAAc,YAAY;QAC1B,eAAmB,oBAAoB;QACvC,kBAAsB,8BAA8B;QACpD,UAAc,uBAAuB;QACrC,gBAAoB,CAAC,mBAAmB;KACrC,EAyFH;IAvJD;;;;;;;;;OASG;IACH,gBAFU,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAEP;IAEtB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,uBAFuB,MAAM,aAAa,MAAM,wBAAwB,OAAO,CAE9D;IAEjB;;;;;;;;;;;;;;;OAeG;IACH,UAFU,OAAO,CAEA;IAab;;OAEG;IACH,8BAAkB;IAElB;;OAEG;IACH,sBAA4B;IAE5B;;OAEG;IACH,mCAAsC;IAEtC;;OAEG;IACH,gDAA4C;IAE5C;;;;OAIG;IACH,iCAA4B;IAE5B;;;;;;;;;;;OAWG;IACH,kBAFU,mBAAiB,IAAI,CAES;IA4BxC;;;;;;;OAOG;IACH,mBAFU,MAAM,CAEqB;IAErC;;;;;;;OAOG;IACH,kBAFU,MAAM,CAEoB;IAGxC;;;;;;;;;;OAUG;IACH,uCAPW,MAAM,GAGJ,OAAO,CAgJnB;;CACJ;mBA3XkB,uCAAuC"}

package/src/engine/network/sim/SimActionExecutor.js

@@ -116,8 +116,7 @@ export class SimActionExecutor {
      *
      * Set by a rollback orchestrator for the span in which the frame's local
      * sim runs (see `ServerAuthoritativeServer.__replay_frame`) and cleared
-     * immediately after, so it covers nested `execute` calls made from an
-     * action's `apply` during that span. Everything else — arrived input,
+     * immediately after. Everything outside that span — arrived input,
      * locally-authored actions — is left with its real sender.
      *
      * Only the RECORDED byte changes. `sender_id` still drives the
@@ -233,7 +232,7 @@ export class SimActionExecutor {
      * @param {SimAction} action
      * @param {number} [sender_id] peer that originated this action.
      *   Defaults to {@link SENDER_LOCAL} for locally-originated actions.
-     *   Must be in `[0, 254]` for remote-originated actions.
+     *   Must be in `[0, MAX_PEER_ID]` for remote-originated actions.
      * @returns {boolean} true if the action was applied; false if it was
      *   rejected by the {@link authorize} gate (and therefore not applied or
      *   logged).
@@ -250,18 +249,18 @@ export class SimActionExecutor {
             `execute: action class '${action.constructor.action_type_name ?? action.constructor.name}' has no wire type_id — register it (NetworkSession.defineAction, or SimActionRegistry.register) before executing it`,
         );
         assert.isNonNegativeInteger(sender_id, 'sender_id');
-        // A remote sender that reaches a provenance sentinel would be recorded
-        // as local-authored or sim-derived, and a rollback replay reads the
-        // sentinel back as "this record is mine to recompute" — so the peer's
-        // input would apply once and then disappear on the first replay of its
-        // frame, with nothing logged. Real runtime check: asserts strip in prod,
-        // and silent input loss is not something to ship behind one.
+        // A sender above the peer range is either the sim-derived sentinel —
+        // which a rollback replay reads back as "this record is mine to
+        // recompute", so the peer's input would apply once and then disappear
+        // on the first replay of its frame, with nothing logged — or a value
+        // that does not fit the record's one byte at all. SENDER_LOCAL itself
+        // is the caller saying "mine". Real runtime check: asserts strip in
+        // prod, and silent input loss is not something to ship behind one.
         if (sender_id > MAX_PEER_ID && sender_id !== SENDER_LOCAL) {
             throw new Error(
-                `SimActionExecutor.execute: sender_id ${sender_id} is reserved (SENDER_DERIVED); remote peer ids must be in [0, ${MAX_PEER_ID}]`,
+                `SimActionExecutor.execute: sender_id ${sender_id} is not a peer id; remote peer ids must be in [0, ${MAX_PEER_ID}] — 254 and 255 are reserved provenance markers`,
             );
         }
-        assert.ok(sender_id <= 0xFF, 'sender_id must fit in a uint8');
 
         // Expose the originating sender to apply / affected_components / the
         // authorize policy before any of them run.

package/src/engine/physics/fluid/ecs/FluidObstacleSystem.d.ts

@@ -64,11 +64,11 @@ export class FluidObstacleSystem extends System<any> {
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#370@#refresh_masks"(fluid: FluidComponent): void;
+    static "__#371@#refresh_masks"(fluid: FluidComponent): void;
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#370@#clear_field"(fluid: FluidComponent): void;
+    static "__#371@#clear_field"(fluid: FluidComponent): void;
     /**
      * Mark every cell of `fluid` whose centre lies within `inflation` of the
      * posed shape as solid. Iteration is clipped to the shape's world AABB
@@ -80,7 +80,7 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} inflation       world-units SDF threshold
      * @param {Float64Array} point     length-3 scratch
      */
-    static "__#370@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
+    static "__#371@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
     /**
      * Write the obstacle's translation velocity onto every face of every cell
      * it voxelized — the moving-wall boundary condition. Runs AFTER the mask
@@ -100,7 +100,7 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} wvy
      * @param {number} wvz
      */
-    static "__#370@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
+    static "__#371@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
     constructor();
     dependencies: (typeof FluidObstacle)[];
     components_used: (ResourceAccessSpecification<typeof Transform> | ResourceAccessSpecification<typeof RigidBody> | ResourceAccessSpecification<typeof Collider> | ResourceAccessSpecification<typeof FluidComponent> | ResourceAccessSpecification<typeof FluidObstacle>)[];

package/src/shade/playground/particle_system/particle_scene.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"particle_scene.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/particle_system/particle_scene.js"],"names":[],"mappings":"AAwEA;;;;;;;GAOG;AAEH;;;;;;;;GAQG;AACH;IAJqC,YAAY;IACrB,QAAQ,GAAzB,MAAM;IACJ,MAAM,CA8OlB;AA3QD;;;;GAIG;AACH,0CAA2C;AAE3C,wGAAwG;AACxG,sCAAuC;;;;;WAOzB,MAAM;;;;UACN,MAAM;;;;cACN,MAAM;;;;cACN,MAAM,EAAE;;;;UACR,MAAM,EAAE"}
+{"version":3,"file":"particle_scene.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/particle_system/particle_scene.js"],"names":[],"mappings":"AAyEA;;;;;;;GAOG;AAEH;;;;;;;;GAQG;AACH;IAJqC,YAAY;IACrB,QAAQ,GAAzB,MAAM;IACJ,MAAM,CA8OlB;AA3QD;;;;GAIG;AACH,0CAA2C;AAE3C,wGAAwG;AACxG,sCAAuC;;;;;WAOzB,MAAM;;;;UACN,MAAM;;;;cACN,MAAM;;;;cACN,MAAM,EAAE;;;;UACR,MAAM,EAAE"}

package/src/shade/playground/particle_system/particle_scene.js

@@ -7,7 +7,8 @@ import { CAMERA_UNIFORM_STRUCT } from "../../renderer/camera/CAMERA_UNIFORM_STRU
 import { PARTICLE_RECORD_WORD_COUNT } from "../../renderer/particles/ParticleConstants.js";
 import { PARTICLE_COUNTER_COUNT } from "../../renderer/particles/data/PARTICLE_COUNTERS.js";
 import { EMITTER_BLEND, EMITTER_PROJECTION } from "../../renderer/particles/data/PARTICLE_EMITTER_LAYOUT.js";
-import { ParticleGraph } from "../../renderer/particles/graph/ParticleGraph.js";
+import { NodeGraph } from "../../../core/model/node-graph/NodeGraph.js";
+import { particle_node, particle_wire } from "../../renderer/particles/graph/particle_graph_authoring.js";
 import { VM_BUILTIN, VM_RANDOM_MODE } from "../../renderer/particles/isa/ParticleVMISA.js";
 import { ParticleLayout } from "../../renderer/particles/layout/ParticleLayout.js";
 import { GPUParticleSystem } from "../../renderer/particles/GPUParticleSystem.js";
@@ -342,49 +343,49 @@ function make_effect({ velocity, velocityJitter = 0, posJitter = 0, accel = 0, l
         { name: "size", components: 1 }, { name: "color", components: 4 },
     ]);
 
-    const spawn = new ParticleGraph();
-    let posN = spawn.add("builtin", { id: VM_BUILTIN.EMITTER_POSITION });
+    const spawn = new NodeGraph();
+    let posN = particle_node(spawn, "builtin", { id: VM_BUILTIN.EMITTER_POSITION });
     if (posJitter > 0) {
-        const d = spawn.add("random", { mode: VM_RANDOM_MODE.UNIT_DISK });
-        const j = spawn.add("scale"); spawn.wire(j, "v", d); spawn.wire(j, "s", [posJitter]);
-        const p = spawn.add("add"); spawn.wire(p, "a", posN); spawn.wire(p, "b", j); posN = p;
+        const d = particle_node(spawn, "random", { mode: VM_RANDOM_MODE.UNIT_DISK });
+        const j = particle_node(spawn, "scale"); particle_wire(spawn, j, "v", d); particle_wire(spawn, j, "s", [posJitter]);
+        const p = particle_node(spawn, "add"); particle_wire(spawn, p, "a", posN); particle_wire(spawn, p, "b", j); posN = p;
     }
-    spawn.wire(spawn.add("setAttribute", { name: "position" }), "value", posN);
+    particle_wire(spawn, particle_node(spawn, "setAttribute", { name: "position" }), "value", posN);
 
-    let velN = spawn.add("const", { value: [velocity[0], velocity[1], velocity[2], 0] });
+    let velN = particle_node(spawn, "const", { value: [velocity[0], velocity[1], velocity[2], 0] });
     if (velocityJitter > 0) {
-        const r = spawn.add("random", { mode: VM_RANDOM_MODE.UNIFORM_SIGNED });
-        const rs = spawn.add("scale"); spawn.wire(rs, "v", r); spawn.wire(rs, "s", [velocityJitter]);
-        const vv = spawn.add("add"); spawn.wire(vv, "a", velN); spawn.wire(vv, "b", rs); velN = vv;
+        const r = particle_node(spawn, "random", { mode: VM_RANDOM_MODE.UNIFORM_SIGNED });
+        const rs = particle_node(spawn, "scale"); particle_wire(spawn, rs, "v", r); particle_wire(spawn, rs, "s", [velocityJitter]);
+        const vv = particle_node(spawn, "add"); particle_wire(spawn, vv, "a", velN); particle_wire(spawn, vv, "b", rs); velN = vv;
     }
-    spawn.wire(spawn.add("setAttribute", { name: "velocity" }), "value", velN);
-    spawn.wire(spawn.add("setAttribute", { name: "age" }), "value", [0]);
-    const lr = spawn.add("random", { mode: VM_RANDOM_MODE.UNIFORM });
-    const lm = spawn.add("mad"); spawn.wire(lm, "a", lr); spawn.wire(lm, "b", [life[1] - life[0]]); spawn.wire(lm, "c", [life[0]]);
-    spawn.wire(spawn.add("setAttribute", { name: "lifetime" }), "value", lm);
-    spawn.wire(spawn.add("setAttribute", { name: "size" }), "value", [size]);
-    spawn.wire(spawn.add("setAttribute", { name: "color" }), "value", color);
-
-    const update = new ParticleGraph();
-    const dt = update.add("builtin", { id: VM_BUILTIN.DELTA_TIME });
-    const age = update.add("attribute", { name: "age" });
-    const nage = update.add("add"); update.wire(nage, "a", age); update.wire(nage, "b", dt);
-    update.wire(update.add("setAttribute", { name: "age" }), "value", nage);
-    const lifeA = update.add("attribute", { name: "lifetime" });
-    const na = update.add("div"); update.wire(na, "a", nage); update.wire(na, "b", lifeA);
-    const dead = update.add("compare", { op: "ge" }); update.wire(dead, "a", na); update.wire(dead, "b", [1]);
-    update.wire(update.add("kill"), "condition", dead);
-    let velN2 = update.add("attribute", { name: "velocity" });
+    particle_wire(spawn, particle_node(spawn, "setAttribute", { name: "velocity" }), "value", velN);
+    particle_wire(spawn, particle_node(spawn, "setAttribute", { name: "age" }), "value", [0]);
+    const lr = particle_node(spawn, "random", { mode: VM_RANDOM_MODE.UNIFORM });
+    const lm = particle_node(spawn, "mad"); particle_wire(spawn, lm, "a", lr); particle_wire(spawn, lm, "b", [life[1] - life[0]]); particle_wire(spawn, lm, "c", [life[0]]);
+    particle_wire(spawn, particle_node(spawn, "setAttribute", { name: "lifetime" }), "value", lm);
+    particle_wire(spawn, particle_node(spawn, "setAttribute", { name: "size" }), "value", [size]);
+    particle_wire(spawn, particle_node(spawn, "setAttribute", { name: "color" }), "value", color);
+
+    const update = new NodeGraph();
+    const dt = particle_node(update, "builtin", { id: VM_BUILTIN.DELTA_TIME });
+    const age = particle_node(update, "attribute", { name: "age" });
+    const nage = particle_node(update, "add"); particle_wire(update, nage, "a", age); particle_wire(update, nage, "b", dt);
+    particle_wire(update, particle_node(update, "setAttribute", { name: "age" }), "value", nage);
+    const lifeA = particle_node(update, "attribute", { name: "lifetime" });
+    const na = particle_node(update, "div"); particle_wire(update, na, "a", nage); particle_wire(update, na, "b", lifeA);
+    const dead = particle_node(update, "compare", { op: "ge" }); particle_wire(update, dead, "a", na); particle_wire(update, dead, "b", [1]);
+    particle_wire(update, particle_node(update, "kill"), "condition", dead);
+    let velN2 = particle_node(update, "attribute", { name: "velocity" });
     if (accel !== 0) {
-        const g = update.add("const", { value: [0, accel, 0, 0] });
-        const gd = update.add("scale"); update.wire(gd, "v", g); update.wire(gd, "s", dt);
-        const nv = update.add("add"); update.wire(nv, "a", velN2); update.wire(nv, "b", gd);
-        update.wire(update.add("setAttribute", { name: "velocity" }), "value", nv); velN2 = nv;
+        const g = particle_node(update, "const", { value: [0, accel, 0, 0] });
+        const gd = particle_node(update, "scale"); particle_wire(update, gd, "v", g); particle_wire(update, gd, "s", dt);
+        const nv = particle_node(update, "add"); particle_wire(update, nv, "a", velN2); particle_wire(update, nv, "b", gd);
+        particle_wire(update, particle_node(update, "setAttribute", { name: "velocity" }), "value", nv); velN2 = nv;
     }
-    const pos = update.add("attribute", { name: "position" });
-    const pd = update.add("scale"); update.wire(pd, "v", velN2); update.wire(pd, "s", dt);
-    const np = update.add("add"); update.wire(np, "a", pos); update.wire(np, "b", pd);
-    update.wire(update.add("setAttribute", { name: "position" }), "value", np);
+    const pos = particle_node(update, "attribute", { name: "position" });
+    const pd = particle_node(update, "scale"); particle_wire(update, pd, "v", velN2); particle_wire(update, pd, "s", dt);
+    const np = particle_node(update, "add"); particle_wire(update, np, "a", pos); particle_wire(update, np, "b", pd);
+    particle_wire(update, particle_node(update, "setAttribute", { name: "position" }), "value", np);
 
     return create_particle_effect({ layout, spawn, update });
 }

package/src/shade/playground/skinned_mesh_soup/README.md

@@ -41,12 +41,12 @@ zero** by the `max`. The rotation it extracts is not the matrix's rotation, and
 depends on the matrix — so it is wrong differently for every joint. That is the soup: not one
 transform applied badly, but sixty-five of them disagreeing.
 
-The two modes make the mechanism visible:
+The two modes made the mechanism visible:
 
-| `?skin=` | what you see | why |
+| `?skin=` | what it did | why |
 | --- | --- | --- |
-| `bind` | the right character, exactly 1/100 the size | every joint folds to the *same* matrix, `100·Rx(90°)`. Its `w` and `x` terms are both `1 + 100`, its `y` and `z` both clamp to zero, and the normalize recovers `Rx(90°)` — by luck. Only the scale is lost. Sampled output is `expected / 100` to the digit. |
-| `animated` | soup | the joints' matrices differ, each loses a different amount, and the mesh comes apart. Mean error 121 in a mesh-local space where the body is 224 across; worst 165, on vertices bound to **a single joint at weight 1** — so the blend is not even involved. |
+| `bind` | the right character, exactly 1/100 the size | every joint folds to the *same* matrix, `100·Rx(90°)`. Its `w` and `x` terms are both `1 + 100`, its `y` and `z` both clamp to zero, and the normalize recovers `Rx(90°)` — by luck. Only the scale is lost. Sampled output was `expected / 100` to the digit. |
+| `animated` | soup | the joints' matrices differ, each loses a different amount, and the mesh comes apart. Mean error 121 in a mesh-local space where the body is 224 across; worst 165, on vertices bound to **a single joint at weight 1** — so the blend was not even involved. |
 
 `__soup_blend_probe.spec.js` is that measurement: the WGSL of `dual_quat_from_m4`,
 `dual_quat_blend4` and `dual_quat_transform_point` ported to JS, run over the character's own
@@ -71,22 +71,42 @@ against the bounds chain's box, and **both are derived from the clone's vertex r
 that are wrong in the same way agree with each other perfectly. A green `verify()` and a soup
 picture are consistent.
 
-## The fix, and why it is a choice
+## What was done about it
 
-The scale is uniform, so it factors: `M = s · Rigid` means `M · p = s · (Rigid · p)`. Dividing the
-folded matrix's 3×3 and its translation by `s = length(column 0)` before the conversion, and scaling
-the transformed position by `s` after, is exact for any uniform scale and costs a length and three
-multiplies per joint. It does not help a *non-uniform* one, which a dual quaternion cannot carry
-either — that would want the linear-blend path the DQ one replaced.
+`renderer/animation/SKINNING_FRAME_PLAN.md`. The short version: glTF says a skinned mesh's node
+transform is ignored, so the frame is not the asset's to choose — it is the engine's.
+`register_skin` now sets it to the skin's own bind transform (`skin_normalize_mesh_frame`), which
+makes the fold the identity at bind and a rigid displacement under a clip, for **both** shapes a
+glTF file arrives in. One matrix per skin, once, at registration. No shader change and no
+per-vertex cost, and a file that was already right is not touched.
 
-The other end is the loader: normalise a skin on load so `joint.global × inverse_bind` and
-`mesh.global` always agree about the scale, and the shader's precondition becomes true by
-construction rather than by the exporter's habits. That is a bigger change and it touches every
-asset, not just this one.
+Same measurement, after:
 
-Not taken here — this page is the repro and the measurement. Whichever end it is fixed at,
-`chunk_skin_blend_mesh_local.spec.js` is where the red test belongs: a folded matrix carrying a
-uniform scale, and the position it must still produce.
+| | folded scale | mean error | worst | worst on a single-joint vertex |
+| --- | --- | --- | --- | --- |
+| bind, mesh node as the file gave it | 100.0000 | 121.2470 | 165.4281 | 165.4281 |
+| posed at 0.5 s, the same | 100.0000 | 121.6197 | 165.5332 | — |
+| bind, on the skin frame | 1.0000 | 0.0002 | 0.0016 | 0.0014 |
+| posed at 0.5 s, on the skin frame | 1.0000 | 0.0001 | 0.0062 | 0.000014 |
+| bind, skin frame and §9 | 1.0000 | 0.0000 | 0.0000 | **0** |
+| posed at 0.5 s, skin frame and §9 | 1.0000 | 0.0001 | 0.0062 | **0.000001** |
+
+Neither residual was the frame. The blended ones are dual-quaternion skinning declining to be a
+linear blend, which is what it is for. The `0.0014` at bind was `dual_quat_from_m4`'s square-root
+conditioning near the identity — pre-existing, and maximally exposed by a fold that now lands every
+joint *on* the identity. Plan §9 moved the conversion onto `quat_from_m3`'s branch-picking form,
+which was already in the tree and used by nothing, and it went to zero.
+
+Confirmed on an NVIDIA RTX 4090: the frame correction fires and logs, `?skin=bind` draws a full-size
+character, `?skin=animated` dances, and §9's WGSL — which nothing offline type-checks — compiles.
+
+So the modes now read the other way round:
+
+| `?skin=` | what it should be |
+| --- | --- |
+| `off` | a 1.7 cm figure on her side — nothing deforms the clone, so the mesh node's own transform is all there is. Unchanged by the fix, and still the control for "is the geometry upload sound". |
+| `bind` | a full-size character standing in bind pose, and `await diagnose()` clean |
+| `animated` | dancing, with the traced and rasterized silhouettes the same silhouette |
 
 ## The switches
 
@@ -101,7 +121,8 @@ uniform scale, and the position it must still produce.
   vertex-slot range says the workgroup stride loop, whole meshlets say addressing, and a uniform
   factor says this bug. It checks the clone's meshlet records address a region of their own first —
   a clone still pointing at the source's vertex data would be deforming the shared rest pose in
-  place.
+  place. Since the frame is now the skin's, `inverse(mesh.global)` is the identity here and the
+  clone should come back holding the source's own positions.
 - **`?skin=animated`** — the file's dance, as `skinned_blas_refit` runs it.
 - **Path tracer** — off by default. The rasterizer reads the deformed vertices directly, with no
   tree in the way, so it is the reading to establish the answer on: soup in *both* is the vertices,

package/src/shade/playground/skinned_mesh_soup/index.html

@@ -107,10 +107,11 @@
     <p class="note">
         <strong>The answer, for the record.</strong> <code>chunk_skin_blend_mesh_local</code> needs
         <code>inverse(mesh.global) × joint.global × inverse_bind</code> to be rigid; for this file
-        it carries a uniform <strong>100×</strong>, and a dual quaternion cannot carry a scale. So
-        <code>bind</code> below is the right character at 1/100 size — one shared matrix, one shared
-        error — and <code>animated</code> is soup, sixty-five matrices each losing a different
-        amount. The README has the measurement.
+        it carried a uniform <strong>100×</strong>, and a dual quaternion cannot carry a scale.
+        <code>register_skin</code> now puts the mesh on the skin's own bind transform, so the fold
+        is the identity at bind and a rigid displacement under a clip. The README and
+        <code>SKINNING_FRAME_PLAN.md</code> have the measurement; this page is where it is confirmed
+        on a device.
     </p>
 
     <hr>
@@ -135,12 +136,14 @@
             The skinning pass runs every frame over a pose that never moves — and that pose has an
             answer the CPU knows exactly. <code>await diagnose()</code> reads the clone's vertices
             back and says which are wrong, and whether the wrong ones are a vertex-slot range (the
-            workgroup stride loop) or whole meshlets (addressing).
+            workgroup stride loop) or whole meshlets (addressing). Should be a full-size character
+            standing still, and a clean report.
         </dd>
         <dt>animated</dt>
         <dd>
             Soup only in this mode is the pose: the joint matrices, their range, or the order the
-            skin's joints resolved in.
+            skin's joints resolved in. Should be dancing, with the traced and rasterized silhouettes
+            the same silhouette.
         </dd>
     </dl>
 

package/src/shade/playground/skinned_mesh_soup/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_mesh_soup/main.js"],"names":[],"mappings":"AA8PA;;;;GAIG;AACH,yBAFa,QAAQ,IAAI,CAAC,CAkTzB"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_mesh_soup/main.js"],"names":[],"mappings":"AAiQA;;;;GAIG;AACH,yBAFa,QAAQ,IAAI,CAAC,CAkTzB"}

package/src/shade/playground/skinned_mesh_soup/main.js

@@ -50,22 +50,25 @@ import { load_default_environment } from "../load_default_environment.js";
  * - **`?skin=animated`** — the dance, as `skinned_blas_refit` runs it. Soup only here is the pose:
  *   the joint matrices, their range, or the order the skin's joints were resolved in.
  *
- * ## What the bisect found
+ * ## What the bisect found, and what was done
  *
  * `chunk_skin_blend_mesh_local` folds `inverse(mesh.transform_global)` into each joint matrix and
- * converts the product to a dual quaternion, which can only carry a rigid motion. Its doc comment
- * says so and names the precondition: the joints and the mesh node must share the scaling
- * ancestors, so that `joint.global × inverse_bind` carries the same scale `mesh.global` does and
- * the fold cancels it. Michelle is the other legal shape — her positions and inverse-bind matrices
- * are authored in the already-scaled space, `joint.global × inverse_bind` is the *identity*, and
- * the fold is a bare 100×. `dual_quat_from_m4` reads `sqrt(max(0, 1 ± m00 ± m11 ± m22))` over terms
- * of `1 + 100·(…)`, clamps whichever go negative and normalizes the rest, so the rotation it
- * extracts is wrong — and wrong differently per joint, which is what tears the mesh apart.
+ * converts the product to a dual quaternion, which can only carry a rigid motion. Michelle's
+ * positions and inverse-bind matrices are authored in the already-scaled space, so
+ * `joint.global × inverse_bind` is the *identity* and the fold was a bare 100×.
+ * `dual_quat_from_m4` reads `sqrt(max(0, 1 ± m00 ± m11 ± m22))` over terms of `1 + 100·(…)`, clamps
+ * whichever go negative and normalizes the rest, so the rotation it extracted was wrong — and wrong
+ * differently per joint, which is what tore the mesh apart. `?skin=bind` was the right character at
+ * 1/100 size (one shared matrix, one shared error) and `?skin=animated` was soup.
  *
- * So `?skin=bind` is the right character at 1/100 size (one shared matrix, one shared error) and
- * `?skin=animated` is soup (sixty-five matrices disagreeing). The README carries the numbers, and
- * `__soup_blend_probe.spec.js` is where they came from — the shader's own blend, ported to JS and
- * run over this character's own matrices, with no device involved.
+ * The frame is now the engine's rather than the asset's: `register_skin` puts each skinned mesh on
+ * its skin's own bind transform, so the fold is the identity at bind and a rigid displacement under
+ * a clip, for every shape a glTF file arrives in. See `renderer/animation/SKINNING_FRAME_PLAN.md`.
+ *
+ * All of which was established without a device — `__soup_blend_probe.spec.js` runs the shader's own
+ * blend over this character's own matrices, and the emulator tier in
+ * `chunk_skin_blend_mesh_local.spec.js` runs the real WGSL over both shapes. This page is where that
+ * is confirmed against pixels, which by then is a formality.
  *
  * ## Why through the asset framework
  *

package/src/shade/playground/skinned_mesh_soup/verify_clone_vertices.d.ts

@@ -10,8 +10,14 @@
  * @param {Renderer} options.renderer
  * @param {Scene} options.scene
  * @param {SkinnedMesh} options.mesh
- * @param {number} [options.tolerance] in mesh-local units — the space the clone is written in,
- *        which for a glTF character carrying a centimetre scale is a hundred times its world size
+ * @param {number} [options.tolerance] in mesh-local units. Since `register_skin` puts the mesh on
+ *        the skin's bind transform, mesh-local *is* world scale — a metre is a metre here, and at
+ *        bind the clone should hold the source's own positions. `1e-4` is f32 headroom over a
+ *        chain — a matrix product, a quaternion conversion and a screw motion, all at single
+ *        precision — against a smallest real violation of `1.6`, so there are four orders between
+ *        the two. It was `5e-3` while `dual_quat_from_m4` amplified a near-identity matrix's error
+ *        by its square root; `SKINNING_FRAME_PLAN.md` §9 took that out, and the same measurement on
+ *        the CPU now reads zero at bind.
  * @returns {Promise<object>}
  */
 export function verify_clone_vertices({ renderer, scene, mesh, tolerance }: {

package/src/shade/playground/skinned_mesh_soup/verify_clone_vertices.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"verify_clone_vertices.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_mesh_soup/verify_clone_vertices.js"],"names":[],"mappings":"AAsJA;;;;;;;;;;;;;;;GAeG;AACH;IAP6B,QAAQ;IACX,KAAK;IACC,IAAI;IACR,SAAS,GAA1B,MAAM;IAEJ,QAAQ,MAAM,CAAC,CAoP3B"}
+{"version":3,"file":"verify_clone_vertices.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_mesh_soup/verify_clone_vertices.js"],"names":[],"mappings":"AAyJA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IAb6B,QAAQ;IACX,KAAK;IACC,IAAI;IACR,SAAS,GAA1B,MAAM;IAQJ,QAAQ,MAAM,CAAC,CA8P3B"}