@woosh/meep-engine 3.17.1 → 3.18.0

package/src/format/scene/gltf/MESHOPT_COMPRESSION_PLAN.md

@@ -80,7 +80,12 @@ a `0xa1` stream or a `COLOR` filter under the `EXT_` name is an invalid file and
 | `meshopt_decode_filter_color.js` | filter 4, in place |
 | `meshopt_decode.js` | dispatch: mode, then filter |
 | `meshopt_read_uint_var.js` | bounded LEB128 over a `Uint8Array` |
-| `__meshopt_test_streams.js` | test-only encoders, shared by the codec specs and the glTF fixtures |
+| `MESHOPT_VERTEX_BLOCK.js` | the attribute stream's block shape, shared by both sides |
+| `meshopt_encode_byte_group.js` | one group, at a width it prices out of the four on offer |
+| `meshopt_encode_data_block.js` | one data block: a width per group, then the header and the groups |
+| `meshopt_encode_vertex_buffer.js` | mode 0, versions 0 and 1 |
+| `meshopt_encode_index_sequence.js` | mode 2, choosing a baseline per index |
+| `meshopt_write_uint_var.js` | LEB128 into a `Uint8Array` at an offset |
 
 Signatures:
 
@@ -706,7 +711,23 @@ written down where they live rather than left to look like tested behaviour.
   the module twice.
 - The test-only encoder §5.3 put inline in a spec file became `__meshopt_test_streams.js`, because
   the end-to-end glTF fixtures need the same streams. `**/__**.js` is already how meep's coverage
-  configuration spells "scaffolding".
+  configuration spells "scaffolding" — but the package's `files` list is not the coverage
+  configuration, and it drops `*.spec.js` and `__fixtures__/` and nothing else, so the file shipped
+  to every consumer of the engine.
+
+  Since replaced by a real encoder (`meshopt_encode_vertex_buffer.js` and
+  `meshopt_encode_index_sequence.js`), which belongs in the package on its own merits and leaves the
+  specs with nothing test-only to share. The encoder decides what the decoder was only ever told:
+  a width per group, a control mode per byte position, a mode per channel — each priced against the
+  alternatives rather than fixed, where the test-only encoder stored every group raw.
+
+  What it does not cover: mode 1, the triangle codec, whose encoder is a different algorithm
+  (vertex and edge FIFOs, and a rotation per triangle) rather than the inverse of a decode loop;
+  and the four filters, which are lossy and so are a quantisation choice rather than a codec one.
+  Neither had a consumer here, and neither is what the test-only encoder was doing. A triangle list
+  can go through mode 2 in the meantime, which is legal and decodes, just larger. There is no
+  `meshopt_encode.js` to match `meshopt_decode.js` for the same reason: a dispatcher over three
+  modes and five filters, two thirds of which throw, is worse than the two functions that exist.
 - Three test vectors in the first draft were wrong and the implementation was right: a quaternion
   component stored at full scale is `1/sqrt(2)` and not 1; a quaternion whose four components are
   equal has its dropped component absorb all three of the others' rounding, so it is up to three and

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

@@ -1,139 +1,139 @@
-# GPU particles, through AVBOIT — playground
-
-The GPU particle path where it belongs: inside the engine's own `Renderer`, drawn by the AVBOIT
-transparency pipeline as a side channel of the transparent meshes. The page owns a `Scene` and a
-camera and nothing else — no frame graph, no pass, no pipeline, no camera buffer and no depth
-texture. Two lines turn the particles on:
-
-```js
-renderer.transparency_mode = ShadeTransparencyMode.AVBOIT;
-renderer.feature_particles_enabled = true;
-```
-
-`particle_prototype.js` — the worked-example `fire_effect` / `smoke_effect` / `register_campfire` —
-lives here too, and is spec'd here rather than from the engine's own suite so that the dependency
-runs playground → renderer and never back.
-
-## Running it
-
-```bash
-npm run dev --workspace @woosh/meep-engine
-```
-
-then open <http://localhost:5173/src/shade/playground/particle_system/index.html>.
-
-It has to be `http://localhost` rather than `file://`: WebGPU needs a secure context, and module
-imports from `file://` are blocked by CORS anyway.
-
-**It needs `subgroups` and immediate data**, both of which the renderer requires of any device it
-accepts — the prefix scans behind the spawn counts, the coherence bucketing and the scene hierarchy
-are built on subgroup ops, and every particle compute pass carries its per-dispatch state as an
-immediate block. Chrome/Edge 113+ with immediates; Claude Code's in-app browser pane is **not** one
-— it has reported no adapter at all since 2026-09-02, and no `immediate_address_space` in
-`wgslLanguageFeatures` before that.
-
-## What is on screen
-
-A `Scene` with opaque geometry (a floor, a pillar, a block), **one transparent pane** across the
-middle of the set, a sunlight, the default environment, and five emitters sharing one pool:
-
-| emitter | blend | projection | what it is there to show |
-|---|---|---|---|
-| fire | additive | billboard | `fire_effect()` straight out of `particle_prototype.js` next door, at the foot of the pillar |
-| smoke | alpha | billboard, soft-depth | a rising column that fades where it meets the pillar rather than cutting into it |
-| sparks | additive | **stretched** | short-lived, gravity-fed, stretched along velocity — the one non-billboard projection |
-| dust | alpha | billboard, soft-depth | a wide slow drift, so the floor gets a soft intersection |
-| torch | additive | billboard | a child of a node that orbits — the emitter never moves, its parent does, and the GPU hierarchy pass composes the two |
-
-The torch is the point of the scene-node design. Its record holds a row of the scene's
-`transforms` table, not a matrix; the page writes its parent's translation once a frame the way it
-would for any node, and the emitter's world position comes out of the same hierarchy pass that
-places every mesh. An emitter parented to an animated joint works the same way, with nothing copied
-through the CPU.
-
-Four distinct compiled programs, so this is also where the simulation-order bucketing has something
-to do: without it a simulate wave holds fire, smoke, spark and dust particles side by side, each
-wanting different opcodes out of the interpreter's `switch`. Nothing on screen changes when it is on
-— it is a coherence change, not a visual one — which is why it is pinned by specs rather than by
-looking.
-
-## The property the page exists to demonstrate
-
-**Particles and transparent surfaces composite against each other with no order between them.**
-Orbit around the pane. From in front, the particles behind it are dimmed by it; from behind, the
-pane is dimmed by the smoke in front of it — and neither was sorted against the other, because both
-wrote their extinction into the same voxel volume and both were resolved out of the same
-accumulators. That is what a side channel buys, and what a blended pass bolted on after the
-transparency pipeline cannot do at any price.
-
-Two more things are visible from the same seat:
-
-- **the additive emitters do not darken what is behind them.** Fire, sparks and the torch write the
-  emission accumulator, which the resolve adds outside the coverage normalization, so they light
-  the frame without taking coverage from it.
-- **switch the mode to MBOIT and the particles vanish while the pane stays.** MBOIT is the legacy
-  path and has no particle channel. The simulation keeps running — turn AVBOIT back on and the
-  effects are where they would have been, not restarted — which is the honest way to see which
-  pipeline the particles now live in.
-
-Also worth looking at, from the path itself:
-
-- particles disappearing behind the pillar as the camera orbits — the depth test, read-only, on the
-  same buffer the soft fade samples,
-- smoke and dust softening where they touch a surface instead of showing a hard intersection line,
-- sparks leaning into their own velocity — `EMITTER_PROJECTION.STRETCHED`,
-- the torch's trail following its carrier.
-
-The frame is GPU-driven end to end, spawning included. The host walks no emitters and counts no
-particles: the emitter tick pass integrates every emitter's rate on the GPU, a prefix scan of its
-counts sizes the emit dispatch, and `shader_particle_build_indirect` writes the simulate dispatch
-args and the draw args. The "Burst 4000 sparks" button is the one thing the CPU asks for, and it
-asks through the same path — a command list a pass adds to that emitter's pending spawns.
-
-The overlay shows fps and, every 30 frames, the alive count, the free-list length and the two
-indirect arg buffers. Those are read back **to look at**, on a command buffer of their own after the
-renderer's. Nothing on the CPU sizes a pass.
-
-## Bounds spheres matter here
-
-Every emitter carries one, and under AVBOIT it is not only the culling test it used to be: the
-occupancy pass marks the depth slices an emitter may occlude in from that sphere, once per emitter
-rather than once per particle. A sphere that does not hold its effect leaves particles occluding at
-slightly the wrong depth. `PARTICLE_EMITTER_MOTION` in `particle_scene.js` is the motion each effect
-is built from, and `particle_scene.spec.js` checks the spheres against it.
-
-They are sized to hold where the effect actually goes, not the last corner its jitter could reach:
-a sphere big enough for the worst case would mark most of the depth range and cost the adaptive
-slicing the very thing it is for.
-
-## Verifying it
-
-```bash
-npx vitest run src/shade/playground/particle_system
-```
-
-`particle_scene.js` holds the scene and the configuration with every reference to the page removed,
-so the spec builds the real scene — meshlets, materials, emitters — with no device, and checks what
-is the page's to get wrong: the emitters are the scene's nodes, the torch hangs off the carrier, the
-pane is transparent while the rest is opaque, the bounds spheres hold their effects, and
-`configure_particles` turns the feature on, selects AVBOIT and hands the system its sprite.
-
-What a particle *frame* encodes is not this page's business any more. It is pinned next to the code,
-against `SoftwareGPUDevice`, in `renderer/particles/graph_particles.spec.js` (the simulation, pass
-by pass, and every dispatch sized by GPU-written args) and `graph_particles_avboit.spec.js` (the
-three side-channel passes, their attachments and their indirect draws).
-
-The picture is the browser's job; no spec here can see it.
-
-### Stepping frames by hand
-
-Add `?debug` to the URL. `requestAnimationFrame` is then not used at all, and `window.__step(n)`
-runs exactly `n` frames and returns the frame counter — which is what makes the loop drivable in a
-hidden or headless tab, where rAF is suspended. `window.__stats` carries the last counters snapshot,
-and `camera_state()` / `apply_camera(...)` copy a view between sessions.
-
-## What this page does not cover
-
-Lighting is the unlit hook — `chunk_particle_lighting_unlit`, not the shading-chunk-backed one a
-lit-emitter variant would swap in. No emitter opts into simulation culling, so the frustum test in
-the tick pass is never taken here; the bounds spheres are read by the occupancy pass all the same.
+# GPU particles, through AVBOIT — playground
+
+The GPU particle path where it belongs: inside the engine's own `Renderer`, drawn by the AVBOIT
+transparency pipeline as a side channel of the transparent meshes. The page owns a `Scene` and a
+camera and nothing else — no frame graph, no pass, no pipeline, no camera buffer and no depth
+texture. Two lines turn the particles on:
+
+```js
+renderer.transparency_mode = ShadeTransparencyMode.AVBOIT;
+renderer.feature_particles_enabled = true;
+```
+
+`particle_prototype.js` — the worked-example `fire_effect` / `smoke_effect` / `register_campfire` —
+lives here too, and is spec'd here rather than from the engine's own suite so that the dependency
+runs playground → renderer and never back.
+
+## Running it
+
+```bash
+npm run dev --workspace @woosh/meep-engine
+```
+
+then open <http://localhost:5173/src/shade/playground/particle_system/index.html>.
+
+It has to be `http://localhost` rather than `file://`: WebGPU needs a secure context, and module
+imports from `file://` are blocked by CORS anyway.
+
+**It needs `subgroups` and immediate data**, both of which the renderer requires of any device it
+accepts — the prefix scans behind the spawn counts, the coherence bucketing and the scene hierarchy
+are built on subgroup ops, and every particle compute pass carries its per-dispatch state as an
+immediate block. Chrome/Edge 113+ with immediates; Claude Code's in-app browser pane is **not** one
+— it has reported no adapter at all since 2026-09-02, and no `immediate_address_space` in
+`wgslLanguageFeatures` before that.
+
+## What is on screen
+
+A `Scene` with opaque geometry (a floor, a pillar, a block), **one transparent pane** across the
+middle of the set, a sunlight, the default environment, and five emitters sharing one pool:
+
+| emitter | blend | projection | what it is there to show |
+|---|---|---|---|
+| fire | additive | billboard | `fire_effect()` straight out of `particle_prototype.js` next door, at the foot of the pillar |
+| smoke | alpha | billboard, soft-depth | a rising column that fades where it meets the pillar rather than cutting into it |
+| sparks | additive | **stretched** | short-lived, gravity-fed, stretched along velocity — the one non-billboard projection |
+| dust | alpha | billboard, soft-depth | a wide slow drift, so the floor gets a soft intersection |
+| torch | additive | billboard | a child of a node that orbits — the emitter never moves, its parent does, and the GPU hierarchy pass composes the two |
+
+The torch is the point of the scene-node design. Its record holds a row of the scene's
+`transforms` table, not a matrix; the page writes its parent's translation once a frame the way it
+would for any node, and the emitter's world position comes out of the same hierarchy pass that
+places every mesh. An emitter parented to an animated joint works the same way, with nothing copied
+through the CPU.
+
+Four distinct compiled programs, so this is also where the simulation-order bucketing has something
+to do: without it a simulate wave holds fire, smoke, spark and dust particles side by side, each
+wanting different opcodes out of the interpreter's `switch`. Nothing on screen changes when it is on
+— it is a coherence change, not a visual one — which is why it is pinned by specs rather than by
+looking.
+
+## The property the page exists to demonstrate
+
+**Particles and transparent surfaces composite against each other with no order between them.**
+Orbit around the pane. From in front, the particles behind it are dimmed by it; from behind, the
+pane is dimmed by the smoke in front of it — and neither was sorted against the other, because both
+wrote their extinction into the same voxel volume and both were resolved out of the same
+accumulators. That is what a side channel buys, and what a blended pass bolted on after the
+transparency pipeline cannot do at any price.
+
+Two more things are visible from the same seat:
+
+- **the additive emitters do not darken what is behind them.** Fire, sparks and the torch write the
+  emission accumulator, which the resolve adds outside the coverage normalization, so they light
+  the frame without taking coverage from it.
+- **switch the mode to MBOIT and the particles vanish while the pane stays.** MBOIT is the legacy
+  path and has no particle channel. The simulation keeps running — turn AVBOIT back on and the
+  effects are where they would have been, not restarted — which is the honest way to see which
+  pipeline the particles now live in.
+
+Also worth looking at, from the path itself:
+
+- particles disappearing behind the pillar as the camera orbits — the depth test, read-only, on the
+  same buffer the soft fade samples,
+- smoke and dust softening where they touch a surface instead of showing a hard intersection line,
+- sparks leaning into their own velocity — `EMITTER_PROJECTION.STRETCHED`,
+- the torch's trail following its carrier.
+
+The frame is GPU-driven end to end, spawning included. The host walks no emitters and counts no
+particles: the emitter tick pass integrates every emitter's rate on the GPU, a prefix scan of its
+counts sizes the emit dispatch, and `shader_particle_build_indirect` writes the simulate dispatch
+args and the draw args. The "Burst 4000 sparks" button is the one thing the CPU asks for, and it
+asks through the same path — a command list a pass adds to that emitter's pending spawns.
+
+The overlay shows fps and, every 30 frames, the alive count, the free-list length and the two
+indirect arg buffers. Those are read back **to look at**, on a command buffer of their own after the
+renderer's. Nothing on the CPU sizes a pass.
+
+## Bounds spheres matter here
+
+Every emitter carries one, and under AVBOIT it is not only the culling test it used to be: the
+occupancy pass marks the depth slices an emitter may occlude in from that sphere, once per emitter
+rather than once per particle. A sphere that does not hold its effect leaves particles occluding at
+slightly the wrong depth. `PARTICLE_EMITTER_MOTION` in `particle_scene.js` is the motion each effect
+is built from, and `particle_scene.spec.js` checks the spheres against it.
+
+They are sized to hold where the effect actually goes, not the last corner its jitter could reach:
+a sphere big enough for the worst case would mark most of the depth range and cost the adaptive
+slicing the very thing it is for.
+
+## Verifying it
+
+```bash
+npx vitest run src/shade/playground/particle_system
+```
+
+`particle_scene.js` holds the scene and the configuration with every reference to the page removed,
+so the spec builds the real scene — meshlets, materials, emitters — with no device, and checks what
+is the page's to get wrong: the emitters are the scene's nodes, the torch hangs off the carrier, the
+pane is transparent while the rest is opaque, and `configure_particles` turns the feature on, selects
+AVBOIT and hands the system its sprite.
+
+What a particle *frame* encodes is not this page's business any more. It is pinned next to the code,
+against `SoftwareGPUDevice`, in `renderer/particles/graph_particles.spec.js` (the simulation, pass
+by pass, and every dispatch sized by GPU-written args) and `graph_particles_avboit.spec.js` (the
+three side-channel passes, their attachments and their indirect draws).
+
+The picture is the browser's job; no spec here can see it.
+
+### Stepping frames by hand
+
+Add `?debug` to the URL. `requestAnimationFrame` is then not used at all, and `window.__step(n)`
+runs exactly `n` frames and returns the frame counter — which is what makes the loop drivable in a
+hidden or headless tab, where rAF is suspended. `window.__stats` carries the last counters snapshot,
+and `camera_state()` / `apply_camera(...)` copy a view between sessions.
+
+## What this page does not cover
+
+Lighting is the unlit hook — `chunk_particle_lighting_unlit`, not the shading-chunk-backed one a
+lit-emitter variant would swap in. No emitter opts into simulation culling, so the frustum test in
+the tick pass is never taken here; the measured boxes are read by the occupancy pass all the same.

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

@@ -1 +1 @@
-{"version":3,"file":"particle_prototype.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/particle_system/particle_prototype.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;GASG;AACH;IAL4B,UAAU,GAA3B,MAAM;IACW,WAAW,GAA5B,MAAM;IACW,eAAe,GAAhC,MAAM;;YACK,cAAc;YAAU,MAAM;aAAW,MAAM;EAgHpE;AAED;;;;GAIG;AACH;YAFsB,cAAc;YAAU,MAAM;aAAW,MAAM;EAapE;AAED;;;;;;;;;;;;;GAaG;AACH,yCANW,OAAO,+BAA+B,EAAE,KAAK;IAEa,IAAI,GAA9D,OAAO,gCAAgC,EAAE,MAAM;;UAEtC,eAAe;WAAS,eAAe;EAe1D;+BA3L8B,mDAAmD;gCAElD,qDAAqD"}
+{"version":3,"file":"particle_prototype.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/particle_system/particle_prototype.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;GASG;AACH;IAL4B,UAAU,GAA3B,MAAM;IACW,WAAW,GAA5B,MAAM;IACW,eAAe,GAAhC,MAAM;;YACK,cAAc;YAAU,MAAM;aAAW,MAAM;EA+GpE;AAED;;;;GAIG;AACH;YAFsB,cAAc;YAAU,MAAM;aAAW,MAAM;EAYpE;AAED;;;;;;;;;;;;;GAaG;AACH,yCANW,OAAO,+BAA+B,EAAE,KAAK;IAEa,IAAI,GAA9D,OAAO,gCAAgC,EAAE,MAAM;;UAEtC,eAAe;WAAS,eAAe;EAe1D;+BAzL8B,mDAAmD;gCAElD,qDAAqD"}

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

@@ -139,7 +139,6 @@ export function fire_effect({ size_curve, alpha_curve, flipbook_frames = 16 } =
         spawn_rate: 120,
         flags: { blend: EMITTER_BLEND.ADDITIVE, projection: EMITTER_PROJECTION.BILLBOARD },
         render: { position: "position", size: "size", color: "color", frame: "frame" },
-        bounds: { center: [0, 1.5, 0], radius: 2.5 },
         // No texture, so the flipbook runs over the default atlas — one white texel, read as a
         // 4x4 grid of it. A real effect names an image and the system packs it.
         flipbook: [4, 4],
@@ -160,7 +159,6 @@ export function smoke_effect() {
         spawn_rate: 25,
         flags: { blend: EMITTER_BLEND.ALPHA, projection: EMITTER_PROJECTION.BILLBOARD, soft_depth: true, lighting: true, sort: true },
         render: { position: "position", size: "size", color: "color", frame: "frame" },
-        bounds: { center: [0, 3, 0], radius: 5 },
         flipbook: [1, 1],
     };
     return { layout, effect, emitter };

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

@@ -2,12 +2,11 @@
  * The five emitters, and the node one of them rides. Pure data: no device, no scene, nothing
  * uploaded — {@link build_particle_scene} is what places them.
  *
- * Every one carries a bounds sphere that holds the effect it emits. Under AVBOIT that sphere is
- * not just the culling test it used to be: it is what marks the depth slices the emitter may
- * occlude in, so an emitter whose particles outrun it occludes at slightly the wrong depth. The
- * spheres are sized to hold where the effect actually goes rather than to the last reachable
- * corner of its jitter: a sphere big enough for the worst case would mark most of the depth range
- * and cost the adaptive slicing the very thing it is for.
+ * None of them carries bounds. The box the culling and occupancy passes use is measured from the
+ * live particles on the GPU and published into the emitter state table every tick, so an effect
+ * that travels further than anyone expected marks the depth slices it actually reaches — which is
+ * what these emitters, with their long-lived jittered plumes, would otherwise be a standing
+ * invitation to get wrong.
  *
  * @returns {{fire: ParticleEmitter, smoke: ParticleEmitter, sparks: ParticleEmitter, dust: ParticleEmitter, torch: ParticleEmitter, orbit: Node3D}}
  */
@@ -121,9 +120,7 @@ export const PARTICLE_STATS_BYTES: 64;
  */
 /**
  * What each of the four parametric emitters emits, apart from the fire, whose effect is the worked
- * example next door. Exported because the bounds spheres below are authored against these numbers
- * and a spec can check that they still hold: an emitter that travels further than its sphere
- * occludes at the wrong depth now that the sphere is the occupancy hint.
+ * example next door. Exported so the page can show what each emitter is doing.
  *
  * @type {Object<string, {velocity: number[], velocityJitter: number, posJitter: number, accel: number, life: number[], size: number, color: number[]}>}
  */

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":"AA0FA;;;;;;;;;;;;GAYG;AACH;UAFoB,eAAe;WAAS,eAAe;YAAU,eAAe;UAAQ,eAAe;WAAS,eAAe;WAAS,MAAM;EAmEjJ;AAED;;;;;;;GAOG;AACH;WAF6B,KAAK;cAAY,2CAAoC;;eAAkB,IAAI;gBAAU,IAAI;eAAS,IAAI;cAAQ,IAAI;;GAuD9I;AAED;;;;;;;;;;GAUG;AACH,8CAJW,OAAO,4BAA4B,EAAE,QAAQ,SAC7C,KAAK,GACH,OAAO,+CAA+C,EAAE,iBAAiB,CAmBrF;AAED;;;;;;GAMG;AACH,iDAHW,2CAAoC,QACpC,MAAM,QAWhB;AAED;;;;;;;GAOG;AACH,0CAJW,OAAO,+CAA+C,EAAE,iBAAiB,4DAUnF;AAED;;;;;GAKG;AACH,kCAHW,WAAW,GACT,kBAAkB,CAgB9B;AAED;;;;;GAKG;AACH,mEA4BC;AAnUD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,0FAA0F;AAC1F,sCAAuC;AAKvC;;;;;;;;;;;GAWG;AAEH;;;;;;;GAOG;AACH;QAFiB,MAAM,GAAE;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAA;KAAC;EAOpJ;;;;;WAxBY,MAAM;;;;UACN,MAAM;;;;kBACN,MAAM;;;;;cACN,MAAM;;;;;gBAEN,MAAM;;;;cAEN,MAAM,EAAE;;;;UACR,MAAM,EAAE;;gCAjDU,qDAAqD;uBAE9D,gCAAgC;sBACjC,+BAA+B;qBAFhC,8BAA8B"}
+{"version":3,"file":"particle_scene.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/particle_system/particle_scene.js"],"names":[],"mappings":"AAwFA;;;;;;;;;;;GAWG;AACH;UAFoB,eAAe;WAAS,eAAe;YAAU,eAAe;UAAQ,eAAe;WAAS,eAAe;WAAS,MAAM;EA+DjJ;AAED;;;;;;;GAOG;AACH;WAF6B,KAAK;cAAY,2CAAoC;;eAAkB,IAAI;gBAAU,IAAI;eAAS,IAAI;cAAQ,IAAI;;GAuD9I;AAED;;;;;;;;;;GAUG;AACH,8CAJW,OAAO,4BAA4B,EAAE,QAAQ,SAC7C,KAAK,GACH,OAAO,+CAA+C,EAAE,iBAAiB,CAmBrF;AAED;;;;;;GAMG;AACH,iDAHW,2CAAoC,QACpC,MAAM,QAWhB;AAED;;;;;;;GAOG;AACH,0CAJW,OAAO,+CAA+C,EAAE,iBAAiB,4DAUnF;AAED;;;;;GAKG;AACH,kCAHW,WAAW,GACT,kBAAkB,CAgB9B;AAED;;;;;GAKG;AACH,mEA4BC;AA5TD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,0FAA0F;AAC1F,sCAAuC;AAKvC;;;;;;;;;;;GAWG;AAEH;;;;;GAKG;AACH;QAFiB,MAAM,GAAE;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAA;KAAC;EAOpJ;;;;;WAtBY,MAAM;;;;UACN,MAAM;;;;kBACN,MAAM;;;;;cACN,MAAM;;;;;gBAEN,MAAM;;;;cAEN,MAAM,EAAE;;;;UACR,MAAM,EAAE;;gCAjDU,qDAAqD;uBAE9D,gCAAgC;sBACjC,+BAA+B;qBAFhC,8BAA8B"}

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

@@ -75,9 +75,7 @@ const STATS_OFFSET_DRAW_ARGS = 48;
 
 /**
  * What each of the four parametric emitters emits, apart from the fire, whose effect is the worked
- * example next door. Exported because the bounds spheres below are authored against these numbers
- * and a spec can check that they still hold: an emitter that travels further than its sphere
- * occludes at the wrong depth now that the sphere is the occupancy hint.
+ * example next door. Exported so the page can show what each emitter is doing.
  *
  * @type {Object<string, {velocity: number[], velocityJitter: number, posJitter: number, accel: number, life: number[], size: number, color: number[]}>}
  */
@@ -92,12 +90,11 @@ export const PARTICLE_EMITTER_MOTION = {
  * The five emitters, and the node one of them rides. Pure data: no device, no scene, nothing
  * uploaded — {@link build_particle_scene} is what places them.
  *
- * Every one carries a bounds sphere that holds the effect it emits. Under AVBOIT that sphere is
- * not just the culling test it used to be: it is what marks the depth slices the emitter may
- * occlude in, so an emitter whose particles outrun it occludes at slightly the wrong depth. The
- * spheres are sized to hold where the effect actually goes rather than to the last reachable
- * corner of its jitter: a sphere big enough for the worst case would mark most of the depth range
- * and cost the adaptive slicing the very thing it is for.
+ * None of them carries bounds. The box the culling and occupancy passes use is measured from the
+ * live particles on the GPU and published into the emitter state table every tick, so an effect
+ * that travels further than anyone expected marks the depth slices it actually reaches — which is
+ * what these emitters, with their long-lived jittered plumes, would otherwise be a standing
+ * invitation to get wrong.
  *
  * @returns {{fire: ParticleEmitter, smoke: ParticleEmitter, sparks: ParticleEmitter, dust: ParticleEmitter, torch: ParticleEmitter, orbit: Node3D}}
  */
@@ -120,7 +117,6 @@ export function create_particle_emitters() {
         flags: { blend: EMITTER_BLEND.ALPHA, projection: EMITTER_PROJECTION.BILLBOARD, soft_depth: true },
         render: { position: "position", size: "size", color: "color" },
         // rising at 1.3 m/s for 3 to 5 s, with the buoyancy adding a couple of metres on top
-        bounds: { center: [0, 4, 0], radius: 7 },
         position: [-1, 2.5, 0],
     });
 
@@ -132,7 +128,6 @@ export function create_particle_emitters() {
         flags: { blend: EMITTER_BLEND.ADDITIVE, projection: EMITTER_PROJECTION.STRETCHED },
         render: { position: "position", size: "size", color: "color", velocity: "velocity" },
         // thrown a few metres up and out, and pulled back down inside a second
-        bounds: { center: [0, 0.5, 0], radius: 5 },
         position: [2, 1.9, -1],
     });
 
@@ -144,7 +139,6 @@ export function create_particle_emitters() {
         flags: { blend: EMITTER_BLEND.ALPHA, projection: EMITTER_PROJECTION.BILLBOARD, soft_depth: true },
         render: { position: "position", size: "size", color: "color" },
         // emitted across a 6 m disk, then drifting slowly for up to 7 s
-        bounds: { center: [1.5, 1, 0.5], radius: 10 },
         position: [0, 0.3, 0],
     });
 
@@ -159,7 +153,6 @@ export function create_particle_emitters() {
         spawn_rate: 200,
         flags: { blend: EMITTER_BLEND.ADDITIVE, projection: EMITTER_PROJECTION.BILLBOARD },
         render: { position: "position", size: "size", color: "color" },
-        bounds: { center: [0, 1, 0], radius: 2.5 },
         position: [4, 1.2, 0],
     });
 

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

@@ -0,0 +1,103 @@
+# SSR reflection lab
+
+Run `npm run dev` from `packages/meep-engine`, then open
+<http://localhost:5173/src/shade/playground/ssr_reprojection/>.
+The page uses the actual WebGPU renderer and production SSR shaders. Geometry and
+environment lighting are procedural; only the engine's bundled lookup/noise textures
+are loaded. The browser must meet the renderer's WebGPU feature requirements.
+
+## Five-minute check
+
+1. Start with **Lateral camera**, **Parallax**, roughness **0.03**, and final TAA off.
+   Watch the reflected coloured blocks move relative to the floor grid. Solid crosses
+   mark ideal planar-mirror image centres. Dashed crosses are fixed floor positions,
+   aligned at the start of the path. Their separation illustrates surface sticking.
+2. Select **Surface only**, then **No temporal history**. Switching mode restarts
+   the path and resets histories. Compare edge lag and noise at the same part of the
+   repeatable path. Surface only uses the new validation/blending, not the old shader.
+3. Try **Forward camera** and **Orbit camera**, then raise roughness through 0.2.
+   The virtual candidate is deliberately restricted to smooth, coherent reflections.
+4. Use **Moving object** and **Occluder** to expose residual trails and disocclusion.
+   Moving reflected geometry is an acknowledged limitation. Missing off-screen or
+   hidden source geometry is also an SSR limitation, not necessarily a reprojection bug.
+5. Press **Camera cut**, **Reset reflection history**, and change resolution.
+   Old reflections should not persist. **SSR off** is a useful control proving that
+   the visible reflection comes from SSR rather than the flat environment.
+
+The guides reflect physical object centres across y=0 independently of the temporal
+ray-extension formula. They are geometry guides, not colour references: visible
+front faces, occlusion and roughness do not necessarily centre on the marker. The
+floor is planar and its top is exactly y=0. Grid strips slightly above it are visible
+surface landmarks. Guides do not perform occlusion testing.
+
+The page fixes exposure and disables bloom, sharpening, ambient occlusion and motion
+blur. Final-image TAA defaults off to expose SSR's own temporal behaviour. Pause
+motion leaves temporal sampling running; **Still camera / noise** does the same at
+the initial view. **Step frame** advances the motion by 1/60 second. For exact manual
+frame counts, append `?manual` to the URL: no animation loop is scheduled, and the
+step button submits one frame at a time. From the browser console,
+`ssr_lab.step(60)` advances 60 deterministic frames at 1/60 second.
+
+**Validate GPU shaders** compiles trace, both resolves, both spatial variants, and
+temporal reprojection on the live GPU. This checks native WGSL compilation, while
+running the playground also exercises IBL pipeline creation and frame-graph wiring.
+The page reports and stops on uncaptured GPU errors. LPV composition is checked but
+the procedural scene uses IBL, so this does not test LPV atlas content or lighting.
+
+Production integration is small: `renderer.ssr.reprojection_mode` selects
+`SSRReprojectionMode.Parallax`, `.Surface`, or `.CurrentFrame`. Changing it invalidates
+SSR history. Default rendering continues to use Parallax.
+
+Do not use frame rate on this page as an SSR-only GPU timing measurement. It includes
+the entire renderer, the browser, and the overlay. Profile the actual passes before
+making performance claims. HMR is disabled by the playground Vite config; reload
+the browser explicitly after source edits.
+
+## Validation performed
+
+The page was exercised on the native NVIDIA adapter: IBL rendering, all four
+comparison modes, a moving target and occluder, camera cut, resolution change,
+and final TAA toggle. The SSR-off control visibly removes the reflections.
+All six SSR shader modules compile on that device, and the 14 SSR regression
+tests pass. Declaration emission and consumer API pins pass; the existing
+repository type-error budget is still exceeded (899 errors versus 897).
+
+## Spatial denoising
+
+The **Spatial denoising** checkbox defaults on. It toggles one spatial pass before
+reprojection and two afterward; the chosen reprojection mode stays unchanged.
+Changing this setting resets SSR history so filtered and unfiltered inputs are not
+mixed across the transition. The runtime setting is
+`renderer.ssr.spatial_denoising_enabled`. With the box unchecked and **No temporal
+history** selected, the output comes directly from resolve. Resolve still borrows
+neighbouring ray hits and uses roughness-dependent radiance filtering; this switch
+does not turn the resolve stage into a raw one-ray-per-pixel view.
+
+## Measuring actual filter effectiveness
+
+**Measure spatial filter** records the first spatial pass's input and output in
+one GPU frame. It reports the fraction of upward-facing mirror pixels whose maximum
+RGB-channel difference exceeds 0.001, mean/max difference in linear HDR radiance,
+and the fraction whose input variance is effectively zero. It is an effect check,
+not an image-quality score or an SSR performance benchmark. Readback runs only on
+request; its temporary texture is released afterward. Ordinary playback has no
+probe passes. SSR must be enabled. With spatial filtering off, the bypass is compared
+with itself and the measured difference is zero.
+
+This probe exposed a filter failure on 2026-09-08: roughly 98% of this scene's mirror
+pixels had resolve variance ≤1e-6. The old first pass changed radiance by just 0.00137
+on average; the sparse noisy samples were being rejected as colour edges. Resolve's
+within-pixel ray variance is not sufficient evidence of low spatial noise when only
+one hit supplies radiance or the hit confidence switches between SSR and fallback.
+
+The first pass now bootstraps uncertainty from a Gaussian-weighted 3×3 luminance
+neighbourhood, using the existing geometry weights, and carries that uncertainty
+through the subsequent spatial passes. It does not bootstrap again at larger radii.
+A representative corrected GPU measurement gave mean change 0.00552 with filtering
+on, and 0 with it off. These are separate frames, not a matched-noise quality metric.
+The native images visibly differ, and an emulator regression verifies reduced
+checker noise with zero input variance, unchanged constant colour (within float
+precision), and rejection across opposite normals. The full SSR suite has 16 tests.
+
+Spatial filtering trades sharpness for noise reduction, including at reflected
+colour edges; these guides and tests do not establish an optimal filter bandwidth.

package/src/shade/playground/ssr_reprojection/SpatialFilterProbe.d.ts

@@ -0,0 +1,17 @@
+/** Same-frame GPU input/output comparison. Opt-in; no cost during ordinary playback. */
+export class SpatialFilterProbe extends RenderExtension {
+    constructor(device: any);
+    enabled: boolean;
+    texture: any;
+    device: any;
+    record(frame: any): void;
+    read(): Promise<{
+        pixels: number;
+        changed_percent: number;
+        zero_variance_percent: number;
+        mean: number;
+        max: number;
+    }>;
+}
+import { RenderExtension } from "../../renderer/extension/RenderExtension.js";
+//# sourceMappingURL=SpatialFilterProbe.d.ts.map

package/src/shade/playground/ssr_reprojection/SpatialFilterProbe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpatialFilterProbe.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/ssr_reprojection/SpatialFilterProbe.js"],"names":[],"mappings":"AA2BA,wFAAwF;AACxF;IAKI,yBAAoD;IAHpD,iBAAgB;IAChB,aAAQ;IACR,YAAO;IAEP,yBAoBC;IACD;;;;;;OAWC;CACJ;gCAnE+B,6CAA6C"}