@woosh/meep-engine 3.14.3 → 3.14.4

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

@@ -0,0 +1,552 @@
+import { m4_allocate } from "../../../core/geom/3d/mat4/m4_allocate.js";
+import { m4_invert } from "../../../core/geom/3d/mat4/m4_invert.js";
+import { m4_look_at } from "../../../core/geom/3d/mat4/m4_look_at.js";
+import { m4_multiply } from "../../../core/geom/3d/mat4/m4_multiply.js";
+import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
+import { CAMERA_UNIFORM_STRUCT } from "../../renderer/camera/CAMERA_UNIFORM_STRUCT.js";
+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 { 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";
+import { create_particle_effect } from "../../renderer/particles/runtime/create_particle_effect.js";
+import { fire_effect } from "../../renderer/particles/particle_prototype.js";
+import {
+    PARTICLE_BILLBOARD_RESOURCES,
+    create_particle_billboard_pipeline,
+} from "../../renderer/particles/shaders/shader_particle_render.js";
+import { shader_particle_emit } from "../../renderer/particles/shaders/shader_particle_emit.js";
+import {
+    shader_particle_build_indirect,
+    shader_particle_reset_counters,
+} from "../../renderer/particles/shaders/shader_particle_finalize.js";
+import {
+    PARTICLE_SIMULATE_WORKGROUP_SIZE,
+    shader_particle_simulate,
+} from "../../renderer/particles/shaders/shader_particle_simulate.js";
+
+/**
+ * The scene the particle playground draws, with every reference to the page removed: it takes a
+ * {@link GraphicsContext} and a colour target, and encodes one frame into a command context.
+ *
+ * Separate from `main.js` so the whole frame — every pass, binding, buffer usage and immediate
+ * block — can be encoded against {@link ../../device/mock/SoftwareGPUDevice.js} in a vitest spec
+ * (see `particle_scene.spec.js`). That is the only tier available to CI here; the mock validates
+ * the WebGPU API surface but executes no shaders, so what a spec can prove is that the frame is
+ * *legal*, not what it looks like. The picture is the browser's job.
+ *
+ * What the scene contains:
+ *
+ * - lit solid geometry (a ground plane + boxes) rendered into a reverse-Z depth buffer,
+ * - four emitters with distinct settings — an additive fire, an alpha soft-depth smoke column,
+ *   additive velocity-stretched sparks, and a wide soft-depth dust drift,
+ * - a billboard pass that depth-tests against the scene, so particles are occluded by the boxes and
+ *   soft-depth emitters fade as they approach surfaces.
+ *
+ * The loop is fully GPU-driven: the simulate dispatch runs via `dispatchWorkgroupsIndirect` and the
+ * billboard draw via `drawIndirect`, both from args the build-indirect pass writes on the GPU. No
+ * CPU readback participates in sizing anything — a stale CPU count would orphan alive-list entries
+ * when the population grows and double-free slots when it shrinks.
+ */
+
+/** Maximum simultaneous particles across every emitter — they share one pool. */
+const PARTICLE_CAPACITY = 1 << 15; // 32k
+
+/** Camera near plane. Also the numerator of the reverse-Z depth linearisation (see {@link write_camera}). */
+const PARTICLE_NEAR = 0.2;
+
+/**
+ * The largest immediate block any of the three compute passes declares (emit's 20-byte settings
+ * struct). Immediate data is an optional WebGPU capability, so callers check for it up front rather
+ * than letting pipeline creation fail with an error that names neither pass nor feature.
+ */
+export const PARTICLE_IMMEDIATE_BYTES = 20;
+
+/** Bytes of stats {@link ParticleScene#encode_stats_copy} writes: 8 counters, then both arg buffers. */
+export const PARTICLE_STATS_BYTES = 64;
+
+const STATS_OFFSET_DISPATCH_ARGS = 32;
+const STATS_OFFSET_DRAW_ARGS = 48;
+
+/**
+ * @typedef {object} ParticleSceneStats
+ * @property {number} alive particles alive at the end of the captured frame
+ * @property {number} dead free slots left in the pool
+ * @property {number} alive_in the snapshot next frame's simulate reads as its input length
+ * @property {number[]} dispatch simulate's indirect dispatch args, `[x, y, z]` workgroups
+ * @property {number[]} draw the billboard draw's indirect args, `[vertices, instances]`
+ */
+
+/**
+ * Build the scene against a live (or mock) device.
+ *
+ * @param {GraphicsContext} graphics
+ * @param {object} options
+ * @param {GPUTextureFormat} options.color_format format of the colour target frames are encoded into
+ * @param {number} [options.capacity] particle pool size
+ * @returns {object} the scene, see the returned object's own members
+ */
+export function create_particle_scene(graphics, { color_format, capacity = PARTICLE_CAPACITY }) {
+    const device = graphics.device;
+
+    // --- emitters: four, each with different settings -----------------------------------------
+    const system = new GPUParticleSystem(graphics, { capacity });
+
+    // fire — additive, billboard, at the base of the tall pillar
+    system.addEmitter({
+        ...fire_effect().emitter,
+        spawn_rate: 500, flipbook: [1, 1], atlas_region: [0, 0, 1, 1],
+        flags: { blend: EMITTER_BLEND.ADDITIVE, projection: EMITTER_PROJECTION.BILLBOARD },
+        transform: translation(-1, 0, 0),
+    });
+    // smoke — alpha, soft-depth, rising column above the fire
+    system.addEmitter({
+        effect: make_effect({ velocity: [0, 1.3, 0], velocityJitter: 0.35, posJitter: 0.5, accel: 0.25, life: [3, 5], size: 1.4, color: [0.45, 0.45, 0.48, 0.28] }),
+        spawn_rate: 60, atlas_region: [0, 0, 1, 1], flipbook: [1, 1],
+        flags: { blend: EMITTER_BLEND.ALPHA, projection: EMITTER_PROJECTION.BILLBOARD, soft_depth: true },
+        render: { position: "position", size: "size", color: "color" },
+        transform: translation(-1, 2.5, 0),
+    });
+    // sparks — additive, velocity-stretched, fast, short-lived, gravity, near the box
+    system.addEmitter({
+        effect: make_effect({ velocity: [0, 5, 0], velocityJitter: 4.5, posJitter: 0.15, accel: -14, life: [0.3, 0.8], size: 0.09, color: [1.0, 0.8, 0.35, 1.0] }),
+        spawn_rate: 350, atlas_region: [0, 0, 1, 1], flipbook: [1, 1],
+        flags: { blend: EMITTER_BLEND.ADDITIVE, projection: EMITTER_PROJECTION.STRETCHED },
+        render: { position: "position", size: "size", color: "color", velocity: "velocity" },
+        transform: translation(2, 1.9, -1),
+    });
+    // dust — alpha, soft-depth, slow wide drift across the ground
+    system.addEmitter({
+        effect: make_effect({ velocity: [0.3, 0.15, 0.1], velocityJitter: 0.35, posJitter: 6, accel: 0, life: [4, 7], size: 0.7, color: [0.55, 0.5, 0.42, 0.16] }),
+        spawn_rate: 120, atlas_region: [0, 0, 1, 1], flipbook: [1, 1],
+        flags: { blend: EMITTER_BLEND.ALPHA, projection: EMITTER_PROJECTION.BILLBOARD, soft_depth: true },
+        render: { position: "position", size: "size", color: "color" },
+        transform: translation(0, 0.3, 0),
+    });
+
+    const built = system.buildEmitterData();
+
+    // --- particle GPU buffers -----------------------------------------------------------------
+    const storage = GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC;
+    const pool = device.createBuffer({ label: "particles/pool", size: capacity * PARTICLE_RECORD_WORD_COUNT * 4, usage: storage });
+    const alive_a = device.createBuffer({ label: "particles/alive_a", size: capacity * 4, usage: storage });
+    const alive_b = device.createBuffer({ label: "particles/alive_b", size: capacity * 4, usage: storage });
+    const dead = device.createBuffer({ label: "particles/dead", size: capacity * 4, usage: storage });
+    const counters = device.createBuffer({ label: "particles/counters", size: PARTICLE_COUNTER_COUNT * 4, usage: storage });
+    const spawn_requests = device.createBuffer({ label: "particles/spawn_requests", size: capacity * 4, usage: storage });
+    const emitters = data_buffer(device, "particles/emitters", built.emitters, storage);
+    const program = data_buffer(device, "particles/program", built.program, storage);
+    const constants = data_buffer(device, "particles/constants", built.constants, storage);
+
+    // Indirect args, written on-GPU by the build-indirect pass. Zero-initialised (WebGPU spec), so
+    // the first frame's indirect dispatch/draw are no-ops until the first snapshot lands. COPY_SRC
+    // only so the stats copy can *display* them; nothing read back here sizes a pass.
+    const args_usage = GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT | GPUBufferUsage.COPY_SRC;
+    const dispatch_args = device.createBuffer({ label: "particles/dispatch_args", size: 3 * 4, usage: args_usage });
+    const draw_args = device.createBuffer({ label: "particles/draw_args", size: 4 * 4, usage: args_usage });
+
+    const initial = system.initialFreeList();
+    device.queue.writeBuffer(dead, 0, initial.dead);
+    device.queue.writeBuffer(counters, 0, initial.counters);
+
+    // --- camera + geometry --------------------------------------------------------------------
+    const camera_buffer = device.createBuffer({ label: "particles/camera", size: CAMERA_UNIFORM_STRUCT.aligned_size, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+    const vp_buffer = device.createBuffer({ label: "particles/vp", size: 64, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+
+    const geometry = build_geometry();
+    const geometry_buffer = device.createBuffer({ label: "particles/geometry", size: geometry.byteLength, usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST });
+    device.queue.writeBuffer(geometry_buffer, 0, geometry);
+    const geometry_vertex_count = geometry.length / GEOMETRY_FLOATS_PER_VERTEX;
+    const { geometry_pipeline, geometry_bind_group } = make_geometry_pipeline(device, color_format, vp_buffer);
+
+    // atlas sprite — soft round falloff — and the filtering sampler the billboard shader declares
+    const atlas_view = make_sprite_texture(device).createView();
+    const atlas_sampler = device.createSampler({ magFilter: "linear", minFilter: "linear", addressModeU: "clamp-to-edge", addressModeV: "clamp-to-edge" });
+
+    // billboard pipeline: reverse-Z depth test (same compare as the geometry pass), no write;
+    // soft-depth reads the scene depth texture
+    const billboard_pipeline = create_particle_billboard_pipeline({
+        color_format,
+        depth_format: DEPTH_FORMAT,
+        depth_compare: "greater",
+    });
+
+    // reverse-Z depth buffer, recreated on resize
+    let depth_texture = null;
+    let depth_view = null;
+    let depth_width = 0;
+    let depth_height = 0;
+
+    function ensure_depth(width, height) {
+        if (depth_view !== null && depth_width === width && depth_height === height) {
+            return;
+        }
+
+        depth_texture?.destroy();
+        depth_texture = device.createTexture({
+            label: "particles/scene_depth",
+            size: [width, height],
+            format: DEPTH_FORMAT,
+            usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING,
+        });
+        depth_view = depth_texture.createView();
+        depth_width = width;
+        depth_height = height;
+    }
+
+    let alive_read = alive_a;
+    let alive_write = alive_b;
+
+    return {
+        system,
+        capacity,
+
+        /** Buffers a harness may inspect. Not for the frame loop, which never reads them back. */
+        buffers: { pool, alive_a, alive_b, dead, counters, spawn_requests, emitters, program, constants, dispatch_args, draw_args },
+
+        /**
+         * Encode one whole frame: geometry, then emit + simulate + build-indirect, then the
+         * billboard draw. Does not submit — the caller finishes the context.
+         *
+         * @param {ShadeGPUCommandContext} cmd
+         * @param {object} frame
+         * @param {GPUTextureView} frame.color_view where the frame is drawn
+         * @param {number} frame.width colour target width, in texels
+         * @param {number} frame.height colour target height, in texels
+         * @param {number} frame.dt seconds since the previous frame
+         * @param {number} frame.time seconds since start, for the camera orbit and the VM's clock
+         */
+        encode_frame(cmd, { color_view, width, height, dt, time }) {
+            ensure_depth(width, height);
+            write_camera(device, camera_buffer, vp_buffer, width / height, time);
+
+            const requests = system.update(dt);
+            if (requests.length > 0) {
+                device.queue.writeBuffer(spawn_requests, 0, requests);
+            }
+
+            // --- geometry pass: clear colour + reverse-Z depth (far = 0), lit, writes depth ---
+            const geometry_pass = cmd.beginRenderPass({
+                label: "particles/geometry",
+                colorAttachments: [{ view: color_view, loadOp: "clear", storeOp: "store", clearValue: { r: 0.03, g: 0.035, b: 0.05, a: 1 } }],
+                depthStencilAttachment: { view: depth_view, depthLoadOp: "clear", depthStoreOp: "store", depthClearValue: 0.0 },
+            });
+            geometry_pass.setPipeline(geometry_pipeline);
+            geometry_pass.setBindGroup(0, geometry_bind_group);
+            geometry_pass.setVertexBuffer(0, geometry_buffer);
+            geometry_pass.draw(geometry_vertex_count);
+            geometry_pass.end();
+
+            // --- emit + simulate (simulate is sized by LAST frame's GPU-written dispatch args) ---
+            shader_particle_reset_counters.dispatch({ encoder: cmd, bindings: { counters }, group_count_x: 1 });
+
+            if (requests.length > 0) {
+                shader_particle_emit.dispatchThreads({
+                    encoder: cmd,
+                    bindings: {
+                        emitters, program, vm_constants: constants, pool, spawn_requests,
+                        alive_out: alive_write, dead, counters,
+                        settings: { u_dt: dt, u_time: time, u_frame: system.frame, u_count: requests.length, u_capacity: capacity },
+                    },
+                    thread_count_x: requests.length,
+                });
+            }
+
+            shader_particle_simulate.dispatchIndirect({
+                encoder: cmd,
+                bindings: {
+                    emitters, program, vm_constants: constants, pool,
+                    alive_in: alive_read, alive_out: alive_write, dead, counters,
+                    settings: { u_dt: dt, u_time: time, u_frame: system.frame },
+                },
+                command: dispatch_args,
+            });
+
+            // Snapshot the final alive count (next frame's simulate input) + write this frame's draw args.
+            shader_particle_build_indirect.dispatch({
+                encoder: cmd,
+                bindings: { counters, dispatch_args, draw_args, u_workgroup_size: PARTICLE_SIMULATE_WORKGROUP_SIZE },
+                group_count_x: 1,
+            });
+
+            // --- billboard pass: load colour, depth-test against the scene (read-only), indirect draw ---
+            const bindings = PARTICLE_BILLBOARD_RESOURCES.generateBindings({
+                camera: camera_buffer, pool, sorted: alive_write, emitters,
+                atlas: atlas_view, atlas_sampler, scene_depth: depth_view,
+            }, cmd);
+
+            const billboard_pass = cmd.constructRenderPass({
+                pipeline: billboard_pipeline,
+                bindings,
+                colorAttachments: [{ view: color_view, loadOp: "load", storeOp: "store" }],
+                depthStencilAttachment: { view: depth_view, depthReadOnly: true },
+            });
+            billboard_pass.drawIndirect(draw_args, 0);
+            billboard_pass.end();
+
+            const previous = alive_read;
+            alive_read = alive_write;
+            alive_write = previous;
+        },
+
+        /**
+         * Copy the counters and both indirect arg buffers into a {@link PARTICLE_STATS_BYTES}-byte
+         * MAP_READ destination, for display. Read back to *look at*: nothing here may size a pass.
+         *
+         * @param {ShadeGPUCommandContext} cmd
+         * @param {GPUBuffer} destination
+         */
+        encode_stats_copy(cmd, destination) {
+            cmd.copyBufferToBuffer(counters, 0, destination, 0, PARTICLE_COUNTER_COUNT * 4);
+            cmd.copyBufferToBuffer(dispatch_args, 0, destination, STATS_OFFSET_DISPATCH_ARGS, 3 * 4);
+            cmd.copyBufferToBuffer(draw_args, 0, destination, STATS_OFFSET_DRAW_ARGS, 4 * 4);
+        },
+
+        /**
+         * Interpret the bytes {@link encode_stats_copy} wrote.
+         *
+         * @param {ArrayBuffer} bytes
+         * @returns {ParticleSceneStats}
+         */
+        read_stats(bytes) {
+            const words = new Uint32Array(bytes);
+            const dispatch_base = STATS_OFFSET_DISPATCH_ARGS / 4;
+            const draw_base = STATS_OFFSET_DRAW_ARGS / 4;
+
+            return {
+                alive: words[0],
+                dead: words[1],
+                alive_in: words[4],
+                dispatch: [words[dispatch_base], words[dispatch_base + 1], words[dispatch_base + 2]],
+                draw: [words[draw_base], words[draw_base + 1]],
+            };
+        },
+    };
+}
+
+// ---------------------------------------------------------------------------------------------
+// Effect authoring
+// ---------------------------------------------------------------------------------------------
+
+/**
+ * A parametric point-emission effect: emit with a base velocity + jitter from a disk, integrate
+ * under a vertical acceleration, and die at end of life. Only nAge.x is consumed (kill), so the
+ * NaN lanes from the scalar age/lifetime divide are harmless.
+ */
+function make_effect({ velocity, velocityJitter = 0, posJitter = 0, accel = 0, life = [1, 2], size = 1, color = [1, 1, 1, 1] }) {
+    const layout = new ParticleLayout([
+        { name: "position", components: 3 }, { name: "velocity", components: 3 },
+        { name: "age", components: 1 }, { name: "lifetime", components: 1 },
+        { name: "size", components: 1 }, { name: "color", components: 4 },
+    ]);
+
+    const spawn = new ParticleGraph();
+    let posN = spawn.add("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;
+    }
+    spawn.wire(spawn.add("setAttribute", { name: "position" }), "value", posN);
+
+    let velN = spawn.add("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;
+    }
+    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" });
+    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 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);
+
+    return create_particle_effect({ layout, spawn, update });
+}
+
+// ---------------------------------------------------------------------------------------------
+// Geometry + camera + helpers
+// ---------------------------------------------------------------------------------------------
+
+const DEPTH_FORMAT = "depth32float";
+
+/** Interleaved `[x, y, z, nx, ny, nz]`. */
+const GEOMETRY_FLOATS_PER_VERTEX = 6;
+
+const GEOM_WGSL = /* wgsl */ `
+@group(0) @binding(0) var<uniform> vp : mat4x4<f32>;
+struct VOut { @builtin(position) clip : vec4<f32>, @location(0) normal : vec3<f32> }
+@vertex fn vs(@location(0) pos : vec3<f32>, @location(1) normal : vec3<f32>) -> VOut {
+    var o : VOut;
+    o.clip = vp * vec4<f32>(pos, 1.0);
+    o.normal = normal;
+    return o;
+}
+@fragment fn fs(in : VOut) -> @location(0) vec4<f32> {
+    let N = normalize(in.normal);
+    let L = normalize(vec3<f32>(0.35, 1.0, 0.4));
+    let diffuse = max(dot(N, L), 0.0);
+    let albedo = select(vec3<f32>(0.30, 0.32, 0.36), vec3<f32>(0.22, 0.24, 0.28), N.y < 0.9);
+    let color = albedo * (0.18 + diffuse * 0.9);
+    return vec4<f32>(color, 1.0);
+}
+`;
+
+function make_geometry_pipeline(device, format, vp_buffer) {
+    const module = device.createShaderModule({ label: "particles/geometry", code: GEOM_WGSL });
+    const layout = device.createBindGroupLayout({
+        entries: [{ binding: 0, visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT, buffer: { type: "uniform" } }],
+    });
+
+    const geometry_pipeline = device.createRenderPipeline({
+        label: "particles/geometry",
+        layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+        vertex: {
+            module,
+            entryPoint: "vs",
+            buffers: [{
+                arrayStride: GEOMETRY_FLOATS_PER_VERTEX * 4,
+                attributes: [
+                    { shaderLocation: 0, offset: 0, format: "float32x3" },
+                    { shaderLocation: 1, offset: 12, format: "float32x3" },
+                ],
+            }],
+        },
+        fragment: { module, entryPoint: "fs", targets: [{ format }] },
+        primitive: { topology: "triangle-list", cullMode: "none" },
+        depthStencil: { format: DEPTH_FORMAT, depthWriteEnabled: true, depthCompare: "greater" }, // reverse-Z
+    });
+
+    const geometry_bind_group = device.createBindGroup({ layout, entries: [{ binding: 0, resource: { buffer: vp_buffer } }] });
+
+    return { geometry_pipeline, geometry_bind_group };
+}
+
+/** Ground plane + a few boxes as an interleaved `[x,y,z, nx,ny,nz]` vertex array. */
+function build_geometry() {
+    const v = [];
+    const quad = (a, b, c, d, n) => { for (const p of [a, b, c, a, c, d]) v.push(p[0], p[1], p[2], n[0], n[1], n[2]); };
+    const box = (cx, cy, cz, sx, sy, sz) => {
+        const x0 = cx - sx / 2, x1 = cx + sx / 2, y0 = cy - sy / 2, y1 = cy + sy / 2, z0 = cz - sz / 2, z1 = cz + sz / 2;
+        quad([x0, y0, z1], [x1, y0, z1], [x1, y1, z1], [x0, y1, z1], [0, 0, 1]);
+        quad([x1, y0, z0], [x0, y0, z0], [x0, y1, z0], [x1, y1, z0], [0, 0, -1]);
+        quad([x1, y0, z1], [x1, y0, z0], [x1, y1, z0], [x1, y1, z1], [1, 0, 0]);
+        quad([x0, y0, z0], [x0, y0, z1], [x0, y1, z1], [x0, y1, z0], [-1, 0, 0]);
+        quad([x0, y1, z1], [x1, y1, z1], [x1, y1, z0], [x0, y1, z0], [0, 1, 0]);
+        quad([x0, y0, z0], [x1, y0, z0], [x1, y0, z1], [x0, y0, z1], [0, -1, 0]);
+    };
+    quad([-15, 0, -15], [15, 0, -15], [15, 0, 15], [-15, 0, 15], [0, 1, 0]); // ground
+    box(-1, 1.5, 0, 1, 3, 1);        // tall pillar next to the fire
+    box(2, 0.9, -1, 1.6, 1.8, 1.6);  // block near the sparks
+    box(0, 0.6, 3.5, 7, 1.2, 0.6);   // low wall the dust drifts against
+    return new Float32Array(v);
+}
+
+// Scratch for write_camera. One scene drives one camera, and the loop runs every frame, so these
+// are reused rather than reallocated 60 times a second.
+const camera_view = m4_allocate();
+const camera_world = m4_allocate();
+const camera_projection = m4_allocate();
+const camera_view_projection = m4_allocate();
+const camera_bytes = new Float32Array(CAMERA_UNIFORM_STRUCT.aligned_size / 4);
+
+/**
+ * Reverse-Z, infinite-far perspective (WebGPU 0..1 depth: near -> 1, far -> 0).
+ *
+ * @param {Float32Array} out column-major 4x4
+ * @param {number} fov_y vertical field of view, radians
+ * @param {number} aspect width / height
+ * @param {number} near near plane distance
+ * @returns {Float32Array} `out`
+ */
+function perspective_reverse_z(out, fov_y, aspect, near) {
+    const f = 1 / Math.tan(fov_y / 2);
+
+    out.fill(0);
+    out[0] = f / aspect;
+    out[5] = f;
+    out[11] = -1;
+    out[14] = near;
+
+    return out;
+}
+
+/**
+ * Orbit the camera and upload both camera buffers: the engine's full camera struct for the
+ * billboard shader, and a bare view-projection for the geometry pass.
+ */
+function write_camera(device, camera_buffer, vp_buffer, aspect, t) {
+    const radius = 12, height = 5.5;
+    const eye = [Math.cos(t * 0.22) * radius, height, Math.sin(t * 0.22) * radius];
+    const center = [0, 1.6, 0];
+
+    const view = m4_look_at(camera_view, eye, center, [0, 1, 0]);
+    // A look-at basis is orthonormal plus a translation, so this never reports singular.
+    m4_invert(camera_world, view);
+    const world = camera_world;
+    const projection = perspective_reverse_z(camera_projection, (58 * Math.PI) / 180, aspect, PARTICLE_NEAR);
+    const view_projection = m4_multiply(camera_view_projection, projection, view);
+
+    const put = (field, m) => camera_bytes.set(m, CAMERA_UNIFORM_STRUCT.get(field).offset / 4);
+    put("transform", world);
+    put("view_matrix", view);
+    put("projection_matrix", projection);
+    put("view_projection_matrix", view_projection);
+    // Reverse-Z infinite-far linearisation: view_depth = A / (device_depth + B), with A=near, B=0.
+    camera_bytes.set([0, PARTICLE_NEAR, 0, 0], CAMERA_UNIFORM_STRUCT.get("device_depth_to_view_space").offset / 4);
+
+    device.queue.writeBuffer(camera_buffer, 0, camera_bytes);
+    device.queue.writeBuffer(vp_buffer, 0, view_projection);
+}
+
+function translation(x, y, z) {
+    return [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, x, y, z, 1];
+}
+
+function data_buffer(device, label, data, usage) {
+    const buffer = device.createBuffer({ label, size: Math.max(data.byteLength, 4), usage });
+    device.queue.writeBuffer(buffer, 0, data);
+    return buffer;
+}
+
+/** A 64x64 radial-falloff sprite (white, alpha falloff) for soft additive/alpha blobs. */
+function make_sprite_texture(device) {
+    const N = 64;
+    const px = new Uint8Array(N * N * 4);
+    for (let y = 0; y < N; y++) {
+        for (let x = 0; x < N; x++) {
+            const dx = (x + 0.5) / N * 2 - 1, dy = (y + 0.5) / N * 2 - 1;
+            const a = Math.max(0, 1 - Math.hypot(dx, dy));
+            const i = (y * N + x) * 4;
+            px[i] = 255; px[i + 1] = 255; px[i + 2] = 255; px[i + 3] = Math.round(a * a * 255);
+        }
+    }
+    const tex = device.createTexture({ label: "particles/sprite", size: [N, N], format: "rgba8unorm", usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST });
+    device.queue.writeTexture({ texture: tex }, px, { bytesPerRow: N * 4, rowsPerImage: N }, [N, N]);
+    return tex;
+}

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

@@ -0,0 +1,122 @@
+# skinned mesh soup — repro
+
+The character from `skinned_blas_refit`, loaded the way the game loads one, with the pieces that
+could be making soup on switches.
+
+```bash
+npm run dev
+```
+
+then open `/src/shade/playground/skinned_mesh_soup/index.html`.
+
+`?count=N` for N characters, `?skin=off|bind|animated`, `?trace=1` for the path tracer. Every switch
+is in the url so a state worth showing someone can be sent as a link.
+
+## What it turned out to be
+
+**`chunk_skin_blend_mesh_local` requires `inverse(mesh.global) × joint.global × inverse_bind` to be
+rigid. For `Michelle.glb` it carries a uniform scale of exactly 100, and a dual quaternion cannot
+carry a scale.**
+
+The chunk's own doc comment states the precondition — *"the four products must be rigid, which holds
+whenever the joints and the mesh node share the scaling ancestors"* — and names the shape it was
+written for: an FBX-derived glTF that puts its unit conversion on a root node and authors the
+inverse-bind matrices in **pre-scale** mesh space, so `joint.global × inverse_bind` carries the same
+scale `mesh.global` does and the fold cancels it.
+
+Michelle is the other legal shape. Her POSITION data and her inverse-bind matrices are authored in
+the **already-scaled** space — 1.66 m tall, Y-up, as they stand — so
+
+```
+joint.global × inverse_bind = I          for every one of her 65 joints
+mesh.global                 = 0.01 scale × the up-axis rotation, from her "Character" root
+```
+
+and the fold is `inverse(mesh.global) × I`, a bare **100×**. Measured, at bind and under the dance:
+every folded matrix's column length is `100.0000`, where rigid is 1.
+
+`dual_quat_from_m4` builds its quaternion from `sqrt(max(0, 1 ± m00 ± m11 ± m22))`. Those terms are
+`1 + 100·(…)`, so the `1` is swamped and every component whose sum goes negative is **clamped to
+zero** by the `max`. The rotation it extracts is not the matrix's rotation, and how wrong it is
+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:
+
+| `?skin=` | what you see | 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. |
+
+`__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
+matrices at bind and at `t = 0.5 s` of `SambaDance`, against the position the glTF formula puts each
+vertex at. No device.
+
+### What it is not
+
+`__soup_probe.spec.js` is the ruling-out, and every one of these passes on the parsed asset before a
+GPU is involved:
+
+- the geometry is a surface, not a soup — 28 106 triangles, no degenerates, longest edge 0.093
+  against a 2.24 diagonal, every meshlet index in range;
+- the skinning attributes are sound — all 19 106 vertices land back on their rest position under
+  `joint.global × inverse_bind`, no zero-weight vertices, no out-of-range joint;
+- the source BLAS is exact — 56 211 nodes all reachable, 28 106 leaves each naming a distinct
+  triangle whose box matches to the bit, all 28 105 internal nodes exactly their children's union.
+
+So it is not the loader, not the meshlet build, not the tree, and not the refit. `skinned_blas_refit`'s
+`verify()` cannot see this at all, and that is worth saying plainly: it holds the tree's root box
+against the bounds chain's box, and **both are derived from the clone's vertex region**. Vertices
+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
+
+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.
+
+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.
+
+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.
+
+## The switches
+
+- **`?skin=off`** — no skin registered. A `SkinnedMesh` still gets a vertex clone
+  (`GPUMeshSkinningContext#obtain_geometry_index` allocates one for every skinned mesh), but nothing
+  deforms it, so what is drawn is the memcpy of the source: the rest pose under the mesh node's own
+  transform. For Michelle a *correct* result is a 1.7 cm figure on her side. Soup here would be the
+  geometry upload — the meshlet copy or its address patch — and nothing to do with skinning.
+- **`?skin=bind`** — the skin registered, no clip. `await diagnose()` in the console reads the
+  clone's vertices back off the GPU and holds them against `inverse(mesh.global) × rest`, which is
+  what the bind pose must produce. It reports which vertices are wrong and in what shape: a
+  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.
+- **`?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,
+  soup in the tracer alone is the tree.
+
+## Why through `GLTFSceneBundleAssetLoader`
+
+`skinned_blas_refit` calls `load_gltf` directly and parses the file once per character. The asset
+loader is what the game and the editor register, and it hands out **the same bundle** to every
+caller — so a second character is not a second parse, it is `instantiate_scene_bundle`: its own node
+tree, its own skins bound to that tree's joints, its own clips retargeted onto it, sharing the
+geometry and the inverse-bind matrices. Running the repro on that path is what makes a fix found
+here a fix for the engine rather than for one prototype page.
+
+## Assets
+
+`/test_assets/Michelle.glb`, gitignored and unpublished — see `test_assets/README.md`. The two
+probes skip themselves when it is absent.