@woosh/meep-engine 3.23.0 → 3.25.0

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

@@ -11,6 +11,7 @@ import { ssr_resolve_shader_LPV } from "../../renderer/postprocess/ssr/resolve/s
 import { ssr_reproject_shader } from "../../renderer/postprocess/ssr/ssr_reproject_shader.js";
 import { ssr_spatial_denoise_shader, ssr_spatial_denoise_metadata_shader } from "../../renderer/postprocess/ssr/ssr_spatial_denoise_shader.js";
 import { create_scene } from "./scene.js";
+import { move_primitive } from "../../renderer/scene/rows/place_primitive.js";
 
 const element = id => document.getElementById(id);
 const hints = {
@@ -47,7 +48,8 @@ async function start() {
     renderer.exposure_compensation = 1;
     renderer.internal_resolution_scale = 1;
     report("Building procedural scene…");
-    const world = await create_scene();
+    const world = await create_scene(renderer);
+    const scene_context = renderer.scenes.obtain(world.scene);
     const camera = new PerspectiveCamera();
     camera.near = 0.1;
     camera.far = 80;
@@ -76,17 +78,17 @@ async function start() {
         else { pose([offset, 3.4, 8], [0, 0.3, -1.5]); }
         const moving = world.targets[2];
         const x = moving.position[0] + (experiment === 'object' ? 1.3 * t : 0);
-        moving.mesh.transform_local.setTranslation(x, moving.position[1], moving.position[2]);
-        moving.mesh.updateMatrices();
-        world.occluder.transform_local.setTranslation(experiment === 'occluder' ? 3 * t : 20, 1, 1);
-        world.occluder.updateMatrices();
+        moving.transform.setTranslation(x, moving.position[1], moving.position[2]);
+        move_primitive(scene_context, moving.entity, moving.transform);
+        world.occluder.transform.setTranslation(experiment === 'occluder' ? 3 * t : 20, 1, 1);
+        move_primitive(scene_context, world.occluder.entity, world.occluder.transform);
     }
     function reset_anchors() {
         const c = camera.transform.translation;
         // Independent oracle: mirror physical centres across y=0, then intersect C->V
         // with the plane once. These anchors stay on the floor as the camera moves.
-        anchors = world.targets.map(({ mesh }) => {
-            const p = mesh.transform_local.translation;
+        anchors = world.targets.map(({ transform }) => {
+            const p = transform.translation;
             const v = [p[0], -p[1], p[2]];
             const t = -c[1] / (v[1] - c[1]);
             return [c[0] + (v[0] - c[0]) * t, 0, c[2] + (v[2] - c[2]) * t];
@@ -133,8 +135,8 @@ async function start() {
             ctx.beginPath(); ctx.moveTo(x-8,y); ctx.lineTo(x+8,y); ctx.moveTo(x,y-8); ctx.lineTo(x,y+8); ctx.stroke();
             if (label) { ctx.font = '12px system-ui'; ctx.fillText(label,x+11,y-5); }
         };
-        world.targets.forEach(({mesh,color,label},i) => {
-            const p = mesh.transform_local.translation;
+        world.targets.forEach(({transform,color,label},i) => {
+            const p = transform.translation;
             cross([p[0],-p[1],p[2]],false,color,label);
             cross(anchors[i],true,'#c2ccd9','');
         });

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

@@ -1,18 +1,29 @@
+/**
+ * @typedef {import("../../renderer/Renderer.js").Renderer} Renderer
+ */
 /** Small, entirely procedural scene. The top of the mirror is exactly y=0. */
-export function create_scene(): Promise<{
+/**
+ * @param {Renderer} renderer whose scene context the primitives take rows on
+ */
+export function create_scene(renderer: Renderer): Promise<{
     scene: Scene;
     mirror_material: StandardShadeMaterial;
     targets: {
-        mesh: Mesh;
+        entity: number;
+        transform: Transform64;
         label: string;
         position: number[];
         size: number[];
         color: string;
         rgb: number[];
     }[];
-    occluder: Mesh;
+    occluder: {
+        entity: number;
+        transform: Transform64;
+    };
 }>;
+export type Renderer = import("../../renderer/Renderer.js").Renderer;
 import { Scene } from "../../renderer/scene/Scene.js";
 import { StandardShadeMaterial } from "../../renderer/material/StandardShadeMaterial.js";
-import { Mesh } from "../../renderer/scene/Mesh.js";
+import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
 //# sourceMappingURL=scene.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"scene.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/ssr_reprojection/scene.js"],"names":[],"mappings":"AAUA,8EAA8E;AAC9E;;;;;;;;;;;;GAuCC;sBA3CqB,+BAA+B;sCAHf,kDAAkD;qBAEnE,8BAA8B"}
+{"version":3,"file":"scene.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/ssr_reprojection/scene.js"],"names":[],"mappings":"AAaA;;GAEG;AAEH,8EAA8E;AAC9E;;GAEG;AACH,uCAFW,QAAQ;;;;gBAuBO,MAAM;mBAAa,WAAW;;;;;;;;gBAA9B,MAAM;mBAAa,WAAW;;GA6BvD;uBAzDY,OAAO,4BAA4B,EAAE,QAAQ;sBAJpC,+BAA+B;sCANf,kDAAkD;4BAI5D,8CAA8C"}

package/src/shade/playground/ssr_reprojection/scene.js

@@ -4,14 +4,30 @@ import { BoxGeometry } from "../../renderer/geometry/BoxGeometry.js";
 import { MeshoptClusterizer } from "../../renderer/geometry/meshlet/build/meshoptimizer/meshopt_clusterizer.js";
 import { StandardShadeMaterial } from "../../renderer/material/StandardShadeMaterial.js";
 import { make_sunlight } from "../../renderer/light/make_sunlight.js";
-import { Mesh } from "../../renderer/scene/Mesh.js";
+import { place_light } from "../../renderer/light/place_light.js";
+import { EntityComponentDataset } from "../../../engine/ecs/EntityComponentDataset.js";
+import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
+import { place_primitive } from "../../renderer/scene/rows/place_primitive.js";
 import { Scene } from "../../renderer/scene/Scene.js";
 import { make_flat_environment } from "../skinned_blas_refit/flat_environment.js";
 
+/**
+ * @typedef {import("../../renderer/Renderer.js").Renderer} Renderer
+ */
+
 /** Small, entirely procedural scene. The top of the mirror is exactly y=0. */
-export async function create_scene() {
+/**
+ * @param {Renderer} renderer whose scene context the primitives take rows on
+ */
+export async function create_scene(renderer) {
     await MeshoptClusterizer.ready;
+
     const scene = new Scene();
+
+    // the sun and every box stand at entities, so the scene names a dataset for them
+    scene.dataset = new EntityComponentDataset();
+
+    const scene_context = renderer.scenes.obtain(scene);
     const cube = new BoxGeometry();
     const material = (rgb, roughness = 0.65, metallic = 0, glow = 0) => {
         const result = new StandardShadeMaterial();
@@ -21,14 +37,19 @@ export async function create_scene() {
         result.metallic_factor = metallic;
         return result;
     };
+        /**
+     * A box at a row. The transform is the page's to move, through `move_primitive`.
+     *
+     * @returns {{entity: number, transform: Transform64}}
+     */
     const box = (name, position, scale, mat) => {
-        const mesh = Mesh.from(cube, mat);
-        mesh.name = name;
-        mesh.transform_local.setTranslation(...position);
-        mesh.transform_local.setScale(...scale);
-        mesh.updateMatrices();
-        scene.add(mesh);
-        return mesh;
+        const transform = new Transform64();
+
+        transform.setTranslation(...position);
+        transform.setScale(...scale);
+        transform.updateMatrix();
+
+        return { entity: place_primitive(scene_context, cube, mat, transform, { name }), transform };
     };
     const mirror_material = material([0.85, 0.88, 0.92], 0.03, 1);
     box('Planar mirror', [0, -0.1, -1], [14, 0.2, 13], mirror_material);
@@ -42,10 +63,10 @@ export async function create_scene() {
         { label: 'A', position: [-2.4, 1.3, -1.8], size: [0.85, 2.1, 0.8], color: '#ff966b', rgb: [1, 0.23, 0.08] },
         { label: 'B', position: [0, 1.7, -3.4], size: [0.9, 2.7, 0.8], color: '#82cfff', rgb: [0.08, 0.5, 1] },
         { label: 'C', position: [2.3, 1.1, -0.8], size: [0.85, 1.7, 0.8], color: '#e9a4ff', rgb: [0.75, 0.1, 1] },
-    ].map(spec => ({ ...spec, mesh: box(spec.label, spec.position, spec.size, material(spec.rgb, 0.5, 0, 0.35)) }));
+    ].map(spec => ({ ...spec, ...box(spec.label, spec.position, spec.size, material(spec.rgb, 0.5, 0, 0.35)) }));
     // Keep its resource identity stable while moving it into/out of the view.
     const occluder = box('Moving occluder', [20, 1, 1], [0.7, 2, 0.35], material([0.04, 0.05, 0.06]));
     scene.lights.environment = make_flat_environment([0.045, 0.055, 0.075]);
-    scene.lights.add(make_sunlight({ intensity: 1.5, direction: new Vector3(-0.4, -1, -0.3), temperature: 6500 }));
+    place_light(scene, make_sunlight({ intensity: 1.5, direction: new Vector3(-0.4, -1, -0.3), temperature: 6500 }));
     return { scene, mirror_material, targets, occluder };
 }

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

@@ -45,7 +45,7 @@ async function start() {
     renderer.internal_resolution_scale = 1;
     renderer.ssr.spatial_denoising_enabled = element('spatial').value === 'on';
     renderer.ssr.reprojection_mode = element('temporal').value === 'off' ? 2 : 0;
-    const world = await create_scene();
+    const world = await create_scene(renderer);
     const camera = new PerspectiveCamera();
     camera.near = 0.1; camera.far = 50; camera.fov = 50 * Math.PI / 180;
     camera.aspect = canvas.width / canvas.height;

package/src/shade/playground/ssr_variance/scene.d.ts

@@ -1,11 +1,17 @@
+/**
+ * @typedef {import("../../renderer/Renderer.js").Renderer} Renderer
+ */
 /** Two quads. The cross is a texture, with no extra geometry or surface-normal edges. */
-export function create_scene(): Promise<{
+/**
+ * @param {Renderer} renderer whose scene context the quads take rows on
+ */
+export function create_scene(renderer: Renderer): Promise<{
     scene: Scene;
-    ground: Mesh;
-    card: Mesh;
+    ground: number;
+    card: number;
     ground_material: StandardShadeMaterial;
 }>;
+export type Renderer = import("../../renderer/Renderer.js").Renderer;
 import { Scene } from "../../renderer/scene/Scene.js";
-import { Mesh } from "../../renderer/scene/Mesh.js";
 import { StandardShadeMaterial } from "../../renderer/material/StandardShadeMaterial.js";
 //# sourceMappingURL=scene.d.ts.map

package/src/shade/playground/ssr_variance/scene.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scene.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/ssr_variance/scene.js"],"names":[],"mappings":"AAeA,yFAAyF;AACzF;;;;;GA4CC;sBAnDqB,+BAA+B;qBADhC,8BAA8B;sCADb,kDAAkD"}
+{"version":3,"file":"scene.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/ssr_variance/scene.js"],"names":[],"mappings":"AAiBA;;GAEG;AAEH,yFAAyF;AACzF;;GAEG;AACH,uCAFW,QAAQ;;;;;GA6DlB;uBAlEY,OAAO,4BAA4B,EAAE,QAAQ;sBAPpC,+BAA+B;sCAJf,kDAAkD"}

package/src/shade/playground/ssr_variance/scene.js

@@ -6,34 +6,55 @@ import { make_plane_geometry } from "../../renderer/geometry/primitives/make_pla
 import { MeshletGeometry } from "../../renderer/geometry/MeshletGeometry.js";
 import { meshlet_geometry_build_from_geometry } from "../../renderer/geometry/meshlet_geometry_build_from_geometry.js";
 import { StandardShadeMaterial } from "../../renderer/material/StandardShadeMaterial.js";
-import { Mesh } from "../../renderer/scene/Mesh.js";
+import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
+import { EntityComponentDataset } from "../../../engine/ecs/EntityComponentDataset.js";
+import { place_primitive } from "../../renderer/scene/rows/place_primitive.js";
 import { Scene } from "../../renderer/scene/Scene.js";
 import { ColorSpace } from "../../renderer/texture/ColorSpace.js";
 import { ShadeTexture } from "../../renderer/texture/ShadeTexture.js";
 import { ShadeImage } from "../../renderer/texture/source/ShadeImage.js";
 import { make_flat_environment } from "../skinned_blas_refit/flat_environment.js";
 
+/**
+ * @typedef {import("../../renderer/Renderer.js").Renderer} Renderer
+ */
+
 /** Two quads. The cross is a texture, with no extra geometry or surface-normal edges. */
-export async function create_scene() {
+/**
+ * @param {Renderer} renderer whose scene context the quads take rows on
+ */
+export async function create_scene(renderer) {
     await MeshoptClusterizer.ready;
+
     const scene = new Scene();
-    const quad = (name, width, height, material) => {
+
+    // the quads stand at entities, so the scene names a dataset for them
+    scene.dataset = new EntityComponentDataset();
+
+    const scene_context = renderer.scenes.obtain(scene);
+
+    /**
+     * @returns {number} the quad's entity
+     */
+    const quad = (name, width, height, material, transform) => {
         const geometry = new MeshletGeometry();
+
         meshlet_geometry_build_from_geometry(make_plane_geometry(width, height), geometry);
-        const mesh = Mesh.from(geometry, material);
-        mesh.name = name;
-        scene.add(mesh);
-        return mesh;
+
+        return place_primitive(scene_context, geometry, material, transform, { name });
     };
     const ground_material = new StandardShadeMaterial();
     ground_material.diffuse_color.copy(new Color(0.85, 0.85, 0.85));
     ground_material.roughness_factor = 0.3;
     ground_material.metallic_factor = 1;
-    const ground = quad('Ground / roughness 0.30', 18, 18, ground_material);
-    const rotation = Quaternion.fromAxisAngle(Vector3.right, -Math.PI / 2);
-    ground.transform_local.setRotation(rotation.x, rotation.y, rotation.z, rotation.w);
-    ground.transform_local.setTranslation(0, 0, -2);
-    ground.updateMatrices();
+        const rotation = Quaternion.fromAxisAngle(Vector3.right, -Math.PI / 2);
+    const ground_transform = new Transform64();
+
+    ground_transform.setRotation(rotation.x, rotation.y, rotation.z, rotation.w);
+    ground_transform.setTranslation(0, 0, -2);
+    ground_transform.updateMatrix();
+
+    const ground = quad('Ground / roughness 0.30', 18, 18, ground_material, ground_transform);
 
     const canvas = document.createElement('canvas');
     canvas.width = canvas.height = 512;
@@ -53,9 +74,12 @@ export async function create_scene() {
     card_material.texture_emissive = pattern;
     card_material.emissive_factor.copy(new Color(1, 1, 1));
     card_material.roughness_factor = 1;
-    const card = quad('Pattern card', 3, 3, card_material);
-    card.transform_local.setTranslation(0, 2, -2);
-    card.updateMatrices();
+        const card_transform = new Transform64();
+
+    card_transform.setTranslation(0, 2, -2);
+    card_transform.updateMatrix();
+
+    const card = quad('Pattern card', 3, 3, card_material, card_transform);
     scene.lights.environment = make_flat_environment([0.025, 0.025, 0.025]);
     return { scene, ground, card, ground_material };
 }

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

@@ -0,0 +1,94 @@
+# `vgeo_runtime` — the cut, on the GPU, through the engine
+
+A `.vgeo` container drawn as an ordinary `Mesh`, in an ordinary `Scene`, with an ordinary material.
+This page draws nothing itself: every triangle on screen is there because the compute cut appended
+`MESHLET_DEFINITION_STRUCT` records into the same collection a static mesh's meshlets go into, and
+the HZB meshlet filter, the material bucket, the indirect draw and the G-buffer took it from there
+without knowing that virtual geometry exists.
+
+That is the whole difference from [`../vgeo_viewer/`](../vgeo_viewer/README.md), and the two are
+worth keeping apart. The viewer draws a **CPU** cut through Shade's direct geometry path — it
+proves the DAG, the format and the residency clamp, and by construction it proves nothing about the
+engine. This page proves the engine seam and nothing about the DAG, because the DAG has its own
+tests and its own oracle.
+
+## What it shows
+
+The container is built in the page and opened holding **only its root page**. Everything else
+arrives because the cut asked for it: a clamped cluster emits a want, the want names the page it
+was discovered through, the feedback readback resolves it to a byte range out of that page's own
+child table, and the page installs. Nothing is prefetched and no directory is read.
+
+Measured on an nvidia/lovelace adapter, a 128×48 torus at 64 KB pages — 13 pages, built in ~0.5 s
+in-page — and **re-measured on the same adapter after the review campaign**, which rewrote the VRAM
+tier onto fixed-stride page slots, moved selectability off the RAM tier, corrected the near plane's
+sign and replaced the scale correction. Every row is identical:
+
+| τ (px) | drawn clusters | pages visited | clamped | wavefronts | queue remaining |
+|---:|---:|---:|---:|---:|---:|
+| 0.5 | 50 | 9 | 0 | 14 | 0 |
+| 1 | 31 | 8 | 0 | 14 | 0 |
+| 2 | 18 | 6 | 0 | 11 | 0 |
+| 4 | 17 | 6 | 0 | 11 | 0 |
+| 8 | 9 | 5 | 0 | 8 | 0 |
+| 16 | 8 | 5 | 0 | 8 | 0 |
+
+The last two columns are new and are what the review's M8 was about: the descent ran fourteen
+wavefronts at its deepest against a budget of 64, and stopped with nothing still queued. A non-zero
+`queue remaining` is the one reading here that means a **hole** rather than a coarser surface.
+
+The cut is monotone in τ and it is a *fraction* of the asset at every setting, which is design §1's
+whole claim: rendering cost is a function of the threshold and the resolution, not of the source
+triangle count. Residency settles at 9 of 13 pages and 230 KB — the four it never fetches are the
+ones the cut never wanted.
+
+Two readings are worth watching for what they say about the loop rather than the picture:
+
+- **`clamped` goes to zero.** The first frames draw a coarse, watertight surface because the pages
+  holding the refinement have not arrived. That is not a fallback — it is the correct surface over
+  exactly that region — and the count falling to zero is the streaming finishing.
+- **`feedback skipped` is about half the frames.** The readback cap is two in flight, and a frame
+  that finds it saturated drops its feedback entirely. That is the virtual-texture contract, it
+  costs streaming latency and nothing on screen, and a loop that insisted on a reading every frame
+  would stall the frame it was reading.
+
+## Driving it
+
+`__state()` is the whole surface a headless session needs — frames, the cut's counters, and both
+residency tiers. `__page.runtime.tau` is the threshold. The panel shows nothing `__state()` does
+not.
+
+```
+npm run dev --workspace @woosh/meep-engine
+# then open /src/shade/playground/vgeo_runtime/index.html
+```
+
+**This page is the only thing that exercises the engine-integration path**, and that is not a
+rhetorical claim: 18,569 passing specs did not notice it failing to boot at all, because
+`scene.add(make_sunlight())` had outlived `Scene.add` and the page threw before defining
+`__state`. Treat a green suite without a drive as unverified.
+
+### The headless recipe, and the two things that cost an hour
+
+Start the dev server, then launch Chrome with a debugging port and connect over CDP:
+
+```
+node node_modules/vite/bin/vite.js --port 5199 --strictPort    # from packages/meep-engine
+chrome --headless=new --enable-unsafe-webgpu --remote-debugging-port=9333 \
+       --user-data-dir=<a fresh one> \
+       http://localhost:5199/src/shade/playground/vgeo_runtime/index.html
+```
+
+- **`--enable-unsafe-webgpu` and nothing else.** Adding `--enable-features=Vulkan`,
+  `--use-angle=vulkan` or `--disable-gpu-sandbox` — all of which appear in the recipes people write
+  down for headless WebGPU — makes `requestAdapter()` return nothing on this machine, and the page
+  reports it as "the browser supports WebGPU but would not provide a GPU to run on". The plain flag
+  gives a real nvidia/lovelace adapter.
+- **Pick the CDP target by URL.** `/json/list` returns extension background pages and
+  `chrome://omnibox-popup` targets as well, and the first entry is routinely not the page. Attaching
+  to one of those and asking it for `navigator.gpu` answers `undefined`, which reads exactly like a
+  browser without WebGPU.
+
+Open the page as Chrome's startup URL rather than with `Page.navigate` — the `load` event is not a
+reliable signal here, so poll for `__state` itself. Then set `__page.runtime.tau` and read
+`__state()` back.

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

@@ -0,0 +1,62 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title>meep — virtual geometry runtime</title>
+
+    <link rel="icon" href="data:,">
+
+    <style>
+        :root { color-scheme: dark; }
+
+        html, body { height: 100%; margin: 0; overflow: hidden; background: #070b10; }
+
+        #panel {
+            position: absolute; top: 0; right: 0; width: 320px; max-height: 100vh; overflow-y: auto;
+            z-index: 10; padding: 12px 14px; box-sizing: border-box;
+            font: 12px/1.45 ui-monospace, "Cascadia Mono", Consolas, monospace;
+            color: #dfe6ee; background: rgba(12, 16, 22, 0.88);
+            border-left: 1px solid #2b3947;
+        }
+
+        #panel h1 { margin: 0 0 8px; font-size: 13px; letter-spacing: 0.06em; color: #7fd2ff; }
+
+        #panel h2 {
+            margin: 14px 0 6px; font-size: 11px; letter-spacing: 0.12em; text-transform: uppercase;
+            color: #6b7c8d; border-bottom: 1px solid #24313d; padding-bottom: 3px;
+        }
+
+        #panel .row { display: flex; justify-content: space-between; gap: 8px; }
+        #panel .row span:last-child { color: #f2f6fa; text-align: right; }
+        #panel .muted { color: #6b7c8d; }
+        #panel .bad { color: #ff8a7a; }
+        #panel .good { color: #8fe388; }
+        #panel input[type=range] { width: 100%; }
+        #panel label { display: block; margin: 6px 0 2px; }
+
+        #status { white-space: pre-wrap; }
+        #status.error { color: #ff8a7a; }
+    </style>
+</head>
+<body tabindex="0">
+
+<div id="panel">
+    <h1>virtual geometry runtime</h1>
+    <div id="status" class="muted">starting…</div>
+
+    <label>threshold τ <span id="tau-value">1.0</span> px</label>
+    <input id="tau" type="range" min="0.25" max="16" step="0.25" value="1">
+
+    <h2>cut</h2>
+    <div id="cut"></div>
+
+    <h2>residency</h2>
+    <div id="residency"></div>
+</div>
+
+<canvas id="view" width="960" height="600"></canvas>
+
+<script type="module" src="./main.js"></script>
+
+</body>
+</html>

package/src/shade/playground/vgeo_runtime/main.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=main.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/vgeo_runtime/main.js"],"names":[],"mappings":""}