narraleaf-react 0.43.1 → 0.45.0

package/dist/game/nlcore/common/player.d.ts

@@ -5,4 +5,5 @@ import { useRouter } from "../../player/lib/PageRouter/router";
 import { usePathname, useParams, useQueryParams } from "../../player/lib/PageRouter/routerHooks";
 export * from "../../player/type";
 export * from "../../player/libElements";
+export type { ImageCacheManager, ImageCacheStats } from "../../player/lib/ImageCacheManager";
 export { GameProviders, Player, useGame, useRouter, usePathname, useParams, useQueryParams, };

package/dist/game/nlcore/elements/sound.d.ts

@@ -45,9 +45,18 @@ export interface ISoundUserConfig {
      */
     rate: number;
     /**
-     * Set to `true` to force HTML5 Audio.
-     * This should be used for large audio files
-     * so that you don't have to wait for the full file to be downloaded and decoded before playing.
+     * Set to `true` to force this clip to be streamed through an HTML5 `<audio>` element instead of
+     * decoded into memory. Use it for large audio files: playback starts as soon as the first bytes
+     * arrive rather than after the whole file has been downloaded and decoded, and no decoded PCM
+     * buffer is held for as long as it plays.
+     *
+     * Leaving it `false` does not forbid streaming — it leaves the choice to the engine, which
+     * streams whole-file loops (background music, by construction) and decodes everything else. See
+     * {@link import("../gameTypes").GameConfig.audioStreaming} for that rule and how to turn it
+     * off.
+     *
+     * A streamed clip has no loop *region*: with `loop` it repeats the whole file, so
+     * {@link ISoundUserConfig.endTime} and {@link ISoundUserConfig.loopStart} are ignored for one.
      * @default false
      */
     streaming: boolean;

package/dist/game/nlcore/gameTypes.d.ts

@@ -217,6 +217,49 @@ export type GameConfig = {
      * @default 10
      */
     maxPreloadActions: number;
+    /**
+     * How many bytes of fetched image data the preload cache may hold at once.
+     *
+     * Every image the cache fetches stays in memory as a blob until the cache lets it go, and a
+     * scene's registered set plus a hop of look-ahead is most of a chapter's artwork. Past this
+     * budget the least recently used images that nothing on stage is showing are released; a
+     * released image is fetched again the next time a scene wants it.
+     *
+     * The current scene's opening background and every image a mounted `<img>` is showing are
+     * never released whatever the budget says, so a budget too small for the frame on screen
+     * degrades to fetching on demand, never to a broken frame. `Infinity` removes the limit.
+     *
+     * The default is meant to hold a whole scene's registered set on a large project without
+     * releasing anything it is about to want again - a chapter's worth of artwork measured at
+     * around 200 MB of files - while capping a session that visits fifty scenes at that rather
+     * than at the size of the library. Raise it for a game whose scenes are heavier than that.
+     *
+     * @default 256 * 1024 * 1024
+     */
+    imageCacheBudgetBytes: number;
+    /**
+     * How many bytes of decoded bitmaps the preload cache may keep decoded, at width × height × 4
+     * bytes each.
+     *
+     * A decoded bitmap is what lets an image paint the frame it is revealed on without an
+     * asynchronous decode first, and it is the expensive half of an image: a 1080p background
+     * decodes to about 8 MB whatever its file size, a 2000-pixel sprite to about 10 MB. The cache
+     * keeps the current scene's registered images decoded up to this budget, least recently used
+     * first to go past it; an image it let go of is decoded again on demand, which costs tens of
+     * milliseconds for a 1080p JPEG and is paid before the transition that reveals it starts.
+     *
+     * The current scene's opening background and every image on stage are exempt. `Infinity`
+     * removes the limit; `0` keeps nothing decoded beyond those.
+     *
+     * The default is fifteen 1080p backgrounds or a dozen large sprites - several times what a
+     * scene has on screen at once, which is a background and two or three characters - so the
+     * frame being revealed and the ones about to follow it stay warm while a chapter's worth of
+     * alternative poses does not. This is the pool that grew without limit before there was a
+     * budget, because a bitmap's size has nothing to do with how well its file compressed.
+     *
+     * @default 128 * 1024 * 1024
+     */
+    decodedImageBudgetBytes: number;
     /**
      * The audio bus tree, declared by the host at boot.
      *
@@ -257,6 +300,30 @@ export type GameConfig = {
      * ```
      */
     audioBuses: AudioBusDeclaration[];
+    /**
+     * Which clips are streamed through an `<audio>` element instead of being decoded into memory.
+     *
+     * Decoded audio is float32 PCM, so its size has nothing to do with the size of the file it came
+     * from: a five-minute 44.1 kHz stereo track occupies about 106 MB decoded however small the mp3
+     * was. Background music is the worst case of that — long, and resident for as long as the scene
+     * lasts — while a short effect wants to be decoded so that it can start on the frame it is
+     * asked to and overlap with itself.
+     *
+     * - `"loops"` — a clip is streamed when {@link import("./elements/sound").ISoundUserConfig.streaming} says so, **or** when
+     *   it loops the whole file (`loop` with no `endTime`). A whole-file loop is background music
+     *   by construction, and repeating a whole file is the one thing an `<audio>` element does
+     *   exactly. A loop that marks an out point is asking for a sample-accurate loop *region*,
+     *   which only a decoded buffer has, so it keeps decoding.
+     * - `"declared"` — only clips whose `streaming` is set are streamed; everything else is decoded.
+     *   Choose this when a game would rather spend the memory than let its music loop through an
+     *   element: `<audio>` repeats the file rather than the samples, and on some browsers and
+     *   formats the loop point is audible.
+     *
+     * A `data:` or `blob:` source is already in memory and is always decoded, whichever this says.
+     *
+     * @default "loops"
+     */
+    audioStreaming: "loops" | "declared";
     /**
      * Src of the cursor image, if null, the game will show the default cursor
      * @default null
@@ -433,22 +500,6 @@ export type GameConfig = {
      * @default false
      */
     disableTextScaling: boolean;
-    /**
-     * How long a newly typed character takes to fade in, in milliseconds. `0` turns it off.
-     *
-     * Dialogue text is normally typed at full strength, one character appearing after another. With
-     * a duration here, each character arrives faded and comes up over that time while the typewriter
-     * carries on, so the few newest characters of a line are always part-way in and the line has a
-     * soft edge rather than a hard one.
-     *
-     * The fade never outlasts the gap between two characters by more than a little: a player who
-     * raises the typing speed gets a shorter fade, and one who raises it a long way gets none worth
-     * seeing, which is what asking for fast text means. It applies only to text actually being typed
-     * - a line revealed at once, skipped, or drawn again from a save is not faded in - and a player
-     * whose system asks for reduced motion never sees it.
-     * @default 0
-     */
-    textRevealDuration: number;
     /**
      * Override the default stage
      * @default null
@@ -495,6 +546,23 @@ export interface NotificationToken extends LiveGameEventToken {
     promise: Promise<void>;
 }
 export type GamePreference = {
+    /**
+     * How long a newly typed character takes to fade in, in milliseconds. `0` turns it off.
+     *
+     * Dialogue text is normally typed at full strength, one character appearing after another.
+     * With a duration here each character arrives faded and comes up over that time while the
+     * typewriter carries on, so the few newest characters of a line are always part-way in and
+     * the line has a soft edge rather than a hard one.
+     *
+     * The player's, like the typing speed it is read against: someone who finds the softness
+     * distracting turns it down, and a settings screen can offer it beside `cps`. The fade never
+     * outlasts the gap between two characters by more than a little, so raising the typing speed
+     * shortens it and raising it a long way leaves none worth seeing. It applies only to text
+     * actually being typed - a line revealed at once, skipped, or drawn again from a save is not
+     * faded in - and a player whose system asks for reduced motion never sees it.
+     * @default 0
+     */
+    textRevealDuration: number;
     /**
      * If true, the game will automatically forward to the next sentence when the player has finished the current sentence
      * @default false

package/dist/game/player/gameState.d.ts

@@ -25,6 +25,7 @@ import { Video, VideoStateRaw } from "../nlcore/elements/video";
 import { Vfx, VfxStateRaw } from "../nlcore/elements/vfx";
 import { Timelines } from "./Tasks";
 import { Notification, NotificationManager } from "./lib/notification";
+import type { ImageCacheManager } from "./lib/ImageCacheManager";
 import { ActionHistoryManager } from "../../game/nlcore/action/actionHistory";
 import { GameHistoryManager } from "../../game/nlcore/action/gameHistory";
 import type { Character } from "../nlcore/elements/character";
@@ -233,6 +234,15 @@ export declare class GameState {
     removeElement(element: PlayerStateElement): this;
     preloadScene(arg: Scene | Story): this;
     getPreloadingScene(): Scene | null;
+    /**
+     * The image cache the mounted player is using, or `null` while no player is mounted.
+     *
+     * What it holds against {@link GameConfig.imageCacheBudgetBytes} and
+     * {@link GameConfig.decodedImageBudgetBytes} is readable at any time, which is what a profiler
+     * or a host checking a long session's memory wants:
+     * `game.getLiveGame().getGameState()?.getImageCache()?.getStats()`.
+     */
+    getImageCache(): ImageCacheManager | null;
     addElement(element: PlayerStateElement): this;
     addScene(scene: Scene): this;
     flush(): this;

package/dist/game/player/lib/AudioManager.d.ts

@@ -1,5 +1,5 @@
 import { Sound as SoundElement, SoundBusId } from "../../nlcore/elements/sound";
-import { SoundToken } from "@narraleaf/sound";
+import { CacheStats, SoundToken } from "@narraleaf/sound";
 import { FadeOptions, SoundPlayOptions } from "../../nlcore/elements/type";
 import { Awaitable } from "../../../util/data";
 import { GameState } from "../gameState";
@@ -57,11 +57,28 @@ export declare class AudioManager {
      * not have.
      */
     private static readonly BusRampSettle;
+    /**
+     * How long the backend keeps a decoded clip that nothing holds any more, in milliseconds.
+     *
+     * Zero would be the tidiest answer, but a clip nothing references is exactly the shape of a
+     * short effect fired repeatedly - an interface click, a footstep - and re-fetching and
+     * re-decoding one per keystroke is worse than holding it. A few seconds is long enough to
+     * cover a burst and short enough that nothing accumulates: what is still resident after this
+     * is only what is playing or what {@link AudioManager.preload} is holding for the scene.
+     */
+    private static readonly CacheGrace;
     private state;
     private channels;
     private busTree;
     private busSubscription;
     private unknownBuses;
+    /**
+     * Sources this manager holds a cache reference on - the current scene's, plus anything a host
+     * preloaded by hand. One reference per distinct source, given back by
+     * {@link AudioManager.retainOnly} when the scene that wanted it is left. The value resolves to
+     * whether the reference was really taken, which a release has to wait for.
+     */
+    private retained;
     private globalVolume;
     private sound;
     private ready;
@@ -192,43 +209,40 @@ export declare class AudioManager {
      */
     private static clipRegionOf;
     /**
-     * The region as the sound backend's play options.
+     * Everything the backend needs to start a clip, apart from the volume the caller is fading to.
      *
-     * A looping clip deliberately hands over **no** `endTime`. The backend turns `endTime` into a
-     * timer that stops the token after one pass, whether or not the clip loops, so passing it here
-     * is what kept the loop region from ever repeating. The region reaches a looping clip through
-     * {@link AudioManager.applyLoopRegion} instead; for a one-shot `endTime` *is* the out point and
-     * the backend's timer is exactly the right mechanism.
+     * The region goes over as it stands: an out point is an out point for a one-shot and the point
+     * a looping clip repeats *from* when `loop` is set, and `loopStart` moves that repeat's in
+     * point without moving where the first pass begins. A streamed clip has no region to speak of
+     * (see {@link AudioManager.loadModeOf}) and the backend ignores both keys for one.
      */
-    private static playRegionOf;
+    private playOptionsOf;
     /**
-     * Write a looping clip's region onto the Web Audio node the backend is playing it through.
-     *
-     * **This is a shim against `@narraleaf/sound@0.1.0`'s internals, and the only place in this
-     * repo that reaches into them.** Two things in that version make the region unusable from the
-     * outside:
-     *
-     * - `SoundToken`'s constructor arms `setTimeout(stop, duration * 1000)` whenever a duration was
-     *   given, without consulting `loop` — so a looping clip with an out point hard-stops after its
-     *   first pass through the region.
-     * - `Sound.createToken` pins `loopStart` to the playback start offset, so "play the intro from
-     *   0s, then repeat 12s→90s forever" cannot be expressed at all.
-     *
-     * The fix belongs upstream and is small: honour `loop` before arming the duration timer, and
-     * accept an independent `loopStart` in `PlayOptions`. Until that ships, this manager withholds
-     * `endTime` from a looping clip's play options (which is what disarms the timer) and sets the
-     * loop region here.
-     *
-     * `SoundToken.sourceController` is TypeScript-`private` while `AudioSourceController.getSource`
-     * is public, so the node is reachable at runtime but not through the types — hence the cast and
-     * the shape check. If a later backend changes that shape this returns silently and the clip
-     * degrades to the behaviour it has today: the region plays once and the clip stops.
-     *
-     * Seeking survives this. `SoundToken.seek` rebuilds the buffer source and copies `loop`,
-     * `loopStart` and `loopEnd` off the old node onto the new one, so a jump inside a looping track
-     * keeps the region.
+     * Whether a clip is decoded into memory or streamed through an `<audio>` element.
+     *
+     * Decoding is what a short clip wants: it can start on the frame it is asked to, several copies
+     * can overlap, and its loop region is sample-accurate. What it costs is memory, and the cost has
+     * nothing to do with the size of the file - decoded audio is float32 PCM, so a five-minute
+     * 44.1 kHz stereo track is about 106 MB however small the mp3 was. Background music is the worst
+     * case of exactly that: long, and playing for as long as the scene lasts.
+     *
+     * So a clip is streamed when it is background music by construction:
+     *
+     * - the author set `streaming` on it, which has always meant "force this one to stream";
+     * - or it loops the **whole file**. A whole-file loop is a track meant to play under a scene
+     *   rather than to punctuate it, and repeating a whole file is the one thing an element does
+     *   exactly. A loop with an out point is asking for a region instead, which only a decoded
+     *   buffer has, so it keeps decoding.
+     *
+     * `data:` and `blob:` sources are already in memory and are always decoded; there is nothing to
+     * stream and an element would only add latency.
+     *
+     * {@link import("../../nlcore/gameTypes").GameConfig.audioStreaming} set to `"declared"` drops the
+     * second rule, for a game that would rather spend the memory than let its music loop through an
+     * element - `<audio>` repeats the file rather than the samples, so a loop point can be heard on
+     * some browsers and formats.
      */
-    private static applyLoopRegion;
+    private loadModeOf;
     private static clampToRegion;
     setRate(sound: SoundElement, rate: number): Awaitable<void>;
     getPosition(sound: SoundElement): number;
@@ -242,6 +256,16 @@ export declare class AudioManager {
      * Fetch and decode a sound into the audio cache without playing it, so the first `play()` of
      * this source starts on the same frame it is asked to instead of after a fetch and a decode.
      *
+     * **Holds the clip decoded until it is released.** A decoded clip is dropped as soon as nothing
+     * plays it, which is what keeps a session's audio from growing without bound; a preload is the
+     * one thing that says "keep this one anyway". The reference is given back by
+     * {@link AudioManager.retainOnly} - what the player preloads is the scene's set, and a scene
+     * change replaces it - or by {@link AudioManager.reset}.
+     *
+     * A clip that streams rather than decodes ({@link AudioManager.loadModeOf}) has nothing to warm:
+     * an element fetches as it plays, so there is no decoded buffer to have ready and this resolves
+     * having done nothing.
+     *
      * Deliberately **not** something to gate a loading screen on: the audio context only becomes
      * ready once the browser's autoplay policy is satisfied by a user gesture, so this can sit
      * pending indefinitely on a page nobody has interacted with yet. Start it and let it land —
@@ -250,6 +274,33 @@ export declare class AudioManager {
      * as it did before.
      */
     preload(sound: SoundElement): Promise<void>;
+    /**
+     * Preload `sounds` and give back every cache reference this manager holds that is not among
+     * them - the audio counterpart of the image cache being filtered down to the scene that is
+     * about to paint.
+     *
+     * Called with a scene's own sounds when that scene opens. Clips shared with the previous scene
+     * keep their reference rather than being released and re-decoded, so the common case of a
+     * carried-over effect costs nothing.
+     *
+     * Releasing a reference does not stop anything: a clip that is still playing is held by its
+     * token until it ends, and only then does the buffer go.
+     */
+    retainOnly(sounds: SoundElement[]): void;
+    /**
+     * What the audio cache is holding: decoded clips, clips in flight, and the bytes of PCM the
+     * decoded ones occupy. Zeroes before the audio context has unlocked.
+     *
+     * Here so that a game can see its own audio residency - the number that used to grow for the
+     * length of a session and now tracks what is playing plus what the current scene declared.
+     */
+    getCacheStats(): CacheStats;
+    /**
+     * Give back the cache reference held on one source, if there is one, once it has actually been
+     * taken - a release that overtook its own load would find nothing to release and leave the
+     * reference behind for good.
+     */
+    private releaseSource;
     /**
      * Start a new game: stop everything and put the mixer back on the wire.
      *

package/dist/game/player/lib/ImageCacheManager.d.ts

@@ -1,13 +1,62 @@
-import { Game } from "../../../game/nlcore/game";
-import { GameState } from "../gameState";
+import type { Game } from "../../../game/nlcore/game";
+import type { GameState } from "../gameState";
 export type PreloadedToken = {
     abort: () => void;
     onFinished: (callback: () => void) => PreloadedToken;
     onErrored: (callback: (reason: any) => void) => PreloadedToken;
 };
+/**
+ * What the image cache is holding, against what it is allowed to hold. All sizes are bytes.
+ *
+ * Read through {@link GameState.getImageCache}:
+ * `game.getLiveGame().getGameState()?.getImageCache()?.getStats()`.
+ */
+export type ImageCacheStats = {
+    /** Sources the cache holds a url for. */
+    entries: number;
+    /** Bytes of fetched image data kept alive by the object urls the cache minted. */
+    blobBytes: number;
+    /** Sources whose decoded bitmap the cache is holding on to. */
+    decodedEntries: number;
+    /** Estimated size of those bitmaps, at width × height × 4 bytes each. */
+    decodedBytes: number;
+    /** Entries that cannot be evicted right now: shown by a mounted `<img>`, or pinned by the scene. */
+    pinned: number;
+    /** The budgets in force: {@link GameConfig.imageCacheBudgetBytes} and {@link GameConfig.decodedImageBudgetBytes}. */
+    budget: {
+        blobBytes: number;
+        decodedBytes: number;
+    };
+};
+/**
+ * The player's image cache: fetched bytes as object urls, and decoded bitmaps for the images about
+ * to be revealed, both under a memory budget.
+ *
+ * The cache used to be unbounded, and what it held was decided by the preload pass after the one
+ * that filled it: a scene's registered images - every pose of every character it shows, every
+ * background it cuts to - stayed fetched and decoded until the *next* scene's look-ahead pool had
+ * finished, and stayed for ever if that pass was superseded before it got there. A long session on
+ * a large library grew without limit and ended in a renderer out of memory. Now:
+ *
+ * - Both pools have a budget, read live from the game config. Past it, the least recently used
+ *   entries that nothing pins go first: a bitmap is dropped and decoded again on demand, a fetched
+ *   image is released and fetched again when a scene wants it. Recency is the {@link entries} map's
+ *   order, refreshed by every {@link get}.
+ * - Two things pin an entry against both budgets. A scene pins its opening background through
+ *   {@link pin}; and every mounted `<img>` holds the url it is showing through {@link hold}, so the
+ *   frame on screen - both halves of a transition in flight, a caller parked behind a scene call -
+ *   is never taken out from under the DOM.
+ * - What a scene keeps is decided when its pass starts, through {@link retain}: everything outside
+ *   the plan is stale, dropped at once if nothing shows it and the moment its last `<img>` unmounts
+ *   otherwise. That is what releases a left scene at scene exit rather than a pass later.
+ */
 export declare class ImageCacheManager {
     private readonly game;
-    static getImage(src: string, abortSignal?: AbortSignal, options?: RequestInit): Promise<string>;
+    /** Fetch `src` and hand back a url for its bytes, and how many there are. Mocked by tests. */
+    static getImage(src: string, abortSignal?: AbortSignal, options?: RequestInit): Promise<{
+        url: string;
+        bytes: number;
+    }>;
     /**
      * Decode an image source off-screen so the browser's decoded-image cache is warm before
      * the source is ever attached to a visible `<img>`. Without this, "preloaded" only means
@@ -20,29 +69,49 @@ export declare class ImageCacheManager {
      * `Image` or no `decode()`.
      */
     private static decodeImage;
-    private src;
-    private preloadTasks;
     /**
-     * Decoded images held on purpose. A decoded bitmap only stays in the browser's cache while
-     * something still references it, so dropping the element right after `decode()` lets the
-     * bitmap be evicted and the reveal decodes all over again. Retention is opt-in per preload
-     * (`retainDecoded`) because a full-resolution bitmap costs width × height × 4 bytes — worth
-     * it for the scene that is about to paint, far too expensive for a whole reachable graph.
+     * What a retained bitmap costs. The browser keeps a decoded image as 32-bit pixels at its
+     * natural size whatever the file's format or size was, so this is the number that matters.
      */
-    private decoded;
+    private static estimateDecodedBytes;
+    /** A budget as configured; anything that is not a number reads as no limit. */
+    private static readBudget;
+    /**
+     * Every cached source, least recently used first. A touch deletes and re-inserts its entry,
+     * so eviction walks the map from the front.
+     */
+    private entries;
+    /** The same entries by the url an `<img>` shows, which is the only name an `<img>` knows. */
+    private byUrl;
+    private preloadTasks;
+    /** Urls some mounted `<img>` is showing, with how many are showing each. */
+    private holds;
+    /** Sources the scene pinned - its opening background - replaced as a whole by {@link pin}. */
+    private pinned;
+    /** Every source that has been through the cache, kept for {@link wasCached}. */
+    private seen;
+    private blobBytes;
+    private decodedBytes;
     constructor(game: Game);
+    has(name: string): boolean;
     /**
-     * Release the object URL an entry holds.
+     * Whether this source has ever been through the cache, whether or not it still is.
      *
-     * Every path that drops an entry goes through this. An object URL pins its blob for the
-     * lifetime of the document, so a cache that forgets an entry without revoking leaks the whole
-     * image - which on a scene change is most of a scene's artwork.
+     * For diagnostics that want to tell "the preloader never heard of this image" - which means an
+     * image action nothing could predict, and is worth telling the author about - from "the cache
+     * had it and a budget released it again", which is the cache working as designed and is not.
+     */
+    wasCached(name: string): boolean;
+    /**
+     * Cache `src` under `name` without fetching it. The bytes behind a url given this way are not
+     * the cache's to count, so it weighs nothing against the fetched budget.
      */
-    private release;
-    private releaseAll;
-    has(name: string): boolean;
     add(name: string, src: string): this;
     remove(name: string): this;
+    /**
+     * The url to show for `name`, or `undefined` when it is not cached. This is the cache's notion
+     * of a use: the entry becomes the most recently used one.
+     */
     get(name: string): string | undefined;
     /**
      * Whether this source has been decoded and its decoded bitmap is still held, i.e. attaching
@@ -56,9 +125,16 @@ export declare class ImageCacheManager {
      * Fetch `url`, cache it as an object URL and decode it, resolving the returned token's
      * `onFinished` only once the decode has settled.
      *
-     * @param options.retainDecoded keep the decoded bitmap alive until this source leaves the
-     * cache. Use it for the assets that are about to be revealed; leave it off for speculative
-     * look-ahead preloading, whose bitmaps would otherwise pile up in memory.
+     * Asking again is safe and converges. A url that is cached and, if asked, decoded settles at
+     * once. One that is cached but whose bitmap the budget let go of - or that was fetched as
+     * look-ahead, which never retains - is decoded again and held when `retainDecoded` asks for it,
+     * so a first frame the budget evicted still gates on a decode rather than on nothing. One that
+     * another pass is still fetching follows that fetch instead of getting a token that never fires.
+     *
+     * @param options.retainDecoded keep the decoded bitmap alive, within
+     * {@link GameConfig.decodedImageBudgetBytes}, until this source leaves the cache. Use it for the
+     * assets that are about to be revealed; leave it off for speculative look-ahead preloading,
+     * whose bitmaps would otherwise pile up in memory.
      */
     preload(gameState: GameState, url: string, options?: {
         retainDecoded?: boolean;
@@ -66,5 +142,66 @@ export declare class ImageCacheManager {
     abortAll(): void;
     abort(src: string): void;
     preloadedSrc(): string[];
-    filter(names: string[]): this;
+    /**
+     * Keep `names` and let everything else go.
+     *
+     * Called when a scene's preload pass starts, with everything the pass is about to want. An entry
+     * outside the set is dropped at once unless something pins it; a pinned one is marked stale and
+     * dropped the moment it is not - which for the scene that was just left is the moment its last
+     * `<img>` unmounts. An entry that is back in the set is not stale any more.
+     */
+    retain(names: Iterable<string>): this;
+    /**
+     * Exempt `names` from both budgets, replacing whatever was pinned before.
+     *
+     * For the current scene's opening background: fetched and decoded before the scene is allowed
+     * to paint, and the one image a budget must never take back. Whatever a mounted `<img>` shows is
+     * pinned separately, through {@link hold}, so this only needs to name what is about to be shown.
+     */
+    pin(names: Iterable<string>): this;
+    /**
+     * Report that a mounted `<img>` is showing `url`; the entry behind it cannot be evicted until
+     * every such `<img>` has called {@link release}. By url rather than by source name, because the
+     * url is all an `<img>` knows - and a url the cache never minted is remembered and ignored.
+     */
+    hold(url: string): void;
+    /** Undo one {@link hold}. The last release drops a stale entry, and lets the budgets run again. */
+    release(url: string): void;
+    getStats(): ImageCacheStats;
+    private budget;
+    private isPinned;
+    private touch;
+    private insert;
+    /**
+     * Drop an entry entirely, handing back its object url.
+     *
+     * Every path that drops an entry goes through this. An object URL pins its blob for the
+     * lifetime of the document, so a cache that forgets an entry without revoking leaks the whole
+     * image - which on a scene change is most of a scene's artwork.
+     */
+    private drop;
+    /** Let the bitmap go and keep the bytes; the browser decodes them again when they are next shown. */
+    private dropDecoded;
+    private retainDecoded;
+    /**
+     * Bring both pools back under budget, least recently used first, skipping what is pinned.
+     *
+     * Fetched bytes first: dropping an entry takes its bitmap with it, and may settle the decoded
+     * pool on its own. An entry that is over a budget all by itself goes too, unless it is pinned -
+     * the budget is a limit, not a preference, and what is on stage is protected by the pins.
+     */
+    private enforce;
+    private fetchAndDecode;
+    /** A cached entry's bitmap, wanted again after the budget let it go or a look-ahead skipped it. */
+    private decodeAgain;
+    private runTask;
+    /**
+     * A token for a url another caller is already fetching. It finishes when that fetch has landed
+     * *and* this caller's own request is met: the running task may be a look-ahead that retains no
+     * bitmap, so asking again once it is done settles the difference - unless it failed, in which
+     * case asking again would only fetch a broken url once per follower.
+     */
+    private followTask;
+    /** A token for a request that is already met; it finishes on the next microtask, like the others. */
+    private static settledToken;
 }

package/dist/game/player/lib/useHoldImageSrc.d.ts

@@ -0,0 +1,19 @@
+import { RefObject } from "react";
+/**
+ * Tell the image cache which url this `<img>` is showing, for as long as it shows it.
+ *
+ * The cache evicts by budget and drops a left scene's images as soon as nothing needs them, and
+ * "nothing needs them" has exactly one witness: whether some mounted `<img>` still has the url as
+ * its `src`. So the leaf reports it. The attribute is watched rather than a prop, because a
+ * non-layered image's `src` is written imperatively, frame by frame, by its transition and never
+ * passes through React - and because both halves of a transition in flight are `<img>`s, which is
+ * what keeps the outgoing picture from being taken back mid-fade.
+ *
+ * Layout effects rather than passive ones: the first hold has to land in the same task as the
+ * commit that wrote the `src`, before any fetch that finishes in between gets to run the budget.
+ * The attaching one runs after every commit rather than only the first, because the element may
+ * not exist yet on the pass this hook is first called on - a dialogue avatar renders nothing until
+ * there is a speaker with one - and because React may replace the node underneath the ref. It does
+ * nothing at all once it is already watching the right element.
+ */
+export declare function useHoldImageSrc(ref: RefObject<HTMLImageElement | null>): void;