@woosh/meep-engine 3.39.0 → 3.40.0

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

@@ -0,0 +1,320 @@
+import { Color } from "../../../core/color/Color.js";
+import Quaternion from "../../../core/geom/Quaternion.js";
+import Vector3 from "../../../core/geom/Vector3.js";
+import { EntityComponentDataset } from "../../../engine/ecs/EntityComponentDataset.js";
+import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
+import { BoxGeometry } from "../../renderer/geometry/BoxGeometry.js";
+import { MeshoptClusterizer } from "../../renderer/geometry/meshlet/build/meshoptimizer/meshopt_clusterizer.js";
+import { make_sunlight } from "../../renderer/light/make_sunlight.js";
+import { place_light } from "../../renderer/light/place_light.js";
+import { StandardShadeMaterial } from "../../renderer/material/StandardShadeMaterial.js";
+import { move_primitive, place_primitive, remove_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
+ */
+
+/**
+ * Scratch for {@link aim_sun}, which a sweep calls every frame.
+ */
+const scratch_direction = new Vector3();
+const scratch_rotation = new Quaternion();
+
+/**
+ * Turn a sun to shine down at a fixed elevation, from an azimuth about the vertical.
+ *
+ * @param {import("../../renderer/light/model/DirectionalLight.js").DirectionalLight} sun
+ * @param {number} azimuth radians
+ */
+export function aim_sun(sun, azimuth) {
+    scratch_direction.set(-Math.cos(azimuth) * 0.45, -0.95, -Math.sin(azimuth) * 0.45);
+    scratch_direction.normalize();
+
+    scratch_rotation.fromUnitVectors(Vector3.forward, scratch_direction);
+    scratch_rotation.normalize();
+
+    sun.transform.setRotation(scratch_rotation.x, scratch_rotation.y, scratch_rotation.z, scratch_rotation.w);
+    sun.transform.updateMatrix();
+}
+
+/**
+ * What both scenes share: a scene with a dataset, its context, a box geometry, a material maker,
+ * a box placer, a flat sky and a sun.
+ *
+ * @param {Renderer} renderer
+ */
+async function scene_base(renderer) {
+    await MeshoptClusterizer.ready;
+
+    const scene = new Scene();
+
+    scene.dataset = new EntityComponentDataset();
+
+    const scene_context = renderer.scenes.obtain(scene);
+    const cube = new BoxGeometry();
+
+    /**
+     * @param {number[]} rgb
+     * @param {number} [roughness]
+     * @returns {StandardShadeMaterial}
+     */
+    const material = (rgb, roughness = 0.75) => {
+        const result = new StandardShadeMaterial();
+
+        result.diffuse_color.copy(new Color(...rgb));
+        result.roughness_factor = roughness;
+        result.metallic_factor = 0;
+
+        return result;
+    };
+
+    /**
+     * A box at an entity of its own; the transform stays the caller's to move.
+     *
+     * @param {string} name
+     * @param {number[]} position
+     * @param {number[]} scale
+     * @param {StandardShadeMaterial} mat
+     * @returns {{entity: number, transform: Transform64}}
+     */
+    const box = (name, position, scale, mat) => {
+        const transform = new Transform64();
+
+        transform.setTranslation(position[0], position[1], position[2]);
+        transform.setScale(scale[0], scale[1], scale[2]);
+        transform.updateMatrix();
+
+        return { entity: place_primitive(scene_context, cube, mat, transform, { name }), transform };
+    };
+
+    scene.lights.environment = make_flat_environment([0.06, 0.075, 0.1]);
+
+    const sun = make_sunlight({ intensity: 3, temperature: 5800 });
+
+    aim_sun(sun, 0.6);
+    place_light(scene, sun);
+
+    return { scene, scene_context, material, box, sun };
+}
+
+/**
+ * The courtyard: static structure at every scale a clipmap level covers, and casters that move in
+ * every way the mover pass has to see.
+ *
+ * - a fence of 5 cm slats by the camera for the finest levels, pillars and walls a few metres out,
+ *   an overhang on posts, thin poles twenty metres off, and an avenue of pillars reaching two
+ *   hundred metres down the coarser levels;
+ * - movers: boxes orbiting (a translation), a column bobbing (a translation along the light more or
+ *   less), a bar turning about its centre (a rotation that keeps its centre still), and a block that
+ *   blinks in and out of the scene every few seconds (a row appearing and leaving).
+ *
+ * @param {Renderer} renderer
+ */
+export async function create_courtyard(renderer) {
+    const { scene, scene_context, material, box, sun } = await scene_base(renderer);
+
+    const ground = material([0.55, 0.53, 0.5], 0.9);
+    const stone = material([0.72, 0.68, 0.6]);
+    const dark = material([0.3, 0.32, 0.36]);
+    const wood = material([0.55, 0.38, 0.22]);
+
+    box('Ground', [0, -0.1, -60], [240, 0.2, 320], ground);
+
+    // a fence of slats by the camera: the finest levels' business
+    for (let i = 0; i < 40; i++) {
+        box('Slat', [-4 + i * 0.2, 0.6, 3], [0.05, 1.2, 0.05], wood);
+    }
+
+    box('Fence rail', [0, 1.15, 3], [8.2, 0.06, 0.06], wood);
+
+    // pillars and walls a few metres out
+    for (let x = -20; x <= 20; x += 8) {
+        for (let z = -20; z <= 4; z += 8) {
+            if (Math.abs(x) < 5 && Math.abs(z) < 5) {
+                continue;
+            }
+
+            // 4, 6 or 8 m tall; % keeps the sign of x + z, and a negative remainder made pillars of
+            // no height lying in the ground's top face
+            const step = ((x + z) % 3 + 3) % 3;
+
+            box('Pillar', [x, 2 + step, z], [0.6, 4 + 2 * step, 0.6], stone);
+        }
+    }
+
+    box('Wall', [-12, 1.5, -6], [0.4, 3, 12], stone);
+    box('Wall', [14, 1.25, -14], [10, 2.5, 0.4], stone);
+
+    // an overhang on four posts
+    for (const [x, z] of [[4, -8], [12, -8], [4, -2], [12, -2]]) {
+        box('Post', [x, 2, z], [0.3, 4, 0.3], dark);
+    }
+
+    box('Overhang', [8, 4.15, -5], [9, 0.3, 7], stone);
+
+    // thin poles twenty metres off
+    for (let i = 0; i < 16; i++) {
+        box('Pole', [-15 + i * 2, 2.5, -22], [0.05, 5, 0.05], dark);
+    }
+
+    // an avenue of pillars down the coarser levels
+    for (let z = -30; z >= -220; z -= 7) {
+        box('Avenue pillar', [-7, 3, z], [0.8, 6, 0.8], stone);
+        box('Avenue pillar', [7, 3, z], [0.8, 6, 0.8], stone);
+    }
+
+    const movers_material = material([0.85, 0.25, 0.15], 0.5);
+    const orbiters = [];
+
+    for (let i = 0; i < 4; i++) {
+        orbiters.push(box('Orbiter', [0, 1, 0], [1, 1, 1], movers_material));
+    }
+
+    const column = box('Bobbing column', [-6, 2, -10], [1, 3, 1], material([0.2, 0.55, 0.85], 0.5));
+    const bar = box('Turning bar', [0, 2.6, -12], [6, 0.25, 0.25], material([0.95, 0.75, 0.15], 0.5));
+
+    const blinker_material = material([0.6, 0.2, 0.8], 0.5);
+    const blinker_transform = new Transform64();
+
+    blinker_transform.setTranslation(16, 1.25, -2);
+    blinker_transform.setScale(2, 2.5, 2);
+    blinker_transform.updateMatrix();
+
+    const cube = new BoxGeometry();
+    let blinker = -1;
+
+    const rotation = new Quaternion();
+
+    return {
+        scene,
+        sun,
+        mover_count: orbiters.length + 3,
+
+        /**
+         * Put every mover where it is at time `t`.
+         *
+         * @param {number} t seconds
+         */
+        update(t) {
+            for (let i = 0; i < orbiters.length; i++) {
+                const a = t * 0.6 + i * Math.PI / 2;
+                const o = orbiters[i];
+
+                o.transform.setTranslation(Math.cos(a) * 6, 1.2 + Math.sin(t * 1.3 + i) * 0.8, Math.sin(a) * 6 - 6);
+                move_primitive(scene_context, o.entity, o.transform);
+            }
+
+            column.transform.setTranslation(-6, 2.5 + Math.sin(t * 0.9) * 2, -10);
+            move_primitive(scene_context, column.entity, column.transform);
+
+            rotation.fromAxisAngle(Vector3.up, t * 0.7);
+            bar.transform.setRotation(rotation.x, rotation.y, rotation.z, rotation.w);
+            move_primitive(scene_context, bar.entity, bar.transform);
+
+            // in for two seconds, out for two
+            const present = Math.floor(t / 2) % 2 === 0;
+
+            if (present && blinker === -1) {
+                blinker = place_primitive(scene_context, cube, blinker_material, blinker_transform, { name: 'Blinker' });
+            } else if (!present && blinker !== -1) {
+                remove_primitive(scene_context, blinker);
+                blinker = -1;
+            }
+        },
+    };
+}
+
+/**
+ * The crowd: a field of small boxes wandering, as many as asked for — past the mover list's capacity
+ * if that is the point — to load the stale pass and the page budget. {@link resize} adds walkers to
+ * the same scene or takes them away, which the mover pass sees as rows appearing and leaving.
+ *
+ * @param {Renderer} renderer
+ * @param {number} count
+ */
+export async function create_crowd(renderer, count) {
+    const { scene, scene_context, material, box, sun } = await scene_base(renderer);
+
+    box('Ground', [0, -0.1, 0], [160, 0.2, 160], material([0.5, 0.52, 0.48], 0.9));
+
+    // a few fixed landmarks for scale
+    for (let i = 0; i < 8; i++) {
+        const a = i / 8 * Math.PI * 2;
+
+        box('Landmark', [Math.cos(a) * 40, 4, Math.sin(a) * 40], [2, 8, 2], material([0.7, 0.66, 0.6]));
+    }
+
+    const walker_material = material([0.85, 0.3, 0.2], 0.5);
+    const walkers = [];
+
+    // a fixed sequence of walkers, so a given count is always the same crowd
+    let seed = 12345;
+    const random = () => {
+        seed = (seed * 1664525 + 1013904223) >>> 0;
+        return seed / 4294967296;
+    };
+
+    /**
+     * Lay the walkers out on a square grid sized to their number.
+     */
+    const lay_out = () => {
+        const side = Math.ceil(Math.sqrt(walkers.length));
+        const spacing = Math.min(1.6, 70 / side);
+
+        for (let i = 0; i < walkers.length; i++) {
+            walkers[i].x = (i % side - side / 2) * spacing;
+            walkers[i].z = (Math.floor(i / side) - side / 2) * spacing;
+        }
+    };
+
+    /**
+     * Add walkers or take them away until there are `target`.
+     *
+     * @param {number} target
+     */
+    const resize = target => {
+        while (walkers.length > target) {
+            remove_primitive(scene_context, walkers.pop().entity);
+        }
+
+        while (walkers.length < target) {
+            walkers.push({
+                ...box('Walker', [0, 0.6, 0], [0.5, 1.2, 0.5], walker_material),
+                x: 0,
+                z: 0,
+                phase: random() * Math.PI * 2,
+                speed: 0.4 + random() * 0.8,
+                radius: 0.5 + random() * 1.5,
+            });
+        }
+
+        lay_out();
+    };
+
+    resize(count);
+
+    return {
+        scene,
+        sun,
+        resize,
+
+        get mover_count() {
+            return walkers.length;
+        },
+
+        /**
+         * @param {number} t seconds
+         */
+        update(t) {
+            for (let i = 0; i < walkers.length; i++) {
+                const w = walkers[i];
+                const a = t * w.speed + w.phase;
+
+                w.transform.setTranslation(w.x + Math.cos(a) * w.radius, 0.6, w.z + Math.sin(a * 1.3) * w.radius);
+                move_primitive(scene_context, w.entity, w.transform);
+            }
+        },
+    };
+}

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

@@ -0,0 +1,38 @@
+/**
+ * Check a virtual shadow map against itself on the device: hold still, let the pages settle, then
+ * read the light database back from the GPU and compare what the shaders read with what the CPU
+ * believes, and with itself.
+ *
+ * 1. **Settles**: with nothing moving, a reading recorded after the scene stopped asks for pages,
+ *    and leaves nothing uncovered and nothing waiting — a page refused a slot is waiting — within
+ *    {@link SETTLE_FRAMES} frames.
+ * 2. **Rows**: every row the map claimed comes back.
+ * 3. **Record**: the map's `shadow_virtual` row names its runs and depth range.
+ * 4. **Page table**: every `shadow_virtual_page` row on the GPU equals the CPU's entry for its cell.
+ * 5. **Slots**: every `shadow_virtual_slot` row on the GPU names the page the CPU says the slot holds.
+ * 6. **Page to slot to page**: on the GPU alone, every resident entry's slot names a page whose cell
+ *    is the entry's own.
+ * 7. **Windows**: every `shadow_virtual_level` row on the GPU is the CPU's window corner.
+ * 8. **One slot per page**: no world page is held by two slots.
+ *
+ * The caller holds the movers and the sun still across this, and holds page updates when asked —
+ * the readbacks span frames, and no page is drawn or given back between them and the comparison.
+ *
+ * @param {object} options
+ * @param {import("../../renderer/Renderer.js").Renderer} options.renderer
+ * @param {import("../../renderer/shadow/vsm/VirtualShadowMap.js").VirtualShadowMap|null} options.map
+ * @param {import("../../renderer/scene/Scene.js").Scene} options.scene
+ * @param {function(boolean): void} options.hold_pages stop or restart page updates
+ * @returns {Promise<{pass: boolean, checks: object[], stats: object}>}
+ */
+export function verify_vsm({ renderer, map, scene, hold_pages }: {
+    renderer: import("../../renderer/Renderer.js").Renderer;
+    map: import("../../renderer/shadow/vsm/VirtualShadowMap.js").VirtualShadowMap | null;
+    scene: import("../../renderer/scene/Scene.js").Scene;
+    hold_pages: (arg0: boolean) => void;
+}): Promise<{
+    pass: boolean;
+    checks: object[];
+    stats: object;
+}>;
+//# sourceMappingURL=verify_vsm.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"verify_vsm.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/vsm/verify_vsm.js"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;IANkE,QAAQ,EAA/D,OAAO,4BAA4B,EAAE,QAAQ;IAC0C,GAAG,EAA1F,OAAO,+CAA+C,EAAE,gBAAgB,GAAC,IAAI;IACtB,KAAK,EAA5D,OAAO,+BAA+B,EAAE,KAAK;IACZ,UAAU,SAAlC,OAAO,KAAG,IAAI;IACrB,QAAQ;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAC,CAAC,CAuPrE"}

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

@@ -0,0 +1,305 @@
+import { VSM_READBACKS_IN_FLIGHT } from "../../renderer/shadow/vsm/graph_vsm_feedback.js";
+import { VSM_SLOT_EMPTY } from "../../renderer/shadow/vsm/VSM_SLOT_STRUCT.js";
+import { vt_entry_unpack } from "../../renderer/texture/virtual/VT_CONSTANTS.js";
+
+/**
+ * Frames to wait, at most, for a still scene's pages to settle.
+ * @type {number}
+ */
+const SETTLE_FRAMES = 240;
+
+/**
+ * @returns {Promise<void>} after the next frame
+ */
+function next_frame() {
+    return new Promise(resolve => requestAnimationFrame(() => resolve()));
+}
+
+/**
+ * Check a virtual shadow map against itself on the device: hold still, let the pages settle, then
+ * read the light database back from the GPU and compare what the shaders read with what the CPU
+ * believes, and with itself.
+ *
+ * 1. **Settles**: with nothing moving, a reading recorded after the scene stopped asks for pages,
+ *    and leaves nothing uncovered and nothing waiting — a page refused a slot is waiting — within
+ *    {@link SETTLE_FRAMES} frames.
+ * 2. **Rows**: every row the map claimed comes back.
+ * 3. **Record**: the map's `shadow_virtual` row names its runs and depth range.
+ * 4. **Page table**: every `shadow_virtual_page` row on the GPU equals the CPU's entry for its cell.
+ * 5. **Slots**: every `shadow_virtual_slot` row on the GPU names the page the CPU says the slot holds.
+ * 6. **Page to slot to page**: on the GPU alone, every resident entry's slot names a page whose cell
+ *    is the entry's own.
+ * 7. **Windows**: every `shadow_virtual_level` row on the GPU is the CPU's window corner.
+ * 8. **One slot per page**: no world page is held by two slots.
+ *
+ * The caller holds the movers and the sun still across this, and holds page updates when asked —
+ * the readbacks span frames, and no page is drawn or given back between them and the comparison.
+ *
+ * @param {object} options
+ * @param {import("../../renderer/Renderer.js").Renderer} options.renderer
+ * @param {import("../../renderer/shadow/vsm/VirtualShadowMap.js").VirtualShadowMap|null} options.map
+ * @param {import("../../renderer/scene/Scene.js").Scene} options.scene
+ * @param {function(boolean): void} options.hold_pages stop or restart page updates
+ * @returns {Promise<{pass: boolean, checks: object[], stats: object}>}
+ */
+export async function verify_vsm({ renderer, map, scene, hold_pages }) {
+    if (map === null) {
+        return { pass: false, checks: [{ name: 'map', pass: false, detail: 'no virtual shadow map — choose "Virtual shadow map"' }], stats: {} };
+    }
+
+    const manager = map.manager;
+    const checks = [];
+
+    // 1. settle, on readings recorded after the scene stopped: those in flight at the freeze land
+    // first, and the one after them was asked for still
+    const readings_at_freeze = manager.stats.readings_applied;
+
+    let settled_after = -1;
+
+    for (let i = 0; i < SETTLE_FRAMES; i++) {
+        await next_frame();
+
+        const s = manager.stats;
+
+        if (s.readings_applied > readings_at_freeze + VSM_READBACKS_IN_FLIGHT
+            && s.wants > 0
+            && s.uncovered === 0
+            && s.backlog === 0
+            && s.renders === 0) {
+            settled_after = i;
+            break;
+        }
+    }
+
+    const s = manager.stats;
+
+    checks.push({
+        name: 'settles',
+        pass: settled_after !== -1,
+        detail: settled_after !== -1
+            ? `${s.wants} pages wanted, nothing uncovered or waiting after ${settled_after + 1} frames`
+            : s.wants === 0
+                ? 'the readings ask for no page: point the camera at something the sun lights'
+                : `after ${SETTLE_FRAMES} frames, ${s.backlog} waiting (${s.refused} refused so far) and ${s.uncovered} uncovered`,
+    });
+
+    // 2–8. what the GPU holds, read with page updates held so that nothing changes on either side
+    // while the readbacks are on their way
+    hold_pages(true);
+
+    const database = renderer.scenes.obtain(scene).lights.database;
+
+    let records;
+    let pages;
+    let slots;
+    let levels;
+
+    try {
+        // a frame with the hold in place, so that whatever the last one wrote has gone up
+        await next_frame();
+
+        [records, pages, slots, levels] = await Promise.all([
+            database.debug_table_read_all('shadow_virtual'),
+            database.debug_table_read_all('shadow_virtual_page'),
+            database.debug_table_read_all('shadow_virtual_slot'),
+            database.debug_table_read_all('shadow_virtual_level'),
+        ]);
+    } finally {
+        hold_pages(false);
+    }
+
+    // 2. every claimed row is there
+    const missing = [];
+
+    const count_missing = (rows, first, count, table) => {
+        let absent = 0;
+
+        for (let i = 0; i < count; i++) {
+            if (rows[first + i] === undefined) {
+                absent++;
+            }
+        }
+
+        if (absent > 0) {
+            missing.push(`${table}: ${absent} of ${count}`);
+        }
+    };
+
+    count_missing(records, map.record_row, 1, 'shadow_virtual');
+    count_missing(pages, map.first_page, manager.cell_count, 'shadow_virtual_page');
+    count_missing(slots, map.first_slot, manager.slots.capacity, 'shadow_virtual_slot');
+    count_missing(levels, map.first_level, manager.level_count, 'shadow_virtual_level');
+
+    checks.push({
+        name: 'rows',
+        pass: missing.length === 0,
+        detail: missing.length === 0 ? 'every row the map claimed came back' : `missing ${missing.join(', ')}`,
+    });
+
+    if (missing.length > 0) {
+        return finish(checks, manager);
+    }
+
+    // 3. the record
+    const record = records[map.record_row];
+    const record_faults = [];
+
+    const expect_field = (name, gpu, cpu) => {
+        if (gpu !== cpu) {
+            record_faults.push(`${name}: gpu ${gpu} cpu ${cpu}`);
+        }
+    };
+
+    expect_field('first_page', record.first_page, map.first_page);
+    expect_field('page_count', record.page_count, manager.cell_count);
+    expect_field('first_slot', record.first_slot, map.first_slot);
+    expect_field('slot_count', record.slot_count, manager.slots.capacity);
+    expect_field('first_level', record.first_level, map.first_level);
+    expect_field('level_count', record.level_count, manager.level_count);
+    expect_field('near', record.near, Math.fround(map.near));
+    expect_field('far', record.far, Math.fround(map.far));
+
+    checks.push({
+        name: 'record',
+        pass: record_faults.length === 0,
+        detail: record_faults.length === 0 ? 'runs and depth range agree' : record_faults.join('; '),
+    });
+
+    // 4. the page table
+    let page_mismatches = 0;
+    let first_page_mismatch = '';
+
+    for (let cell = 0; cell < manager.cell_count; cell++) {
+        const gpu = pages[map.first_page + cell];
+        const cpu = manager.cell_entry(cell);
+
+        if (gpu !== cpu) {
+            if (page_mismatches === 0) {
+                first_page_mismatch = `cell ${cell}: gpu ${gpu} cpu ${cpu}`;
+            }
+
+            page_mismatches++;
+        }
+    }
+
+    checks.push({
+        name: 'page table',
+        pass: page_mismatches === 0,
+        detail: page_mismatches === 0 ? `${manager.cell_count} entries agree` : `${page_mismatches} differ, first ${first_page_mismatch}`,
+    });
+
+    // 5, 8. the slots, and no page twice
+    let slot_mismatches = 0;
+    const held = new Set();
+    let doubled = 0;
+
+    for (let slot = 0; slot < manager.slots.capacity; slot++) {
+        const gpu = slots[map.first_slot + slot];
+        const level = manager.slot_level(slot);
+
+        if (level === -1) {
+            if (gpu.level !== VSM_SLOT_EMPTY) {
+                slot_mismatches++;
+            }
+
+            continue;
+        }
+
+        if (gpu.level !== level || gpu.x !== manager.slot_x(slot) || gpu.y !== manager.slot_y(slot)) {
+            slot_mismatches++;
+        }
+
+        const key = `${level}:${manager.slot_x(slot)},${manager.slot_y(slot)}`;
+
+        if (held.has(key)) {
+            doubled++;
+        }
+
+        held.add(key);
+    }
+
+    checks.push({
+        name: 'slots',
+        pass: slot_mismatches === 0,
+        detail: `${slot_mismatches} of ${manager.slots.capacity} differ`,
+    });
+
+    // 6. the GPU's rows against each other: an entry's slot holds a page of the entry's own cell
+    const slots_per_axis = manager.slots.slots_per_axis;
+
+    let resident_entries = 0;
+    let broken_links = 0;
+    let first_broken = '';
+
+    for (let cell = 0; cell < manager.cell_count; cell++) {
+        const entry = vt_entry_unpack(pages[map.first_page + cell]);
+
+        if (!entry.valid) {
+            continue;
+        }
+
+        resident_entries++;
+
+        const slot = entry.phys_y * slots_per_axis + entry.phys_x;
+        const page = slots[map.first_slot + slot];
+
+        const linked = page !== undefined
+            && page.level === entry.mip
+            && manager.window_contains(page.level, page.x, page.y)
+            && manager.cell_of(page.level, page.x, page.y) === cell;
+
+        if (!linked) {
+            if (broken_links === 0) {
+                first_broken = `cell ${cell} → slot ${slot} → ${page === undefined ? 'nothing' : `${page.level}:${page.x},${page.y}`}`;
+            }
+
+            broken_links++;
+        }
+    }
+
+    checks.push({
+        name: 'page to slot to page',
+        pass: broken_links === 0,
+        detail: broken_links === 0 ? `${resident_entries} resident entries link back` : `${broken_links} do not, first ${first_broken}`,
+    });
+
+    checks.push({
+        name: 'one slot per page',
+        pass: doubled === 0,
+        detail: `${held.size} pages held, ${doubled} twice`,
+    });
+
+    // 7. the windows
+    let level_mismatches = 0;
+
+    for (let level = 0; level < manager.level_count; level++) {
+        const corner = levels[map.first_level + level];
+
+        if (corner[0] !== manager.origin_x(level) || corner[1] !== manager.origin_y(level)) {
+            level_mismatches++;
+        }
+    }
+
+    checks.push({
+        name: 'windows',
+        pass: level_mismatches === 0,
+        detail: `${level_mismatches} of ${manager.level_count} differ`,
+    });
+
+    return finish(checks, manager);
+}
+
+/**
+ * @param {object[]} checks
+ * @param {import("../../renderer/shadow/vsm/VSMPageManager.js").VSMPageManager} manager
+ * @returns {{pass: boolean, checks: object[], stats: object}}
+ */
+function finish(checks, manager) {
+    console.table(checks);
+
+    return {
+        pass: checks.every(c => c.pass),
+        checks,
+        stats: { ...manager.stats, resident: manager.slots.used },
+    };
+}