narraleaf-react 0.16.1 → 0.17.1

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

@@ -92,9 +92,13 @@ export declare class LiveGame {
      *
      * Every line in between is executed for real, so the backlog and its restore snapshots
      * accumulate exactly as in normal play — only faster and silent. Audio is muted for the
-     * duration, in-flight transitions are settled immediately, and timed pauses (`Control.sleep`,
-     * auto-forward) resolve at once. It stops as soon as a menu is waiting for a choice, so the
-     * choice itself is always left to the player.
+     * duration, and timed pauses (`Control.sleep`, auto-forward) resolve at once. It stops as soon
+     * as a menu is waiting for a choice, so the choice itself is always left to the player.
+     *
+     * Skipping a line is a *request* to the renderer, not a synchronous state change: it is
+     * re-issued until the line settles. A line that never responds (an unskippable in-flight
+     * media/transition step) ends the run with `"stalled"` rather than hanging — this method always
+     * settles.
      *
      * Because history accumulates the whole way, {@link getHistory} and
      * {@link restoreToHistory} cover the fast-forwarded span just like normal play.
@@ -113,9 +117,13 @@ export declare class LiveGame {
      *                         unreachable / already-passed id from a successful jump.
      * @param options.maxSteps - safety bound on the number of advance steps (defaults to the
      *                           `maxStackModelLoop` config).
+     * @param options.stepTimeout - how long (ms) a single line is given to settle before the run
+     *                              reports `"stalled"`. Defaults to 10000. Raise it if the story
+     *                              fast-forwards through long unskippable media.
      * @returns why it stopped: `"action"` (reached `until.actionId`), `"menu"`, `"end"` (the stack
-     *          drained), or `"maxSteps"`. When an `actionId` target was requested, `reachedTarget`
-     *          is also set (`true` only for reason `"action"`).
+     *          drained), `"maxSteps"`, or `"stalled"` (a line refused to settle). When an
+     *          `actionId` target was requested, `reachedTarget` is also set (`true` only for reason
+     *          `"action"`).
      *
      * Note: only the root execution stack is scanned for the target — an id buried inside an
      * in-flight parallel (`Control.all`/`any`) or async branch is not a stop point.
@@ -125,8 +133,9 @@ export declare class LiveGame {
             actionId: string;
         };
         maxSteps?: number;
+        stepTimeout?: number;
     }): Promise<{
-        reason: "menu" | "end" | "maxSteps" | "action";
+        reason: "menu" | "end" | "maxSteps" | "action" | "stalled";
         reachedTarget?: boolean;
     }>;
     private assertScreenshot;

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

@@ -0,0 +1,34 @@
+import type { Scene } from "../../../nlcore/elements/scene";
+import type { Sound } from "../../../nlcore/elements/sound";
+export type ScenePreloadPlan = {
+    /**
+     * Image urls the scene that is about to paint registers directly: its own backgrounds and
+     * images, plus the immediate background of any scene it jumps to. This tier is on the path to
+     * the first painted frame, so it is fetched unpaced and nothing is revealed until it is warm.
+     */
+    critical: string[];
+    /**
+     * Image urls belonging to the scenes reachable from here, minus anything already in
+     * {@link ScenePreloadPlan.critical}. Speculative: warmed after the critical tier, paced, and
+     * nothing waits for it.
+     */
+    lookAhead: string[];
+    /** Every url in the plan, in order — the set the cache should keep for this scene. */
+    all: string[];
+    /**
+     * Sounds this scene registers. Warmed alongside the critical tier but never gated on: the
+     * audio context can be locked until the player interacts with the page (see
+     * `AudioManager.preload`), so waiting for these could wait forever.
+     */
+    criticalAudio: Sound[];
+};
+/**
+ * Split a scene's registered image sources into what must be warm before the scene paints and what
+ * is merely likely to be needed soon.
+ *
+ * The distinction matters because a scene's `srcManager` reaches transitively: `getFutureSrc()`
+ * carries the whole asset set of every scene this one can jump to. Treating that as one preload
+ * pass meant the first frame of a large story waited on assets from scenes the player had not
+ * reached yet.
+ */
+export declare function planScenePreload(scene: Scene): ScenePreloadPlan;

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

@@ -43,6 +43,18 @@ export declare class AudioManager {
     fromData(data: AudioManagerDataRaw, elementMap: Map<string, LogicAction.GameElement>): this;
     soundFromData(sound: SoundElement, data: AudioDataRaw): void;
     isManaged(sound: SoundElement): boolean;
+    /**
+     * 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.
+     *
+     * 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 —
+     * in practice the gesture that opens a menu unlocks the context long before the scene it
+     * belongs to is entered. Failures resolve quietly; the sound then loads on first play, exactly
+     * as it did before.
+     */
+    preload(sound: SoundElement): Promise<void>;
     reset(): void;
     setGroupVolume(type: SoundType, volume: number): void;
     setGlobalVolume(volume: number): void;

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

@@ -14,19 +14,46 @@ export declare class ImageCacheManager {
      * the bytes are cached — the first reveal still pays the (async) decode cost and can paint
      * a blank frame. Decode failures are ignored: the image then simply decodes lazily on
      * first paint, exactly as before.
+     *
+     * Returns the element the decode ran on so callers can keep it alive (see
+     * {@link ImageCacheManager.preload}'s `retainDecoded`); `null` when the environment has no
+     * `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.
+     */
+    private decoded;
     constructor(game: Game);
     has(name: string): boolean;
     add(name: string, src: string): this;
     remove(name: string): this;
     get(name: string): string | undefined;
+    /**
+     * Whether this source has been decoded and its decoded bitmap is still held, i.e. attaching
+     * it to an `<img>` can paint without an asynchronous decode first.
+     */
+    isDecoded(name: string): boolean;
     clear(): this;
     size(): number;
     isPreloading(src: string): boolean;
-    preload(gameState: GameState, url: string): PreloadedToken;
+    /**
+     * Fetch `url`, cache it as a data 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.
+     */
+    preload(gameState: GameState, url: string, options?: {
+        retainDecoded?: boolean;
+    }): PreloadedToken;
     abortAll(): void;
     abort(src: string): void;
     preloadedSrc(): string[];