@woosh/meep-engine 3.38.0 → 3.40.0

package/src/shade/playground/vsm/VSMDebugOverlay.js

@@ -0,0 +1,351 @@
+import { CAMERA_UNIFORM_STRUCT } from "../../renderer/camera/CAMERA_UNIFORM_STRUCT.js";
+import { DEPTH_BACKGROUND_VALUE } from "../../renderer/depth/DEPTH_BACKGROUND_VALUE.js";
+import { FramePhase } from "../../renderer/extension/FramePhase.js";
+import { RenderExtension } from "../../renderer/extension/RenderExtension.js";
+import { SceneColor } from "../../renderer/extension/SceneColor.js";
+import { ViewTextures } from "../../renderer/extension/ViewTextures.js";
+import { LIGHT_DATABASE_SPEC } from "../../renderer/light/LIGHT_DATABASE_SPEC.js";
+import { chunk_project_position_from_depth } from "../../renderer/shader/chunk/camera/chunk_project_position_from_depth.js";
+import { chunk_u32_to_hash_color } from "../../renderer/shader/chunk/color/chunk_u32_to_hash_color.js";
+import { chunk_lut_turbo } from "../../renderer/shader/chunk/color/lut/chunk_lut_turbo.js";
+import { CodeChunk } from "../../renderer/shader/compiler/CodeChunk.js";
+import { graph_image_pass } from "../../renderer/shader/graph/graph_image_pass.js";
+import { graph_import_texture } from "../../renderer/shader/graph/graph_import_texture.js";
+import { ImageShader } from "../../renderer/shader/ImageShader.js";
+import { ShaderResourceSetDescriptor } from "../../renderer/shader/resource/ShaderResourceSetDescriptor.js";
+import { ShaderDescriptor } from "../../renderer/shader/ShaderDescriptor.js";
+import { u32 } from "../../renderer/shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../renderer/shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../renderer/shader/type/WebGPUStruct.js";
+import { chunk_vsm_find_page } from "../../renderer/shadow/vsm/shader/chunk_vsm_find_page.js";
+import { VSM_RECORD_STRUCT } from "../../renderer/shadow/vsm/VSM_RECORD_STRUCT.js";
+import { VSM_SLOT_EMPTY } from "../../renderer/shadow/vsm/VSM_SLOT_STRUCT.js";
+
+/**
+ * What the overlay shows over the picture.
+ * @enum {number}
+ */
+export const VSMDebugView = {
+    None: 0,
+    /** the level of the page each pixel is shadowed by */
+    ServingLevel: 1,
+    /** how many levels coarser than it asked for the page a pixel is shadowed by is */
+    Deficit: 2,
+    /** the page each pixel is shadowed by, a colour per page, its edges drawn */
+    Pages: 3,
+};
+
+const RECORD_TABLE = LIGHT_DATABASE_SPEC.get('shadow_virtual');
+const SLOT_TABLE = LIGHT_DATABASE_SPEC.get('shadow_virtual_slot');
+
+const SETTINGS = WebGPUStruct.from({
+    record_row: u32,
+    mode: u32,
+    inset: u32,
+    output_width: u32,
+    output_height: u32,
+}, "VSMDebugSettings");
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate('settings', SETTINGS);
+
+resources.createGroup()
+    .addTexture('tScene', 'unfilterable-float')
+    .addTexture('tDepth', 'depth')
+    .addTexture('tAtlas', 'depth')
+    .addUniform('camera', CAMERA_UNIFORM_STRUCT)
+    .addStorageBuffer('light_database', WebGPUArray.from(u32), false)
+    .addStorageBuffer('slot_stale', WebGPUArray.from(u32), false);
+
+const shader_vsm_debug = new ImageShader({
+    descriptor: ShaderDescriptor.from({
+        label: "playground/vsm debug overlay",
+        resources,
+        body: CodeChunk.from(
+            //language=WGSL
+            `
+fn vsm_debug_level_color(level: u32) -> vec3f {
+    // the finest level red, coarser through the spectrum to violet
+    return turbo(1.0 - f32(level) / 11.0);
+}
+
+fn vsm_debug_inset(coord: vec2f, record: ${VSM_RECORD_STRUCT.wgsl_ref}) -> vec4f {
+    let output_size = vec2f(f32(settings.output_width), f32(settings.output_height));
+    let side = floor(output_size.y * 0.42);
+    // bottom left, clear of the page's side panel
+    let origin = vec2f(12.0, output_size.y - side - 12.0);
+
+    let local = coord - origin;
+
+    if (any(local < vec2f(0.0)) || any(local >= vec2f(side))) {
+        return vec4f(-1.0);
+    }
+
+    let slot_size = f32(record.page_size + 2u * record.border);
+    let pool_size = f32(record.slots_per_axis) * slot_size;
+
+    let pool_texel = local / side * pool_size;
+    let slot_xy = vec2u(pool_texel / slot_size);
+    let slot = slot_xy.y * record.slots_per_axis + slot_xy.x;
+
+    let depth = textureLoad(tAtlas, vec2u(pool_texel) + record.pool_origin, 0);
+
+    // the depth range is wide, so the stored depth barely varies across a page: band the depth along
+    // the light in metres instead, a band every two
+    let metres = record.far - depth * (record.far - record.near);
+    var colour = select(vec3f(0.02), turbo(fract(metres * 0.5)) * 0.8, depth > 0.0);
+
+    // a stale slot washed red all over, so it reads apart from the finest level's dark red edge
+    let stale = slot_stale[slot] != 0u;
+
+    if (stale) {
+        colour = mix(colour, vec3f(1.0, 0.1, 0.1), 0.65);
+    }
+
+    // the slot grid, an inset pixel and a half wide, tinted by what the slot holds
+    let in_slot = pool_texel - vec2f(slot_xy) * slot_size;
+    let edge = min(min(in_slot.x, in_slot.y), min(slot_size - in_slot.x, slot_size - in_slot.y));
+
+    if (edge < pool_size / side * 1.5) {
+        let held = ${SLOT_TABLE.marshalling_method_read}(&light_database, record.first_slot + slot);
+
+        if (held.level == ${VSM_SLOT_EMPTY}u) {
+            colour = vec3f(0.12);
+        } else if (stale) {
+            colour = vec3f(1.0, 0.1, 0.1);
+        } else {
+            colour = vsm_debug_level_color(held.level);
+        }
+    }
+
+    return vec4f(colour, 1.0);
+}
+
+@fragment
+fn main(@builtin(position) coord: vec4f) -> @location(0) vec4f {
+    let pixel = vec2u(coord.xy);
+    let scene = textureLoad(tScene, pixel, 0);
+
+    let record = ${RECORD_TABLE.marshalling_method_read}(&light_database, settings.record_row);
+
+    if (settings.inset != 0u) {
+        let inset = vsm_debug_inset(coord.xy, record);
+
+        if (inset.a > 0.0) {
+            return inset;
+        }
+    }
+
+    if (settings.mode == 0u) {
+        return scene;
+    }
+
+    let output_size = vec2f(f32(settings.output_width), f32(settings.output_height));
+    let uv = coord.xy / output_size;
+
+    let depth_size = textureDimensions(tDepth);
+    let depth_pixel = min(vec2u(uv * vec2f(depth_size)), depth_size - 1u);
+    let z = textureLoad(tDepth, depth_pixel, 0);
+
+    if (z == ${DEPTH_BACKGROUND_VALUE}) {
+        return scene;
+    }
+
+    let position = project_position_from_depth(uv, z, camera.view_projection_matrix_inverse);
+
+    let wanted = vsm_request_page(&light_database, record, position);
+    let found = vsm_find_resident_page(&light_database, record, position);
+
+    // nothing stands in at all: magenta
+    var tint = vec3f(1.0, 0.0, 1.0);
+
+    if (found.level != VSM_LEVEL_NONE) {
+        if (settings.mode == ${VSMDebugView.ServingLevel}u) {
+            tint = vsm_debug_level_color(found.level);
+        } else if (settings.mode == ${VSMDebugView.Deficit}u) {
+            let deficit = found.level - min(found.level, wanted.level);
+
+            tint = select(
+                select(select(vec3f(1.0, 0.1, 0.05), vec3f(1.0, 0.5, 0.0), deficit < 3u), vec3f(1.0, 0.95, 0.1), deficit < 2u),
+                vec3f(0.1, 0.9, 0.2),
+                deficit == 0u
+            );
+        } else {
+            tint = u32_to_hash_color(found.level * 7919u + bitcast<u32>(found.page.x) * 104729u + bitcast<u32>(found.page.y));
+
+            // the page's edges, a texel and a half wide at its own resolution
+            let light_space = vsm_light_space(record, position);
+            let in_page = fract(light_space.xy / vsm_page_world_size(record, found.level)) * f32(record.page_size);
+            let edge = min(min(in_page.x, in_page.y), min(f32(record.page_size) - in_page.x, f32(record.page_size) - in_page.y));
+
+            if (edge < 1.5) {
+                tint = vec3f(0.0);
+            }
+        }
+    }
+
+    // modulated by the picture, so the shadows stay readable under the tint
+    let luminance = dot(scene.rgb, vec3f(0.2126, 0.7152, 0.0722));
+
+    return vec4f(tint * (0.15 + luminance), scene.a);
+}
+`,
+            [
+                CAMERA_UNIFORM_STRUCT.declaration_chunk,
+                RECORD_TABLE.chunk_read,
+                SLOT_TABLE.chunk_read,
+                chunk_project_position_from_depth,
+                chunk_vsm_find_page,
+                chunk_lut_turbo,
+                chunk_u32_to_hash_color,
+            ]
+        ),
+    }),
+    targets: [
+        {
+            label: "vsm debug",
+            format: "rgba16float",
+        }
+    ],
+});
+
+/**
+ * The playground's view into a virtual shadow map, drawn over the frame before it is presented:
+ * a tint per pixel saying what shadows it ({@link VSMDebugView}), and an inset of the physical pool
+ * — every slot's depth, its edge tinted by its page's level, washed red where the page manager holds
+ * it stale (a mover crossed it and it has not been drawn since), its edge grey where it is empty.
+ *
+ * The tint runs the lighting's own page lookup on the frame's light database rows, so the page it
+ * names for a pixel is the page the lighting samples there. The stale state is the CPU's, uploaded
+ * each frame the inset is drawn.
+ */
+export class VSMDebugOverlay extends RenderExtension {
+    name = 'playground/vsm debug overlay';
+    phase = FramePhase.BeforePresent;
+    relative_order = 1000;
+
+    /**
+     * @type {number} a {@link VSMDebugView}
+     */
+    mode = VSMDebugView.None;
+
+    /**
+     * Whether to draw the pool inset.
+     * @type {boolean}
+     */
+    inset = false;
+
+    /**
+     * The map to show; the overlay draws nothing without one.
+     * @type {import("../../renderer/shadow/vsm/VirtualShadowMap.js").VirtualShadowMap|null}
+     */
+    map = null;
+
+    /**
+     * The shadow context whose atlas the map's pool is in.
+     * @type {import("../../renderer/shadow/map/GPUSceneShadowmapContext.js").GPUSceneShadowmapContext|null}
+     */
+    shadows = null;
+
+    /**
+     * @type {import("../../renderer/GraphicsContext.js").GraphicsContext}
+     */
+    #graphics;
+
+    /**
+     * The page manager's stale state, a word per slot, and the buffer the inset reads it from.
+     */
+    #stale_words = new Uint32Array(0);
+    #stale_buffer = null;
+
+    /**
+     * @param {import("../../renderer/GraphicsContext.js").GraphicsContext} graphics
+     */
+    constructor(graphics) {
+        super();
+
+        this.#graphics = graphics;
+    }
+
+    /**
+     * Upload which slots the page manager holds stale.
+     *
+     * @param {import("../../renderer/shadow/vsm/VSMPageManager.js").VSMPageManager} manager
+     * @returns {GPUBuffer}
+     */
+    #upload_stale(manager) {
+        const count = manager.slots.capacity;
+        const device = this.#graphics.device;
+
+        if (this.#stale_words.length !== count) {
+            this.#stale_buffer?.destroy();
+
+            this.#stale_words = new Uint32Array(count);
+            this.#stale_buffer = device.createBuffer({
+                label: 'playground/vsm debug / slot stale',
+                size: count * Uint32Array.BYTES_PER_ELEMENT,
+                usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+            });
+        }
+
+        const words = this.#stale_words;
+
+        for (let slot = 0; slot < count; slot++) {
+            words[slot] = manager.slot_stale(slot) ? 1 : 0;
+        }
+
+        // queued ahead of the frame's commands, behind the last frame's
+        device.queue.writeBuffer(this.#stale_buffer, 0, words);
+
+        return this.#stale_buffer;
+    }
+
+    /**
+     * @param {import("../../renderer/extension/FrameContext.js").FrameContext} frame
+     */
+    record(frame) {
+        const map = this.map;
+
+        if (map === null || map.destroyed || map.record_row === -1) {
+            return;
+        }
+
+        if (this.mode === VSMDebugView.None && !this.inset) {
+            return;
+        }
+
+        const graph = frame.graph;
+        const view = frame.view;
+        const resolution = frame.resolution;
+
+        const [output] = graph_image_pass({
+            graph,
+            shader: shader_vsm_debug,
+            inputs: {
+                settings: {
+                    record_row: map.record_row,
+                    mode: this.mode,
+                    inset: this.inset ? 1 : 0,
+                    output_width: resolution[0],
+                    output_height: resolution[1],
+                },
+                tScene: frame.get(SceneColor).color,
+                tDepth: frame.get(ViewTextures).depth,
+                tAtlas: graph_import_texture(graph, this.shadows.texture, 'vsm debug / atlas'),
+                camera: view.camera.gpu_buffer,
+                light_database: view.scene.lights.database.buffer,
+                slot_stale: this.#upload_stale(map.manager),
+            },
+            output_resolution: resolution,
+        });
+
+        frame.get(SceneColor).color = output;
+    }
+
+    destroy() {
+        this.#stale_buffer?.destroy();
+        this.#stale_buffer = null;
+        this.#stale_words = new Uint32Array(0);
+    }
+}

package/src/shade/playground/vsm/clipmap_panel.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @param {HTMLCanvasElement} canvas
+ * @param {import("../../renderer/shadow/vsm/VirtualShadowMap.js").VirtualShadowMap} map
+ * @param {number[]} camera_position world
+ * @param {number} only one level to draw alone, or -1 for every level side by side
+ */
+export function draw_clipmap_panel(canvas: HTMLCanvasElement, map: import("../../renderer/shadow/vsm/VirtualShadowMap.js").VirtualShadowMap, camera_position: number[], only: number): void;
+//# sourceMappingURL=clipmap_panel.d.ts.map

package/src/shade/playground/vsm/clipmap_panel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clipmap_panel.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/vsm/clipmap_panel.js"],"names":[],"mappings":"AA2BA;;;;;GAKG;AACH,2CALW,iBAAiB,OACjB,OAAO,+CAA+C,EAAE,gBAAgB,mBACxE,MAAM,EAAE,QACR,MAAM,QA0GhB"}

package/src/shade/playground/vsm/clipmap_panel.js

@@ -0,0 +1,138 @@
+/**
+ * A picture of a virtual shadow map's clipmap, from the CPU's side of it: one panel per level, one
+ * pixel per page of the level's window, in world order with light-space y up.
+ *
+ * - dark: nothing resident
+ * - green: resident; white: rendered this frame
+ * - red: resident and stale — a mover crossed it since it was drawn
+ * - amber: wanted by the latest reading and missing
+ * - a cyan cross: the page the camera stands over
+ *
+ * Every number comes from the page manager's public accessors, so what it shows is what the CPU
+ * believes; the page table the GPU reads is written from the same state.
+ */
+
+/** Gap between panels, in cells. */
+const GAP = 2;
+
+/** Panels per row. */
+const COLUMNS = 4;
+
+const COLOR_EMPTY = [16, 20, 24];
+const COLOR_RESIDENT = [46, 130, 66];
+const COLOR_RENDERED = [235, 255, 235];
+const COLOR_STALE = [225, 60, 40];
+const COLOR_WANTED = [215, 170, 40];
+const COLOR_CAMERA = [80, 220, 255];
+
+/**
+ * @param {HTMLCanvasElement} canvas
+ * @param {import("../../renderer/shadow/vsm/VirtualShadowMap.js").VirtualShadowMap} map
+ * @param {number[]} camera_position world
+ * @param {number} only one level to draw alone, or -1 for every level side by side
+ */
+export function draw_clipmap_panel(canvas, map, camera_position, only) {
+    const manager = map.manager;
+    const n = manager.pages_per_level;
+    const levels = manager.level_count;
+    const columns = only === -1 ? COLUMNS : 1;
+    const rows = only === -1 ? Math.ceil(levels / COLUMNS) : 1;
+
+    const width = columns * (n + GAP) - GAP;
+    const height = rows * (n + GAP) - GAP;
+
+    if (canvas.width !== width || canvas.height !== height) {
+        canvas.width = width;
+        canvas.height = height;
+    }
+
+    const context = canvas.getContext('2d');
+    const image = context.createImageData(width, height);
+    const pixels = image.data;
+
+    // what the latest reading wants, by cell
+    const wanted = new Uint8Array(manager.cell_count);
+
+    for (let i = 0; i < manager.want_count; i++) {
+        const level = manager.want_level(i);
+        const x = manager.want_x(i);
+        const y = manager.want_y(i);
+
+        if (manager.window_contains(level, x, y)) {
+            wanted[manager.cell_of(level, x, y)] = 1;
+        }
+    }
+
+    // the camera in light space
+    const view = map.light_camera.view_matrix;
+    const [cx, cy, cz] = camera_position;
+    const light_x = view[0] * cx + view[4] * cy + view[8] * cz + view[12];
+    const light_y = view[1] * cx + view[5] * cy + view[9] * cz + view[13];
+
+    const frame = map.frame_index;
+
+    const put = (px, py, rgb) => {
+        const o = (py * width + px) * 4;
+
+        pixels[o] = rgb[0];
+        pixels[o + 1] = rgb[1];
+        pixels[o + 2] = rgb[2];
+        pixels[o + 3] = 255;
+    };
+
+    for (let level = 0; level < levels; level++) {
+        if (only !== -1 && level !== only) {
+            continue;
+        }
+
+        const index = only === -1 ? level : 0;
+        const panel_x = (index % columns) * (n + GAP);
+        const panel_y = Math.floor(index / columns) * (n + GAP);
+
+        const origin_x = manager.origin_x(level);
+        const origin_y = manager.origin_y(level);
+
+        for (let j = 0; j < n; j++) {
+            for (let i = 0; i < n; i++) {
+                const cell = manager.cell_of(level, origin_x + i, origin_y + j);
+                const slot = manager.cell_slot(cell);
+
+                let rgb = COLOR_EMPTY;
+
+                if (slot !== -1) {
+                    if (manager.slot_stale(slot)) {
+                        rgb = COLOR_STALE;
+                    } else if (manager.slot_rendered_frame(slot) === frame) {
+                        rgb = COLOR_RENDERED;
+                    } else {
+                        rgb = COLOR_RESIDENT;
+                    }
+                } else if (wanted[cell] !== 0) {
+                    rgb = COLOR_WANTED;
+                }
+
+                // light-space y up
+                put(panel_x + i, panel_y + (n - 1 - j), rgb);
+            }
+        }
+
+        const size = manager.page_world_size(level);
+        const camera_i = Math.floor(light_x / size) - origin_x;
+        const camera_j = Math.floor(light_y / size) - origin_y;
+
+        for (let d = -2; d <= 2; d++) {
+            const i = camera_i + d;
+            const j = camera_j + d;
+
+            if (i >= 0 && i < n && camera_j >= 0 && camera_j < n) {
+                put(panel_x + i, panel_y + (n - 1 - camera_j), COLOR_CAMERA);
+            }
+
+            if (j >= 0 && j < n && camera_i >= 0 && camera_i < n) {
+                put(panel_x + camera_i, panel_y + (n - 1 - j), COLOR_CAMERA);
+            }
+        }
+    }
+
+    context.putImageData(image, 0, 0);
+}

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

@@ -0,0 +1,170 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>Meep — virtual shadow maps</title>
+    <style>
+        :root {
+            color-scheme: dark;
+            font: 13px/1.45 system-ui, sans-serif;
+            --panel: rgba(20, 25, 33, 0.92);
+            --line: #34404f;
+            --text: #e2e8f0;
+            --muted: #9aa8ba;
+            --pass: #8fd6a8;
+            --fail: #ff9a9a;
+        }
+
+        * { box-sizing: border-box; }
+
+        html, body { margin: 0; height: 100%; background: #0b0e13; color: var(--text); overflow: hidden; }
+
+        #view { position: fixed; inset: 0; width: 100vw; height: 100vh; display: block; }
+
+        #panel {
+            position: fixed; top: 12px; right: 12px; bottom: 12px; width: 300px;
+            overflow-y: auto; padding: 14px 16px;
+            background: var(--panel); border: 1px solid var(--line); border-radius: 8px;
+        }
+
+        h1 { font-size: 16px; margin: 0 0 4px; font-weight: 600; }
+        h2 { font-size: 12px; margin: 14px 0 6px; color: var(--muted); font-weight: 600; text-transform: uppercase; letter-spacing: .05em; }
+        p.lead { margin: 0 0 8px; color: var(--muted); }
+
+        label { display: block; margin: 6px 0; }
+        label > span { display: flex; justify-content: space-between; color: var(--muted); font-size: 12px; margin-bottom: 2px; }
+        label.check { display: flex; gap: 8px; align-items: center; }
+
+        select, button { width: 100%; background: #232c39; border: 1px solid #45556a; color: inherit; border-radius: 4px; padding: 5px 6px; font: inherit; }
+        button { cursor: pointer; }
+        button:hover { background: #2f3b4d; }
+        input[type=range] { width: 100%; accent-color: #6fc3ff; }
+
+        .row { display: grid; grid-template-columns: repeat(4, 1fr); gap: 6px; }
+
+        #stats { font: 11px/1.5 ui-monospace, Consolas, monospace; white-space: pre-wrap; color: var(--text); margin: 6px 0 0; }
+        #status { font: 11px/1.5 ui-monospace, Consolas, monospace; white-space: pre-wrap; color: var(--pass); margin: 8px 0 0; }
+        #status.fail { color: var(--fail); }
+
+        #clipmap { width: 100%; image-rendering: pixelated; border: 1px solid var(--line); background: #000; display: block; }
+
+        .legend { font-size: 11px; color: var(--muted); }
+        .legend b { font-weight: 600; }
+        .swatch { display: inline-block; width: 9px; height: 9px; border-radius: 2px; margin-right: 3px; vertical-align: -1px; }
+    </style>
+</head>
+<body tabindex="0">
+<canvas id="view" tabindex="0" aria-label="Virtual shadow map scene"></canvas>
+<div id="panel">
+    <h1>Virtual shadow maps</h1>
+    <p class="lead">A clipmap of pages around the camera, drawn as the view asks for them and as moving casters make them stale.</p>
+
+    <h2>Shadows</h2>
+    <label><span>Technique</span>
+        <select id="technique">
+            <option value="vsm" selected>Virtual shadow map</option>
+            <option value="csm">Cascades (A/B)</option>
+        </select>
+    </label>
+    <label><span>Page updates per frame <output id="budget-value">8</output></span>
+        <input id="budget" type="range" min="0" max="64" step="1" value="8">
+    </label>
+    <label><span>LOD bias (coarser →) <output id="bias-value">0.0</output></span>
+        <input id="bias" type="range" min="-2" max="3" step="0.5" value="0">
+    </label>
+    <label><span>Finest texel</span>
+        <select id="texel">
+            <option value="0.001">1 mm</option>
+            <option value="0.01" selected>1 cm</option>
+            <option value="0.02">2 cm</option>
+            <option value="0.04">4 cm</option>
+        </select>
+    </label>
+    <label class="check"><input id="pause" type="checkbox">Pause page updates (budget 0)</label>
+    <label class="check"><input id="taa" type="checkbox">TAA</label>
+
+    <h2>Scene</h2>
+    <label><span>Scene</span>
+        <select id="scene">
+            <option value="courtyard" selected>Courtyard</option>
+            <option value="crowd">Crowd</option>
+        </select>
+    </label>
+    <label><span>Crowd size <output id="crowd-value">500</output></span>
+        <input id="crowd" type="range" min="50" max="6000" step="50" value="500">
+    </label>
+    <label class="check"><input id="animate" type="checkbox" checked>Animate movers</label>
+    <label class="check"><input id="sweep" type="checkbox">Sweep the sun</label>
+    <label><span>Sweep speed (rad/s)</span>
+        <input id="sweep-speed" type="range" min="0.005" max="0.5" step="0.005" value="0.05">
+    </label>
+    <button id="nudge">Nudge the sun (invalidate)</button>
+
+    <h2>Camera</h2>
+    <div class="row">
+        <button id="preset-near">Near</button>
+        <button id="preset-overview">Over</button>
+        <button id="preset-avenue">Avenue</button>
+        <button id="preset-crowd">Crowd</button>
+    </div>
+
+    <h2>Debug</h2>
+    <label><span>Overlay</span>
+        <select id="debug">
+            <option value="0">None</option>
+            <option value="1">Serving level</option>
+            <option value="2">Resolution deficit</option>
+            <option value="3">Page IDs and edges</option>
+        </select>
+    </label>
+    <label class="check"><input id="inset" type="checkbox">Physical pool inset</label>
+    <label class="check"><input id="panel-on" type="checkbox" checked>Clipmap panel</label>
+    <label><span>Panel shows</span>
+        <select id="panel-level">
+            <option value="-1">All levels</option>
+                <option value="0">Level 0</option>
+                <option value="1">Level 1</option>
+                <option value="2">Level 2</option>
+                <option value="3">Level 3</option>
+                <option value="4">Level 4</option>
+                <option value="5">Level 5</option>
+                <option value="6">Level 6</option>
+                <option value="7">Level 7</option>
+                <option value="8">Level 8</option>
+                <option value="9">Level 9</option>
+                <option value="10">Level 10</option>
+                <option value="11">Level 11</option>
+        </select>
+    </label>
+    <canvas id="clipmap" width="262" height="196"></canvas>
+    <p class="legend">
+        <span class="swatch" style="background:#2e8242"></span>resident
+        <span class="swatch" style="background:#ebffeb"></span>rendered now
+        <span class="swatch" style="background:#e13c28"></span>stale
+        <span class="swatch" style="background:#d7aa28"></span>wanted, missing
+        <span class="swatch" style="background:#50dcff"></span>camera
+        <br>Levels left to right, top to bottom, finest first; light-space y up.
+    </p>
+    <p class="legend">
+        <b>Serving level</b>: red finest → violet coarsest. <b>Deficit</b>: green as asked, yellow one level coarser, orange two, red more; magenta nothing resident.
+        <b>Pool inset</b>: slot depth, edges by level, red edge = flagged stale on the GPU, grey = empty.
+    </p>
+
+    <h2>State</h2>
+    <pre id="stats"></pre>
+    <p id="status">Starting WebGPU…</p>
+</div>
+<script type="module">
+    import { start } from './main.js';
+
+    start().catch(error => {
+        const status = document.getElementById('status');
+
+        status.className = 'fail';
+        status.textContent = String(error?.message ?? error);
+        console.error(error);
+    });
+</script>
+</body>
+</html>

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

@@ -0,0 +1,2 @@
+export function start(): Promise<void>;
+//# sourceMappingURL=main.d.ts.map

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

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