@woosh/meep-engine 3.0.2 → 3.2.0

package/src/shade/renderer/particles/prototypeParticleSystem.js

@@ -1,450 +1,450 @@
-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 { f32, u32 } from "../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { GraphicsContext } from "../GraphicsContext.js";
-import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
-import { CAMERA_UNIFORM_STRUCT } from "../camera/CAMERA_UNIFORM_STRUCT.js";
-import { PARTICLE_RECORD_WORD_COUNT } from "./ParticleConstants.js";
-import { PARTICLE_COUNTER_COUNT } from "./data/PARTICLE_COUNTERS.js";
-import { EMITTER_BLEND, EMITTER_PROJECTION } from "./data/PARTICLE_EMITTER_LAYOUT.js";
-import { ParticleGraph } from "./graph/ParticleGraph.js";
-import { VM_BUILTIN, VM_RANDOM_MODE } from "./isa/ParticleVMISA.js";
-import { ParticleLayout } from "./layout/ParticleLayout.js";
-import { GPUParticleSystem } from "./GPUParticleSystem.js";
-import { create_particle_effect } from "./runtime/create_particle_effect.js";
-import { fire_effect } from "./particle_prototype.js";
-import {
-    PARTICLE_BILLBOARD_RESOURCES,
-    create_particle_billboard_pipeline,
-} from "./shaders/shader_particle_render.js";
-import { shader_particle_emit } from "./shaders/shader_particle_emit.js";
-import {
-    shader_particle_build_indirect,
-    shader_particle_reset_counters,
-} from "./shaders/shader_particle_finalize.js";
-import {
-    PARTICLE_SIMULATE_WORKGROUP_SIZE,
-    shader_particle_simulate,
-} from "./shaders/shader_particle_simulate.js";
-
-/**
- * Rich, runnable demonstration of the GPU particle system in a real scene:
- *
- * - 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,
- * - the billboard pass 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.
- *
- * Everything runs against a live WebGPU device (no Renderer dependency): geometry pass, then the
- * real emit + simulate compute passes, then one instanced billboard draw over all particles (a
- * single premultiplied blend state expresses both additive and alpha). `index.html` points vite at
- * this module; run with `npm run start` (HTTPS) or `VITE_HTTP=1 npx vite` for headless browsers.
- */
-
-const CAPACITY = 1 << 15; // 32k particles
-const EMIT_WG = 64;
-const NEAR = 0.2;
-
-async function main() {
-    document.body.style.cssText = "margin:0;background:#000;overflow:hidden";
-    const canvas = document.createElement("canvas");
-    document.body.appendChild(canvas);
-
-    if (navigator.gpu === undefined) return show_message("WebGPU is not available in this browser.");
-
-    const adapter = await navigator.gpu.requestAdapter();
-    const device = await adapter.requestDevice();
-    device.addEventListener?.("uncapturederror", (e) => console.error("WebGPU error:", e.error.message));
-
-    const graphics = new GraphicsContext(device);
-    const context = canvas.getContext("webgpu");
-    const format = navigator.gpu.getPreferredCanvasFormat();
-    context.configure({ device, format, alphaMode: "opaque" });
-
-    // --- scene: four emitters, each with different settings -----------------------------------
-    const system = new GPUParticleSystem(graphics, { capacity: 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 S = () => GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC;
-    const pool = device.createBuffer({ label: "particles/pool", size: CAPACITY * PARTICLE_RECORD_WORD_COUNT * 4, usage: S() });
-    const aliveA = device.createBuffer({ label: "particles/alive_a", size: CAPACITY * 4, usage: S() });
-    const aliveB = device.createBuffer({ label: "particles/alive_b", size: CAPACITY * 4, usage: S() });
-    const dead = device.createBuffer({ label: "particles/dead", size: CAPACITY * 4, usage: S() });
-    const counters = device.createBuffer({ label: "particles/counters", size: PARTICLE_COUNTER_COUNT * 4, usage: S() });
-    const spawnRequests = device.createBuffer({ label: "particles/spawn_requests", size: CAPACITY * 4, usage: S() });
-    const emitters = data_buffer(device, "particles/emitters", built.emitters, S());
-    const program = data_buffer(device, "particles/program", built.program, S());
-    const constants = data_buffer(device, "particles/constants", built.constants, S());
-    // Debug instrumentation (counters readback + manual frame stepping) — opt in with ?debug.
-    // Useful for verifying the loop numerically in a headless / hidden tab where rAF is suspended.
-    const DEBUG = new URLSearchParams(location.search).has("debug");
-
-    // 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.
-    const argsUsage = GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT | (DEBUG ? GPUBufferUsage.COPY_SRC : 0);
-    const dispatchArgs = device.createBuffer({ label: "particles/dispatch_args", size: 3 * 4, usage: argsUsage });
-    const drawArgs = device.createBuffer({ label: "particles/draw_args", size: 4 * 4, usage: argsUsage });
-    const initial = system.initialFreeList();
-    device.queue.writeBuffer(dead, 0, initial.dead);
-    device.queue.writeBuffer(counters, 0, initial.counters);
-
-    // --- camera + geometry --------------------------------------------------------------------
-    const cameraBuffer = device.createBuffer({ label: "particles/camera", size: CAMERA_UNIFORM_STRUCT.aligned_size, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
-    const vpBuffer = device.createBuffer({ label: "vp", size: 64, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
-
-    const geo = build_geometry();
-    const geoBuffer = device.createBuffer({ label: "geometry", size: geo.byteLength, usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST });
-    device.queue.writeBuffer(geoBuffer, 0, geo);
-    const geoVertexCount = geo.length / 6;
-    const { geoPipeline, geoBindGroup } = make_geometry_pipeline(device, format, vpBuffer);
-
-    // atlas sprite + soft round falloff, filtering sampler
-    const atlasView = make_sprite_texture(device).createView();
-    const atlasSampler = device.createSampler({ magFilter: "linear", minFilter: "linear", addressModeU: "clamp-to-edge", addressModeV: "clamp-to-edge" });
-
-    // reverse-Z depth buffer (recreated on resize)
-    let depthTex = null, depthView = null, depthW = 0, depthH = 0;
-    function ensure_depth(w, h) {
-        if (depthView && depthW === w && depthH === h) return;
-        depthTex?.destroy();
-        depthTex = device.createTexture({ label: "scene_depth", size: [w, h], format: "depth32float", usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING });
-        depthView = depthTex.createView();
-        depthW = w; depthH = h;
-    }
-
-    // billboard pipeline: reverse-Z depth test (same compare as the geometry pass), no write;
-    // soft-depth reads the scene depth texture
-    const particlePipeline = create_particle_billboard_pipeline({ color_format: format, depth_format: "depth32float", depth_compare: "greater" });
-
-    let aliveRead = aliveA, aliveWrite = aliveB;
-    let last = performance.now();
-
-    // ?debug: heartbeat + occasional counters/args readback exposed on window.__stats.
-    const dbgBuf = DEBUG ? device.createBuffer({ label: "dbg", size: 64, usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ }) : null;
-    let dbgPending = false;
-    let frame_index = 0;
-
-    function frame(now) {
-        const dt = Math.min((now - last) / 1000, 0.05);
-        last = now;
-
-        const w = Math.max(1, window.innerWidth), h = Math.max(1, window.innerHeight);
-        if (canvas.width !== w || canvas.height !== h) { canvas.width = w; canvas.height = h; }
-        ensure_depth(w, h);
-        write_camera(device, cameraBuffer, vpBuffer, w / h, now / 1000);
-
-        const requests = system.update(dt);
-        if (requests.length > 0) device.queue.writeBuffer(spawnRequests, 0, requests);
-
-        const cmd = ShadeGPUCommandContext.create(graphics);
-        const u = (type, value) => cmd.allocateTransientValueBuffer(type, value, GPUBufferUsage.UNIFORM);
-        const colorView = context.getCurrentTexture().createView();
-
-        // --- geometry pass: clear colour + reverse-Z depth (far = 0), lit, writes depth ---
-        const gpass = cmd.beginRenderPass({
-            colorAttachments: [{ view: colorView, loadOp: "clear", storeOp: "store", clearValue: { r: 0.03, g: 0.035, b: 0.05, a: 1 } }],
-            depthStencilAttachment: { view: depthView, depthLoadOp: "clear", depthStoreOp: "store", depthClearValue: 0.0 },
-        });
-        gpass.setPipeline(geoPipeline);
-        gpass.setBindGroup(0, geoBindGroup);
-        gpass.setVertexBuffer(0, geoBuffer);
-        gpass.draw(geoVertexCount);
-        gpass.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.dispatch({
-                encoder: cmd,
-                bindings: { emitters, program, vm_constants: constants, pool, spawn_requests: spawnRequests, alive_out: aliveWrite, dead, counters, u_dt: u(f32, dt), u_time: u(f32, now / 1000), u_frame: u(u32, system.frame), u_count: u(u32, requests.length), u_capacity: u(u32, CAPACITY) },
-                group_count_x: Math.ceil(requests.length / EMIT_WG),
-            });
-        }
-        shader_particle_simulate.dispatchIndirect({
-            encoder: cmd,
-            bindings: { emitters, program, vm_constants: constants, pool, alive_in: aliveRead, alive_out: aliveWrite, dead, counters, u_dt: u(f32, dt), u_time: u(f32, now / 1000), u_frame: u(u32, system.frame) },
-            command: dispatchArgs,
-        });
-        // 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: dispatchArgs, draw_args: drawArgs, u_workgroup_size: u(u32, PARTICLE_SIMULATE_WORKGROUP_SIZE) },
-            group_count_x: 1,
-        });
-
-        // --- billboard pass: load colour, depth-test against the scene (read-only), exact indirect draw ---
-        const bindings = PARTICLE_BILLBOARD_RESOURCES.generateBindings({
-            camera: cameraBuffer, pool, sorted: aliveWrite, emitters,
-            atlas: atlasView, atlas_sampler: atlasSampler, scene_depth: depthView,
-        }, cmd);
-        const ppass = cmd.constructRenderPass({
-            pipeline: particlePipeline,
-            bindings,
-            colorAttachments: [{ view: colorView, loadOp: "load", storeOp: "store" }],
-            depthStencilAttachment: { view: depthView, depthReadOnly: true },
-        });
-        ppass.drawIndirect(drawArgs, 0);
-        ppass.end();
-
-        // ?debug: copy counters + args for readback every ~30 frames (stats only; never used for sizing).
-        const capture_stats = DEBUG && !dbgPending && frame_index % 30 === 0;
-        if (capture_stats) {
-            cmd.copyBufferToBuffer(counters, 0, dbgBuf, 0, PARTICLE_COUNTER_COUNT * 4);
-            cmd.copyBufferToBuffer(dispatchArgs, 0, dbgBuf, 32, 12);
-            cmd.copyBufferToBuffer(drawArgs, 0, dbgBuf, 48, 16);
-        }
-
-        cmd.finish();
-
-        frame_index++;
-        if (capture_stats) {
-            dbgPending = true;
-            dbgBuf.mapAsync(GPUMapMode.READ).then(() => {
-                const v = new Uint32Array(dbgBuf.getMappedRange().slice(0));
-                window.__stats = { f: frame_index, alive: v[0], dead: v[1], alive_in: v[4], dispatch: [v[8], v[9], v[10]], draw: [v[12], v[13]] };
-                dbgBuf.unmap(); dbgPending = false;
-            }).catch(() => { dbgPending = false; });
-        }
-
-        const t = aliveRead; aliveRead = aliveWrite; aliveWrite = t;
-        requestAnimationFrame(frame);
-    }
-    if (DEBUG) {
-        // Drive frames manually when the tab is hidden (rAF suspended) — headless verification.
-        window.__step = (n = 1) => { for (let i = 0; i < n; i++) frame(performance.now()); };
-    }
-    requestAnimationFrame(frame);
-}
-
-// ---------------------------------------------------------------------------------------------
-// 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 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, vpBuffer) {
-    const module = device.createShaderModule({ code: GEOM_WGSL });
-    const bgl = device.createBindGroupLayout({ entries: [{ binding: 0, visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT, buffer: { type: "uniform" } }] });
-    const geoPipeline = device.createRenderPipeline({
-        layout: device.createPipelineLayout({ bindGroupLayouts: [bgl] }),
-        vertex: { module, entryPoint: "vs", buffers: [{ arrayStride: 24, 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: "depth32float", depthWriteEnabled: true, depthCompare: "greater" }, // reverse-Z
-    });
-    const geoBindGroup = device.createBindGroup({ layout: bgl, entries: [{ binding: 0, resource: { buffer: vpBuffer } }] });
-    return { geoPipeline, geoBindGroup };
-}
-
-/** 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);
-}
-
-/** Reverse-Z, infinite-far perspective (WebGPU 0..1 depth: near -> 1, far -> 0). */
-function perspective_reverse_z(fovY, aspect, near) {
-    const f = 1 / Math.tan(fovY / 2);
-    return new Float32Array([
-        f / aspect, 0, 0, 0,
-        0, f, 0, 0,
-        0, 0, 0, -1,
-        0, 0, near, 0,
-    ]);
-}
-
-function write_camera(device, cameraBuffer, vpBuffer, 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(m4_allocate(), eye, center, [0, 1, 0]);
-
-    const world = m4_allocate();
-    m4_invert(world, view);
-
-    const proj = perspective_reverse_z((58 * Math.PI) / 180, aspect, NEAR);
-
-    const vp = m4_multiply(m4_allocate(), proj, view);
-
-    const data = new Float32Array(CAMERA_UNIFORM_STRUCT.aligned_size / 4);
-    const put = (field, m) => data.set(m, CAMERA_UNIFORM_STRUCT.get(field).offset / 4);
-    put("transform", world);
-    put("view_matrix", view);
-    put("projection_matrix", proj);
-    put("view_projection_matrix", vp);
-    // Reverse-Z infinite-far linearisation: view_depth = A / (device_depth + B), with A=near, B=0.
-    data.set([0, NEAR, 0, 0], CAMERA_UNIFORM_STRUCT.get("device_depth_to_view_space").offset / 4);
-    device.queue.writeBuffer(cameraBuffer, 0, data);
-    device.queue.writeBuffer(vpBuffer, 0, vp);
-}
-
-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: "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;
-}
-
-function show_message(text) {
-    const d = document.createElement("div");
-    d.textContent = text;
-    d.style.cssText = "position:fixed;inset:0;display:flex;align-items:center;justify-content:center;color:#fff;font-family:sans-serif;font-size:20px";
-    document.body.appendChild(d);
-}
-
-main().catch((e) => { console.error(e); show_message("Particle prototype failed to start — see console. " + e.message); });
+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 { f32, u32 } from "../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { GraphicsContext } from "../GraphicsContext.js";
+import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
+import { CAMERA_UNIFORM_STRUCT } from "../camera/CAMERA_UNIFORM_STRUCT.js";
+import { PARTICLE_RECORD_WORD_COUNT } from "./ParticleConstants.js";
+import { PARTICLE_COUNTER_COUNT } from "./data/PARTICLE_COUNTERS.js";
+import { EMITTER_BLEND, EMITTER_PROJECTION } from "./data/PARTICLE_EMITTER_LAYOUT.js";
+import { ParticleGraph } from "./graph/ParticleGraph.js";
+import { VM_BUILTIN, VM_RANDOM_MODE } from "./isa/ParticleVMISA.js";
+import { ParticleLayout } from "./layout/ParticleLayout.js";
+import { GPUParticleSystem } from "./GPUParticleSystem.js";
+import { create_particle_effect } from "./runtime/create_particle_effect.js";
+import { fire_effect } from "./particle_prototype.js";
+import {
+    PARTICLE_BILLBOARD_RESOURCES,
+    create_particle_billboard_pipeline,
+} from "./shaders/shader_particle_render.js";
+import { shader_particle_emit } from "./shaders/shader_particle_emit.js";
+import {
+    shader_particle_build_indirect,
+    shader_particle_reset_counters,
+} from "./shaders/shader_particle_finalize.js";
+import {
+    PARTICLE_SIMULATE_WORKGROUP_SIZE,
+    shader_particle_simulate,
+} from "./shaders/shader_particle_simulate.js";
+
+/**
+ * Rich, runnable demonstration of the GPU particle system in a real scene:
+ *
+ * - 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,
+ * - the billboard pass 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.
+ *
+ * Everything runs against a live WebGPU device (no Renderer dependency): geometry pass, then the
+ * real emit + simulate compute passes, then one instanced billboard draw over all particles (a
+ * single premultiplied blend state expresses both additive and alpha). `index.html` points vite at
+ * this module; run with `npm run start` (HTTPS) or `VITE_HTTP=1 npx vite` for headless browsers.
+ */
+
+const CAPACITY = 1 << 15; // 32k particles
+const EMIT_WG = 64;
+const NEAR = 0.2;
+
+async function main() {
+    document.body.style.cssText = "margin:0;background:#000;overflow:hidden";
+    const canvas = document.createElement("canvas");
+    document.body.appendChild(canvas);
+
+    if (navigator.gpu === undefined) return show_message("WebGPU is not available in this browser.");
+
+    const adapter = await navigator.gpu.requestAdapter();
+    const device = await adapter.requestDevice();
+    device.addEventListener?.("uncapturederror", (e) => console.error("WebGPU error:", e.error.message));
+
+    const graphics = new GraphicsContext(device);
+    const context = canvas.getContext("webgpu");
+    const format = navigator.gpu.getPreferredCanvasFormat();
+    context.configure({ device, format, alphaMode: "opaque" });
+
+    // --- scene: four emitters, each with different settings -----------------------------------
+    const system = new GPUParticleSystem(graphics, { capacity: 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 S = () => GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC;
+    const pool = device.createBuffer({ label: "particles/pool", size: CAPACITY * PARTICLE_RECORD_WORD_COUNT * 4, usage: S() });
+    const aliveA = device.createBuffer({ label: "particles/alive_a", size: CAPACITY * 4, usage: S() });
+    const aliveB = device.createBuffer({ label: "particles/alive_b", size: CAPACITY * 4, usage: S() });
+    const dead = device.createBuffer({ label: "particles/dead", size: CAPACITY * 4, usage: S() });
+    const counters = device.createBuffer({ label: "particles/counters", size: PARTICLE_COUNTER_COUNT * 4, usage: S() });
+    const spawnRequests = device.createBuffer({ label: "particles/spawn_requests", size: CAPACITY * 4, usage: S() });
+    const emitters = data_buffer(device, "particles/emitters", built.emitters, S());
+    const program = data_buffer(device, "particles/program", built.program, S());
+    const constants = data_buffer(device, "particles/constants", built.constants, S());
+    // Debug instrumentation (counters readback + manual frame stepping) — opt in with ?debug.
+    // Useful for verifying the loop numerically in a headless / hidden tab where rAF is suspended.
+    const DEBUG = new URLSearchParams(location.search).has("debug");
+
+    // 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.
+    const argsUsage = GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT | (DEBUG ? GPUBufferUsage.COPY_SRC : 0);
+    const dispatchArgs = device.createBuffer({ label: "particles/dispatch_args", size: 3 * 4, usage: argsUsage });
+    const drawArgs = device.createBuffer({ label: "particles/draw_args", size: 4 * 4, usage: argsUsage });
+    const initial = system.initialFreeList();
+    device.queue.writeBuffer(dead, 0, initial.dead);
+    device.queue.writeBuffer(counters, 0, initial.counters);
+
+    // --- camera + geometry --------------------------------------------------------------------
+    const cameraBuffer = device.createBuffer({ label: "particles/camera", size: CAMERA_UNIFORM_STRUCT.aligned_size, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+    const vpBuffer = device.createBuffer({ label: "vp", size: 64, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+
+    const geo = build_geometry();
+    const geoBuffer = device.createBuffer({ label: "geometry", size: geo.byteLength, usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST });
+    device.queue.writeBuffer(geoBuffer, 0, geo);
+    const geoVertexCount = geo.length / 6;
+    const { geoPipeline, geoBindGroup } = make_geometry_pipeline(device, format, vpBuffer);
+
+    // atlas sprite + soft round falloff, filtering sampler
+    const atlasView = make_sprite_texture(device).createView();
+    const atlasSampler = device.createSampler({ magFilter: "linear", minFilter: "linear", addressModeU: "clamp-to-edge", addressModeV: "clamp-to-edge" });
+
+    // reverse-Z depth buffer (recreated on resize)
+    let depthTex = null, depthView = null, depthW = 0, depthH = 0;
+    function ensure_depth(w, h) {
+        if (depthView && depthW === w && depthH === h) return;
+        depthTex?.destroy();
+        depthTex = device.createTexture({ label: "scene_depth", size: [w, h], format: "depth32float", usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING });
+        depthView = depthTex.createView();
+        depthW = w; depthH = h;
+    }
+
+    // billboard pipeline: reverse-Z depth test (same compare as the geometry pass), no write;
+    // soft-depth reads the scene depth texture
+    const particlePipeline = create_particle_billboard_pipeline({ color_format: format, depth_format: "depth32float", depth_compare: "greater" });
+
+    let aliveRead = aliveA, aliveWrite = aliveB;
+    let last = performance.now();
+
+    // ?debug: heartbeat + occasional counters/args readback exposed on window.__stats.
+    const dbgBuf = DEBUG ? device.createBuffer({ label: "dbg", size: 64, usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ }) : null;
+    let dbgPending = false;
+    let frame_index = 0;
+
+    function frame(now) {
+        const dt = Math.min((now - last) / 1000, 0.05);
+        last = now;
+
+        const w = Math.max(1, window.innerWidth), h = Math.max(1, window.innerHeight);
+        if (canvas.width !== w || canvas.height !== h) { canvas.width = w; canvas.height = h; }
+        ensure_depth(w, h);
+        write_camera(device, cameraBuffer, vpBuffer, w / h, now / 1000);
+
+        const requests = system.update(dt);
+        if (requests.length > 0) device.queue.writeBuffer(spawnRequests, 0, requests);
+
+        const cmd = ShadeGPUCommandContext.create(graphics);
+        const u = (type, value) => cmd.allocateTransientValueBuffer(type, value, GPUBufferUsage.UNIFORM);
+        const colorView = context.getCurrentTexture().createView();
+
+        // --- geometry pass: clear colour + reverse-Z depth (far = 0), lit, writes depth ---
+        const gpass = cmd.beginRenderPass({
+            colorAttachments: [{ view: colorView, loadOp: "clear", storeOp: "store", clearValue: { r: 0.03, g: 0.035, b: 0.05, a: 1 } }],
+            depthStencilAttachment: { view: depthView, depthLoadOp: "clear", depthStoreOp: "store", depthClearValue: 0.0 },
+        });
+        gpass.setPipeline(geoPipeline);
+        gpass.setBindGroup(0, geoBindGroup);
+        gpass.setVertexBuffer(0, geoBuffer);
+        gpass.draw(geoVertexCount);
+        gpass.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.dispatch({
+                encoder: cmd,
+                bindings: { emitters, program, vm_constants: constants, pool, spawn_requests: spawnRequests, alive_out: aliveWrite, dead, counters, u_dt: u(f32, dt), u_time: u(f32, now / 1000), u_frame: u(u32, system.frame), u_count: u(u32, requests.length), u_capacity: u(u32, CAPACITY) },
+                group_count_x: Math.ceil(requests.length / EMIT_WG),
+            });
+        }
+        shader_particle_simulate.dispatchIndirect({
+            encoder: cmd,
+            bindings: { emitters, program, vm_constants: constants, pool, alive_in: aliveRead, alive_out: aliveWrite, dead, counters, u_dt: u(f32, dt), u_time: u(f32, now / 1000), u_frame: u(u32, system.frame) },
+            command: dispatchArgs,
+        });
+        // 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: dispatchArgs, draw_args: drawArgs, u_workgroup_size: u(u32, PARTICLE_SIMULATE_WORKGROUP_SIZE) },
+            group_count_x: 1,
+        });
+
+        // --- billboard pass: load colour, depth-test against the scene (read-only), exact indirect draw ---
+        const bindings = PARTICLE_BILLBOARD_RESOURCES.generateBindings({
+            camera: cameraBuffer, pool, sorted: aliveWrite, emitters,
+            atlas: atlasView, atlas_sampler: atlasSampler, scene_depth: depthView,
+        }, cmd);
+        const ppass = cmd.constructRenderPass({
+            pipeline: particlePipeline,
+            bindings,
+            colorAttachments: [{ view: colorView, loadOp: "load", storeOp: "store" }],
+            depthStencilAttachment: { view: depthView, depthReadOnly: true },
+        });
+        ppass.drawIndirect(drawArgs, 0);
+        ppass.end();
+
+        // ?debug: copy counters + args for readback every ~30 frames (stats only; never used for sizing).
+        const capture_stats = DEBUG && !dbgPending && frame_index % 30 === 0;
+        if (capture_stats) {
+            cmd.copyBufferToBuffer(counters, 0, dbgBuf, 0, PARTICLE_COUNTER_COUNT * 4);
+            cmd.copyBufferToBuffer(dispatchArgs, 0, dbgBuf, 32, 12);
+            cmd.copyBufferToBuffer(drawArgs, 0, dbgBuf, 48, 16);
+        }
+
+        cmd.finish();
+
+        frame_index++;
+        if (capture_stats) {
+            dbgPending = true;
+            dbgBuf.mapAsync(GPUMapMode.READ).then(() => {
+                const v = new Uint32Array(dbgBuf.getMappedRange().slice(0));
+                window.__stats = { f: frame_index, alive: v[0], dead: v[1], alive_in: v[4], dispatch: [v[8], v[9], v[10]], draw: [v[12], v[13]] };
+                dbgBuf.unmap(); dbgPending = false;
+            }).catch(() => { dbgPending = false; });
+        }
+
+        const t = aliveRead; aliveRead = aliveWrite; aliveWrite = t;
+        requestAnimationFrame(frame);
+    }
+    if (DEBUG) {
+        // Drive frames manually when the tab is hidden (rAF suspended) — headless verification.
+        window.__step = (n = 1) => { for (let i = 0; i < n; i++) frame(performance.now()); };
+    }
+    requestAnimationFrame(frame);
+}
+
+// ---------------------------------------------------------------------------------------------
+// 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 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, vpBuffer) {
+    const module = device.createShaderModule({ code: GEOM_WGSL });
+    const bgl = device.createBindGroupLayout({ entries: [{ binding: 0, visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT, buffer: { type: "uniform" } }] });
+    const geoPipeline = device.createRenderPipeline({
+        layout: device.createPipelineLayout({ bindGroupLayouts: [bgl] }),
+        vertex: { module, entryPoint: "vs", buffers: [{ arrayStride: 24, 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: "depth32float", depthWriteEnabled: true, depthCompare: "greater" }, // reverse-Z
+    });
+    const geoBindGroup = device.createBindGroup({ layout: bgl, entries: [{ binding: 0, resource: { buffer: vpBuffer } }] });
+    return { geoPipeline, geoBindGroup };
+}
+
+/** 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);
+}
+
+/** Reverse-Z, infinite-far perspective (WebGPU 0..1 depth: near -> 1, far -> 0). */
+function perspective_reverse_z(fovY, aspect, near) {
+    const f = 1 / Math.tan(fovY / 2);
+    return new Float32Array([
+        f / aspect, 0, 0, 0,
+        0, f, 0, 0,
+        0, 0, 0, -1,
+        0, 0, near, 0,
+    ]);
+}
+
+function write_camera(device, cameraBuffer, vpBuffer, 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(m4_allocate(), eye, center, [0, 1, 0]);
+
+    const world = m4_allocate();
+    m4_invert(world, view);
+
+    const proj = perspective_reverse_z((58 * Math.PI) / 180, aspect, NEAR);
+
+    const vp = m4_multiply(m4_allocate(), proj, view);
+
+    const data = new Float32Array(CAMERA_UNIFORM_STRUCT.aligned_size / 4);
+    const put = (field, m) => data.set(m, CAMERA_UNIFORM_STRUCT.get(field).offset / 4);
+    put("transform", world);
+    put("view_matrix", view);
+    put("projection_matrix", proj);
+    put("view_projection_matrix", vp);
+    // Reverse-Z infinite-far linearisation: view_depth = A / (device_depth + B), with A=near, B=0.
+    data.set([0, NEAR, 0, 0], CAMERA_UNIFORM_STRUCT.get("device_depth_to_view_space").offset / 4);
+    device.queue.writeBuffer(cameraBuffer, 0, data);
+    device.queue.writeBuffer(vpBuffer, 0, vp);
+}
+
+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: "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;
+}
+
+function show_message(text) {
+    const d = document.createElement("div");
+    d.textContent = text;
+    d.style.cssText = "position:fixed;inset:0;display:flex;align-items:center;justify-content:center;color:#fff;font-family:sans-serif;font-size:20px";
+    document.body.appendChild(d);
+}
+
+main().catch((e) => { console.error(e); show_message("Particle prototype failed to start — see console. " + e.message); });