narraleaf-react 0.45.1 → 0.46.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,174 @@
+import type { Scene } from "../elements/scene";
+import type { Sound } from "../elements/sound";
+import type { Story } from "../elements/story";
+/**
+ * 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 plan entry names. Audio is not one of these - see {@link PreloadPlan.audio}. */
+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 = PreloadResource & {
+    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[];
+    /**
+     * 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/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;