narraleaf-react 0.45.1 → 0.47.0

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

@@ -6,4 +6,5 @@ export * from "./types";
 export * from "./position";
 export * from "./transition";
 export * from "./interface";
+export type { PreloadAcquisition, PreloadBand, PreloadEntry, PreloadMoment, PreloadPlan, PreloadResource, PreloadResourceType, PreloadStrategy, } from "../preload/types";
 export { i, c, b };

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

@@ -6,4 +6,5 @@ import { usePathname, useParams, useQueryParams } from "../../player/lib/PageRou
 export * from "../../player/type";
 export * from "../../player/libElements";
 export type { ImageCacheManager, ImageCacheStats } from "../../player/lib/ImageCacheManager";
+export { createDefaultPreloadStrategy } from "../../player/elements/preload/defaultStrategy";
 export { GameProviders, Player, useGame, useRouter, usePathname, useParams, useQueryParams, };

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

@@ -11,6 +11,7 @@ import type { GameElementHistory } from "./action/gameHistory";
 import { MenuComponent, NotificationComponent, NvlDialogComponent, SayComponent } from "./common/player";
 import { LiveGameEventToken } from "./types";
 import type { AudioBusDeclaration } from "./game/audioBus";
+import type { PreloadStrategy } from "./preload/types";
 /**
  * Current save format version.
  *
@@ -168,10 +169,30 @@ export type GameConfig = {
      * @default 50
      */
     ratioUpdateInterval: number;
+    /**
+     * Who decides what the player warms, when, and where the bytes come from.
+     *
+     * Unset, the player uses its built-in strategy, which is the behaviour it has always had: walk
+     * the action tree of the scene about to paint and of the scenes reachable from it, split the
+     * result into a first frame, the scene's registered set and a look-ahead, and fetch each one
+     * into an object url with an off-screen decode. Every `preload*` field below steers that
+     * strategy and nothing else.
+     *
+     * Set it and the player stops guessing. It asks this object what should be warm at each moment
+     * in the story and does exactly that, and if the object also supplies
+     * {@link PreloadStrategy.acquire} it stops fetching too - which is what lets a host whose assets
+     * are already on local disk hand back the url it was given and keep no second copy in memory.
+     * The cache, its budgets and the pins are still the player's; the plan is not.
+     *
+     * See {@link PreloadStrategy}.
+     */
+    preload?: PreloadStrategy;
     /**
      * The game will preload the image with this delay between each preload task
      *
-     * A single preload task may contain {@link GameConfig.preloadConcurrency} images
+     * A single preload task may contain {@link GameConfig.preloadConcurrency} images.
+     * Read by the built-in strategy's speculative band only; a game with its own
+     * {@link GameConfig.preload} paces that band with the same field.
      * @default 100
      */
     preloadDelay: number;

package/dist/game/nlcore/preload/types.d.ts

@@ -0,0 +1,213 @@
+import type { Scene } from "../elements/scene";
+import type { Sound } from "../elements/sound";
+import type { Story } from "../elements/story";
+import type { Video } from "../elements/video";
+/**
+ * The preload seam: what the player warms, when it warms it, and where the bytes come from.
+ *
+ * ## Why this is a seam and not a policy
+ *
+ * The player used to answer three questions on its own. *What will be needed* it guessed, by
+ * walking the action tree of the scene about to paint and of every scene reachable from it. *When*
+ * followed from that walk: one pass per scene, split into a first frame, the scene's whole
+ * registered set, and a look-ahead. *How* was fixed: fetch the bytes, mint an object url, decode
+ * the image off-screen, hold the bitmap under a budget.
+ *
+ * All three answers are wrong for a host that knows more than the walk can see. A tool that
+ * compiled the story knows exactly which row shows which asset, in which order, and how big each
+ * one is; the walk only knows what a scene mentions anywhere in it, which on a real project is
+ * most of the library - so the pass fetched and decoded a chapter's artwork in order to paint one
+ * background. A host serving assets off local disk has no use for the object url either: the file
+ * is already there, and copying it into a blob costs that memory a second time.
+ *
+ * So the player now asks instead of deciding. A {@link PreloadStrategy} answers *what* and *when*
+ * as a {@link PreloadPlan}, and may answer *how* as well through
+ * {@link PreloadStrategy.acquire}. Everything the player still owns - the cache, its budgets, what
+ * a mounted element pins, and the url an element is finally pointed at - is unchanged, which is
+ * what lets a strategy replace the plan without replacing the player.
+ *
+ * A game that supplies no strategy gets the built-in one, which reproduces the walk and the tiers
+ * exactly as they were, driven by the same `preload*` fields of `GameConfig`.
+ */
+/**
+ * What kind of thing a preload resource names.
+ *
+ * Only images are named this way in a plan's {@link PreloadPlan.entries}: they are the resources
+ * the player fetches, caches and decodes, so a url is the whole of what it needs to know. Audio and
+ * video are named by element instead ({@link PreloadPlan.audio}, {@link PreloadPlan.video}),
+ * because what warming them means is a property of the element and not of the url. `video` survives
+ * here for {@link PreloadStrategy.onMissing} and {@link PreloadStrategy.acquire}, which speak about
+ * a resource rather than about a plan.
+ */
+export type PreloadResourceType = "image" | "video";
+/** One thing a plan can ask for, named by the url the stage will show. */
+export type PreloadResource = {
+    type: PreloadResourceType;
+    /**
+     * The url the stage points an element at, which is also the key the cache stores it under.
+     *
+     * A strategy that rewrites urls - a host serving through its own protocol, say - must name the
+     * resource by the url the *stage* will use and do the rewriting inside
+     * {@link PreloadStrategy.acquire}. The two are the same string for every ordinary game.
+     */
+    src: string;
+};
+/**
+ * How urgently a resource is wanted. One axis, three points, and only the first of them blocks.
+ *
+ * - `gate` - the frame is not allowed to paint until this has landed. That is the loading screen's
+ *   whole meaning, so a plan that puts a chapter in this band is a plan that opens late.
+ * - `soon` - start now, at full speed, but nothing waits on it: what the player is a click away
+ *   from needing.
+ * - `idle` - speculative. Paced by `GameConfig.preloadDelay`, run after the other two, and
+ *   abandoned without ceremony when the moment is superseded.
+ */
+export type PreloadBand = "gate" | "soon" | "idle";
+export type PreloadEntry = {
+    /**
+     * Always an image.
+     *
+     * Video used to be nameable here, and warming it meant reading the bytes once and dropping
+     * them, in the hope that whatever served them kept a copy. That hope is unfounded on the hosts
+     * that matter - a game serving assets through its own protocol has no cache to warm - so it
+     * reported warming that had not happened. {@link PreloadPlan.video} is the answer that works.
+     */
+    type: "image";
+    src: string;
+    band: PreloadBand;
+    /**
+     * Whether to decode the image off-screen before anything shows it, and hold the bitmap.
+     *
+     * A decode is what lets an image paint on the frame it is revealed on rather than a frame or
+     * two later, and it is the expensive half of warming one: measured over a real library,
+     * fetching every image took 473 ms and fetching *and* decoding them took 2,140 ms, with each
+     * retained bitmap costing width x height x 4 bytes for as long as it is held. So it is worth
+     * paying for what is about to be revealed and wasteful for what merely might be.
+     *
+     * Defaults to true on the `gate` and `soon` bands and false on `idle`.
+     */
+    decode?: boolean;
+};
+/**
+ * What should be warm at one moment in the story, and what may be forgotten.
+ *
+ * A plan is complete: it replaces the previous one rather than adding to it. That is what makes
+ * {@link PreloadPlan.keep} meaningful - a scene the story has left keeps nothing, and its artwork
+ * is released as soon as no element is still showing it.
+ */
+export type PreloadPlan = {
+    /** Every image and video this moment wants, in the order each band should warm them. */
+    readonly entries: readonly PreloadEntry[];
+    /**
+     * Sounds the audio cache should hold for this moment, and only these.
+     *
+     * Separate from {@link PreloadPlan.entries}, and named by element rather than by url, because
+     * audio is warmed by a different cache with a different budget, and whether a clip is decoded
+     * into memory or streamed as it plays is a property of the sound rather than of its url. It is
+     * also never gated on: the audio context stays locked until the page has been interacted with,
+     * so a loading screen that waited for a clip could wait for ever.
+     */
+    readonly audio?: readonly Sound[];
+    /**
+     * Clips this moment wants buffering, nearest first, and only these.
+     *
+     * Named by element for the same reason audio is, only more so: warming a video means putting
+     * its element in the document and letting the browser buffer into it, and the element that
+     * buffered has to be the one that plays or nothing was gained. There is no video cache in the
+     * player, and there is no url-shaped way to fill one.
+     *
+     * The order is a statement of what is coming first. The player admits the clips one at a time
+     * and starts the next when the current one reports it can play, so how many are really being
+     * fetched at once follows the connection rather than the length of this list - which is why
+     * there is no setting for it and no number for a host to choose. A clip the story has already
+     * declared is left alone: it is on the stage on the author's own instruction.
+     *
+     * Never gated on. A clip can take arbitrarily long to buffer, and a loading screen that waited
+     * for one would be a download bar wearing a story's clothes. Omit the field to leave the warm
+     * set as it is; an empty array releases it.
+     */
+    readonly video?: readonly Video[];
+    /**
+     * Every url the image cache may keep, which is normally the plan's own entries.
+     *
+     * Anything outside this set is released at once if nothing is showing it, and the moment its
+     * last element unmounts otherwise. Omit it to leave what the cache holds alone - which is what
+     * a plan that only adds to a scene's warm set wants.
+     */
+    readonly keep?: readonly string[];
+    /**
+     * Urls no budget may release, whatever else happens - normally the opening frame.
+     *
+     * Whatever a mounted element is showing is protected separately and does not need naming here.
+     */
+    readonly pin?: readonly string[];
+};
+/** Why the player is asking. A strategy may answer only the moments it cares about. */
+export type PreloadMoment = {
+    /** A scene is about to paint, or has just been entered. */
+    kind: "scene";
+    scene: Scene;
+    story: Story | null;
+} | {
+    /**
+     * The story advanced. Sent for every action, so a strategy that plans row by row answers here
+     * and one that plans per scene returns null.
+     */
+    kind: "advance";
+    actionId: string | null;
+    scene: Scene | null;
+    story: Story | null;
+};
+/**
+ * Where the bytes for one resource came from, and what keeping them costs.
+ *
+ * Returned by {@link PreloadStrategy.acquire}. A host that serves assets from local disk should
+ * hand back the url it was given with `bytes: 0` and no `release`: the browser then fetches and
+ * caches the file once, the way it would for any other url on the page, and the player holds no
+ * second copy of it in the renderer's heap.
+ */
+export type PreloadAcquisition = {
+    /** The url an element should be pointed at. May be the resource's own url. */
+    url: string;
+    /**
+     * What holding this costs the player's fetched-bytes budget. Zero when the host owns the
+     * memory, which is the honest answer for a url the player copied nothing for.
+     */
+    bytes?: number;
+    /** Called once when the player lets the entry go, for a url the host has to clean up. */
+    release?: () => void;
+};
+/**
+ * The host's answer to what the player should warm, and optionally to how.
+ *
+ * Supplied as `GameConfig.preload`. Every method is asked on the player's own schedule; none may
+ * assume it is called in order, and all may be called again for the same moment after a reload.
+ */
+export interface PreloadStrategy {
+    /**
+     * What should be warm at this moment, or null to leave the previous plan in force.
+     *
+     * May be asynchronous: a host that has to ask another process what a scene uses answers when it
+     * knows. The player will not paint a gated frame until the plan has arrived and its `gate` band
+     * has landed, so a strategy that takes its time is a strategy that opens late - the same trade
+     * the built-in one makes, only visible.
+     */
+    plan(moment: PreloadMoment): PreloadPlan | null | Promise<PreloadPlan | null>;
+    /**
+     * Obtain the url for one resource, replacing the player's own fetch.
+     *
+     * Omit it and the player fetches the resource itself and mints an object url, which is what it
+     * has always done. Return null to say "nothing to warm, show it directly": the player then
+     * points the element at the resource's own url and caches nothing for it.
+     */
+    acquire?(resource: PreloadResource, signal: AbortSignal): Promise<PreloadAcquisition | null>;
+    /**
+     * Told when the stage shows something no plan named.
+     *
+     * This is the case the player used to report by asking the author, in a console warning, to
+     * register the image by hand. A host that plans from a compiled story can say something far
+     * more useful - which row shows it - so the player hands the fact over rather than guessing at
+     * the remedy. Called at most once per url.
+     */
+    onMissing?(resource: PreloadResource): void;
+}

package/dist/game/player/elements/preload/defaultStrategy.d.ts

@@ -0,0 +1,16 @@
+import type { Game } from "../../../nlcore/game";
+import type { PreloadStrategy } from "../../../nlcore/preload/types";
+/**
+ * The strategy a game gets when it supplies none: the walk and the tiers exactly as they were.
+ *
+ * It exists for two reasons beyond compatibility. It is the only proof that the seam is wide
+ * enough - if the behaviour the player shipped for years cannot be expressed as a
+ * {@link PreloadPlan}, the seam is the wrong shape. And it is what a host can fall back to for the
+ * parts of a story it does not know about, since a strategy is free to call this one and merge.
+ *
+ * Everything it does is read off `GameConfig`, so the fields that used to steer the player directly
+ * now steer this: `preloadAllImages` chooses between the two passes below, `preloadGate` decides
+ * whether the scene's whole registered set blocks the first frame or only its opening background,
+ * and `maxPreloadActions` sizes the prediction window.
+ */
+export declare function createDefaultPreloadStrategy(game: Game): PreloadStrategy;

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

@@ -26,6 +26,7 @@ import { Vfx, VfxStateRaw } from "../nlcore/elements/vfx";
 import { Timelines } from "./Tasks";
 import { Notification, NotificationManager } from "./lib/notification";
 import type { ImageCacheManager } from "./lib/ImageCacheManager";
+import type { PreloadResource } from "../nlcore/preload/types";
 import { ActionHistoryManager } from "../../game/nlcore/action/actionHistory";
 import { GameHistoryManager } from "../../game/nlcore/action/gameHistory";
 import type { Character } from "../nlcore/elements/character";
@@ -204,6 +205,14 @@ export declare class GameState {
     preloadingScene: Scene | null;
     flushDep: number;
     rollLock: Lock;
+    /**
+     * Clips held on the stage, hidden, because a plan said they are coming - never part of a save.
+     * See {@link VideoWarmQueue}.
+     */
+    private readonly videoWarmQueue;
+    private videoMissingReporter;
+    /** Sources already reported as unwarmed, so one clip in a loop does not report every pass. */
+    private readonly reportedUnwarmedVideos;
     readonly notificationMgr: NotificationManager;
     readonly events: EventDispatcher<GameStateEvents>;
     readonly logger: Logger;
@@ -222,8 +231,50 @@ export declare class GameState {
     get deps(): number;
     addVideo(video: Video): this;
     removeVideo(video: Video): this;
+    /**
+     * Whether the STORY has put this clip on the stage - a declaration row, a show, a play.
+     *
+     * Deliberately not "is it in the document": a clip the warm queue is holding is mounted and
+     * buffering but nothing has shown it, and the two answers are wanted in different places. What
+     * a save records, what an undo takes back and what a second declaration skips are all this one;
+     * whether an action may talk to the element is {@link GameState.isVideoOnStage}.
+     */
     isVideoAdded(video: Video): boolean;
+    /** Whether the clip is in the document at all, warmed or shown - so whether it has a state to talk to. */
+    isVideoOnStage(video: Video): boolean;
+    /**
+     * Every clip the stage renders: the story's own, then whatever the warm queue is holding.
+     *
+     * The two lists are kept apart rather than merged on insert because only the first is state.
+     * A save is a list of what the story put on the stage; a warmed clip is a performance detail of
+     * this run of it, and writing it into a save would make a story edit able to invalidate a save
+     * that has nothing to do with the change (`fromData` throws on a video id it cannot find).
+     */
     getVideos(): Video[];
+    /**
+     * Hold exactly these clips buffering ahead of the story, in this order of preference.
+     *
+     * What a {@link PreloadPlan.video} asks for. The queue starts them one at a time and waits for
+     * each to become playable before starting the next, so how many are really being fetched at
+     * once follows the connection rather than the plan; see {@link VideoWarmQueue}.
+     */
+    retainWarmVideos(videos: readonly Video[]): this;
+    /**
+     * Where to report a clip the story played that no plan named, or null for nowhere.
+     *
+     * The image half of this lives on the cache manager, which is the thing that would have fetched
+     * the image; a video is never fetched by the player, so the report has to come from the action
+     * that starts it.
+     */
+    useVideoMissingReporter(reporter: ((resource: PreloadResource) => void) | null): this;
+    /**
+     * Note that a clip is about to be shown or played with nothing having warmed it.
+     *
+     * Once per source, and only when no plan named it and nothing has it on the stage: a clip the
+     * author declared a few rows earlier is warm by authorship, and reporting that would be
+     * reporting the feature working.
+     */
+    reportUnwarmedVideo(video: Video): this;
     addVfx(vfx: Vfx): this;
     removeVfx(vfx: Vfx): this;
     isVfxAdded(vfx: Vfx): boolean;

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

@@ -1,5 +1,6 @@
 import type { Game } from "../../../game/nlcore/game";
 import type { GameState } from "../gameState";
+import type { PreloadStrategy } from "../../nlcore/preload/types";
 export type PreloadedToken = {
     abort: () => void;
     onFinished: (callback: () => void) => PreloadedToken;
@@ -92,7 +93,37 @@ export declare class ImageCacheManager {
     private seen;
     private blobBytes;
     private decodedBytes;
+    /**
+     * How the cache gets bytes for a source, when the host would rather it did not fetch them.
+     *
+     * Installed by the preloader from `GameConfig.preload`. Unset, the cache fetches the url and
+     * mints an object url for it, which is what it has always done - and which costs the renderer a
+     * second copy of every image on a host whose assets are already on local disk.
+     */
+    private acquisition;
+    /** Where a source nothing warmed is reported, when the host wants to hear about it. */
+    private missingReporter;
+    /** Sources already reported missing, so one unpredicted image is one report and not one a frame. */
+    private reportedMissing;
     constructor(game: Game);
+    /**
+     * Install the host's way of obtaining bytes, or clear it.
+     *
+     * Set once, from the preloader, before anything is warmed. Entries already in the cache keep
+     * whatever url they were built with; the cache never re-acquires something it holds.
+     */
+    useAcquisition(acquire: PreloadStrategy["acquire"] | null): this;
+    /** Install the host's ear for sources nothing warmed, or clear it. */
+    useMissingReporter(onMissing: PreloadStrategy["onMissing"] | null): this;
+    /**
+     * Say that the stage is showing `src` and no plan named it. Answers whether the host took it.
+     *
+     * The player's own answer to this was a console warning telling the author to register the
+     * image by hand, which is only useful to someone who writes the story in TypeScript. A host that
+     * planned from a compiled story can name the row instead, so it gets first refusal and the
+     * warning stays for the games that have no host to ask.
+     */
+    reportMissing(src: string): boolean;
     has(name: string): boolean;
     /**
      * Whether this source has ever been through the cache, whether or not it still is.
@@ -135,9 +166,14 @@ export declare class ImageCacheManager {
      * {@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.
+     * @param options.decode run the off-screen decode at all. Defaults to true. Off, the bytes are
+     * obtained and nothing else: measured over a real library, that is the difference between 473
+     * and 2,140 milliseconds, and it is the right trade for anything the plan does not expect to be
+     * revealed soon. `retainDecoded` implies a decode and overrides this.
      */
     preload(gameState: GameState, url: string, options?: {
         retainDecoded?: boolean;
+        decode?: boolean;
     }): PreloadedToken;
     abortAll(): void;
     abort(src: string): void;
@@ -191,7 +227,23 @@ export declare class ImageCacheManager {
      * the budget is a limit, not a preference, and what is on stage is protected by the pins.
      */
     private enforce;
-    private fetchAndDecode;
+    /**
+     * Get the bytes for one source and, unless told not to, decode them off-screen.
+     *
+     * The acquisition step is the host's when one is installed: it may hand back the url unchanged
+     * and own the memory itself, which is what a host serving local files should do. Otherwise the
+     * cache fetches and mints an object url, and is the thing that has to revoke it.
+     */
+    private acquireAndDecode;
+    /** The bytes for one source, from the host when it has an opinion and by fetching otherwise. */
+    private acquire;
+    /**
+     * Give a url back to whoever owns it: the host that supplied it, or the browser that minted it.
+     *
+     * One place, because the two are indistinguishable to every caller and getting it wrong leaks a
+     * whole image - an object url pins its blob for the lifetime of the document.
+     */
+    private handBack;
     /** A cached entry's bitmap, wanted again after the budget let it go or a look-ahead skipped it. */
     private decodeAgain;
     private runTask;

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

@@ -0,0 +1,78 @@
+import type { Video } from "../../nlcore/elements/video";
+export type VideoWarmQueueOptions = {
+    /**
+     * Whether the story itself has put this clip on the stage.
+     *
+     * Declared clips are the author's own instruction (`/video`, or a `Video.preload()` call) and
+     * are never queued: they are already buffering, they are not subject to the ceiling, and
+     * releasing one would take away something the story asked for.
+     */
+    isDeclared(video: Video): boolean;
+    /** Ask the player to re-render the stage, because what is mounted has changed. */
+    onChange(): void;
+};
+/**
+ * Which clips are held on the stage buffering, and in what order they are started.
+ *
+ * ## Why a queue and not a number
+ *
+ * Warming a video is not warming an image. An image is bytes plus a decode, and the player can hold
+ * both in a cache under a budget it can measure. A video is a `<video>` element that is in the
+ * document: the browser buffers into it, the buffer belongs to that element, and the element that
+ * buffered has to be the element that plays or the buffering bought nothing. So "warm this clip"
+ * means "mount it hidden, early", and the only questions left are how many and in what order.
+ *
+ * Both are answered here rather than by whoever wrote the story or configured the game. The host's
+ * plan says which clips are coming and in what order (nearest first); this admits them one at a
+ * time and starts the next when the current one reports it can play. On a fast local disk that
+ * empties the queue almost at once; on a slow connection it keeps a single read running instead of
+ * five that finish together and too late. Nobody has to know what number to write, which is the
+ * point - it is not a number an author could be expected to get right, and the browser is telling
+ * us the answer anyway.
+ */
+export declare class VideoWarmQueue {
+    private readonly options;
+    /** Everything the current plan named, declared clips included - what {@link isPlanned} answers. */
+    private planned;
+    /** What this queue may mount, in plan order, minus anything the story declared itself. */
+    private desired;
+    /** Mounted by this queue, hidden and buffering. A subset of {@link desired}, in admission order. */
+    private admitted;
+    /** The clip whose "can play" the queue is waiting for before it starts another. */
+    private pending;
+    private pendingTimer;
+    constructor(options: VideoWarmQueueOptions);
+    /**
+     * Take a plan's clips as the complete set this moment wants warm.
+     *
+     * Total replacement, like every other part of a plan: a clip the new plan does not name is
+     * released as soon as this returns, because the scene that wanted it is behind the reader. What
+     * the story declared is untouched - releasing that is the story's business, not the plan's.
+     */
+    retain(next: readonly Video[]): void;
+    /**
+     * A clip is playable, or has failed trying - either way the queue stops waiting for it.
+     *
+     * Fed from the player's exposed-state mount, which the video component performs on `canplay`
+     * and, for a source that will not load, on `error`. Anything that is not the clip being waited
+     * for is ignored, so this can be wired to every state mount there is.
+     */
+    noteReady(video: unknown): void;
+    /**
+     * Stop holding a clip the story has taken over.
+     *
+     * Called when a row declares, shows or plays something this queue had mounted. The element does
+     * not move and does not reload - it is the same element, now on the stage for a better reason -
+     * so this only stops counting it against the ceiling and frees the queue to start another.
+     */
+    forget(video: Video): void;
+    /** Clips this queue is holding on the stage, hidden. */
+    getAdmitted(): readonly Video[];
+    /** Whether the current plan named this clip at all, declared or not. */
+    isPlanned(video: Video): boolean;
+    /** Drop everything, for a player being torn down or reset. */
+    clear(): void;
+    /** Start the next clip if there is room and nothing is being waited on. Reports whether it did. */
+    private admit;
+    private clearPending;
+}