@woosh/meep-engine 3.25.0 → 3.27.0

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

@@ -12,36 +12,95 @@ proves the DAG, the format and the residency clamp, and by construction it prove
 engine. This page proves the engine seam and nothing about the DAG, because the DAG has its own
 tests and its own oracle.
 
+And it proves one thing neither the specs nor the viewer can, which is what the surface **looks
+like**. The viewer draws with `cullMode: 'none'` and colours its cut per cluster; this page draws
+through a `Front`-sided standard material with a light on it. That is the difference that caught
+the shared sample torus being wound inside-out — the near surface culled away, the far inner wall
+showing through the hole where it should have been, and normals pointing into the tube so what
+survived was lit from inside. Eighteen thousand specs and a second playground had drawn that
+container without a single one of them being able to notice.
+
+## How it is lit, and why that is not decoration
+
+A sun and an **environment map** (`load_default_environment`, the same octahedral sky eight other
+playgrounds light themselves with), and **TAA on**.
+
+Both are here for the geometry rather than for the picture. A directional light alone puts every
+surface facing away from it at ambient zero, which is precisely the silhouette and the creases —
+the places a cut is worth looking at — and a converted asset arrives with normals and no material
+authoring, so the environment is most of what there is to shade it with. TAA is the other half: a
+cut is re-selected every frame against a threshold in *pixels*, so the seams between two levels of
+detail land on different pixels from one frame to the next, and without a temporal filter every one
+of them is an aliased edge that crawls. The crawl reads as the cut being unstable when it is the
+rasterizer being point-sampled.
+
+Neither costs a reading. TAA runs downstream of the G-buffer, long after the cut has been selected
+and drawn, and its sub-pixel jitter does not move the cut: the τ table below is identical with it on
+and off. The environment is not awaited — `test_assets/` is gitignored, so a checkout without it
+gets the sun alone and still draws every triangle the cut selected.
+
+**Not the GPU sky, and that is worth writing down.** `renderer/atmosphere/GPUSky.js` and
+`view/GPUViewSkyContext.js` would be the natural source for this and are **not reachable**: nothing
+in the engine constructs either, `GPUSceneContext` has no `sky` for `GPUViewSkyContext.update` to
+ask for, and `Renderer` does not mention the atmosphere at all. Reviving it is not a playground's
+change — the sky produces an already-convolved GPU texture with `SPHERE_PROBE_MIPMAP_LEVELS` mips,
+while `GPULightCollection` builds its environment privately from a CPU `ShadeTexture` and convolves
+a full mip chain itself, so the two do not meet without a new way to hand that class a GPU-side
+environment. That is a lighting change every scene in the engine would take, and it wants its own
+piece of work.
+
 ## 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.
+A container is 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.
+
+The one the page loads itself is built in the page, so there is something to look at without a file.
+It is not what the page is *for*: **drop a `.vgeo` on the window**, or open the page at
+`?file=<url>`, and that container is swapped for a real one. A sample torus is thirteen pages and a
+converted asset is thousands, and the claim being made here is about the second.
 
-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:
+Measured on an nvidia/lovelace adapter, a 128×48 torus at 64 KB pages — 13 pages, built in ~0.4 s
+in-page — at a render target of 978×546. **The viewport is part of the measurement now**: τ is a
+count of render-target pixels, the canvas follows the window, so a row of this table without the
+resolution beside it is half a reading.
 
 | τ (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 |
+| 0.5 | 38 | 9 | 0 | 14 | 0 |
+| 1 | 18 | 6 | 0 | 11 | 0 |
+| 2 | 15 | 6 | 0 | 11 | 0 |
+| 4 | 9 | 5 | 0 | 8 | 0 |
+| 8 | 6 | 5 | 0 | 8 | 0 |
+| 16 | 4 | 3 | 0 | 6 | 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 last two columns 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
+triangle count. Residency settles at 9 of 13 pages and 231 KB — the four it never fetches are the
 ones the cut never wanted.
 
+The same claim, on the largest container of a converted 2,975-asset set — 920 MB, 17,172 pages,
+27,960,383 source triangles, served over HTTP by range requests at `?file=`:
+
+| | |
+|---|---:|
+| drawn clusters | 10,766 |
+| pages resident | 1,691 of 17,172 |
+| bytes read | 87.6 MB of 920.7 MB |
+| clamped | 0 |
+| refused installs | 0 |
+| opened in | 5 ms |
+
+Nine and a half per cent of the file, and the container was on screen five milliseconds after its
+first range came back. `clamped` reaching zero is the streaming having finished rather than the
+budget having given up — which is a distinction the panel can now make, because `refused` is beside
+it.
+
 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
@@ -52,11 +111,87 @@ Two readings are worth watching for what they say about the loop rather than the
   costs streaming latency and nothing on screen, and a loop that insisted on a reading every frame
   would stall the frame it was reading.
 
+## What residency costs, and what it used to
+
+The numbers above were taken with the tier nowhere near full. The reading that matters for a
+runtime is the one with the tier full and the camera moving, and until 2026-09-14 it was
+disqualifying: on this same container at 4,096 slots, zoomed in on a rosette, a DevTools trace had
+twenty-four main-thread tasks over 50 ms in five and a half seconds, the longest 637 ms, `refused`
+at 4.1 million and `pages visited` at 4,044 of 4,096 — every resident page touched every frame, so
+nothing could be evicted, while selectability was recomputed over the whole geometry on every
+install and every evict. `RUNTIME_PLAN_2026_09_14.md` in `runtime/` is the diagnosis and the
+rebuild.
+
+Measured after it, on an nvidia/lovelace adapter at 1258×646, a tour of eight rosettes held five
+seconds each, twice round, then the rosette at rest:
+
+| | before | after |
+|---|---:|---:|
+| main-thread tasks over 50 ms | 24 in 5.5 s, longest 637 ms | 4 in 150 s, longest 115 ms |
+| `refused`, whole run | 4,166,982 | 999, over 3,009 evictions |
+| `clamped` at rest, zoomed in | 1,334 | 0 |
+| `pages visited` zoomed in | 4,044 of 4,096 | 2,000–3,200 of 4,096 |
+| frame time zoomed in | — | p50 8.3 ms, p95 12.6 ms |
+| page fetches on workers | 0 | all of them |
+
+The panel's `RAM evicted`, `fetching` and `worker fetches` rows are new with it, and `refused` is
+the reading to keep watching: it climbs only while the tier is full of pages the cut still draws
+from, which is a budget saying no and not a tier scanning.
+
+Two things the tour still shows. The four long tasks left are `GPUMeshletManager` compactions —
+a refused allocation with free space behind it rebuilds every batch, which is the one O(resident)
+event the rebuild deferred. And under a vite dev server the first seconds after a container opens
+stall while the four page-fetch workers' module graphs are served; a bundled build does not pay
+that.
+
+## Putting an asset in it
+
+Drop a `.vgeo` anywhere on the window, or open the page at `?file=/some/asset.vgeo` — a URL source
+reads by `Range` request, so a container is opened out of its header and root page rather than
+downloaded. Either way the asset on screen is retired first: its mesh row, its entity, its VRAM
+pages and its place in the RAM tier's budget all go back, and the camera reframes on the new
+container's own bounding sphere, which is the difference between a torus a unit across and a
+building thirty metres up.
+
+Two refusals are worth recognising, because both leave what is on screen exactly as it was and say
+so in the panel rather than clearing the page:
+
+- **"this container makes no promise about its own [page size]"** — built before `FORMAT` §11.14, so
+  its pages may be over the size its header names, and this tier lays out fixed-stride slots.
+  Rebuild it.
+- **"this container's pages are bounded at N and this pool holds pages of 65536"** — right format,
+  wrong size. The pool's page size is fixed for the life of the page, because there is no slot-size
+  class table; build the asset at 64 KB.
+
+The VRAM tier here is built with **4,096 page slots** rather than the engine default of 1,024,
+which is a decision this page takes on its own and worth knowing when reading its numbers against
+another host's. At the default, an asset over a thousand pages fills the tier and `refused` starts
+climbing — and the cut then clamps against a budget instead of against τ, which is the one thing
+this page is not supposed to be showing you. `refused` is in the panel so that when it *is* the
+budget, you can see it is.
+
+## Profiling it
+
+**`T` records a GPU capture, `T` again stops it and downloads an `.sgpt`** — the same key and the
+same module (`playground/profile_hotkey.js`) the other playgrounds bind, so there is one
+implementation of the drain and the naming rather than one per page. The level is `WORKLOAD`: pass
+spans, the frame graph, and dispatch/draw counts, which measures around 14 KB a frame here.
+
+It answers the question the panel cannot. Every reading above is a **count** — clusters drawn, pages
+visited, wavefronts run — and not one of them is a cost. What is worth knowing is how the seed, the
+traverse loop, the collect and the expansion compare against the rasterization they feed, and
+whether the descent's wavefront count shows up as time or disappears into occupancy.
+
+The capture's note carries **τ, the asset and the cut it selected**, next to the adapter and the
+resolution, because the same 0.4 ms is a triumph at ten thousand clusters and a scandal at nine. A
+capture without those is a number with nothing to divide it by.
+
 ## 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.
+`__state()` is the whole surface a headless session needs — frames, the cut's counters, the asset,
+the render target's size, and both residency tiers. `__page.runtime.tau` is the threshold,
+`__load_url(url)` opens a container without a pointer to drop with. The panel shows nothing
+`__state()` does not.
 
 ```
 npm run dev --workspace @woosh/meep-engine
@@ -68,7 +203,7 @@ rhetorical claim: 18,569 passing specs did not notice it failing to boot at all,
 `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
+### The headless recipe, and the four things that cost an hour
 
 Start the dev server, then launch Chrome with a debugging port and connect over CDP:
 
@@ -88,6 +223,16 @@ chrome --headless=new --enable-unsafe-webgpu --remote-debugging-port=9333 \
   `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.
+- **Resize the window, not the viewport.** `Emulation.setDeviceMetricsOverride` moves `innerWidth`
+  and leaves `document.documentElement.clientWidth` where it was, so the page never resizes and the
+  override reads as the fix not working. `Browser.getWindowForTarget` then `Browser.setWindowBounds`
+  is a real resize and the canvas follows it.
+- **A drop is dispatchable.** `new DataTransfer()`, `items.add(new File([bytes], name))`, then
+  `window.dispatchEvent(new DragEvent('drop', { dataTransfer }))` goes through the page's own
+  handler — no pointer, and no separate code path to keep honest. `?file=` needs a server that
+  answers `Range` with a `206`; vite refuses `/@fs/` outside the workspace, so an asset off the
+  tree wants twenty lines of `http.createServer` with `Access-Control-Expose-Headers:
+  Content-Range`.
 
 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

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

@@ -1,62 +1,112 @@
-<!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>
+<!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; }
+
+        /* Placed, not sized. `Renderer` owns both of the canvas's sizes — it writes `width`/`height`
+           in device pixels and an **inline** `style.width`/`style.height` in CSS pixels every time
+           it configures the context — and an inline style beats a rule in here. So a `width: 100%`
+           on this selector would look like it was doing the work while the renderer quietly pinned
+           the canvas to whatever it was first told, and `main.js` measures the window rather than
+           the canvas for exactly that reason. */
+        #view { position: absolute; top: 0; left: 0; display: block; }
+
+        #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; }
+
+        /* A dropped file's name is as long as the file's name, and a converter's names are hashes.
+           Clipped rather than wrapped so the rows stay one line each, and `min-width: 0` because a
+           flex item refuses to shrink below its content without it — which is what put a horizontal
+           scrollbar across the whole panel. The full name is in the tooltip. */
+        #panel .row span:last-child {
+            color: #f2f6fa; text-align: right;
+            min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+        }
+
+        #panel .row span:first-child { flex: none; }
+        #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; }
+
+        /* `overflow-wrap` as well as the wrap, because the status carries a URL and a URL has no
+           spaces to break at — one `?file=` was enough to push a scrollbar across the panel. */
+        #status { white-space: pre-wrap; overflow-wrap: anywhere; }
+        #status.error { color: #ff8a7a; }
+
+        #hint, #profile-note { margin-top: 10px; color: #6b7c8d; }
+
+        #profile-status { margin-top: 4px; color: #dfe6ee; word-break: break-word; }
+        #profile-status.recording { color: #ff8a7a; }
+
+        /* Shown only while something is being dragged over the window. `inset: 0` rather than the
+           canvas's box because a file dropped on the panel is a file dropped on the page. */
+        #drop {
+            position: absolute; inset: 0; z-index: 20;
+            display: none; align-items: center; justify-content: center;
+            font: 20px ui-monospace, monospace; color: #7fd2ff;
+            background: rgba(6, 12, 20, 0.82); border: 3px dashed #7fd2ff; box-sizing: border-box;
+        }
+
+        #drop.active { display: flex; }
+    </style>
+</head>
+<body tabindex="0">
+
+<canvas id="view"></canvas>
+
+<div id="drop">drop a .vgeo file</div>
+
+<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>asset</h2>
+    <div id="asset"></div>
+
+    <h2>cut</h2>
+    <div id="cut"></div>
+
+    <h2>residency</h2>
+    <div id="residency"></div>
+
+    <h2>profiling</h2>
+    <div id="profile-status">idle · T to record</div>
+    <div id="profile-note"><strong>T</strong> starts a GPU capture and <strong>T</strong> again
+        stops it and downloads an <code>.sgpt</code>. The capture's note carries τ and the cut it
+        selected, because a pass timing here means nothing without them.</div>
+
+    <div id="hint">drop a <code>.vgeo</code> file anywhere on the page, or open
+        <code>?file=/some/asset.vgeo</code></div>
+</div>
+
+<script type="module" src="./main.js"></script>
+
+</body>
+</html>