@woosh/meep-engine 3.1.0 → 3.3.0

package/src/shade/renderer/texture/virtual/VirtualTextureManager.js

@@ -1,1276 +1,1276 @@
-import { assert } from "../../../../core/assert.js";
-import { isPowerOfTwo } from "../../../../core/math/isPowerOfTwo.js";
-import { write_gpu_typed_buffer } from "../../shader/type/serde/write_gpu_typed_buffer.js";
-import { BufferResourceDescriptor } from "../../../device/graph/BufferResourceDescriptor.js";
-import { graph_read_buffer } from "../../buffer/graph_read_buffer.js";
-import { build_vt_material_pipeline_descriptor } from "../../material/standard/fragment_gbuffer_vt.js";
-import { build_chunk_vt_lookup } from "./build_chunk_vt_lookup.js";
-import { build_shader_vt_feedback, VT_FEEDBACK_PARAMS_STRUCT, VT_FEEDBACK_WORKGROUP_SIZE } from "./build_shader_vt_feedback.js";
-import {
-    VT_ENTRY_INVALID,
-    VT_ENTRY_MIP_MASK,
-    VT_MAX_MIP_COUNT,
-    VT_MAX_PAGES_PER_AXIS,
-    VT_STACK_FLAG_LAYER_MASK_SHIFT,
-    VT_STACK_FLAG_UV_SET_1,
-    VT_STACK_FLAG_WRAP_REPEAT,
-    VT_STACK_ID_INVALID,
-    vt_entry_pack,
-    vt_entry_unpack,
-    vt_request_key_pack,
-    vt_request_key_unpack,
-} from "./VT_CONSTANTS.js";
-import { VT_STACK_INFO_STRUCT } from "./VT_STACK_INFO_STRUCT.js";
-import { VTPageTable } from "./VTPageTable.js";
-import { VTPhysicalCache } from "./VTPhysicalCache.js";
-
-/**
- * Local page key within one stack — never leaves the CPU.
- * @param {number} mip
- * @param {number} x
- * @param {number} y
- * @returns {number}
- */
-function local_key(mip, x, y) {
-    return (mip << 20) | (y << 10) | x;
-}
-
-/**
- * Release decoded tile payloads that will not be uploaded. ImageBitmaps pin
- * pixel memory until GC; explicit close keeps drops/discards cheap.
- * @param {Array} payloads
- */
-function vt_close_payloads(payloads) {
-    if (!Array.isArray(payloads)) {
-        return;
-    }
-
-    for (const payload of payloads) {
-        if (payload != null && typeof payload.close === 'function') {
-            payload.close();
-        }
-    }
-}
-
-/**
- * Bookkeeping for one registered stack.
- */
-class VTStackRecord {
-    /**
-     * @type {VirtualTextureStack}
-     */
-    stack = null;
-
-    id = 0;
-
-    /**
-     * Region in the shared page table, mip-0 texels.
-     * @type {{x: number, y: number, size: number}}
-     */
-    region = null;
-
-    size_pages = 0;
-    mip_count = 0;
-    layer_mask = 0;
-
-    /**
-     * Materials currently referencing the stack.
-     * @type {number}
-     */
-    ref_count = 0;
-
-    /**
-     * local_key(mip,x,y) → physical slot.
-     * @type {Map<number, number>}
-     */
-    resident = new Map();
-}
-
-class VTPendingLoad {
-    key = 0;
-    stack_id = 0;
-    mip = 0;
-    x = 0;
-    y = 0;
-    issued = false;
-    lock = false;
-    last_touch = 0;
-
-    /**
-     * @type {AbortController}
-     */
-    controller = null;
-}
-
-/**
- * Virtual texture system orchestrator. Owns the shared page table, the
- * physical cache group, the stack registry, the streaming pipeline and the
- * FrameGraph feedback wiring. One instance per GraphicsContext.
- *
- * Opt-in and lazy: constructing it costs nothing; GPU resources (page table
- * texture, cache atlases, shaders) materialize when the first stack
- * registers. `configure()` before that point to change geometry.
- *
- * Per-frame protocol (driven by the Renderer):
- *   1. `update()` — before the shading graph: apply arrived pages (budgeted
- *      uploads + page-table maintenance), flush GPU state, issue loads.
- *   2. `graph_feedback(...)` — inside the shading graph: viz-buffer → unique
- *      request hash set → async readback. Results are folded in whenever the
- *      map resolves (typically next frame): resident touches refresh LRU,
- *      misses enter the load queue coarse-first.
- *
- * Scale properties: state per registered stack is one table region + one
- * 32-byte info row; per-frame cost is one screen-space compute pass and one
- * small readback regardless of how many stacks exist.
- */
-export class VirtualTextureManager {
-
-    /**
-     * @type {GPUDevice}
-     */
-    #device;
-
-    /**
-     * Geometry/config — frozen at first stack registration.
-     */
-    #config = {
-        page_size: 128,
-        border: 4,
-        atlas_size: 4096,
-        table_size: 1024,
-        hash_capacity: 16384,
-        /** feedback samples one pixel per stride×stride block, jittered over stride² frames */
-        feedback_stride: 4,
-        max_uploads_per_frame: 8,
-        max_concurrent_loads: 32,
-        /** in-flight + queued requests cap, as a fraction of cache capacity */
-        request_cap_fraction: 1 / 3,
-        /** frames a touched page is safe from eviction (covers feedback latency) */
-        eviction_protect_window: 4,
-        /** queued (unissued) requests untouched for this many frames are dropped */
-        queue_stale_window: 30,
-        /** residency water marks driving the feedback mip bias */
-        pressure_high_watermark: 0.9,
-        pressure_low_watermark: 0.75,
-        layers: [
-            { name: 'albedo', format: 'rgba8unorm-srgb', premultiplied: true },
-            { name: 'normal', format: 'rgba8unorm' },
-            { name: 'orm', format: 'rgba8unorm' },
-        ],
-    };
-
-    #initialized = false;
-
-    /**
-     * @type {VTPageTable}
-     */
-    #page_table = null;
-
-    /**
-     * @type {VTPhysicalCache}
-     */
-    #cache = null;
-
-    /**
-     * Per-slot reverse lookup: owning stack id (-1 = free), page address.
-     */
-    #slot_stack = null;
-    #slot_mip = null;
-    #slot_x = null;
-    #slot_y = null;
-
-    /**
-     * Index 0 is permanently reserved: GPU-side tables (material metadata,
-     * stack info) zero-initialize, and a row that hasn't been flushed yet
-     * reads as "stack 0". Never assigning id 0 turns that entire class of
-     * zero-init/flush-lag states into a clean "unknown stack, skip" instead
-     * of junk requests against a real stack.
-     * @type {(VTStackRecord|undefined)[]}
-     */
-    #stacks = [undefined];
-
-    /**
-     * @type {number[]}
-     */
-    #free_stack_ids = [];
-
-    #stack_count = 0;
-
-    /**
-     * Fixed-capacity GPU mirror of stack info rows.
-     * @type {GPUBuffer}
-     */
-    #stack_info_buffer = null;
-
-    /**
-     * @type {ArrayBuffer}
-     */
-    #stack_info_staging = null;
-
-    /**
-     * @type {Set<number>}
-     */
-    #stack_info_dirty = new Set();
-
-    /**
-     * key → pending load (queued or in flight).
-     * @type {Map<number, VTPendingLoad>}
-     */
-    #pending = new Map();
-
-    /**
-     * Keys of queued (not yet issued) loads.
-     * @type {number[]}
-     */
-    #queue = [];
-
-    #loads_in_flight = 0;
-
-    /**
-     * Loaded payloads waiting for their budgeted upload.
-     * @type {{pending: VTPendingLoad, payloads: Array}[]}
-     */
-    #arrived = [];
-
-    /**
-     * Negative cache: request key → {failures, retry_after_frame}. Keeps a
-     * permanently-missing tile (404, decode error) from being re-fetched at
-     * feedback rate forever; backoff doubles per failure up to ~30 s.
-     * @type {Map<number, {failures: number, retry_after_frame: number}>}
-     */
-    #load_failures = new Map();
-
-    #readbacks_in_flight = 0;
-
-    /**
-     * Manager frame counter — advanced by update(), used for LRU and
-     * staleness. Deliberately independent of the renderer's frame index.
-     */
-    #frame = 0;
-
-    /**
-     * Current feedback mip bias from residency pressure (0 = no pressure).
-     */
-    #residency_bias = 0;
-
-    /**
-     * @type {import("../../shader/ComputeShader.js").ComputeShader}
-     */
-    #shader_feedback = null;
-
-    /**
-     * @type {CodeChunk}
-     */
-    #chunk_lookup = null;
-
-    /**
-     * @type {RenderPipelineDescriptor}
-     */
-    #material_pipeline_descriptor = null;
-
-    /**
-     * @type {GPUTextureView}
-     */
-    #page_table_view = null;
-
-    /**
-     * Bilinear clamp sampler for the physical caches — addressing is done
-     * in-shader, page borders make bilinear seamless.
-     * @type {GPUSampler}
-     */
-    #cache_sampler = null;
-
-    /**
-     * Diagnostics, refreshed every update().
-     */
-    stats = {
-        stacks: 0,
-        resident_pages: 0,
-        pending_loads: 0,
-        queued_loads: 0,
-        uploads_last_frame: 0,
-        evictions_last_frame: 0,
-        dropped_requests: 0,
-        residency_bias: 0,
-        cache_capacity: 0,
-    };
-
-    /**
-     *
-     * @param {GPUDevice} device
-     */
-    constructor(device) {
-        assert.defined(device, 'device');
-
-        this.#device = device;
-    }
-
-    /**
-     * Override defaults. Must be called before the first stack registers.
-     * @param {Object} options subset of the config block
-     */
-    configure(options) {
-        assert.equal(this.#initialized, false, 'configure() after initialization');
-
-        Object.assign(this.#config, options);
-    }
-
-    /**
-     * @returns {boolean} true when at least one stack is registered
-     */
-    get active() {
-        return this.#stack_count > 0;
-    }
-
-    /**
-     * @returns {Object}
-     */
-    get config() {
-        return this.#config;
-    }
-
-    /**
-     * The lookup chunk shared by the feedback shader and material samplers.
-     * @returns {CodeChunk}
-     */
-    get chunk_lookup() {
-        this.#ensure_initialized();
-
-        return this.#chunk_lookup;
-    }
-
-    /**
-     * @returns {GPUTexture}
-     */
-    get page_table_texture() {
-        this.#ensure_initialized();
-
-        return this.#page_table.texture;
-    }
-
-    /**
-     * @returns {GPUBuffer}
-     */
-    get stack_info_buffer() {
-        this.#ensure_initialized();
-
-        return this.#stack_info_buffer;
-    }
-
-    /**
-     * @returns {VTPhysicalCache}
-     */
-    get cache() {
-        this.#ensure_initialized();
-
-        return this.#cache;
-    }
-
-    /**
-     * @returns {GPUTextureView}
-     */
-    get page_table_view() {
-        this.#ensure_initialized();
-
-        return this.#page_table_view;
-    }
-
-    /**
-     * @returns {GPUSampler}
-     */
-    get cache_sampler() {
-        this.#ensure_initialized();
-
-        return this.#cache_sampler;
-    }
-
-    /**
-     * Pipeline descriptor of the virtual-texture material variant, built for
-     * this manager's cache geometry. Shared by every VT material.
-     * @returns {RenderPipelineDescriptor}
-     */
-    get material_pipeline_descriptor() {
-        this.#ensure_initialized();
-
-        if (this.#material_pipeline_descriptor === null) {
-            this.#material_pipeline_descriptor = build_vt_material_pipeline_descriptor(this.#chunk_lookup);
-        }
-
-        return this.#material_pipeline_descriptor;
-    }
-
-    #ensure_initialized() {
-        if (this.#initialized) {
-            return;
-        }
-
-        const config = this.#config;
-        const device = this.#device;
-
-        this.#page_table = new VTPageTable(device, config.table_size);
-
-        this.#cache = new VTPhysicalCache(device, {
-            atlas_size: config.atlas_size,
-            page_size: config.page_size,
-            border: config.border,
-            layers: config.layers,
-        });
-
-        const capacity = this.#cache.capacity;
-
-        this.#slot_stack = new Int32Array(capacity).fill(-1);
-        this.#slot_mip = new Uint8Array(capacity);
-        this.#slot_x = new Uint16Array(capacity);
-        this.#slot_y = new Uint16Array(capacity);
-
-        this.#stack_info_staging = new ArrayBuffer(VT_STACK_ID_INVALID * VT_STACK_INFO_STRUCT.size);
-
-        this.#stack_info_buffer = device.createBuffer({
-            label: 'vt/stack-info',
-            size: this.#stack_info_staging.byteLength,
-            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
-        });
-
-        this.#chunk_lookup = build_chunk_vt_lookup({
-            page_size: config.page_size,
-            border: config.border,
-            atlas_size: config.atlas_size,
-        });
-
-        this.#shader_feedback = build_shader_vt_feedback({
-            chunk_vt_lookup: this.#chunk_lookup,
-            hash_capacity: config.hash_capacity,
-        });
-
-        this.#page_table_view = this.#page_table.texture.createView();
-
-        this.#cache_sampler = device.createSampler({
-            label: 'vt/cache-sampler',
-            magFilter: 'linear',
-            minFilter: 'linear',
-            addressModeU: 'clamp-to-edge',
-            addressModeV: 'clamp-to-edge',
-        });
-
-        this.stats.cache_capacity = capacity;
-
-        this.#initialized = true;
-    }
-
-    // ── Stack registry ──────────────────────────────────────────────
-
-    /**
-     * Register a stack (idempotent per stack — shared stacks ref-count).
-     * Allocates the page-table region, publishes the info row, and pins the
-     * root page so a fallback is always resident once it streams in.
-     *
-     * @param {VirtualTextureStack} stack
-     * @returns {number} stack id
-     */
-    register_stack(stack) {
-        assert.equal(stack.isVirtualTextureStack, true, 'not a VirtualTextureStack');
-
-        if (stack.id !== -1) {
-            const existing = this.#stacks[stack.id];
-
-            assert.defined(existing, 'stack carries an id but is not registered');
-
-            existing.ref_count++;
-
-            return stack.id;
-        }
-
-        this.#ensure_initialized();
-
-        const config = this.#config;
-
-        assert.defined(stack.source, 'stack.source');
-        assert.greaterThanOrEqual(stack.size, config.page_size, 'stack smaller than a page');
-        assert.equal(stack.size % config.page_size, 0, 'stack size is not a multiple of page size');
-
-        const size_pages = stack.size / config.page_size;
-
-        assert.ok(isPowerOfTwo(size_pages), 'stack page count must be a power of two');
-        assert.lessThanOrEqual(size_pages, VT_MAX_PAGES_PER_AXIS, 'stack exceeds page coordinate budget');
-
-        const mip_count = Math.log2(size_pages) + 1;
-
-        assert.lessThanOrEqual(mip_count, VT_MAX_MIP_COUNT, 'mip chain exceeds request key budget');
-        assert.lessThanOrEqual(mip_count - 1, VT_ENTRY_MIP_MASK, 'mip chain exceeds page table entry budget');
-
-        const region = this.#page_table.allocate_region(size_pages);
-
-        if (region === null) {
-            throw new Error(`vt: page table is full (registering '${stack.label}', ${size_pages}² pages)`);
-        }
-
-        let id;
-
-        if (this.#free_stack_ids.length > 0) {
-            id = this.#free_stack_ids.pop();
-        } else {
-            id = this.#stacks.length;
-        }
-
-        if (id >= VT_STACK_ID_INVALID) {
-            this.#page_table.allocator.free(region.x, region.y, region.size);
-            throw new Error(`vt: stack budget exhausted (${VT_STACK_ID_INVALID})`);
-        }
-
-        const record = new VTStackRecord();
-
-        record.stack = stack;
-        record.id = id;
-        record.region = region;
-        record.size_pages = size_pages;
-        record.mip_count = mip_count;
-        record.layer_mask = (stack.source.layer_mask ?? 0b111) & ((1 << config.layers.length) - 1);
-        record.ref_count = 1;
-
-        try {
-            if (typeof stack.source.prepare === 'function') {
-                stack.source.prepare({
-                    page_size: config.page_size,
-                    border: config.border,
-                    slot_size: this.#cache.slot_size,
-                    layer_count: config.layers.length,
-                    size: stack.size,
-                    mip_count,
-                });
-            }
-        } catch (e) {
-            // a throwing source must not leak the table region or the id —
-            // half-registered stacks would poison later registrations
-            this.#page_table.allocator.free(region.x, region.y, region.size);
-            this.#free_stack_ids.push(id);
-
-            throw e;
-        }
-
-        this.#stacks[id] = record;
-        this.#stack_count++;
-
-        stack.id = id;
-
-        this.#write_stack_info(record);
-
-        // pin the root: request it immediately, locked on arrival
-        this.#enqueue_key(record, mip_count - 1, 0, 0, true);
-
-        return id;
-    }
-
-    /**
-     * Drop one reference; on the last one, tear the stack's residency down
-     * and release its region and id.
-     *
-     * @param {VirtualTextureStack} stack
-     */
-    unregister_stack(stack) {
-        assert.notEqual(stack.id, -1, 'stack is not registered');
-
-        const record = this.#stacks[stack.id];
-
-        assert.defined(record, 'stack record missing');
-
-        record.ref_count--;
-
-        if (record.ref_count > 0) {
-            return;
-        }
-
-        const id = record.id;
-
-        // cancel pending loads
-        for (const pending of this.#pending.values()) {
-            if (pending.stack_id !== id) {
-                continue;
-            }
-
-            if (pending.controller !== null) {
-                pending.controller.abort();
-            }
-
-            this.#pending.delete(pending.key);
-        }
-
-        this.#queue = this.#queue.filter(key => this.#pending.has(key));
-
-        // drop undelivered arrivals
-        this.#arrived = this.#arrived.filter(a => {
-            if (a.pending.stack_id !== id) {
-                return true;
-            }
-
-            vt_close_payloads(a.payloads);
-
-            return false;
-        });
-
-        // evict residency (any order — the table repoints incrementally)
-        for (const [key, slot] of record.resident) {
-            const mip = key >> 20;
-            const y = (key >> 10) & 0x3FF;
-            const x = key & 0x3FF;
-
-            this.#page_table.page_evicted(record.region, mip, x, y);
-
-            this.#cache.free(slot);
-            this.#slot_stack[slot] = -1;
-        }
-
-        record.resident.clear();
-
-        this.#page_table.free_region(record.region);
-
-        // zero the info row so stale samples read as invalid/empty
-        new Uint8Array(this.#stack_info_staging, id * VT_STACK_INFO_STRUCT.size, VT_STACK_INFO_STRUCT.size).fill(0);
-        this.#stack_info_dirty.add(id);
-
-        // drop this stack's negative-cache entries — the key space belongs
-        // to whoever reuses the id next
-        for (const key of this.#load_failures.keys()) {
-            if (vt_request_key_unpack(key).stack_id === id) {
-                this.#load_failures.delete(key);
-            }
-        }
-
-        this.#stacks[id] = undefined;
-        this.#free_stack_ids.push(id);
-        this.#stack_count--;
-
-        stack.id = -1;
-
-        if (typeof stack.source.destroy === 'function') {
-            stack.source.destroy();
-        }
-    }
-
-    /**
-     * @param {VTStackRecord} record
-     */
-    #write_stack_info(record) {
-        const stack = record.stack;
-
-        let flags = 0;
-
-        if (stack.wrap) {
-            flags |= VT_STACK_FLAG_WRAP_REPEAT;
-        }
-
-        if (stack.uv_set === 1) {
-            flags |= VT_STACK_FLAG_UV_SET_1;
-        }
-
-        flags |= record.layer_mask << VT_STACK_FLAG_LAYER_MASK_SHIFT;
-
-        write_gpu_typed_buffer(
-            {
-                table_origin: [record.region.x, record.region.y],
-                size_pages_log2: Math.log2(record.size_pages),
-                flags,
-                average_color: stack.average_color,
-            },
-            VT_STACK_INFO_STRUCT,
-            this.#stack_info_staging,
-            record.id * VT_STACK_INFO_STRUCT.size
-        );
-
-        this.#stack_info_dirty.add(record.id);
-    }
-
-    // ── Streaming ───────────────────────────────────────────────────
-
-    /**
-     * @param {VTStackRecord} record
-     * @param {number} mip
-     * @param {number} x
-     * @param {number} y
-     * @param {boolean} lock
-     */
-    #enqueue_key(record, mip, x, y, lock) {
-        const key = vt_request_key_pack(record.id, mip, x, y);
-
-        if (this.#pending.has(key)) {
-            return;
-        }
-
-        const failure = this.#load_failures.get(key);
-
-        if (failure !== undefined && this.#frame < failure.retry_after_frame) {
-            return;
-        }
-
-        const cap = Math.max(1, Math.floor(this.#cache.capacity * this.#config.request_cap_fraction));
-
-        if (this.#pending.size >= cap && !lock) {
-            this.stats.dropped_requests++;
-            return;
-        }
-
-        const pending = new VTPendingLoad();
-
-        pending.key = key;
-        pending.stack_id = record.id;
-        pending.mip = mip;
-        pending.x = x;
-        pending.y = y;
-        pending.lock = lock;
-        pending.last_touch = this.#frame;
-
-        this.#pending.set(key, pending);
-        this.#queue.push(key);
-    }
-
-    /**
-     * Fold a feedback snapshot into residency state. Every word is a unique
-     * (stack, mip, page) touched since the previous snapshot: resident pages
-     * get their LRU refreshed (including the ancestor actually serving a
-     * not-yet-resident cell — evicting what is on screen is the classic
-     * fallback-chain bug), misses become load requests, coarse ancestors of
-     * misses are requested too so the fallback ladder fills bottom-up.
-     *
-     * @param {Uint32Array} words raw hash set snapshot
-     */
-    process_feedback(words) {
-        const frame = this.#frame;
-
-        for (let i = 0; i < words.length; i++) {
-            const w = words[i];
-
-            if (w === 0) {
-                continue;
-            }
-
-            const { stack_id, mip, page_x, page_y } = vt_request_key_unpack(w - 1);
-
-            const record = this.#stacks[stack_id];
-
-            if (record === undefined) {
-                // stack unregistered between feedback capture and readback
-                continue;
-            }
-
-            if (mip >= record.mip_count) {
-                // stale key — the id was reused by a smaller stack between
-                // feedback capture and readback
-                continue;
-            }
-
-            const pages = record.size_pages >> mip;
-
-            if (page_x >= pages || page_y >= pages) {
-                // Same staleness, in the page fields: without this guard a
-                // stale key would pass the mip check and page_loaded would
-                // later write OUTSIDE the stack's region — into a
-                // neighbouring stack's cells of the shared table.
-                continue;
-            }
-
-            const resident_slot = record.resident.get(local_key(mip, page_x, page_y));
-
-            if (resident_slot !== undefined) {
-                this.#cache.touch(resident_slot, frame);
-                continue;
-            }
-
-            // touch whatever is currently serving this cell
-            const serving = this.#page_table.read_entry(record.region, mip, page_x, page_y);
-
-            if (serving !== VT_ENTRY_INVALID) {
-                const entry = vt_entry_unpack(serving);
-
-                this.#cache.touch(entry.phys_y * this.#cache.slots_per_axis + entry.phys_x, frame);
-            }
-
-            const pending = this.#pending.get(w - 1);
-
-            if (pending !== undefined) {
-                pending.last_touch = frame;
-                continue;
-            }
-
-            this.#enqueue_key(record, mip, page_x, page_y, false);
-
-            // request missing ancestors, nearest first; stop at the first
-            // level that is already resident or pending
-            for (let m = mip + 1; m < record.mip_count; m++) {
-                const ax = page_x >> (m - mip);
-                const ay = page_y >> (m - mip);
-
-                if (record.resident.has(local_key(m, ax, ay))) {
-                    break;
-                }
-
-                const a_key = vt_request_key_pack(record.id, m, ax, ay);
-
-                const a_pending = this.#pending.get(a_key);
-
-                if (a_pending !== undefined) {
-                    a_pending.last_touch = frame;
-                    break;
-                }
-
-                this.#enqueue_key(record, m, ax, ay, false);
-            }
-        }
-    }
-
-    /**
-     * Evict one page to make room. Prefers least-recently-touched outside
-     * the protection window, finest mip on ties (shrink the resident
-     * quadtree from the leaves); under absolute pressure ignores the window.
-     *
-     * @returns {number} freed slot, or -1 when everything is locked
-     */
-    #evict_one() {
-        let slot = this.#cache.find_eviction_candidate(this.#frame, this.#config.eviction_protect_window);
-
-        if (slot === -1) {
-            slot = this.#cache.find_eviction_candidate(this.#frame, 0);
-        }
-
-        if (slot === -1) {
-            return -1;
-        }
-
-        const stack_id = this.#slot_stack[slot];
-
-        assert.greaterThanOrEqual(stack_id, 0, 'evicting a slot with no owner');
-
-        const record = this.#stacks[stack_id];
-
-        const mip = this.#slot_mip[slot];
-        const x = this.#slot_x[slot];
-        const y = this.#slot_y[slot];
-
-        this.#page_table.page_evicted(record.region, mip, x, y);
-
-        record.resident.delete(local_key(mip, x, y));
-
-        this.#cache.free(slot);
-        this.#slot_stack[slot] = -1;
-
-        this.stats.evictions_last_frame++;
-
-        return slot;
-    }
-
-    /**
-     * @param {{pending: VTPendingLoad, payloads: Array}} arrival
-     * @returns {boolean} applied
-     */
-    #apply_arrival(arrival) {
-        const pending = arrival.pending;
-
-        const record = this.#stacks[pending.stack_id];
-
-        if (record === undefined || record.stack.id !== pending.stack_id) {
-            vt_close_payloads(arrival.payloads);
-            return false;
-        }
-
-        if (record.resident.has(local_key(pending.mip, pending.x, pending.y))) {
-            // duplicate delivery — possible after unregister/register churn
-            vt_close_payloads(arrival.payloads);
-            return false;
-        }
-
-        let slot = this.#cache.allocate(this.#frame, pending.lock, pending.mip);
-
-        if (slot === -1) {
-            const freed = this.#evict_one();
-
-            if (freed === -1) {
-                if (pending.lock) {
-                    // a pinned root must not be lost to transient pressure —
-                    // dropping it here would leave the stack permanently
-                    // without its guaranteed fallback (feedback re-requests
-                    // are unlocked). Hold the arrival and retry next frame.
-                    return 'retry';
-                }
-
-                vt_close_payloads(arrival.payloads);
-                return false;
-            }
-
-            slot = this.#cache.allocate(this.#frame, pending.lock, pending.mip);
-
-            assert.notEqual(slot, -1, 'allocation failed after eviction');
-        }
-
-        const queue = this.#device.queue;
-
-        const layer_count = this.#config.layers.length;
-
-        for (let layer = 0; layer < layer_count; layer++) {
-            if ((record.layer_mask & (1 << layer)) === 0) {
-                continue;
-            }
-
-            const payload = arrival.payloads[layer];
-
-            assert.defined(payload, `source omitted layer ${layer} it declared in layer_mask`);
-
-            this.#cache.upload(queue, slot, layer, payload);
-        }
-
-        // uploads are queue-captured at submission — the bitmaps can go now
-        vt_close_payloads(arrival.payloads);
-
-        this.#slot_stack[slot] = record.id;
-        this.#slot_mip[slot] = pending.mip;
-        this.#slot_x[slot] = pending.x;
-        this.#slot_y[slot] = pending.y;
-
-        record.resident.set(local_key(pending.mip, pending.x, pending.y), slot);
-
-        const coords = this.#cache.slot_coords(slot);
-
-        this.#page_table.page_loaded(
-            record.region,
-            pending.mip, pending.x, pending.y,
-            vt_entry_pack(coords.x, coords.y, pending.mip)
-        );
-
-        return true;
-    }
-
-    /**
-     * @param {VTPendingLoad} pending
-     */
-    #issue_load(pending) {
-        const record = this.#stacks[pending.stack_id];
-
-        pending.issued = true;
-        pending.controller = new AbortController();
-
-        this.#loads_in_flight++;
-
-        // Promise.resolve().then(...) shields against sources whose
-        // load_page throws synchronously or returns a non-promise —
-        // either would otherwise unwind update() mid-frame
-        Promise.resolve()
-            .then(() => record.stack.source.load_page(pending.mip, pending.x, pending.y, pending.controller.signal))
-            .then(payloads => {
-                if (this.#pending.get(pending.key) === pending) {
-                    this.#arrived.push({ pending, payloads });
-                    this.#pending.delete(pending.key);
-                    this.#load_failures.delete(pending.key);
-                } else {
-                    // superseded (stack unregistered, or the key was
-                    // re-enqueued by a later registration) — discard
-                    vt_close_payloads(payloads);
-                }
-            })
-            .catch(e => {
-                // identity-guarded: after unregister/register churn the same
-                // key may belong to a NEW pending load — a stale rejection
-                // must not delete it
-                if (this.#pending.get(pending.key) === pending) {
-                    this.#pending.delete(pending.key);
-                }
-
-                if (e?.name !== 'AbortError') {
-                    const failure = this.#load_failures.get(pending.key) ?? { failures: 0, retry_after_frame: 0 };
-
-                    failure.failures++;
-                    // 30, 60, 120 … 1800 frames (~0.5 s to ~30 s at 60 fps)
-                    failure.retry_after_frame = this.#frame + Math.min(1800, 30 << Math.min(failure.failures - 1, 6));
-
-                    this.#load_failures.set(pending.key, failure);
-
-                    console.error(`vt: page load failed (stack=${pending.stack_id} mip=${pending.mip} ${pending.x},${pending.y})`, e);
-                }
-            })
-            .finally(() => {
-                this.#loads_in_flight--;
-            });
-    }
-
-    /**
-     * Push accumulated page-table dirty rects and stack-info rows to the
-     * GPU. Runs inside update(), and again from graph_feedback() so a stack
-     * registered mid-frame (materials build during scene update, after
-     * begin_frame) is sampled correctly on its very first frame instead of
-     * one frame late. Idempotent — dirty sets drain.
-     */
-    flush_gpu_state() {
-        if (!this.#initialized) {
-            return;
-        }
-
-        const queue = this.#device.queue;
-
-        this.#page_table.flush(queue);
-
-        if (this.#stack_info_dirty.size > 0) {
-            for (const id of this.#stack_info_dirty) {
-                const offset = id * VT_STACK_INFO_STRUCT.size;
-
-                queue.writeBuffer(
-                    this.#stack_info_buffer, offset,
-                    this.#stack_info_staging, offset, VT_STACK_INFO_STRUCT.size
-                );
-            }
-
-            this.#stack_info_dirty.clear();
-        }
-    }
-
-    /**
-     * Per-frame maintenance. Call once per frame, before building the
-     * shading graph, so the material pass samples this frame's page table.
-     */
-    update() {
-        if (!this.#initialized) {
-            return;
-        }
-
-        this.#frame++;
-
-        const config = this.#config;
-
-        this.stats.uploads_last_frame = 0;
-        this.stats.evictions_last_frame = 0;
-
-        // 1. budgeted uploads of arrived pages, oldest first; locked roots
-        //    that couldn't find a slot are held for a later frame
-        let budget = config.max_uploads_per_frame;
-
-        const retries = [];
-
-        while (budget > 0 && this.#arrived.length > 0) {
-            const arrival = this.#arrived.shift();
-
-            const result = this.#apply_arrival(arrival);
-
-            if (result === true) {
-                this.stats.uploads_last_frame++;
-                budget--;
-            } else if (result === 'retry') {
-                retries.push(arrival);
-            }
-        }
-
-        if (retries.length > 0) {
-            this.#arrived.push(...retries);
-        }
-
-        // 2+3. page table dirty rects, stack info dirty rows — flushed even
-        //      with zero stacks registered, so the teardown writes of the
-        //      LAST unregister still reach the GPU
-        this.flush_gpu_state();
-
-        if (this.#stack_count === 0) {
-            this.stats.stacks = 0;
-            this.stats.resident_pages = this.#cache.used;
-            this.stats.pending_loads = this.#pending.size;
-            this.stats.queued_loads = this.#queue.length;
-
-            return;
-        }
-
-        // 4. drop queued requests that stopped being touched
-        if (this.#queue.length > 0) {
-            const stale_before = this.#frame - config.queue_stale_window;
-
-            this.#queue = this.#queue.filter(key => {
-                const pending = this.#pending.get(key);
-
-                if (pending === undefined || pending.issued) {
-                    return false;
-                }
-
-                if (!pending.lock && pending.last_touch < stale_before) {
-                    this.#pending.delete(key);
-                    return false;
-                }
-
-                return true;
-            });
-        }
-
-        // 5. issue loads, coarse mips first (they unblock the most screen area)
-        if (this.#queue.length > 0 && this.#loads_in_flight < config.max_concurrent_loads) {
-            this.#queue.sort((a, b) => {
-                const pa = this.#pending.get(a);
-                const pb = this.#pending.get(b);
-
-                return pb.mip - pa.mip;
-            });
-
-            while (this.#loads_in_flight < config.max_concurrent_loads && this.#queue.length > 0) {
-                const key = this.#queue.shift();
-
-                const pending = this.#pending.get(key);
-
-                if (pending === undefined) {
-                    continue;
-                }
-
-                this.#issue_load(pending);
-            }
-        }
-
-        // 6. residency pressure → feedback mip bias (degrade to blur, not thrash)
-        const load = this.#cache.used / this.#cache.capacity;
-
-        if (load > config.pressure_high_watermark) {
-            this.#residency_bias = Math.min(this.#residency_bias + 0.5, 4);
-        } else if (load < config.pressure_low_watermark && this.#residency_bias > 0) {
-            this.#residency_bias = Math.max(this.#residency_bias - 0.25, 0);
-        }
-
-        const stats = this.stats;
-
-        stats.stacks = this.#stack_count;
-        stats.resident_pages = this.#cache.used;
-        stats.pending_loads = this.#pending.size;
-        stats.queued_loads = this.#queue.length;
-        stats.residency_bias = this.#residency_bias;
-    }
-
-    // ── FrameGraph wiring ───────────────────────────────────────────
-
-    /**
-     * Add the feedback passes to the frame's graph: clear + populate the
-     * request hash set from the visibility buffer, then read it back
-     * asynchronously. Skips itself when idle or when the readback ring is
-     * saturated (slow map resolution must throttle GPU work, not queue it).
-     *
-     * @param {Object} args
-     * @param {FrameGraph} args.graph
-     * @param {GPUViewContext} args.view
-     * @param {number} args.texture_viz_mesh graph handle
-     * @param {number} args.texture_viz_triangle graph handle
-     * @param {GPUBuffer} args.material_metadata_buffer
-     */
-    graph_feedback({
-                       graph,
-                       view,
-                       texture_viz_mesh,
-                       texture_viz_triangle,
-                       material_metadata_buffer,
-                   }) {
-
-        if (!this.#initialized || this.#stack_count === 0) {
-            return;
-        }
-
-        // stacks registered after this frame's update() (materials build
-        // during scene update) publish their rows now — before the material
-        // pass samples them
-        this.flush_gpu_state();
-
-        if (this.#readbacks_in_flight >= 3) {
-            return;
-        }
-
-        const config = this.#config;
-        const scene_ctx = view.scene;
-
-        const stride = config.feedback_stride;
-
-        const jitter_index = this.#frame % (stride * stride);
-        const jitter = [jitter_index % stride, (jitter_index / stride) | 0];
-
-        const resolution = view.resolution;
-
-        const group_count_x = Math.ceil(Math.ceil(resolution[0] / stride) / VT_FEEDBACK_WORKGROUP_SIZE);
-        const group_count_y = Math.ceil(Math.ceil(resolution[1] / stride) / VT_FEEDBACK_WORKGROUP_SIZE);
-
-        const shader = this.#shader_feedback;
-        const mip_bias = this.#residency_bias;
-        const stack_info_buffer = this.#stack_info_buffer;
-
-        const pass_data = {};
-
-        const pass = graph.add("VT Feedback", pass_data, (data, resources, context) => {
-            const requests = resources.get(data.requests);
-
-            // transient pool buffers carry stale contents — the hash set
-            // relies on zero meaning empty
-            context.encoder.clearBuffer(requests);
-
-            shader.dispatch({
-                encoder: context.encoder,
-                group_count_x,
-                group_count_y,
-                group_count_z: 1,
-                bindings: {
-                    viz_buffer_triangle: resources.get(data.viz_triangle).obtainView(),
-                    viz_buffer_mesh: resources.get(data.viz_mesh).obtainView(),
-                    view: view.uniform_buffer.buffer,
-                    vt_params: context.encoder.allocateTransientValueBuffer(
-                        VT_FEEDBACK_PARAMS_STRUCT,
-                        { stride, jitter, mip_bias }
-                    ),
-                    scene_database: scene_ctx.scene_database_buffer,
-                    meshlet_metadata: scene_ctx.geometries.meshlets.buffer_metadata,
-                    meshlet_data: scene_ctx.geometries.meshlets.buffer_data,
-                    material_metadata: material_metadata_buffer,
-                    vt_stacks: stack_info_buffer,
-                    vt_requests: requests,
-                }
-            });
-        });
-
-        pass_data.viz_mesh = pass.read(texture_viz_mesh);
-        pass_data.viz_triangle = pass.read(texture_viz_triangle);
-
-        pass_data.requests = pass.create("vt_requests", BufferResourceDescriptor.from(
-            config.hash_capacity * 4,
-            GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST,
-        ));
-
-        this.#readbacks_in_flight++;
-
-        graph_read_buffer({ graph, buffer: pass_data.requests })
-            .then(ref => {
-                try {
-                    this.process_feedback(new Uint32Array(ref.getValue()));
-                } finally {
-                    ref.release();
-                }
-            })
-            .catch(e => {
-                console.error('vt: feedback readback failed', e);
-            })
-            .finally(() => {
-                this.#readbacks_in_flight--;
-            });
-    }
-
-    destroy() {
-        if (!this.#initialized) {
-            return;
-        }
-
-        for (const pending of this.#pending.values()) {
-            if (pending.controller !== null) {
-                pending.controller.abort();
-            }
-        }
-
-        this.#pending.clear();
-        this.#queue.length = 0;
-
-        for (const arrival of this.#arrived) {
-            vt_close_payloads(arrival.payloads);
-        }
-
-        this.#arrived.length = 0;
-        this.#load_failures.clear();
-
-        for (const record of this.#stacks) {
-            if (record !== undefined && typeof record.stack.source.destroy === 'function') {
-                record.stack.source.destroy();
-            }
-        }
-
-        this.#page_table.destroy();
-        this.#cache.destroy();
-        this.#stack_info_buffer.destroy();
-    }
-}
+import { assert } from "../../../../core/assert.js";
+import { isPowerOfTwo } from "../../../../core/math/isPowerOfTwo.js";
+import { write_gpu_typed_buffer } from "../../shader/type/serde/write_gpu_typed_buffer.js";
+import { BufferResourceDescriptor } from "../../../device/graph/BufferResourceDescriptor.js";
+import { graph_read_buffer } from "../../buffer/graph_read_buffer.js";
+import { build_vt_material_pipeline_descriptor } from "../../material/standard/fragment_gbuffer_vt.js";
+import { build_chunk_vt_lookup } from "./build_chunk_vt_lookup.js";
+import { build_shader_vt_feedback, VT_FEEDBACK_PARAMS_STRUCT, VT_FEEDBACK_WORKGROUP_SIZE } from "./build_shader_vt_feedback.js";
+import {
+    VT_ENTRY_INVALID,
+    VT_ENTRY_MIP_MASK,
+    VT_MAX_MIP_COUNT,
+    VT_MAX_PAGES_PER_AXIS,
+    VT_STACK_FLAG_LAYER_MASK_SHIFT,
+    VT_STACK_FLAG_UV_SET_1,
+    VT_STACK_FLAG_WRAP_REPEAT,
+    VT_STACK_ID_INVALID,
+    vt_entry_pack,
+    vt_entry_unpack,
+    vt_request_key_pack,
+    vt_request_key_unpack,
+} from "./VT_CONSTANTS.js";
+import { VT_STACK_INFO_STRUCT } from "./VT_STACK_INFO_STRUCT.js";
+import { VTPageTable } from "./VTPageTable.js";
+import { VTPhysicalCache } from "./VTPhysicalCache.js";
+
+/**
+ * Local page key within one stack — never leaves the CPU.
+ * @param {number} mip
+ * @param {number} x
+ * @param {number} y
+ * @returns {number}
+ */
+function local_key(mip, x, y) {
+    return (mip << 20) | (y << 10) | x;
+}
+
+/**
+ * Release decoded tile payloads that will not be uploaded. ImageBitmaps pin
+ * pixel memory until GC; explicit close keeps drops/discards cheap.
+ * @param {Array} payloads
+ */
+function vt_close_payloads(payloads) {
+    if (!Array.isArray(payloads)) {
+        return;
+    }
+
+    for (const payload of payloads) {
+        if (payload != null && typeof payload.close === 'function') {
+            payload.close();
+        }
+    }
+}
+
+/**
+ * Bookkeeping for one registered stack.
+ */
+class VTStackRecord {
+    /**
+     * @type {VirtualTextureStack}
+     */
+    stack = null;
+
+    id = 0;
+
+    /**
+     * Region in the shared page table, mip-0 texels.
+     * @type {{x: number, y: number, size: number}}
+     */
+    region = null;
+
+    size_pages = 0;
+    mip_count = 0;
+    layer_mask = 0;
+
+    /**
+     * Materials currently referencing the stack.
+     * @type {number}
+     */
+    ref_count = 0;
+
+    /**
+     * local_key(mip,x,y) → physical slot.
+     * @type {Map<number, number>}
+     */
+    resident = new Map();
+}
+
+class VTPendingLoad {
+    key = 0;
+    stack_id = 0;
+    mip = 0;
+    x = 0;
+    y = 0;
+    issued = false;
+    lock = false;
+    last_touch = 0;
+
+    /**
+     * @type {AbortController}
+     */
+    controller = null;
+}
+
+/**
+ * Virtual texture system orchestrator. Owns the shared page table, the
+ * physical cache group, the stack registry, the streaming pipeline and the
+ * FrameGraph feedback wiring. One instance per GraphicsContext.
+ *
+ * Opt-in and lazy: constructing it costs nothing; GPU resources (page table
+ * texture, cache atlases, shaders) materialize when the first stack
+ * registers. `configure()` before that point to change geometry.
+ *
+ * Per-frame protocol (driven by the Renderer):
+ *   1. `update()` — before the shading graph: apply arrived pages (budgeted
+ *      uploads + page-table maintenance), flush GPU state, issue loads.
+ *   2. `graph_feedback(...)` — inside the shading graph: viz-buffer → unique
+ *      request hash set → async readback. Results are folded in whenever the
+ *      map resolves (typically next frame): resident touches refresh LRU,
+ *      misses enter the load queue coarse-first.
+ *
+ * Scale properties: state per registered stack is one table region + one
+ * 32-byte info row; per-frame cost is one screen-space compute pass and one
+ * small readback regardless of how many stacks exist.
+ */
+export class VirtualTextureManager {
+
+    /**
+     * @type {GPUDevice}
+     */
+    #device;
+
+    /**
+     * Geometry/config — frozen at first stack registration.
+     */
+    #config = {
+        page_size: 128,
+        border: 4,
+        atlas_size: 4096,
+        table_size: 1024,
+        hash_capacity: 16384,
+        /** feedback samples one pixel per stride×stride block, jittered over stride² frames */
+        feedback_stride: 4,
+        max_uploads_per_frame: 8,
+        max_concurrent_loads: 32,
+        /** in-flight + queued requests cap, as a fraction of cache capacity */
+        request_cap_fraction: 1 / 3,
+        /** frames a touched page is safe from eviction (covers feedback latency) */
+        eviction_protect_window: 4,
+        /** queued (unissued) requests untouched for this many frames are dropped */
+        queue_stale_window: 30,
+        /** residency water marks driving the feedback mip bias */
+        pressure_high_watermark: 0.9,
+        pressure_low_watermark: 0.75,
+        layers: [
+            { name: 'albedo', format: 'rgba8unorm-srgb', premultiplied: true },
+            { name: 'normal', format: 'rgba8unorm' },
+            { name: 'orm', format: 'rgba8unorm' },
+        ],
+    };
+
+    #initialized = false;
+
+    /**
+     * @type {VTPageTable}
+     */
+    #page_table = null;
+
+    /**
+     * @type {VTPhysicalCache}
+     */
+    #cache = null;
+
+    /**
+     * Per-slot reverse lookup: owning stack id (-1 = free), page address.
+     */
+    #slot_stack = null;
+    #slot_mip = null;
+    #slot_x = null;
+    #slot_y = null;
+
+    /**
+     * Index 0 is permanently reserved: GPU-side tables (material metadata,
+     * stack info) zero-initialize, and a row that hasn't been flushed yet
+     * reads as "stack 0". Never assigning id 0 turns that entire class of
+     * zero-init/flush-lag states into a clean "unknown stack, skip" instead
+     * of junk requests against a real stack.
+     * @type {(VTStackRecord|undefined)[]}
+     */
+    #stacks = [undefined];
+
+    /**
+     * @type {number[]}
+     */
+    #free_stack_ids = [];
+
+    #stack_count = 0;
+
+    /**
+     * Fixed-capacity GPU mirror of stack info rows.
+     * @type {GPUBuffer}
+     */
+    #stack_info_buffer = null;
+
+    /**
+     * @type {ArrayBuffer}
+     */
+    #stack_info_staging = null;
+
+    /**
+     * @type {Set<number>}
+     */
+    #stack_info_dirty = new Set();
+
+    /**
+     * key → pending load (queued or in flight).
+     * @type {Map<number, VTPendingLoad>}
+     */
+    #pending = new Map();
+
+    /**
+     * Keys of queued (not yet issued) loads.
+     * @type {number[]}
+     */
+    #queue = [];
+
+    #loads_in_flight = 0;
+
+    /**
+     * Loaded payloads waiting for their budgeted upload.
+     * @type {{pending: VTPendingLoad, payloads: Array}[]}
+     */
+    #arrived = [];
+
+    /**
+     * Negative cache: request key → {failures, retry_after_frame}. Keeps a
+     * permanently-missing tile (404, decode error) from being re-fetched at
+     * feedback rate forever; backoff doubles per failure up to ~30 s.
+     * @type {Map<number, {failures: number, retry_after_frame: number}>}
+     */
+    #load_failures = new Map();
+
+    #readbacks_in_flight = 0;
+
+    /**
+     * Manager frame counter — advanced by update(), used for LRU and
+     * staleness. Deliberately independent of the renderer's frame index.
+     */
+    #frame = 0;
+
+    /**
+     * Current feedback mip bias from residency pressure (0 = no pressure).
+     */
+    #residency_bias = 0;
+
+    /**
+     * @type {import("../../shader/ComputeShader.js").ComputeShader}
+     */
+    #shader_feedback = null;
+
+    /**
+     * @type {CodeChunk}
+     */
+    #chunk_lookup = null;
+
+    /**
+     * @type {RenderPipelineDescriptor}
+     */
+    #material_pipeline_descriptor = null;
+
+    /**
+     * @type {GPUTextureView}
+     */
+    #page_table_view = null;
+
+    /**
+     * Bilinear clamp sampler for the physical caches — addressing is done
+     * in-shader, page borders make bilinear seamless.
+     * @type {GPUSampler}
+     */
+    #cache_sampler = null;
+
+    /**
+     * Diagnostics, refreshed every update().
+     */
+    stats = {
+        stacks: 0,
+        resident_pages: 0,
+        pending_loads: 0,
+        queued_loads: 0,
+        uploads_last_frame: 0,
+        evictions_last_frame: 0,
+        dropped_requests: 0,
+        residency_bias: 0,
+        cache_capacity: 0,
+    };
+
+    /**
+     *
+     * @param {GPUDevice} device
+     */
+    constructor(device) {
+        assert.defined(device, 'device');
+
+        this.#device = device;
+    }
+
+    /**
+     * Override defaults. Must be called before the first stack registers.
+     * @param {Object} options subset of the config block
+     */
+    configure(options) {
+        assert.equal(this.#initialized, false, 'configure() after initialization');
+
+        Object.assign(this.#config, options);
+    }
+
+    /**
+     * @returns {boolean} true when at least one stack is registered
+     */
+    get active() {
+        return this.#stack_count > 0;
+    }
+
+    /**
+     * @returns {Object}
+     */
+    get config() {
+        return this.#config;
+    }
+
+    /**
+     * The lookup chunk shared by the feedback shader and material samplers.
+     * @returns {CodeChunk}
+     */
+    get chunk_lookup() {
+        this.#ensure_initialized();
+
+        return this.#chunk_lookup;
+    }
+
+    /**
+     * @returns {GPUTexture}
+     */
+    get page_table_texture() {
+        this.#ensure_initialized();
+
+        return this.#page_table.texture;
+    }
+
+    /**
+     * @returns {GPUBuffer}
+     */
+    get stack_info_buffer() {
+        this.#ensure_initialized();
+
+        return this.#stack_info_buffer;
+    }
+
+    /**
+     * @returns {VTPhysicalCache}
+     */
+    get cache() {
+        this.#ensure_initialized();
+
+        return this.#cache;
+    }
+
+    /**
+     * @returns {GPUTextureView}
+     */
+    get page_table_view() {
+        this.#ensure_initialized();
+
+        return this.#page_table_view;
+    }
+
+    /**
+     * @returns {GPUSampler}
+     */
+    get cache_sampler() {
+        this.#ensure_initialized();
+
+        return this.#cache_sampler;
+    }
+
+    /**
+     * Pipeline descriptor of the virtual-texture material variant, built for
+     * this manager's cache geometry. Shared by every VT material.
+     * @returns {RenderPipelineDescriptor}
+     */
+    get material_pipeline_descriptor() {
+        this.#ensure_initialized();
+
+        if (this.#material_pipeline_descriptor === null) {
+            this.#material_pipeline_descriptor = build_vt_material_pipeline_descriptor(this.#chunk_lookup);
+        }
+
+        return this.#material_pipeline_descriptor;
+    }
+
+    #ensure_initialized() {
+        if (this.#initialized) {
+            return;
+        }
+
+        const config = this.#config;
+        const device = this.#device;
+
+        this.#page_table = new VTPageTable(device, config.table_size);
+
+        this.#cache = new VTPhysicalCache(device, {
+            atlas_size: config.atlas_size,
+            page_size: config.page_size,
+            border: config.border,
+            layers: config.layers,
+        });
+
+        const capacity = this.#cache.capacity;
+
+        this.#slot_stack = new Int32Array(capacity).fill(-1);
+        this.#slot_mip = new Uint8Array(capacity);
+        this.#slot_x = new Uint16Array(capacity);
+        this.#slot_y = new Uint16Array(capacity);
+
+        this.#stack_info_staging = new ArrayBuffer(VT_STACK_ID_INVALID * VT_STACK_INFO_STRUCT.size);
+
+        this.#stack_info_buffer = device.createBuffer({
+            label: 'vt/stack-info',
+            size: this.#stack_info_staging.byteLength,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+        });
+
+        this.#chunk_lookup = build_chunk_vt_lookup({
+            page_size: config.page_size,
+            border: config.border,
+            atlas_size: config.atlas_size,
+        });
+
+        this.#shader_feedback = build_shader_vt_feedback({
+            chunk_vt_lookup: this.#chunk_lookup,
+            hash_capacity: config.hash_capacity,
+        });
+
+        this.#page_table_view = this.#page_table.texture.createView();
+
+        this.#cache_sampler = device.createSampler({
+            label: 'vt/cache-sampler',
+            magFilter: 'linear',
+            minFilter: 'linear',
+            addressModeU: 'clamp-to-edge',
+            addressModeV: 'clamp-to-edge',
+        });
+
+        this.stats.cache_capacity = capacity;
+
+        this.#initialized = true;
+    }
+
+    // ── Stack registry ──────────────────────────────────────────────
+
+    /**
+     * Register a stack (idempotent per stack — shared stacks ref-count).
+     * Allocates the page-table region, publishes the info row, and pins the
+     * root page so a fallback is always resident once it streams in.
+     *
+     * @param {VirtualTextureStack} stack
+     * @returns {number} stack id
+     */
+    register_stack(stack) {
+        assert.equal(stack.isVirtualTextureStack, true, 'not a VirtualTextureStack');
+
+        if (stack.id !== -1) {
+            const existing = this.#stacks[stack.id];
+
+            assert.defined(existing, 'stack carries an id but is not registered');
+
+            existing.ref_count++;
+
+            return stack.id;
+        }
+
+        this.#ensure_initialized();
+
+        const config = this.#config;
+
+        assert.defined(stack.source, 'stack.source');
+        assert.greaterThanOrEqual(stack.size, config.page_size, 'stack smaller than a page');
+        assert.equal(stack.size % config.page_size, 0, 'stack size is not a multiple of page size');
+
+        const size_pages = stack.size / config.page_size;
+
+        assert.ok(isPowerOfTwo(size_pages), 'stack page count must be a power of two');
+        assert.lessThanOrEqual(size_pages, VT_MAX_PAGES_PER_AXIS, 'stack exceeds page coordinate budget');
+
+        const mip_count = Math.log2(size_pages) + 1;
+
+        assert.lessThanOrEqual(mip_count, VT_MAX_MIP_COUNT, 'mip chain exceeds request key budget');
+        assert.lessThanOrEqual(mip_count - 1, VT_ENTRY_MIP_MASK, 'mip chain exceeds page table entry budget');
+
+        const region = this.#page_table.allocate_region(size_pages);
+
+        if (region === null) {
+            throw new Error(`vt: page table is full (registering '${stack.label}', ${size_pages}² pages)`);
+        }
+
+        let id;
+
+        if (this.#free_stack_ids.length > 0) {
+            id = this.#free_stack_ids.pop();
+        } else {
+            id = this.#stacks.length;
+        }
+
+        if (id >= VT_STACK_ID_INVALID) {
+            this.#page_table.allocator.free(region.x, region.y, region.size);
+            throw new Error(`vt: stack budget exhausted (${VT_STACK_ID_INVALID})`);
+        }
+
+        const record = new VTStackRecord();
+
+        record.stack = stack;
+        record.id = id;
+        record.region = region;
+        record.size_pages = size_pages;
+        record.mip_count = mip_count;
+        record.layer_mask = (stack.source.layer_mask ?? 0b111) & ((1 << config.layers.length) - 1);
+        record.ref_count = 1;
+
+        try {
+            if (typeof stack.source.prepare === 'function') {
+                stack.source.prepare({
+                    page_size: config.page_size,
+                    border: config.border,
+                    slot_size: this.#cache.slot_size,
+                    layer_count: config.layers.length,
+                    size: stack.size,
+                    mip_count,
+                });
+            }
+        } catch (e) {
+            // a throwing source must not leak the table region or the id —
+            // half-registered stacks would poison later registrations
+            this.#page_table.allocator.free(region.x, region.y, region.size);
+            this.#free_stack_ids.push(id);
+
+            throw e;
+        }
+
+        this.#stacks[id] = record;
+        this.#stack_count++;
+
+        stack.id = id;
+
+        this.#write_stack_info(record);
+
+        // pin the root: request it immediately, locked on arrival
+        this.#enqueue_key(record, mip_count - 1, 0, 0, true);
+
+        return id;
+    }
+
+    /**
+     * Drop one reference; on the last one, tear the stack's residency down
+     * and release its region and id.
+     *
+     * @param {VirtualTextureStack} stack
+     */
+    unregister_stack(stack) {
+        assert.notEqual(stack.id, -1, 'stack is not registered');
+
+        const record = this.#stacks[stack.id];
+
+        assert.defined(record, 'stack record missing');
+
+        record.ref_count--;
+
+        if (record.ref_count > 0) {
+            return;
+        }
+
+        const id = record.id;
+
+        // cancel pending loads
+        for (const pending of this.#pending.values()) {
+            if (pending.stack_id !== id) {
+                continue;
+            }
+
+            if (pending.controller !== null) {
+                pending.controller.abort();
+            }
+
+            this.#pending.delete(pending.key);
+        }
+
+        this.#queue = this.#queue.filter(key => this.#pending.has(key));
+
+        // drop undelivered arrivals
+        this.#arrived = this.#arrived.filter(a => {
+            if (a.pending.stack_id !== id) {
+                return true;
+            }
+
+            vt_close_payloads(a.payloads);
+
+            return false;
+        });
+
+        // evict residency (any order — the table repoints incrementally)
+        for (const [key, slot] of record.resident) {
+            const mip = key >> 20;
+            const y = (key >> 10) & 0x3FF;
+            const x = key & 0x3FF;
+
+            this.#page_table.page_evicted(record.region, mip, x, y);
+
+            this.#cache.free(slot);
+            this.#slot_stack[slot] = -1;
+        }
+
+        record.resident.clear();
+
+        this.#page_table.free_region(record.region);
+
+        // zero the info row so stale samples read as invalid/empty
+        new Uint8Array(this.#stack_info_staging, id * VT_STACK_INFO_STRUCT.size, VT_STACK_INFO_STRUCT.size).fill(0);
+        this.#stack_info_dirty.add(id);
+
+        // drop this stack's negative-cache entries — the key space belongs
+        // to whoever reuses the id next
+        for (const key of this.#load_failures.keys()) {
+            if (vt_request_key_unpack(key).stack_id === id) {
+                this.#load_failures.delete(key);
+            }
+        }
+
+        this.#stacks[id] = undefined;
+        this.#free_stack_ids.push(id);
+        this.#stack_count--;
+
+        stack.id = -1;
+
+        if (typeof stack.source.destroy === 'function') {
+            stack.source.destroy();
+        }
+    }
+
+    /**
+     * @param {VTStackRecord} record
+     */
+    #write_stack_info(record) {
+        const stack = record.stack;
+
+        let flags = 0;
+
+        if (stack.wrap) {
+            flags |= VT_STACK_FLAG_WRAP_REPEAT;
+        }
+
+        if (stack.uv_set === 1) {
+            flags |= VT_STACK_FLAG_UV_SET_1;
+        }
+
+        flags |= record.layer_mask << VT_STACK_FLAG_LAYER_MASK_SHIFT;
+
+        write_gpu_typed_buffer(
+            {
+                table_origin: [record.region.x, record.region.y],
+                size_pages_log2: Math.log2(record.size_pages),
+                flags,
+                average_color: stack.average_color,
+            },
+            VT_STACK_INFO_STRUCT,
+            this.#stack_info_staging,
+            record.id * VT_STACK_INFO_STRUCT.size
+        );
+
+        this.#stack_info_dirty.add(record.id);
+    }
+
+    // ── Streaming ───────────────────────────────────────────────────
+
+    /**
+     * @param {VTStackRecord} record
+     * @param {number} mip
+     * @param {number} x
+     * @param {number} y
+     * @param {boolean} lock
+     */
+    #enqueue_key(record, mip, x, y, lock) {
+        const key = vt_request_key_pack(record.id, mip, x, y);
+
+        if (this.#pending.has(key)) {
+            return;
+        }
+
+        const failure = this.#load_failures.get(key);
+
+        if (failure !== undefined && this.#frame < failure.retry_after_frame) {
+            return;
+        }
+
+        const cap = Math.max(1, Math.floor(this.#cache.capacity * this.#config.request_cap_fraction));
+
+        if (this.#pending.size >= cap && !lock) {
+            this.stats.dropped_requests++;
+            return;
+        }
+
+        const pending = new VTPendingLoad();
+
+        pending.key = key;
+        pending.stack_id = record.id;
+        pending.mip = mip;
+        pending.x = x;
+        pending.y = y;
+        pending.lock = lock;
+        pending.last_touch = this.#frame;
+
+        this.#pending.set(key, pending);
+        this.#queue.push(key);
+    }
+
+    /**
+     * Fold a feedback snapshot into residency state. Every word is a unique
+     * (stack, mip, page) touched since the previous snapshot: resident pages
+     * get their LRU refreshed (including the ancestor actually serving a
+     * not-yet-resident cell — evicting what is on screen is the classic
+     * fallback-chain bug), misses become load requests, coarse ancestors of
+     * misses are requested too so the fallback ladder fills bottom-up.
+     *
+     * @param {Uint32Array} words raw hash set snapshot
+     */
+    process_feedback(words) {
+        const frame = this.#frame;
+
+        for (let i = 0; i < words.length; i++) {
+            const w = words[i];
+
+            if (w === 0) {
+                continue;
+            }
+
+            const { stack_id, mip, page_x, page_y } = vt_request_key_unpack(w - 1);
+
+            const record = this.#stacks[stack_id];
+
+            if (record === undefined) {
+                // stack unregistered between feedback capture and readback
+                continue;
+            }
+
+            if (mip >= record.mip_count) {
+                // stale key — the id was reused by a smaller stack between
+                // feedback capture and readback
+                continue;
+            }
+
+            const pages = record.size_pages >> mip;
+
+            if (page_x >= pages || page_y >= pages) {
+                // Same staleness, in the page fields: without this guard a
+                // stale key would pass the mip check and page_loaded would
+                // later write OUTSIDE the stack's region — into a
+                // neighbouring stack's cells of the shared table.
+                continue;
+            }
+
+            const resident_slot = record.resident.get(local_key(mip, page_x, page_y));
+
+            if (resident_slot !== undefined) {
+                this.#cache.touch(resident_slot, frame);
+                continue;
+            }
+
+            // touch whatever is currently serving this cell
+            const serving = this.#page_table.read_entry(record.region, mip, page_x, page_y);
+
+            if (serving !== VT_ENTRY_INVALID) {
+                const entry = vt_entry_unpack(serving);
+
+                this.#cache.touch(entry.phys_y * this.#cache.slots_per_axis + entry.phys_x, frame);
+            }
+
+            const pending = this.#pending.get(w - 1);
+
+            if (pending !== undefined) {
+                pending.last_touch = frame;
+                continue;
+            }
+
+            this.#enqueue_key(record, mip, page_x, page_y, false);
+
+            // request missing ancestors, nearest first; stop at the first
+            // level that is already resident or pending
+            for (let m = mip + 1; m < record.mip_count; m++) {
+                const ax = page_x >> (m - mip);
+                const ay = page_y >> (m - mip);
+
+                if (record.resident.has(local_key(m, ax, ay))) {
+                    break;
+                }
+
+                const a_key = vt_request_key_pack(record.id, m, ax, ay);
+
+                const a_pending = this.#pending.get(a_key);
+
+                if (a_pending !== undefined) {
+                    a_pending.last_touch = frame;
+                    break;
+                }
+
+                this.#enqueue_key(record, m, ax, ay, false);
+            }
+        }
+    }
+
+    /**
+     * Evict one page to make room. Prefers least-recently-touched outside
+     * the protection window, finest mip on ties (shrink the resident
+     * quadtree from the leaves); under absolute pressure ignores the window.
+     *
+     * @returns {number} freed slot, or -1 when everything is locked
+     */
+    #evict_one() {
+        let slot = this.#cache.find_eviction_candidate(this.#frame, this.#config.eviction_protect_window);
+
+        if (slot === -1) {
+            slot = this.#cache.find_eviction_candidate(this.#frame, 0);
+        }
+
+        if (slot === -1) {
+            return -1;
+        }
+
+        const stack_id = this.#slot_stack[slot];
+
+        assert.greaterThanOrEqual(stack_id, 0, 'evicting a slot with no owner');
+
+        const record = this.#stacks[stack_id];
+
+        const mip = this.#slot_mip[slot];
+        const x = this.#slot_x[slot];
+        const y = this.#slot_y[slot];
+
+        this.#page_table.page_evicted(record.region, mip, x, y);
+
+        record.resident.delete(local_key(mip, x, y));
+
+        this.#cache.free(slot);
+        this.#slot_stack[slot] = -1;
+
+        this.stats.evictions_last_frame++;
+
+        return slot;
+    }
+
+    /**
+     * @param {{pending: VTPendingLoad, payloads: Array}} arrival
+     * @returns {boolean} applied
+     */
+    #apply_arrival(arrival) {
+        const pending = arrival.pending;
+
+        const record = this.#stacks[pending.stack_id];
+
+        if (record === undefined || record.stack.id !== pending.stack_id) {
+            vt_close_payloads(arrival.payloads);
+            return false;
+        }
+
+        if (record.resident.has(local_key(pending.mip, pending.x, pending.y))) {
+            // duplicate delivery — possible after unregister/register churn
+            vt_close_payloads(arrival.payloads);
+            return false;
+        }
+
+        let slot = this.#cache.allocate(this.#frame, pending.lock, pending.mip);
+
+        if (slot === -1) {
+            const freed = this.#evict_one();
+
+            if (freed === -1) {
+                if (pending.lock) {
+                    // a pinned root must not be lost to transient pressure —
+                    // dropping it here would leave the stack permanently
+                    // without its guaranteed fallback (feedback re-requests
+                    // are unlocked). Hold the arrival and retry next frame.
+                    return 'retry';
+                }
+
+                vt_close_payloads(arrival.payloads);
+                return false;
+            }
+
+            slot = this.#cache.allocate(this.#frame, pending.lock, pending.mip);
+
+            assert.notEqual(slot, -1, 'allocation failed after eviction');
+        }
+
+        const queue = this.#device.queue;
+
+        const layer_count = this.#config.layers.length;
+
+        for (let layer = 0; layer < layer_count; layer++) {
+            if ((record.layer_mask & (1 << layer)) === 0) {
+                continue;
+            }
+
+            const payload = arrival.payloads[layer];
+
+            assert.defined(payload, `source omitted layer ${layer} it declared in layer_mask`);
+
+            this.#cache.upload(queue, slot, layer, payload);
+        }
+
+        // uploads are queue-captured at submission — the bitmaps can go now
+        vt_close_payloads(arrival.payloads);
+
+        this.#slot_stack[slot] = record.id;
+        this.#slot_mip[slot] = pending.mip;
+        this.#slot_x[slot] = pending.x;
+        this.#slot_y[slot] = pending.y;
+
+        record.resident.set(local_key(pending.mip, pending.x, pending.y), slot);
+
+        const coords = this.#cache.slot_coords(slot);
+
+        this.#page_table.page_loaded(
+            record.region,
+            pending.mip, pending.x, pending.y,
+            vt_entry_pack(coords.x, coords.y, pending.mip)
+        );
+
+        return true;
+    }
+
+    /**
+     * @param {VTPendingLoad} pending
+     */
+    #issue_load(pending) {
+        const record = this.#stacks[pending.stack_id];
+
+        pending.issued = true;
+        pending.controller = new AbortController();
+
+        this.#loads_in_flight++;
+
+        // Promise.resolve().then(...) shields against sources whose
+        // load_page throws synchronously or returns a non-promise —
+        // either would otherwise unwind update() mid-frame
+        Promise.resolve()
+            .then(() => record.stack.source.load_page(pending.mip, pending.x, pending.y, pending.controller.signal))
+            .then(payloads => {
+                if (this.#pending.get(pending.key) === pending) {
+                    this.#arrived.push({ pending, payloads });
+                    this.#pending.delete(pending.key);
+                    this.#load_failures.delete(pending.key);
+                } else {
+                    // superseded (stack unregistered, or the key was
+                    // re-enqueued by a later registration) — discard
+                    vt_close_payloads(payloads);
+                }
+            })
+            .catch(e => {
+                // identity-guarded: after unregister/register churn the same
+                // key may belong to a NEW pending load — a stale rejection
+                // must not delete it
+                if (this.#pending.get(pending.key) === pending) {
+                    this.#pending.delete(pending.key);
+                }
+
+                if (e?.name !== 'AbortError') {
+                    const failure = this.#load_failures.get(pending.key) ?? { failures: 0, retry_after_frame: 0 };
+
+                    failure.failures++;
+                    // 30, 60, 120 … 1800 frames (~0.5 s to ~30 s at 60 fps)
+                    failure.retry_after_frame = this.#frame + Math.min(1800, 30 << Math.min(failure.failures - 1, 6));
+
+                    this.#load_failures.set(pending.key, failure);
+
+                    console.error(`vt: page load failed (stack=${pending.stack_id} mip=${pending.mip} ${pending.x},${pending.y})`, e);
+                }
+            })
+            .finally(() => {
+                this.#loads_in_flight--;
+            });
+    }
+
+    /**
+     * Push accumulated page-table dirty rects and stack-info rows to the
+     * GPU. Runs inside update(), and again from graph_feedback() so a stack
+     * registered mid-frame (materials build during scene update, after
+     * begin_frame) is sampled correctly on its very first frame instead of
+     * one frame late. Idempotent — dirty sets drain.
+     */
+    flush_gpu_state() {
+        if (!this.#initialized) {
+            return;
+        }
+
+        const queue = this.#device.queue;
+
+        this.#page_table.flush(queue);
+
+        if (this.#stack_info_dirty.size > 0) {
+            for (const id of this.#stack_info_dirty) {
+                const offset = id * VT_STACK_INFO_STRUCT.size;
+
+                queue.writeBuffer(
+                    this.#stack_info_buffer, offset,
+                    this.#stack_info_staging, offset, VT_STACK_INFO_STRUCT.size
+                );
+            }
+
+            this.#stack_info_dirty.clear();
+        }
+    }
+
+    /**
+     * Per-frame maintenance. Call once per frame, before building the
+     * shading graph, so the material pass samples this frame's page table.
+     */
+    update() {
+        if (!this.#initialized) {
+            return;
+        }
+
+        this.#frame++;
+
+        const config = this.#config;
+
+        this.stats.uploads_last_frame = 0;
+        this.stats.evictions_last_frame = 0;
+
+        // 1. budgeted uploads of arrived pages, oldest first; locked roots
+        //    that couldn't find a slot are held for a later frame
+        let budget = config.max_uploads_per_frame;
+
+        const retries = [];
+
+        while (budget > 0 && this.#arrived.length > 0) {
+            const arrival = this.#arrived.shift();
+
+            const result = this.#apply_arrival(arrival);
+
+            if (result === true) {
+                this.stats.uploads_last_frame++;
+                budget--;
+            } else if (result === 'retry') {
+                retries.push(arrival);
+            }
+        }
+
+        if (retries.length > 0) {
+            this.#arrived.push(...retries);
+        }
+
+        // 2+3. page table dirty rects, stack info dirty rows — flushed even
+        //      with zero stacks registered, so the teardown writes of the
+        //      LAST unregister still reach the GPU
+        this.flush_gpu_state();
+
+        if (this.#stack_count === 0) {
+            this.stats.stacks = 0;
+            this.stats.resident_pages = this.#cache.used;
+            this.stats.pending_loads = this.#pending.size;
+            this.stats.queued_loads = this.#queue.length;
+
+            return;
+        }
+
+        // 4. drop queued requests that stopped being touched
+        if (this.#queue.length > 0) {
+            const stale_before = this.#frame - config.queue_stale_window;
+
+            this.#queue = this.#queue.filter(key => {
+                const pending = this.#pending.get(key);
+
+                if (pending === undefined || pending.issued) {
+                    return false;
+                }
+
+                if (!pending.lock && pending.last_touch < stale_before) {
+                    this.#pending.delete(key);
+                    return false;
+                }
+
+                return true;
+            });
+        }
+
+        // 5. issue loads, coarse mips first (they unblock the most screen area)
+        if (this.#queue.length > 0 && this.#loads_in_flight < config.max_concurrent_loads) {
+            this.#queue.sort((a, b) => {
+                const pa = this.#pending.get(a);
+                const pb = this.#pending.get(b);
+
+                return pb.mip - pa.mip;
+            });
+
+            while (this.#loads_in_flight < config.max_concurrent_loads && this.#queue.length > 0) {
+                const key = this.#queue.shift();
+
+                const pending = this.#pending.get(key);
+
+                if (pending === undefined) {
+                    continue;
+                }
+
+                this.#issue_load(pending);
+            }
+        }
+
+        // 6. residency pressure → feedback mip bias (degrade to blur, not thrash)
+        const load = this.#cache.used / this.#cache.capacity;
+
+        if (load > config.pressure_high_watermark) {
+            this.#residency_bias = Math.min(this.#residency_bias + 0.5, 4);
+        } else if (load < config.pressure_low_watermark && this.#residency_bias > 0) {
+            this.#residency_bias = Math.max(this.#residency_bias - 0.25, 0);
+        }
+
+        const stats = this.stats;
+
+        stats.stacks = this.#stack_count;
+        stats.resident_pages = this.#cache.used;
+        stats.pending_loads = this.#pending.size;
+        stats.queued_loads = this.#queue.length;
+        stats.residency_bias = this.#residency_bias;
+    }
+
+    // ── FrameGraph wiring ───────────────────────────────────────────
+
+    /**
+     * Add the feedback passes to the frame's graph: clear + populate the
+     * request hash set from the visibility buffer, then read it back
+     * asynchronously. Skips itself when idle or when the readback ring is
+     * saturated (slow map resolution must throttle GPU work, not queue it).
+     *
+     * @param {Object} args
+     * @param {FrameGraph} args.graph
+     * @param {GPUViewContext} args.view
+     * @param {number} args.texture_viz_mesh graph handle
+     * @param {number} args.texture_viz_triangle graph handle
+     * @param {GPUBuffer} args.material_metadata_buffer
+     */
+    graph_feedback({
+                       graph,
+                       view,
+                       texture_viz_mesh,
+                       texture_viz_triangle,
+                       material_metadata_buffer,
+                   }) {
+
+        if (!this.#initialized || this.#stack_count === 0) {
+            return;
+        }
+
+        // stacks registered after this frame's update() (materials build
+        // during scene update) publish their rows now — before the material
+        // pass samples them
+        this.flush_gpu_state();
+
+        if (this.#readbacks_in_flight >= 3) {
+            return;
+        }
+
+        const config = this.#config;
+        const scene_ctx = view.scene;
+
+        const stride = config.feedback_stride;
+
+        const jitter_index = this.#frame % (stride * stride);
+        const jitter = [jitter_index % stride, (jitter_index / stride) | 0];
+
+        const resolution = view.resolution;
+
+        const group_count_x = Math.ceil(Math.ceil(resolution[0] / stride) / VT_FEEDBACK_WORKGROUP_SIZE);
+        const group_count_y = Math.ceil(Math.ceil(resolution[1] / stride) / VT_FEEDBACK_WORKGROUP_SIZE);
+
+        const shader = this.#shader_feedback;
+        const mip_bias = this.#residency_bias;
+        const stack_info_buffer = this.#stack_info_buffer;
+
+        const pass_data = {};
+
+        const pass = graph.add("VT Feedback", pass_data, (data, resources, context) => {
+            const requests = resources.get(data.requests);
+
+            // transient pool buffers carry stale contents — the hash set
+            // relies on zero meaning empty
+            context.encoder.clearBuffer(requests);
+
+            shader.dispatch({
+                encoder: context.encoder,
+                group_count_x,
+                group_count_y,
+                group_count_z: 1,
+                bindings: {
+                    viz_buffer_triangle: resources.get(data.viz_triangle).obtainView(),
+                    viz_buffer_mesh: resources.get(data.viz_mesh).obtainView(),
+                    view: view.uniform_buffer.buffer,
+                    vt_params: context.encoder.allocateTransientValueBuffer(
+                        VT_FEEDBACK_PARAMS_STRUCT,
+                        { stride, jitter, mip_bias }
+                    ),
+                    scene_database: scene_ctx.scene_database_buffer,
+                    meshlet_metadata: scene_ctx.geometries.meshlets.buffer_metadata,
+                    meshlet_data: scene_ctx.geometries.meshlets.buffer_data,
+                    material_metadata: material_metadata_buffer,
+                    vt_stacks: stack_info_buffer,
+                    vt_requests: requests,
+                }
+            });
+        });
+
+        pass_data.viz_mesh = pass.read(texture_viz_mesh);
+        pass_data.viz_triangle = pass.read(texture_viz_triangle);
+
+        pass_data.requests = pass.create("vt_requests", BufferResourceDescriptor.from(
+            config.hash_capacity * 4,
+            GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST,
+        ));
+
+        this.#readbacks_in_flight++;
+
+        graph_read_buffer({ graph, buffer: pass_data.requests })
+            .then(ref => {
+                try {
+                    this.process_feedback(new Uint32Array(ref.getValue()));
+                } finally {
+                    ref.release();
+                }
+            })
+            .catch(e => {
+                console.error('vt: feedback readback failed', e);
+            })
+            .finally(() => {
+                this.#readbacks_in_flight--;
+            });
+    }
+
+    destroy() {
+        if (!this.#initialized) {
+            return;
+        }
+
+        for (const pending of this.#pending.values()) {
+            if (pending.controller !== null) {
+                pending.controller.abort();
+            }
+        }
+
+        this.#pending.clear();
+        this.#queue.length = 0;
+
+        for (const arrival of this.#arrived) {
+            vt_close_payloads(arrival.payloads);
+        }
+
+        this.#arrived.length = 0;
+        this.#load_failures.clear();
+
+        for (const record of this.#stacks) {
+            if (record !== undefined && typeof record.stack.source.destroy === 'function') {
+                record.stack.source.destroy();
+            }
+        }
+
+        this.#page_table.destroy();
+        this.#cache.destroy();
+        this.#stack_info_buffer.destroy();
+    }
+}