@driftengine/texture 4.0.0

package/dist/overlay/sparse.d.ts

@@ -0,0 +1,68 @@
+/** How many channels a texel carries. One bit each in the written mask, so this cannot exceed 8. */
+export declare const OVERLAY_CHANNELS = 4;
+export declare const ADDRESS_CLAMP = 0;
+export declare const ADDRESS_WRAP = 1;
+export interface OverlayTile {
+    readonly tx: number;
+    readonly ty: number;
+    /** `tileSize * tileSize * OVERLAY_CHANNELS` values. */
+    readonly texels: Float32Array;
+    /** One byte a texel; bit `c` is set where channel `c` has been written. */
+    readonly written: Uint8Array;
+    /** Content hash, recomputed lazily after a write. Empty means stale. */
+    hash: string;
+}
+export interface OverlayOptions {
+    /** Tiles across the unit square. With `tileSize`, this fixes the texel density. */
+    readonly tilesAcross?: number;
+    /** `ADDRESS_CLAMP` or `ADDRESS_WRAP`. Take it from the base texture's `DecodeGraph`. */
+    readonly addressMode?: number;
+}
+export interface Overlay {
+    /** Texels along a tile edge. */
+    readonly tileSize: number;
+    /** Tiles along the unit square's edge. */
+    readonly tilesAcross: number;
+    /** Texels along the whole unit square's edge: `tileSize * tilesAcross`. */
+    readonly resolution: number;
+    readonly addressMode: number;
+    /** Written tiles only, keyed `"tx,ty"`. An untouched tile does not exist. */
+    readonly tiles: Map<string, OverlayTile>;
+}
+export declare function createOverlay(tileSize: number, options?: OverlayOptions): Overlay;
+/**
+ * Write `value` into one channel of every texel within `radius` of `(u, v)`.
+ *
+ * A disc rather than a square, because a square decal is a square nobody asked for, and the radius
+ * is in UV so a caller reasons in surface fractions rather than in whatever resolution this is.
+ */
+export declare function writeOverlay(overlay: Overlay, u: number, v: number, radius: number, channel: number, value: number): number;
+/**
+ * Read every channel at a coordinate into `out`. False where nothing has been written there.
+ *
+ * False is the ordinary answer and the important one: it is what tells a sampler to use the base
+ * unchanged rather than compositing a zero over it.
+ */
+export declare function sampleOverlay(overlay: Overlay, u: number, v: number, out: Float32Array): boolean;
+/** Which channels have been written at a coordinate, as a bit per channel. Zero for none. */
+export declare function writtenMaskAt(overlay: Overlay, u: number, v: number): number;
+/**
+ * The distinct content hashes of the written tiles, into `out`. Returns how many.
+ *
+ * **Distinct, because an identical mark in two places is one thing to store.** The same blast
+ * scorch on twenty crates is twenty tiles in memory — each is written in place and they diverge the
+ * moment anything else touches one — and one page to upload, which is where the cost actually is.
+ * Hashed exactly as a base tile is, by `hashTile`, so the two live in one address space.
+ */
+export declare function overlayTiles(overlay: Overlay, out: string[]): number;
+/** How many tiles hold a written texel. What a memory readout shows. */
+export declare function overlayTileCount(overlay: Overlay): number;
+/**
+ * Put the overlay over the base, channel by channel, into `out`.
+ *
+ * **`written` is a parameter because the plan's signature had no way to say which texels and
+ * channels were touched**, and without it compositing either overwrites everything — so one scorch
+ * mark erases the base across the whole tile — or guesses from a sentinel value, which is a value
+ * somebody eventually writes on purpose.
+ */
+export declare function compositeOverlay(out: Float32Array, base: Float32Array, overlay: Float32Array, written: Uint8Array): void;

package/dist/overlay/sparse.js

@@ -0,0 +1,212 @@
+/**
+ * A texture that can be written to at runtime, without allocating a layer for what nobody touched.
+ *
+ * **Sparse, so that a scorch mark on one wall does not allocate a layer for the building.** Only
+ * written tiles exist; an unwritten coordinate reports nothing written and the base is used
+ * unchanged. That is the difference between a decal system a game can leave on for a whole level
+ * and one somebody turns off because of the memory.
+ *
+ * **Written is tracked per texel *and* per channel.** A scorch darkens the albedo and leaves the
+ * normal alone, so compositing has to know which channels a texel had written rather than treating
+ * a written texel as wholly overwritten. One byte a texel, one bit a channel — which caps the
+ * channel count at eight and is stated where the array is declared rather than discovered.
+ *
+ * **Two numbers are needed to turn a UV into a texel, and the plan gave one.** `tileSize` is texels
+ * per tile edge and says nothing about how much of the surface a tile covers; `tilesAcross` is what
+ * closes it. Without both, a radius in UV has no length in texels and every write is either the
+ * whole surface or a single texel depending on which guess was made.
+ *
+ * **The address mode is the base texture's**, not this file's opinion. `DecodeGraph` carries one —
+ * 0 clamps outside the unit square and 1 wraps — and an overlay that disagreed would put a mark on
+ * the far side of a wall from where somebody aimed, on exactly the textures that wrap.
+ */
+import { hashTile } from '../tileHash.js';
+/** How many channels a texel carries. One bit each in the written mask, so this cannot exceed 8. */
+export const OVERLAY_CHANNELS = 4;
+export const ADDRESS_CLAMP = 0;
+export const ADDRESS_WRAP = 1;
+export function createOverlay(tileSize, options = {}) {
+    const size = Math.max(1, Math.floor(tileSize));
+    const across = Math.max(1, Math.floor(options.tilesAcross ?? 16));
+    return {
+        tileSize: size,
+        tilesAcross: across,
+        resolution: size * across,
+        addressMode: options.addressMode === ADDRESS_WRAP ? ADDRESS_WRAP : ADDRESS_CLAMP,
+        tiles: new Map(),
+    };
+}
+function key(tx, ty) {
+    return `${String(tx)},${String(ty)}`;
+}
+function tileAt(overlay, tx, ty, make) {
+    const at = key(tx, ty);
+    const held = overlay.tiles.get(at);
+    if (held !== undefined)
+        return held;
+    if (!make)
+        return null;
+    const texels = overlay.tileSize * overlay.tileSize;
+    const tile = {
+        tx,
+        ty,
+        texels: new Float32Array(texels * OVERLAY_CHANNELS),
+        written: new Uint8Array(texels),
+        hash: '',
+    };
+    overlay.tiles.set(at, tile);
+    return tile;
+}
+/**
+ * A texel coordinate brought inside the surface, or `-1` where it is outside and the mode clamps.
+ *
+ * `-1` rather than a clamped edge texel under `ADDRESS_CLAMP`: clamping a *write* would smear the
+ * whole edge of the texture with whatever somebody aimed past it, which is a visible band rather
+ * than the nothing they expected. Clamping a *read* is right, and `sampleOverlay` does that.
+ */
+function wrapTexel(overlay, texel, forWrite) {
+    const size = overlay.resolution;
+    if (overlay.addressMode === ADDRESS_WRAP)
+        return ((texel % size) + size) % size;
+    if (texel >= 0 && texel < size)
+        return texel;
+    return forWrite ? -1 : Math.min(size - 1, Math.max(0, texel));
+}
+/**
+ * Write `value` into one channel of every texel within `radius` of `(u, v)`.
+ *
+ * A disc rather than a square, because a square decal is a square nobody asked for, and the radius
+ * is in UV so a caller reasons in surface fractions rather than in whatever resolution this is.
+ */
+export function writeOverlay(overlay, u, v, radius, channel, value) {
+    if (channel < 0 || channel >= OVERLAY_CHANNELS)
+        return 0;
+    const size = overlay.resolution;
+    const centreX = u * size;
+    const centreY = v * size;
+    const reach = Math.max(0, radius) * size;
+    const from = Math.floor(centreX - reach);
+    const to = Math.ceil(centreX + reach);
+    const top = Math.floor(centreY - reach);
+    const bottom = Math.ceil(centreY + reach);
+    let touched = 0;
+    for (let y = top; y <= bottom; y += 1) {
+        for (let x = from; x <= to; x += 1) {
+            /* Texel centres, so a radius of half a texel marks one texel rather than none or four. */
+            const dx = x + 0.5 - centreX;
+            const dy = y + 0.5 - centreY;
+            if (dx * dx + dy * dy > reach * reach)
+                continue;
+            const wx = wrapTexel(overlay, x, true);
+            const wy = wrapTexel(overlay, y, true);
+            if (wx < 0 || wy < 0)
+                continue;
+            /*
+             * The tile is found from the *wrapped* texel, which is what makes a write near a boundary
+             * land in both tiles: the loop runs over one continuous span and each texel finds its own
+             * tile. A version that found one tile and wrote into it leaves a hard edge at every seam —
+             * the defect that looks like the decal was clipped and is usually blamed on the mesh.
+             */
+            const tile = tileAt(overlay, Math.floor(wx / overlay.tileSize), Math.floor(wy / overlay.tileSize), true);
+            const local = (wy % overlay.tileSize) * overlay.tileSize + (wx % overlay.tileSize);
+            tile.texels[local * OVERLAY_CHANNELS + channel] = value;
+            tile.written[local] = tile.written[local] | (1 << channel);
+            tile.hash = '';
+            touched += 1;
+        }
+    }
+    return touched;
+}
+/**
+ * Read every channel at a coordinate into `out`. False where nothing has been written there.
+ *
+ * False is the ordinary answer and the important one: it is what tells a sampler to use the base
+ * unchanged rather than compositing a zero over it.
+ */
+export function sampleOverlay(overlay, u, v, out) {
+    const size = overlay.resolution;
+    const x = wrapTexel(overlay, Math.floor(u * size), false);
+    const y = wrapTexel(overlay, Math.floor(v * size), false);
+    const tile = tileAt(overlay, Math.floor(x / overlay.tileSize), Math.floor(y / overlay.tileSize), false);
+    if (tile === null)
+        return false;
+    const local = (y % overlay.tileSize) * overlay.tileSize + (x % overlay.tileSize);
+    if ((tile.written[local] ?? 0) === 0)
+        return false;
+    for (let c = 0; c < OVERLAY_CHANNELS; c += 1) {
+        out[c] = tile.texels[local * OVERLAY_CHANNELS + c];
+    }
+    return true;
+}
+/** Which channels have been written at a coordinate, as a bit per channel. Zero for none. */
+export function writtenMaskAt(overlay, u, v) {
+    const size = overlay.resolution;
+    const x = wrapTexel(overlay, Math.floor(u * size), false);
+    const y = wrapTexel(overlay, Math.floor(v * size), false);
+    const tile = tileAt(overlay, Math.floor(x / overlay.tileSize), Math.floor(y / overlay.tileSize), false);
+    if (tile === null)
+        return 0;
+    return tile.written[(y % overlay.tileSize) * overlay.tileSize + (x % overlay.tileSize)] ?? 0;
+}
+/**
+ * A tile's content hash, computed once per write rather than once per call.
+ *
+ * **A cost guard, not a correctness one**, and it does not change an answer — a perturbation
+ * removing it fails no test and is expected to. It stays because `overlayTiles` is called every
+ * frame to decide uploads, and hashing is bytes: four hundred written tiles of 64×64×4 floats took
+ * **79 ms uncached and 0.061 ms cached**, measured 2026-09-15. The first of those is a frame
+ * budget spent several times over to learn that nothing changed.
+ */
+function hashOf(overlay, tile) {
+    if (tile.hash !== '')
+        return tile.hash;
+    /* The written mask is hashed with the values: two tiles holding the same numbers where one of
+       them wrote a zero and the other did not are different tiles, and compositing proves it. */
+    const bytes = new Uint8Array(tile.texels.buffer.byteLength + tile.written.byteLength);
+    bytes.set(new Uint8Array(tile.texels.buffer), 0);
+    bytes.set(tile.written, tile.texels.buffer.byteLength);
+    tile.hash = hashTile(bytes);
+    return tile.hash;
+}
+/**
+ * The distinct content hashes of the written tiles, into `out`. Returns how many.
+ *
+ * **Distinct, because an identical mark in two places is one thing to store.** The same blast
+ * scorch on twenty crates is twenty tiles in memory — each is written in place and they diverge the
+ * moment anything else touches one — and one page to upload, which is where the cost actually is.
+ * Hashed exactly as a base tile is, by `hashTile`, so the two live in one address space.
+ */
+export function overlayTiles(overlay, out) {
+    out.length = 0;
+    const seen = new Set();
+    for (const tile of overlay.tiles.values()) {
+        const hash = hashOf(overlay, tile);
+        if (seen.has(hash))
+            continue;
+        seen.add(hash);
+        out.push(hash);
+    }
+    out.sort();
+    return out.length;
+}
+/** How many tiles hold a written texel. What a memory readout shows. */
+export function overlayTileCount(overlay) {
+    return overlay.tiles.size;
+}
+/**
+ * Put the overlay over the base, channel by channel, into `out`.
+ *
+ * **`written` is a parameter because the plan's signature had no way to say which texels and
+ * channels were touched**, and without it compositing either overwrites everything — so one scorch
+ * mark erases the base across the whole tile — or guesses from a sentinel value, which is a value
+ * somebody eventually writes on purpose.
+ */
+export function compositeOverlay(out, base, overlay, written) {
+    for (let texel = 0; texel < written.length; texel += 1) {
+        const mask = written[texel];
+        for (let c = 0; c < OVERLAY_CHANNELS; c += 1) {
+            const at = texel * OVERLAY_CHANNELS + c;
+            out[at] = (mask & (1 << c)) === 0 ? base[at] : overlay[at];
+        }
+    }
+}

package/dist/progressive.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The order tiles are sent in, so a material is usable long before it is complete.
+ *
+ * **There is precedent in this repository and this follows it.** `drft/coarseFirst.ts` opens a
+ * splat capture in a fourteenth of its bytes through a Morton quantisation and a bit-reversal
+ * walk, and the principle is the same: a prefix of the stream should be spread over the whole
+ * image rather than filling one corner of it.
+ *
+ * **Bit-reversal is what spreads it.** Counting 0, 1, 2, 3 fills left to right; counting with the
+ * index's bits reversed visits 0, 4, 2, 6, 1, 5, 3, 7 — every prefix roughly uniform over the
+ * range, so an interrupted download is a coarse version of the whole material rather than a sharp
+ * version of part of it.
+ */
+/**
+ * Fill `out` with the order to send `tileCount` tiles in. Returns how many were written.
+ *
+ * A permutation: every tile appears exactly once, which the test asserts because an ordering that
+ * drops one is a material that never completes and never says why.
+ */
+export declare function progressiveOrder(tileCount: number, out: Uint32Array): number;
+/**
+ * What level this many received bytes supports.
+ *
+ * Levels rise monotonically with bytes, which is what lets a loader show something immediately and
+ * refine without ever going backwards.
+ */
+export declare function usableAt(bytesReceived: number, tileBytes: number, tileCount: number): {
+    level: number;
+    complete: boolean;
+};

package/dist/progressive.js

@@ -0,0 +1,56 @@
+/**
+ * The order tiles are sent in, so a material is usable long before it is complete.
+ *
+ * **There is precedent in this repository and this follows it.** `drft/coarseFirst.ts` opens a
+ * splat capture in a fourteenth of its bytes through a Morton quantisation and a bit-reversal
+ * walk, and the principle is the same: a prefix of the stream should be spread over the whole
+ * image rather than filling one corner of it.
+ *
+ * **Bit-reversal is what spreads it.** Counting 0, 1, 2, 3 fills left to right; counting with the
+ * index's bits reversed visits 0, 4, 2, 6, 1, 5, 3, 7 — every prefix roughly uniform over the
+ * range, so an interrupted download is a coarse version of the whole material rather than a sharp
+ * version of part of it.
+ */
+function reverseBits(value, bits) {
+    let out = 0;
+    for (let i = 0; i < bits; i += 1)
+        out = (out << 1) | ((value >>> i) & 1);
+    return out >>> 0;
+}
+/**
+ * Fill `out` with the order to send `tileCount` tiles in. Returns how many were written.
+ *
+ * A permutation: every tile appears exactly once, which the test asserts because an ordering that
+ * drops one is a material that never completes and never says why.
+ */
+export function progressiveOrder(tileCount, out) {
+    if (tileCount <= 0)
+        return 0;
+    const bits = Math.max(1, Math.ceil(Math.log2(tileCount)));
+    const span = 1 << bits;
+    let written = 0;
+    for (let i = 0; i < span; i += 1) {
+        const tile = reverseBits(i, bits);
+        /* The reversal walks a power-of-two range; anything past the real count is skipped. */
+        if (tile < tileCount) {
+            out[written] = tile;
+            written += 1;
+        }
+    }
+    return written;
+}
+/**
+ * What level this many received bytes supports.
+ *
+ * Levels rise monotonically with bytes, which is what lets a loader show something immediately and
+ * refine without ever going backwards.
+ */
+export function usableAt(bytesReceived, tileBytes, tileCount) {
+    if (tileBytes <= 0 || tileCount <= 0)
+        return { level: 0, complete: true };
+    const tiles = Math.min(tileCount, Math.floor(bytesReceived / tileBytes));
+    const complete = tiles >= tileCount;
+    /* Each doubling of received tiles is one more level of detail. */
+    const level = tiles <= 0 ? 0 : Math.floor(Math.log2(tiles)) + 1;
+    return { level, complete };
+}

package/dist/residency/pageCache.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Decoded pages, and the switch that decides when the decoding happens.
+ *
+ * **This carries a mode because the spec's §9 names the risk rather than hoping about it.** If
+ * per-sample neural decode turns out too slow in the general case, the fallback is to decode once
+ * when a tile becomes resident and sample it as an ordinary texture thereafter — which loses
+ * procedural and per-sample parameterisation for the affected materials and keeps the compression,
+ * the joint channels and the streaming. Building the switch now costs a field and a branch.
+ * Retrofitting it into a pipeline that assumes per-sample decode everywhere costs a great deal,
+ * and would be attempted on the day somebody discovered the frame time, which is the worst day.
+ *
+ * **A page acquired this frame is never evicted.** The same rule `table.ts` exists to enforce, one
+ * level down and for the same reason: reclaiming a page the current frame is sampling produces a
+ * frame drawn against bytes somebody else is writing, which is a corruption rather than a stall
+ * and does not look like a streaming problem at all. A cache with nothing else to give refuses —
+ * `acquirePage` returns `-1` — because a wrong page is worse than no page.
+ *
+ * **What was evicted is reported, and the plan's signature had nowhere to say it.** A residency
+ * table that still calls a tile resident after its page has been reused points at a slot another
+ * tile now owns. The eviction has to reach the table, so it is drained rather than dropped.
+ */
+/** Where the decode happens. See the header for which risk the second one is the answer to. */
+export type DecodeMode = 'per-sample' | 'on-residency';
+/** How a page's bytes are produced. Supplied by the caller: a cache cannot know a format. */
+export type PageDecode = (hash: string, into: Uint8Array) => void;
+export interface PageCacheOptions {
+    readonly mode?: DecodeMode;
+    /**
+     * What fills a page in `on-residency` mode.
+     *
+     * Optional, because a cache in `per-sample` mode never decodes and a test of the eviction policy
+     * has nothing to decode. Absent in `on-residency` mode, a page is acquired undecoded and
+     * `pageDecoded` says so rather than the cache pretending.
+     */
+    readonly decode?: PageDecode;
+}
+export interface PageCache {
+    readonly pages: number;
+    readonly pageBytes: number;
+    /** Every page, back to back. Slot `n` is `[n * pageBytes, (n + 1) * pageBytes)`. */
+    readonly bytes: Uint8Array;
+    /** Which hash holds each slot, or `''` where it is free. */
+    readonly holder: string[];
+    /** Whether each slot's bytes have been decoded into. */
+    readonly decoded: boolean[];
+    slotOf: Map<string, number>;
+    /** Monotonic, standing in for time, so eviction needs no clock. As `table.ts` does. */
+    touchedAt: Map<string, number>;
+    clock: number;
+    /** The clock at the start of the frame. Nothing touched after it may be evicted. */
+    frameStart: number;
+    mode: DecodeMode;
+    decode: PageDecode | null;
+    /** Hashes whose pages have been taken since the caller last drained this. */
+    evicted: string[];
+}
+export declare function createPageCache(pages: number, pageBytes: number, options?: PageCacheOptions): PageCache;
+/**
+ * Say a new frame has begun, so everything acquired from here is protected from eviction.
+ *
+ * A caller that never calls this gets a cache that protects everything and fills up, which is a
+ * visible stall rather than a silent corruption — the right way round for a mistake to fail.
+ */
+export declare function beginCacheFrame(cache: PageCache): void;
+/**
+ * The slot holding this tile's page, acquiring one if it is not held. `-1` where none can be given.
+ *
+ * Acquiring a hash that is already here returns the same slot and takes no page from anybody: the
+ * commonest call by far, and the one that must not evict.
+ */
+export declare function acquirePage(cache: PageCache, hash: string): number;
+/** Give a page back. Its slot is free for the next acquisition, and its bytes are not kept. */
+export declare function releasePage(cache: PageCache, hash: string): void;
+export declare function pageSlot(cache: PageCache, hash: string): number;
+export declare function pageDecoded(cache: PageCache, hash: string): boolean;
+/**
+ * Decode a held page if the mode says the cache owns that, and it has not been done.
+ *
+ * Returns whether the page's bytes are now the decoded ones. `false` in `per-sample` mode is the
+ * ordinary answer rather than a failure: the bytes are the compressed page and whoever samples
+ * decodes them.
+ */
+export declare function ensurePageDecoded(cache: PageCache, hash: string): boolean;
+export declare function decodeMode(cache: PageCache): DecodeMode;
+/**
+ * Change where the decode happens, invalidating every page that was decoded under the old rule.
+ *
+ * **Invalidating rather than converting.** A page decoded per-sample and one decoded on residency
+ * hold different bytes, so keeping them and changing the flag serves a sampler the wrong ones —
+ * silently, and only for the pages that happened to be resident when somebody flipped the switch.
+ * The pages stay held; what is lost is the claim that their contents are current.
+ */
+export declare function setDecodeMode(cache: PageCache, mode: DecodeMode): void;
+/** How many pages are held. What a profiler panel shows beside the resident tile count. */
+export declare function occupiedPages(cache: PageCache): number;
+/**
+ * Drain the hashes whose pages have been taken, into `out`. Returns how many.
+ *
+ * A caller that never drains this leaks a string per eviction, which is why it is a drain rather
+ * than a log: the list is a message to the residency table, and a message nobody reads is a bug in
+ * the caller that should grow rather than hide.
+ */
+export declare function takeEvicted(cache: PageCache, out: string[]): number;

package/dist/residency/pageCache.js

@@ -0,0 +1,184 @@
+/**
+ * Decoded pages, and the switch that decides when the decoding happens.
+ *
+ * **This carries a mode because the spec's §9 names the risk rather than hoping about it.** If
+ * per-sample neural decode turns out too slow in the general case, the fallback is to decode once
+ * when a tile becomes resident and sample it as an ordinary texture thereafter — which loses
+ * procedural and per-sample parameterisation for the affected materials and keeps the compression,
+ * the joint channels and the streaming. Building the switch now costs a field and a branch.
+ * Retrofitting it into a pipeline that assumes per-sample decode everywhere costs a great deal,
+ * and would be attempted on the day somebody discovered the frame time, which is the worst day.
+ *
+ * **A page acquired this frame is never evicted.** The same rule `table.ts` exists to enforce, one
+ * level down and for the same reason: reclaiming a page the current frame is sampling produces a
+ * frame drawn against bytes somebody else is writing, which is a corruption rather than a stall
+ * and does not look like a streaming problem at all. A cache with nothing else to give refuses —
+ * `acquirePage` returns `-1` — because a wrong page is worse than no page.
+ *
+ * **What was evicted is reported, and the plan's signature had nowhere to say it.** A residency
+ * table that still calls a tile resident after its page has been reused points at a slot another
+ * tile now owns. The eviction has to reach the table, so it is drained rather than dropped.
+ */
+export function createPageCache(pages, pageBytes, options = {}) {
+    const count = Math.max(1, Math.floor(pages));
+    const size = Math.max(1, Math.floor(pageBytes));
+    return {
+        pages: count,
+        pageBytes: size,
+        bytes: new Uint8Array(count * size),
+        holder: new Array(count).fill(''),
+        decoded: new Array(count).fill(false),
+        slotOf: new Map(),
+        touchedAt: new Map(),
+        clock: 0,
+        frameStart: 0,
+        mode: options.mode ?? 'per-sample',
+        decode: options.decode ?? null,
+        evicted: [],
+    };
+}
+/**
+ * Say a new frame has begun, so everything acquired from here is protected from eviction.
+ *
+ * A caller that never calls this gets a cache that protects everything and fills up, which is a
+ * visible stall rather than a silent corruption — the right way round for a mistake to fail.
+ */
+export function beginCacheFrame(cache) {
+    cache.frameStart = cache.clock;
+}
+function touch(cache, hash) {
+    cache.clock += 1;
+    cache.touchedAt.set(hash, cache.clock);
+}
+/**
+ * The slot holding this tile's page, acquiring one if it is not held. `-1` where none can be given.
+ *
+ * Acquiring a hash that is already here returns the same slot and takes no page from anybody: the
+ * commonest call by far, and the one that must not evict.
+ */
+export function acquirePage(cache, hash) {
+    const held = cache.slotOf.get(hash);
+    if (held !== undefined) {
+        touch(cache, hash);
+        return held;
+    }
+    let slot = cache.holder.indexOf('');
+    if (slot < 0) {
+        const victim = evictable(cache);
+        if (victim === null)
+            return -1;
+        slot = cache.slotOf.get(victim);
+        release(cache, victim, slot);
+        cache.evicted.push(victim);
+    }
+    cache.holder[slot] = hash;
+    cache.slotOf.set(hash, slot);
+    /* No `decoded[slot] = false` here: `release` owns that, and every slot reaching this point came
+       either from `release` or from never having been used. A second reset changed nothing, which a
+       perturbation showed by failing no test. */
+    cache.bytes.fill(0, slot * cache.pageBytes, (slot + 1) * cache.pageBytes);
+    touch(cache, hash);
+    /* The whole of the mode switch: in one, the bytes are produced now; in the other, at sample
+       time by whoever samples, and this cache holds the compressed page unchanged. */
+    if (cache.mode === 'on-residency')
+        ensurePageDecoded(cache, hash);
+    return slot;
+}
+/** The least recently used page that this frame has not touched, or null. */
+function evictable(cache) {
+    let worst = null;
+    let at = Infinity;
+    for (const hash of cache.slotOf.keys()) {
+        const when = cache.touchedAt.get(hash) ?? 0;
+        if (when > cache.frameStart)
+            continue;
+        if (when >= at)
+            continue;
+        at = when;
+        worst = hash;
+    }
+    return worst;
+}
+/**
+ * Take a page back, leaving the slot free and claimed by nobody.
+ *
+ * **`touchedAt` is deleted as well**, which is not tidiness: without it the map grows by one entry
+ * per tile the cache has ever seen, so a three-page cache that streamed a level holds three pages
+ * and thousands of timestamps. There is a test that counts them.
+ */
+function release(cache, hash, slot) {
+    cache.holder[slot] = '';
+    cache.decoded[slot] = false;
+    cache.slotOf.delete(hash);
+    cache.touchedAt.delete(hash);
+}
+/** Give a page back. Its slot is free for the next acquisition, and its bytes are not kept. */
+export function releasePage(cache, hash) {
+    const slot = cache.slotOf.get(hash);
+    if (slot === undefined)
+        return;
+    release(cache, hash, slot);
+}
+export function pageSlot(cache, hash) {
+    return cache.slotOf.get(hash) ?? -1;
+}
+export function pageDecoded(cache, hash) {
+    const slot = cache.slotOf.get(hash);
+    return slot === undefined ? false : (cache.decoded[slot] ?? false);
+}
+/**
+ * Decode a held page if the mode says the cache owns that, and it has not been done.
+ *
+ * Returns whether the page's bytes are now the decoded ones. `false` in `per-sample` mode is the
+ * ordinary answer rather than a failure: the bytes are the compressed page and whoever samples
+ * decodes them.
+ */
+export function ensurePageDecoded(cache, hash) {
+    if (cache.mode !== 'on-residency')
+        return false;
+    const slot = cache.slotOf.get(hash);
+    if (slot === undefined)
+        return false;
+    if (cache.decoded[slot] === true)
+        return true;
+    if (cache.decode === null)
+        return false;
+    cache.decode(hash, cache.bytes.subarray(slot * cache.pageBytes, (slot + 1) * cache.pageBytes));
+    cache.decoded[slot] = true;
+    return true;
+}
+export function decodeMode(cache) {
+    return cache.mode;
+}
+/**
+ * Change where the decode happens, invalidating every page that was decoded under the old rule.
+ *
+ * **Invalidating rather than converting.** A page decoded per-sample and one decoded on residency
+ * hold different bytes, so keeping them and changing the flag serves a sampler the wrong ones —
+ * silently, and only for the pages that happened to be resident when somebody flipped the switch.
+ * The pages stay held; what is lost is the claim that their contents are current.
+ */
+export function setDecodeMode(cache, mode) {
+    if (mode === cache.mode)
+        return;
+    cache.mode = mode;
+    cache.decoded.fill(false);
+}
+/** How many pages are held. What a profiler panel shows beside the resident tile count. */
+export function occupiedPages(cache) {
+    return cache.slotOf.size;
+}
+/**
+ * Drain the hashes whose pages have been taken, into `out`. Returns how many.
+ *
+ * A caller that never drains this leaks a string per eviction, which is why it is a drain rather
+ * than a log: the list is a message to the residency table, and a message nobody reads is a bug in
+ * the caller that should grow rather than hide.
+ */
+export function takeEvicted(cache, out) {
+    out.length = 0;
+    for (const hash of cache.evicted)
+        out.push(hash);
+    cache.evicted.length = 0;
+    return out.length;
+}