narraleaf-react 1.2.0 → 1.3.0

package/dist/game/nlcore/action/skipGate.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -1,4 +1,4 @@
-import { ServiceHandlerCtx } from "../elements/service";
+import { ServiceHandlerCtx, ServiceSkipRequest, ServiceSkipSignal } from "../elements/service";
 import { Origins } from "../elements/story";
 import { TransformDefinitions } from "../elements/transform/type";
 import { IGamePluginRegistry } from "../game/plugin/plugin";
@@ -14,5 +14,5 @@ import { StorableType } from "../elements/persistent/type";
 import { ScriptCtx } from "../elements/script";
 import { IStoryConfig } from "../elements/story";
 export * from "../elements/type";
-export type { GameHistory, IGamePluginRegistry, LiveGameEventToken, Origins, ServiceHandlerCtx, TransformDefinitions, GameConfig, SavedGame, NotificationToken, SavedGameMetaData, LayoutRouter, KeyBindingValue, WebKeyboardKey, StorableType, ScriptCtx, IStoryConfig, SoundBusId };
+export type { GameHistory, IGamePluginRegistry, LiveGameEventToken, Origins, ServiceHandlerCtx, ServiceSkipRequest, ServiceSkipSignal, TransformDefinitions, GameConfig, SavedGame, NotificationToken, SavedGameMetaData, LayoutRouter, KeyBindingValue, WebKeyboardKey, StorableType, ScriptCtx, IStoryConfig, SoundBusId };
 export { KeyBindingType, SoundType, };

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

@@ -1,18 +1,101 @@
 import { Actionable } from "../action/actionable";
-import { SerializableData, StringKeyOf } from "../../../util/data";
+import { EventToken, SerializableData, StringKeyOf } from "../../../util/data";
 import { Chained, Proxied } from "../action/chain";
 import { ServiceAction } from "../action/serviceAction";
 import { ScriptCtx } from "../elements/script";
 type ServiceContentType = {
     [K in string]: any[];
 };
+/**
+ * One request from the player to hurry a running service handler.
+ */
+export interface ServiceSkipRequest {
+    /**
+     * `true` for the skip mode - the skip key held, {@link LiveGame.skipDialog}, and
+     * {@link LiveGame.fastForward} - and `false` for a single press of the skip key.
+     *
+     * The same distinction a line of dialogue draws: a single press reveals a line up to its next
+     * pause, the skip mode walks past the pauses too.
+     */
+    readonly forced: boolean;
+}
+/**
+ * The player asking a running handler to hurry, and the handler's answer.
+ *
+ * A request does not end the handler. The handler decides what being skipped means for it:
+ * - **finish now** - put whatever it was doing into its final state and return, in
+ *   {@link onRequest};
+ * - **ignore it** - carry on; the skip mode waits for the handler, and
+ *   {@link LiveGame.fastForward} waits up to its `stepTimeout` before reporting `"stalled"`.
+ *   This is what a handler that never looks at `ctx.skip` does;
+ * - **refuse** - {@link refuse}: the skip mode still waits, and a fast-forward stops at this step
+ *   at once and reports `"refused"`.
+ *
+ * Requests are broadcast: a handler running in a `Control.all` branch or an async branch is asked
+ * whenever the player skips anything, the way a sprite's transition running beside a line is.
+ *
+ * Only an asynchronous handler is ever asked. A synchronous one has already finished by the time
+ * the player could ask.
+ */
+export interface ServiceSkipSignal {
+    /** Whether the player has asked this handler to hurry yet. */
+    readonly requested: boolean;
+    /** Whether the player has asked it in the skip mode yet. */
+    readonly forced: boolean;
+    /**
+     * Whether the game is in {@link LiveGame.fastForward} right now. A handler that checks it on
+     * entry can go straight to its final state.
+     */
+    readonly fastForwarding: boolean;
+    /**
+     * Listen for the player asking this handler to hurry.
+     *
+     * Called once for the first request, and once more the first time a request is
+     * {@link ServiceSkipRequest.forced | forced} - not for every repeat, which the skip mode sends
+     * many times a second. Registering after a request has already arrived calls the listener at
+     * once.
+     */
+    onRequest(listener: (request: ServiceSkipRequest) => void): EventToken;
+    /**
+     * Refuse to be fast-forwarded past until the returned function is called.
+     *
+     * Refusals stack: the step can be skipped again once every one has been released. The message
+     * is for people - it is logged, and handed back by {@link LiveGame.fastForward} for a host to
+     * show - and nothing in the engine reads it to decide anything.
+     */
+    refuse(message?: string): () => void;
+}
 export type ServiceHandlerCtx = ScriptCtx & {
+    /**
+     * Aborted when this run is cancelled: the player stepped back past it, the story jumped away
+     * from it, a `Control.any` it ran in was won by another branch, or the game was reset or loaded.
+     *
+     * A cancellation cannot be refused, and it does not wait for the handler: by the time the
+     * signal fires the game has already moved on. Pass the signal to whatever the handler is
+     * waiting on (`fetch(url, {signal})`), and check `signal.aborted` after each `await` before
+     * touching the game again.
+     */
+    signal: AbortSignal;
+    /** The player asking this handler to hurry. See {@link ServiceSkipSignal}. */
+    skip: ServiceSkipSignal;
+    /**
+     * Run `handler` when this run is cancelled. Registering after the cancellation runs it at once.
+     * @deprecated Use {@link ServiceHandlerCtx.signal}, which fires on the same occasions.
+     */
     onAbort: (handler: () => void) => void;
 };
 export type ServiceHandler<Args extends any[]> = (ctx: ServiceHandlerCtx, ...args: Args) => void | Promise<void>;
 export declare class ServiceSkeleton<Content extends ServiceContentType = ServiceContentType, RawData extends Record<string, SerializableData> | null = never> extends Actionable<RawData, ServiceSkeleton> {
     /**
      * Register an action handler.
+     *
+     * A handler that returns a promise holds the story until the promise settles, the way a line
+     * of dialogue does; one that returns anything else lets it carry on at once. If the promise
+     * rejects, the story stops at this action and the error is reported.
+     *
+     * While it holds the story, a handler hears about the player through its context:
+     * `ctx.skip` when the player asks it to hurry, which it may answer or refuse, and `ctx.signal`
+     * when its run is cancelled, which it may not.
      * @param key - The action key to handle.
      * @param handler - Callback invoked when the action fires.
      * @example
@@ -20,6 +103,25 @@ export declare class ServiceSkeleton<Content extends ServiceContentType = Servic
      * this.on("add", (ctx, name) => {
      *   console.log("Adding", name);
      * });
+     *
+     * this.on("countdown", async (ctx, seconds: number) => {
+     *   // Skipping finishes the countdown at once.
+     *   const done = new Promise<void>(resolve => {
+     *     const timer = setTimeout(resolve, seconds * 1000);
+     *     ctx.skip.onRequest(() => {
+     *       clearTimeout(timer);
+     *       resolve();
+     *     });
+     *     ctx.signal.addEventListener("abort", () => clearTimeout(timer));
+     *   });
+     *   await done;
+     * });
+     *
+     * this.on("minigame", async (ctx) => {
+     *   // A fast-forward cannot play the minigame for the player, so it stops here.
+     *   ctx.skip.refuse("waiting for the minigame");
+     *   await playMinigame(ctx.signal);
+     * });
      * ```
      */
     on<K extends StringKeyOf<Content>>(key: K, handler: ServiceHandler<Content[K]>): this;

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

@@ -184,7 +184,8 @@ export declare class LiveGame {
      * 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.
+     * settles. A step that answers by refusing to be skipped (a user service calling
+     * `ctx.skip.refuse()`) ends it at once with `"refused"`, and is left running where it is.
      *
      * Because history accumulates the whole way, {@link getHistory} and
      * {@link restoreToHistory} cover the fast-forwarded span just like normal play.
@@ -207,9 +208,11 @@ export declare class LiveGame {
      *                              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), `"maxSteps"`, or `"stalled"` (a line refused to settle). When an
-     *          `actionId` target was requested, `reachedTarget` is also set (`true` only for reason
-     *          `"action"`).
+     *          drained), `"maxSteps"`, `"stalled"` (a line did not settle within `stepTimeout`), or
+     *          `"refused"` (a line refused to be skipped). When an `actionId` target was requested,
+     *          `reachedTarget` is also set (`true` only for reason `"action"`). With `"refused"`,
+     *          `refusal` carries the message the step gave, if it gave one: it is for showing to a
+     *          person, not for deciding what to do next.
      *
      * 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.
@@ -221,8 +224,9 @@ export declare class LiveGame {
         maxSteps?: number;
         stepTimeout?: number;
     }): Promise<{
-        reason: "menu" | "end" | "maxSteps" | "action" | "stalled";
+        reason: "menu" | "end" | "maxSteps" | "action" | "stalled" | "refused";
         reachedTarget?: boolean;
+        refusal?: string;
     }>;
     private assertScreenshot;
     /**