@woosh/meep-engine 3.1.0 → 3.2.0

package/src/shade/renderer/texture/virtual/README.md

@@ -1,276 +1,276 @@
-# Virtual Textures
-
-Opt-in software virtual texturing for the deferred (visibility-buffer)
-renderer: materials sample from streamed pages of arbitrarily large
-textures, with GPU memory bounded by what is visible instead of what is
-loaded. Built for **hundreds of simultaneous virtual textures** sharing one
-page table, one physical cache and one feedback pass.
-
-This README covers running the demo, adopting the system, configuration and
-the working design. The extended design document — literature survey,
-decision log, scale math, future work — is [`VIRTUAL_TEXTURES.md`](../../../../VIRTUAL_TEXTURES.md)
-in the repo root.
-
----
-
-## Demo / prototype
-
-[`prototypeVirtualTexture.js`](./prototypeVirtualTexture.js) is a
-self-contained vite entry point. Two ways to run it:
-
-1. **Dedicated page** — `npm start`, then open `https://localhost:5173/vt.html`
-   (the html at the repo root already points at the prototype).
-2. **Entry-point swap** — point the `<script type="module">` in `index.html`
-   at `src/tools/playground/prototype_virtual_texture.js`, same as the
-   particles prototype workflow.
-
-The scene contains four objects chosen to exercise every path:
-
-| Object | Stack | Source | Demonstrates |
-|---|---|---|---|
-| Ground plane (100 m) | 8192² | `VTSourceProcedural`, instant | mip selection & residency, visually |
-| Back wall | 4096² | `VTSourceProcedural`, 250 ms latency | streaming: pinned root first, refinement blending in |
-| Box | 2048² | `VTSourceImage` (runtime-tiled canvas) | zero-pipeline adoption of ordinary images |
-| Plain orange box | — | regular material | mixed standard/VT pipelines in one material pass |
-
-The procedural tiles are the classic VT debug pattern: **color = mip level,
-label = `mip:x,y` page address**, white page frames. Fly toward the ground
-and watch red (mip 0) pages stream in around you; the concentric color rings
-are the mip ladder.
-
-The GUI exposes the `feature_virtual_textures` kill switch, feedback stride,
-the wall's simulated latency, and live residency stats.
-
-### Headless / scripted driving
-
-Hidden or unfocused tabs never fire `requestAnimationFrame` and clamp timers
-to ~1 s, so the demo also installs console hooks:
-
-```js
-await vt_step(30);      // render 30 frames, paced against the GPU; returns stats
-window.vt               // the VirtualTextureManager (stats, config)
-window.renderer, window.scene, window.camera, window.controller
-```
-
-`vt_step` mirrors the frame loop (resize, controller, render) and awaits
-`onSubmittedWorkDone` per frame so feedback readbacks resolve between frames
-— this is how the system is verified without a visible window.
-
----
-
-## Using it
-
-### Opt a material in
-
-```js
-import { VirtualTextureStack } from "./texture/virtual/VirtualTextureStack.js";
-import { VTSourceTiled } from "./texture/virtual/source/VTSourceTiled.js";
-
-material.vt_stack = VirtualTextureStack.from({
-    label: 'rock',
-    size: 8192,                       // texels; square, power of two
-    source: new VTSourceTiled({
-        layers: [                     // URL template per cache layer
-            'tiles/rock/albedo/{mip}/{x}_{y}.webp',
-            'tiles/rock/normal/{mip}/{x}_{y}.webp',
-            'tiles/rock/orm/{mip}/{x}_{y}.webp',
-        ],
-    }),
-    wrap: true,                       // repeat (false = clamp), applied in-shader
-    uv_set: 0,                        // 0 or 1
-    average_color: [0.4, 0.35, 0.3, 1], // linear premultiplied; shown before the root arrives
-});
-```
-
-That is the entire opt-in. Registration happens automatically when the
-material is first built; a stack may be shared by any number of materials.
-Everything else in the engine renders exactly as before, and the system
-allocates nothing until the first stack registers.
-
-A **stack** is the unit of virtualization: a set of texture layers
-(albedo / normal / ORM in the standard cache group) sharing one UV set and
-one resolution. The whole set streams, resides and is addressed as one —
-one feedback value, one page-table entry, one residency decision, and in the
-material shader one page-table fetch feeds all three layer samples. This is
-the "do the work once for matching UV sets" design, per UE's VT stacks /
-Granite's stacked textures.
-
-### Tile sources
-
-A source implements:
-
-```js
-prepare(geometry)?                 // called on registration: {page_size, border,
-                                   //  slot_size, layer_count, size, mip_count}
-load_page(mip, x, y, signal)       // → Promise<payload[]>, one per layer;
-                                   //   payloads are slot_size² (border baked in);
-                                   //   reject with AbortError on signal abort
-layer_mask                         // bitmask of layers provided (bit0 = albedo…)
-destroy()?                         // called on last unregistration
-```
-
-Included:
-
-- **`VTSourceTiled`** — pre-tiled page files over HTTP, decoded with
-  `createImageBitmap` (WebP/AVIF/PNG/JPEG — browser-native, no WASM).
-  `legacy_meep_mips: true` consumes the original meep VT converter's output
-  (`${mip}-${x}-${y}.png`, coarsest-is-zero naming) unchanged. Serve
-  normal/ORM tiles lossless or 4:4:4 — chroma subsampling mangles them.
-- **`VTSourceImage`** — runtime tiler: hand it ordinary decoded images and it
-  builds a canvas mip pyramid once and blits padded tiles on demand. The
-  adoption path — wins GPU memory and bandwidth, not host memory.
-- **`VTSourceProcedural`** — instant labeled debug tiles, optional artificial
-  latency. Also the reference source implementation.
-
-Missing layers (e.g. albedo-only stacks) fall back per layer in the shader:
-albedo → the stack's `average_color`, normal → flat +Z, ORM → neutral.
-
-### Constraints (v1)
-
-- **Opaque materials only** (asserted). The alpha-tested visibility pass and
-  OIT sample the *regular* albedo texture, where VT residency isn't
-  guaranteed.
-- `size` is square, power-of-two, a multiple of `page_size`, ≤ 512 pages per
-  axis (64k texels at the default page size).
-- Emissive stays a regular texture; a `uv_set: 1` stack re-interpolates uv1
-  for all of that material's samples, emissive included.
-- Feedback covers the primary view. Path tracer / lightmap baker see
-  fallback colors (no VT sampling there yet).
-- Filtering is bilinear + per-pixel nearest mip (id Tech's shipped baseline);
-  anisotropy and trilinear are documented follow-ups — the 4-texel borders
-  already budget for aniso ~4×.
-
-### Configuration
-
-`graphics.virtual_textures.configure({...})` **before the first stack
-registers** (geometry freezes at first use):
-
-| Key | Default | Meaning |
-|---|---|---|
-| `page_size` | 128 | payload texels per page side |
-| `border` | 4 | border texels per side, baked into tiles (slot = 136²) |
-| `atlas_size` | 4096 | physical cache side → 30×30 = 900 pages, ~64 MB/layer |
-| `table_size` | 1024 | shared page table side (texels = pages), mip-mapped r32uint |
-| `layers` | albedo/normal/orm | cache group: name, format, premultiply |
-| `feedback_stride` | 4 | sample 1 px per stride² block, jittered (runtime-adjustable) |
-| `max_uploads_per_frame` | 8 | page-upload budget |
-| `max_concurrent_loads` | 32 | in-flight source loads |
-| `request_cap_fraction` | ⅓ | pending requests ≤ cap × cache capacity |
-| `eviction_protect_window` | 4 | frames a touched page is unevictable (covers readback latency) |
-| `queue_stale_window` | 30 | untouched queued requests dropped after N frames |
-| `pressure_high/low_watermark` | 0.9 / 0.75 | residency bias hysteresis |
-
-Runtime switch: `renderer.feature_virtual_textures` (default true) stops
-feedback and streaming; already-resident pages keep rendering.
-
----
-
-## How it works
-
-```
-viz buffer (mesh+triangle ids)
-      │
-      ▼
-vt_feedback (compute, 1 px per stride², jittered)          [GPU]
-  pixel → mesh → material → stack; UV + analytic gradients
-  (same chunks as the material pass); mip select; insert
-  packed key into a hash set of unique requests
-      │  ~64 KB raw hash buffer
-      ▼
-async readback (pooled staging, mapAsync, ≤3 in flight)    [GPU→CPU, 1–2 frames]
-      │
-      ▼
-VirtualTextureManager.process_feedback                      [CPU]
-  resident → LRU touch (incl. the ancestor actually serving
-  a missing cell); miss → request + missing-ancestor chain
-      │
-update() per frame: apply arrivals (budgeted uploads),
-  evict (LRU + protection window + finest-first ties),
-  flush page-table dirty rects + stack info rows,
-  issue loads coarse-first with backoff on failures
-      │
-      ▼
-VTPageTable (shared r32uint, mips)      VTPhysicalCache (atlas per layer,
-  quadtree regions per stack;             lockstep slots, page+border)
-  every texel = nearest RESIDENT                  │
-  ancestor-or-self entry                          │
-      └───────────────┬───────────────────────────┘
-                      ▼
-      material pass (VT variant): ONE textureLoad into the
-      table → physical UV → N bilinear layer fetches
-```
-
-Design points worth knowing before modifying:
-
-- **Shared page table.** Every stack owns a buddy-allocated square region of
-  one mip-mapped `r32uint` texture. Buddy alignment makes `origin >> mip`
-  exact at every mip the region supports, so hundreds of stacks need no
-  per-mip metadata and never collide. Entries are **pre-filled with the
-  nearest resident ancestor** (maintained incrementally on load/evict by
-  `VTPageTable`'s match-and-prune DFS), which is what keeps sampling a
-  single fetch with automatic coarse fallback — no shader mip-walk.
-- **Feedback ↔ sampler parity.** Both compile the same
-  `build_chunk_vt_lookup` chunk and the same derivative-bias constants; if
-  the mip formulas ever diverge, the system requests pages it doesn't sample.
-  Change the chunk, never one side.
-- **Key formats** (single source: `VT_CONSTANTS.js`, WGSL mirrors tested for
-  parity): request key `stack:10 | mip:4 | x:9 | y:9`, stored `key+1` so a
-  zero-cleared buffer reads empty; page-table entry
-  `phys_x:8 | phys_y:8 | mip:5 | valid:1`. **Stack ids 0 and 1023 are
-  reserved** — 1023 is the "no stack" sentinel, and 0 is never assigned so
-  zero-initialized / not-yet-flushed GPU rows decode to a harmless
-  "unknown stack" instead of junk requests.
-- **Residency policy.** LRU with a protection window covering readback
-  latency; each stack's root page is pinned at registration (a fallback is
-  always resident once it arrives — held and retried, never dropped, even
-  under lock saturation); eviction ties shed the finest mip first; requests
-  are capped per cycle and canceled when stale; failed loads back off
-  exponentially in a negative cache; cache pressure raises a feedback mip
-  bias so oversubscription degrades to blur instead of thrash.
-- **Frame protocol.** `update()` runs in `Renderer.#begin_frame`
-  (queue-ordered before the frame's submits). Stacks registered mid-frame
-  (materials build during scene update) are published by an idempotent
-  `flush_gpu_state()` re-run from `graph_feedback`, so first frames render
-  correctly.
-- **Struct packing hazard.** `WebGPUStruct.pack()` reorders fields — never
-  construct packed structs positionally in WGSL (tests included); use
-  member-wise assignment. Inline chunk structs (`VTPhysical`,
-  `VTPageTableEntry`) are unpacked and safe.
-
-## Files
-
-| File | Role |
-|---|---|
-| `VirtualTextureManager.js` | orchestrator: registry, residency, streaming, FrameGraph wiring |
-| `VirtualTextureStack.js` | scene-side stack description (`material.vt_stack`) |
-| `VTPageTable.js` | shared table texture + CPU mirror + ancestor-closure propagation |
-| `PageTableQuadAllocator.js` | buddy allocator (the `origin >> mip` guarantee) |
-| `VTPhysicalCache.js` | per-layer atlases, lockstep slots, LRU metadata, uploads |
-| `VT_CONSTANTS.js` | bit layouts, sentinels, JS pack/unpack |
-| `VT_STACK_INFO_STRUCT.js` | per-stack GPU record |
-| `build_chunk_vt_lookup.js` | shared WGSL: wrap, mip select, table load, physical UV |
-| `chunk_vt_request_key.js` | WGSL request-key packing |
-| `build_shader_vt_feedback.js` | the feedback compute shader |
-| `source/VTSource{Procedural,Image,Tiled}.js` | tile providers |
-| `prototypeVirtualTexture.js` | this demo |
-| `../../material/standard/fragment_gbuffer_vt.js` | VT material shader variant |
-
-## Tests
-
-```
-npx vitest run src/webgpu/renderer/texture/virtual
-```
-
-~60 tests: allocator properties; page-table nearest-ancestor invariant
-against a brute-force reference model (randomized, including physical-slot
-recycling); cache LRU/pinning/tie-breaks; manager end-to-end with a mocked
-GPU (register → pin → feedback → stream → evict → unregister) plus the
-policy set (request cap, stale aging, coarse-first order, serving-ancestor
-protection, failure backoff, locked-root retry, teardown flush, stale-key
-rejection); WGSL validity for both shaders (tree-sitter); WGSL↔JS packing
-and physical-UV parity through the in-repo emulator, under default and
-non-default geometry; and standard↔VT pipeline bind-group-layout equality.
-
-Known untestable-here: the GPU hash-set insert loop (the emulator has no
-atomics) and the canvas-based sources (no OffscreenCanvas under Node) — both
-are covered by the demo instead.
+# Virtual Textures
+
+Opt-in software virtual texturing for the deferred (visibility-buffer)
+renderer: materials sample from streamed pages of arbitrarily large
+textures, with GPU memory bounded by what is visible instead of what is
+loaded. Built for **hundreds of simultaneous virtual textures** sharing one
+page table, one physical cache and one feedback pass.
+
+This README covers running the demo, adopting the system, configuration and
+the working design. The extended design document — literature survey,
+decision log, scale math, future work — is [`VIRTUAL_TEXTURES.md`](../../../../VIRTUAL_TEXTURES.md)
+in the repo root.
+
+---
+
+## Demo / prototype
+
+[`prototypeVirtualTexture.js`](./prototypeVirtualTexture.js) is a
+self-contained vite entry point. Two ways to run it:
+
+1. **Dedicated page** — `npm start`, then open `https://localhost:5173/vt.html`
+   (the html at the repo root already points at the prototype).
+2. **Entry-point swap** — point the `<script type="module">` in `index.html`
+   at `src/tools/playground/prototype_virtual_texture.js`, same as the
+   particles prototype workflow.
+
+The scene contains four objects chosen to exercise every path:
+
+| Object | Stack | Source | Demonstrates |
+|---|---|---|---|
+| Ground plane (100 m) | 8192² | `VTSourceProcedural`, instant | mip selection & residency, visually |
+| Back wall | 4096² | `VTSourceProcedural`, 250 ms latency | streaming: pinned root first, refinement blending in |
+| Box | 2048² | `VTSourceImage` (runtime-tiled canvas) | zero-pipeline adoption of ordinary images |
+| Plain orange box | — | regular material | mixed standard/VT pipelines in one material pass |
+
+The procedural tiles are the classic VT debug pattern: **color = mip level,
+label = `mip:x,y` page address**, white page frames. Fly toward the ground
+and watch red (mip 0) pages stream in around you; the concentric color rings
+are the mip ladder.
+
+The GUI exposes the `feature_virtual_textures` kill switch, feedback stride,
+the wall's simulated latency, and live residency stats.
+
+### Headless / scripted driving
+
+Hidden or unfocused tabs never fire `requestAnimationFrame` and clamp timers
+to ~1 s, so the demo also installs console hooks:
+
+```js
+await vt_step(30);      // render 30 frames, paced against the GPU; returns stats
+window.vt               // the VirtualTextureManager (stats, config)
+window.renderer, window.scene, window.camera, window.controller
+```
+
+`vt_step` mirrors the frame loop (resize, controller, render) and awaits
+`onSubmittedWorkDone` per frame so feedback readbacks resolve between frames
+— this is how the system is verified without a visible window.
+
+---
+
+## Using it
+
+### Opt a material in
+
+```js
+import { VirtualTextureStack } from "./texture/virtual/VirtualTextureStack.js";
+import { VTSourceTiled } from "./texture/virtual/source/VTSourceTiled.js";
+
+material.vt_stack = VirtualTextureStack.from({
+    label: 'rock',
+    size: 8192,                       // texels; square, power of two
+    source: new VTSourceTiled({
+        layers: [                     // URL template per cache layer
+            'tiles/rock/albedo/{mip}/{x}_{y}.webp',
+            'tiles/rock/normal/{mip}/{x}_{y}.webp',
+            'tiles/rock/orm/{mip}/{x}_{y}.webp',
+        ],
+    }),
+    wrap: true,                       // repeat (false = clamp), applied in-shader
+    uv_set: 0,                        // 0 or 1
+    average_color: [0.4, 0.35, 0.3, 1], // linear premultiplied; shown before the root arrives
+});
+```
+
+That is the entire opt-in. Registration happens automatically when the
+material is first built; a stack may be shared by any number of materials.
+Everything else in the engine renders exactly as before, and the system
+allocates nothing until the first stack registers.
+
+A **stack** is the unit of virtualization: a set of texture layers
+(albedo / normal / ORM in the standard cache group) sharing one UV set and
+one resolution. The whole set streams, resides and is addressed as one —
+one feedback value, one page-table entry, one residency decision, and in the
+material shader one page-table fetch feeds all three layer samples. This is
+the "do the work once for matching UV sets" design, per UE's VT stacks /
+Granite's stacked textures.
+
+### Tile sources
+
+A source implements:
+
+```js
+prepare(geometry)?                 // called on registration: {page_size, border,
+                                   //  slot_size, layer_count, size, mip_count}
+load_page(mip, x, y, signal)       // → Promise<payload[]>, one per layer;
+                                   //   payloads are slot_size² (border baked in);
+                                   //   reject with AbortError on signal abort
+layer_mask                         // bitmask of layers provided (bit0 = albedo…)
+destroy()?                         // called on last unregistration
+```
+
+Included:
+
+- **`VTSourceTiled`** — pre-tiled page files over HTTP, decoded with
+  `createImageBitmap` (WebP/AVIF/PNG/JPEG — browser-native, no WASM).
+  `legacy_meep_mips: true` consumes the original meep VT converter's output
+  (`${mip}-${x}-${y}.png`, coarsest-is-zero naming) unchanged. Serve
+  normal/ORM tiles lossless or 4:4:4 — chroma subsampling mangles them.
+- **`VTSourceImage`** — runtime tiler: hand it ordinary decoded images and it
+  builds a canvas mip pyramid once and blits padded tiles on demand. The
+  adoption path — wins GPU memory and bandwidth, not host memory.
+- **`VTSourceProcedural`** — instant labeled debug tiles, optional artificial
+  latency. Also the reference source implementation.
+
+Missing layers (e.g. albedo-only stacks) fall back per layer in the shader:
+albedo → the stack's `average_color`, normal → flat +Z, ORM → neutral.
+
+### Constraints (v1)
+
+- **Opaque materials only** (asserted). The alpha-tested visibility pass and
+  OIT sample the *regular* albedo texture, where VT residency isn't
+  guaranteed.
+- `size` is square, power-of-two, a multiple of `page_size`, ≤ 512 pages per
+  axis (64k texels at the default page size).
+- Emissive stays a regular texture; a `uv_set: 1` stack re-interpolates uv1
+  for all of that material's samples, emissive included.
+- Feedback covers the primary view. Path tracer / lightmap baker see
+  fallback colors (no VT sampling there yet).
+- Filtering is bilinear + per-pixel nearest mip (id Tech's shipped baseline);
+  anisotropy and trilinear are documented follow-ups — the 4-texel borders
+  already budget for aniso ~4×.
+
+### Configuration
+
+`graphics.virtual_textures.configure({...})` **before the first stack
+registers** (geometry freezes at first use):
+
+| Key | Default | Meaning |
+|---|---|---|
+| `page_size` | 128 | payload texels per page side |
+| `border` | 4 | border texels per side, baked into tiles (slot = 136²) |
+| `atlas_size` | 4096 | physical cache side → 30×30 = 900 pages, ~64 MB/layer |
+| `table_size` | 1024 | shared page table side (texels = pages), mip-mapped r32uint |
+| `layers` | albedo/normal/orm | cache group: name, format, premultiply |
+| `feedback_stride` | 4 | sample 1 px per stride² block, jittered (runtime-adjustable) |
+| `max_uploads_per_frame` | 8 | page-upload budget |
+| `max_concurrent_loads` | 32 | in-flight source loads |
+| `request_cap_fraction` | ⅓ | pending requests ≤ cap × cache capacity |
+| `eviction_protect_window` | 4 | frames a touched page is unevictable (covers readback latency) |
+| `queue_stale_window` | 30 | untouched queued requests dropped after N frames |
+| `pressure_high/low_watermark` | 0.9 / 0.75 | residency bias hysteresis |
+
+Runtime switch: `renderer.feature_virtual_textures` (default true) stops
+feedback and streaming; already-resident pages keep rendering.
+
+---
+
+## How it works
+
+```
+viz buffer (mesh+triangle ids)
+      │
+      ▼
+vt_feedback (compute, 1 px per stride², jittered)          [GPU]
+  pixel → mesh → material → stack; UV + analytic gradients
+  (same chunks as the material pass); mip select; insert
+  packed key into a hash set of unique requests
+      │  ~64 KB raw hash buffer
+      ▼
+async readback (pooled staging, mapAsync, ≤3 in flight)    [GPU→CPU, 1–2 frames]
+      │
+      ▼
+VirtualTextureManager.process_feedback                      [CPU]
+  resident → LRU touch (incl. the ancestor actually serving
+  a missing cell); miss → request + missing-ancestor chain
+      │
+update() per frame: apply arrivals (budgeted uploads),
+  evict (LRU + protection window + finest-first ties),
+  flush page-table dirty rects + stack info rows,
+  issue loads coarse-first with backoff on failures
+      │
+      ▼
+VTPageTable (shared r32uint, mips)      VTPhysicalCache (atlas per layer,
+  quadtree regions per stack;             lockstep slots, page+border)
+  every texel = nearest RESIDENT                  │
+  ancestor-or-self entry                          │
+      └───────────────┬───────────────────────────┘
+                      ▼
+      material pass (VT variant): ONE textureLoad into the
+      table → physical UV → N bilinear layer fetches
+```
+
+Design points worth knowing before modifying:
+
+- **Shared page table.** Every stack owns a buddy-allocated square region of
+  one mip-mapped `r32uint` texture. Buddy alignment makes `origin >> mip`
+  exact at every mip the region supports, so hundreds of stacks need no
+  per-mip metadata and never collide. Entries are **pre-filled with the
+  nearest resident ancestor** (maintained incrementally on load/evict by
+  `VTPageTable`'s match-and-prune DFS), which is what keeps sampling a
+  single fetch with automatic coarse fallback — no shader mip-walk.
+- **Feedback ↔ sampler parity.** Both compile the same
+  `build_chunk_vt_lookup` chunk and the same derivative-bias constants; if
+  the mip formulas ever diverge, the system requests pages it doesn't sample.
+  Change the chunk, never one side.
+- **Key formats** (single source: `VT_CONSTANTS.js`, WGSL mirrors tested for
+  parity): request key `stack:10 | mip:4 | x:9 | y:9`, stored `key+1` so a
+  zero-cleared buffer reads empty; page-table entry
+  `phys_x:8 | phys_y:8 | mip:5 | valid:1`. **Stack ids 0 and 1023 are
+  reserved** — 1023 is the "no stack" sentinel, and 0 is never assigned so
+  zero-initialized / not-yet-flushed GPU rows decode to a harmless
+  "unknown stack" instead of junk requests.
+- **Residency policy.** LRU with a protection window covering readback
+  latency; each stack's root page is pinned at registration (a fallback is
+  always resident once it arrives — held and retried, never dropped, even
+  under lock saturation); eviction ties shed the finest mip first; requests
+  are capped per cycle and canceled when stale; failed loads back off
+  exponentially in a negative cache; cache pressure raises a feedback mip
+  bias so oversubscription degrades to blur instead of thrash.
+- **Frame protocol.** `update()` runs in `Renderer.#begin_frame`
+  (queue-ordered before the frame's submits). Stacks registered mid-frame
+  (materials build during scene update) are published by an idempotent
+  `flush_gpu_state()` re-run from `graph_feedback`, so first frames render
+  correctly.
+- **Struct packing hazard.** `WebGPUStruct.pack()` reorders fields — never
+  construct packed structs positionally in WGSL (tests included); use
+  member-wise assignment. Inline chunk structs (`VTPhysical`,
+  `VTPageTableEntry`) are unpacked and safe.
+
+## Files
+
+| File | Role |
+|---|---|
+| `VirtualTextureManager.js` | orchestrator: registry, residency, streaming, FrameGraph wiring |
+| `VirtualTextureStack.js` | scene-side stack description (`material.vt_stack`) |
+| `VTPageTable.js` | shared table texture + CPU mirror + ancestor-closure propagation |
+| `PageTableQuadAllocator.js` | buddy allocator (the `origin >> mip` guarantee) |
+| `VTPhysicalCache.js` | per-layer atlases, lockstep slots, LRU metadata, uploads |
+| `VT_CONSTANTS.js` | bit layouts, sentinels, JS pack/unpack |
+| `VT_STACK_INFO_STRUCT.js` | per-stack GPU record |
+| `build_chunk_vt_lookup.js` | shared WGSL: wrap, mip select, table load, physical UV |
+| `chunk_vt_request_key.js` | WGSL request-key packing |
+| `build_shader_vt_feedback.js` | the feedback compute shader |
+| `source/VTSource{Procedural,Image,Tiled}.js` | tile providers |
+| `prototypeVirtualTexture.js` | this demo |
+| `../../material/standard/fragment_gbuffer_vt.js` | VT material shader variant |
+
+## Tests
+
+```
+npx vitest run src/webgpu/renderer/texture/virtual
+```
+
+~60 tests: allocator properties; page-table nearest-ancestor invariant
+against a brute-force reference model (randomized, including physical-slot
+recycling); cache LRU/pinning/tie-breaks; manager end-to-end with a mocked
+GPU (register → pin → feedback → stream → evict → unregister) plus the
+policy set (request cap, stale aging, coarse-first order, serving-ancestor
+protection, failure backoff, locked-root retry, teardown flush, stale-key
+rejection); WGSL validity for both shaders (tree-sitter); WGSL↔JS packing
+and physical-UV parity through the in-repo emulator, under default and
+non-default geometry; and standard↔VT pipeline bind-group-layout equality.
+
+Known untestable-here: the GPU hash-set insert loop (the emulator has no
+atomics) and the canvas-based sources (no OffscreenCanvas under Node) — both
+are covered by the demo instead.