@momoyu-ink/kit 0.5.5 → 0.6.1

package/dist/lib.d.mts

@@ -1,13 +1,13 @@
-import * as React$1 from 'react';
-import React__default, { ReactElement, Component, ForwardRefExoticComponent, CSSProperties, FC } from 'react';
-import { M as MouseEvent, a as MoyuEvent, C as Command, b as MaybePromise, J as JSX } from './jsx-dev-runtime-BKsP0hXU.mjs';
-export { A as AudioCommand, c as AudioSettings, B as BubbleEvent, D as DetailedMoyuProps, E as EffectParams, G as GamepadCommand, K as KeyboardEvent, d as KeyboardEventKind, e as MakeNullOptional, f as MouseEventKind, g as MoyuAnimationAttributes, h as MoyuBackdropAttributes, i as MoyuClipAttributes, j as MoyuContainerAttributes, k as MoyuEventHandler, l as MoyuFilterAttributes, m as MoyuListenerAttributes, n as MoyuNodeAttributes, o as MoyuSpriteAttributes, p as MoyuTextAttributes, q as MoyuVideoAttributes, N as Node, S as ScenarioCommand, r as SystemCommand, T as TextCommand, s as TouchEvent, t as TouchEventKind, u as Tuple2, v as Tuple3, w as Tuple4, W as WindowState, x as createBubbleEvent, y as getStageSize } from './jsx-dev-runtime-BKsP0hXU.mjs';
+import * as react from 'react';
+import { ReactElement, Component, ForwardRefExoticComponent, CSSProperties, FC, ComponentType } from 'react';
+import { M as MouseEvent, a as MoyuEvent, C as Command, b as MaybePromise, J as JSX } from './jsx-dev-runtime-CFlTWFj5.mjs';
+export { A as AudioCommand, c as AudioSettings, B as BubbleEvent, D as DetailedMoyuProps, E as EffectParams, G as GamepadCommand, K as KeyboardEvent, d as KeyboardEventKind, e as MakeNullOptional, f as MouseEventKind, g as MoyuAnimationAttributes, h as MoyuBackdropAttributes, i as MoyuClipAttributes, j as MoyuContainerAttributes, k as MoyuEventHandler, l as MoyuFilterAttributes, m as MoyuListenerAttributes, n as MoyuNodeAttributes, o as MoyuSpriteAttributes, p as MoyuTextAttributes, q as MoyuVideoAttributes, N as Node, S as ScenarioCommand, r as SystemCommand, T as TextCommand, s as TouchEvent, t as TouchEventKind, u as Tuple2, v as Tuple3, w as Tuple4, W as WindowState, x as createBubbleEvent, y as getStageSize } from './jsx-dev-runtime-CFlTWFj5.mjs';
 import { FluidValue } from '@react-spring/shared';
 import { ElementType, AssignableKeys, ComponentPropsWithRef } from '@react-spring/types';
 import { Snapshot } from 'valtio';
+import { ZodType } from 'zod';
 import { SpringValues, SpringRef } from '@react-spring/core';
 export * from '@react-spring/core';
-import { ZodType } from 'zod';
 import 'react/jsx-runtime';
 import 'react/jsx-dev-runtime';
 
@@ -217,7 +217,13 @@ type TextLine = {
     tailing: string | null;
 };
 
-type ScenarioEvent = ResolvedCommandLine | ResolvedSystemCallLine | TextLine | null | null | null;
+type MarkerEnter = {
+    markerId: string;
+    story: string;
+    paragraph: string;
+};
+
+type ScenarioEvent = MarkerEnter | ResolvedCommandLine | ResolvedSystemCallLine | TextLine | null | null | null | null;
 
 type WheelEventDeltaMode = 'pixel' | 'line' | 'page';
 
@@ -342,18 +348,16 @@ declare global {
     function queueMicrotask(callback: () => void): void;
 }
 
-/** biome-ignore-all lint/suspicious/noExplicitAny: too tight for this file */
-
 /**
  * Context for page parameters
  * Used to provide params to page components via React tree
  */
-declare const PageParamsContext: React__default.Context<Record<string, any> | undefined>;
+declare const PageParamsContext: react.Context<Record<string, any> | undefined>;
 /**
  * Context for overlay parameters
  * Used to provide params to overlay components via React tree
  */
-declare const OverlayParamsContext: React__default.Context<Record<string, any> | undefined>;
+declare const OverlayParamsContext: react.Context<Record<string, any> | undefined>;
 /**
  * Placeholder for global navigation types.
  * Projects can augment this interface to provide type safety for the global navigator.
@@ -384,12 +388,12 @@ type GetOverlays<T> = T extends {
 type DefaultPageName = GetPages<RootNavigatorList>;
 type DefaultOverlayName = GetOverlays<RootNavigatorList>;
 interface PageDescriptor {
-    component: React__default.ComponentType<any>;
+    component: ComponentType<any>;
     options?: Record<string, any>;
     requiredParams?: string[];
 }
 interface OverlayDescriptor {
-    component: React__default.ComponentType<any>;
+    component: ComponentType<any>;
     options?: Record<string, any>;
     requiredParams?: string[];
 }
@@ -407,6 +411,10 @@ interface Navigator<PageName extends string = DefaultPageName, OverlayName exten
      * @param params Parameters to pass to the page (optional)
      */
     navigate: (page: PageName, params?: Record<string, any>) => void;
+    /**
+     * Check whether a page exists in the navigator configuration.
+     */
+    hasPage: (page: string) => boolean;
     /**
      * Go back to the previous page (not implemented yet)
      */
@@ -471,7 +479,7 @@ declare function createStackNavigator<Pages extends Record<string, PageConfig>,
  * @param navigator The navigator instance
  * @returns A React component that renders the navigation state
  */
-declare function createStaticNavigation(navigator: Navigator<any, any>): React__default.FC;
+declare function createStaticNavigation(navigator: Navigator<any, any>): FC;
 /**
  * Get the navigator instance (stable reference)
  * Can be used in both components and state logic
@@ -503,41 +511,11 @@ declare function useNavigationState(): Snapshot<NavigationState>;
  */
 declare function useNavigationParams<T = Record<string, any>>(): T;
 
-declare function useFadeInOut(inTime: number, _keepTime: number, _outTime: number, pause?: boolean, onFinished?: () => void): [SpringValues<{
-    opacity: number;
-}>, SpringRef<{
-    opacity: number;
-}>, () => void];
-declare function useFadeIn(inTime: number, pause?: boolean, onFinished?: () => void): [SpringValues<{
-    opacity: number;
-}>, SpringRef<{
-    opacity: number;
-}>, () => void];
-declare function useFadeOut(outTime: number, pause?: boolean, onFinished?: () => void): [SpringValues<{
-    opacity: number;
-}>, SpringRef<{
-    opacity: number;
-}>, () => void];
-
-/** Advance to the next line in the current story. */
-declare function nextLine(): any;
-/** Set a timed wait, optionally skippable. */
-declare function setWaiting(time: number, skippable: boolean): void;
-/**
- * Custom hook to manage scenario lifecycle (load, start, terminate).
- * The underlying session is resilient to transient remounts such as Fast Refresh.
- *
- * @param {string[]} stories - An array of story names to load.
- * @param {string} [startName] - The name of the story to start.
- * @param {string} [entryName] - The entry point within the story to start from.
- * @param {boolean} [goNextOnLoad=false] - Whether to automatically advance to the next line after loading.
- */
-declare function useScenario(stories: string[], startName?: string, entryName?: string, goNextOnLoad?: boolean): void;
-
-/**
- * Used to load a sound effect and provide a function to play it.
- */
-declare function useSoundEffect(src: string): () => void;
+type ExecutionCursor = {
+    story: string;
+    paragraph: string;
+    markerId?: string;
+};
 
 /** Flow control interface passed to every handler. */
 interface GameControl {
@@ -568,6 +546,12 @@ interface AutoTicketHandle {
     done(): void;
     cancel(): void;
 }
+interface FastForwardOptions {
+    stepLimit?: number;
+    timeLimitMs?: number;
+    onAbort?: (error: Error) => void;
+    warp?: boolean;
+}
 /** Reactive skip state. Actors read via useIsSkipping(). */
 declare const skipState: {
     active: boolean;
@@ -576,10 +560,22 @@ declare const skipState: {
 declare const autoState: {
     active: boolean;
 };
+/** Reactive fast-forward state. Actors read via useIsSeeking(). */
+declare const fastForwardState: {
+    active: boolean;
+};
+/** Reactive warp state. Handlers use this to suppress live-only behavior during warp. */
+declare const warpState: {
+    active: boolean;
+};
 /** Reactively returns whether skip (Ctrl fast-forward) is active. */
 declare function useIsSkipping(): boolean;
 /** Reactively returns whether auto mode is active. */
 declare function useIsAutoing(): boolean;
+/** Reactively returns whether any seek (fast-forward or warp) is active. */
+declare function useIsSeeking(): boolean;
+/** Returns the current seek type, or null when no seek is active. */
+declare function getSeekingType(): 'warp' | 'fast-forward' | null;
 /** Set the default tail delay in milliseconds for newly created auto tickets. */
 declare function setDefaultAutoTailMs(ms: number): void;
 declare function createStage(): {
@@ -599,6 +595,10 @@ declare function createStage(): {
     startAuto: () => void;
     stopAuto: () => void;
     isAutoing: () => boolean;
+    startFastForward: (options?: FastForwardOptions) => void;
+    stopFastForward: () => void;
+    isFastForwarding: () => boolean;
+    resetRuntimeState: () => void;
     bindEvents: () => () => void;
 };
 type StageInstance = ReturnType<typeof createStage>;
@@ -607,7 +607,7 @@ declare function useStageContext(): StageInstance;
 declare function StageContextProvider({ stage, children }: {
     stage: StageInstance;
     children: React.ReactNode;
-}): React$1.FunctionComponentElement<React$1.ProviderProps<{
+}): react.FunctionComponentElement<react.ProviderProps<{
     registerCommandSchema: <T extends ZodType>(schema: T) => () => void;
     registerCommand: <T extends ScenarioCommandBaseType>(commands: string | string[], handler: CommandHandler<T>) => () => void;
     registerTextLine: (handler: TextLineHandler) => () => void;
@@ -624,6 +624,10 @@ declare function StageContextProvider({ stage, children }: {
     startAuto: () => void;
     stopAuto: () => void;
     isAutoing: () => boolean;
+    startFastForward: (options?: FastForwardOptions) => void;
+    stopFastForward: () => void;
+    isFastForwarding: () => boolean;
+    resetRuntimeState: () => void;
     bindEvents: () => () => void;
 } | null>>;
 /**
@@ -664,6 +668,101 @@ declare function useAutoTicket(): (options?: AutoTicketOptions) => AutoTicketHan
  */
 declare function useBeforeHandleCommandCallback(callback: (upcomingCommand: ResolvedCommandLine) => void): void;
 
+interface AppStateAdapter<TState = unknown> {
+    capture(): TState | Promise<TState>;
+    restore(state: TState): void | Promise<void>;
+    switchPage?(page: string, params?: Record<string, unknown>): void | Promise<void>;
+    enterFastForwardMode?(options?: FastForwardOptions): void | Promise<void>;
+    exitFastForwardMode?(): void | Promise<void>;
+    restartCurrentStoryFromHead?(): void | Promise<void>;
+}
+type CombinedCheckpoint<TState = unknown> = {
+    cursor: ExecutionCursor;
+    appState: TState;
+};
+interface DebugSessionConfig {
+    onMarkerEnter?: (checkpoint: CombinedCheckpoint<unknown>) => void | Promise<void>;
+    onError?: (error: unknown) => void | Promise<void>;
+}
+interface DebugSessionController {
+    restoreCheckpoint(markerId: string): Promise<boolean>;
+    warp(options: DebugWarpOptions): Promise<void>;
+    switchPage(page: string, params?: Record<string, unknown>): Promise<void>;
+}
+type DebugWarpBoundary = 'before' | 'after';
+interface DebugWarpOptions {
+    markerId: string;
+    boundary?: DebugWarpBoundary;
+}
+declare function registerAppStateAdapter<TState = unknown>(adapter: AppStateAdapter<TState> | null): void;
+declare function getAppStateAdapter<TState = unknown>(): AppStateAdapter<TState> | null;
+declare function startDebugSession(config?: DebugSessionConfig): Promise<DebugSessionController>;
+declare function stopDebugSession(): Promise<void>;
+declare function useDebugSession(): {
+    startDebugSession: typeof startDebugSession;
+    stopDebugSession: typeof stopDebugSession;
+    restoreCheckpoint: (markerId: string) => Promise<boolean>;
+    warp: (options: DebugWarpOptions) => Promise<void>;
+    switchPage: (page: string, params?: Record<string, unknown>) => Promise<void>;
+    active: boolean;
+    checkpoints: {
+        readonly [x: string]: {
+            readonly cursor: {
+                readonly story: string;
+                readonly paragraph: string;
+                readonly markerId?: string | undefined;
+            };
+            readonly appState: unknown;
+        };
+    };
+    currentCursor: {
+        readonly story: string;
+        readonly paragraph: string;
+        readonly markerId?: string | undefined;
+    } | null;
+    restoring: boolean;
+    lastError: string | null;
+};
+
+declare function stopRuntimeDebugSession(): Promise<void>;
+declare function startRuntimeDebugSession(): Promise<void>;
+
+declare function useFadeInOut(inTime: number, _keepTime: number, _outTime: number, pause?: boolean, onFinished?: () => void): [SpringValues<{
+    opacity: number;
+}>, SpringRef<{
+    opacity: number;
+}>, () => void];
+declare function useFadeIn(inTime: number, pause?: boolean, onFinished?: () => void): [SpringValues<{
+    opacity: number;
+}>, SpringRef<{
+    opacity: number;
+}>, () => void];
+declare function useFadeOut(outTime: number, pause?: boolean, onFinished?: () => void): [SpringValues<{
+    opacity: number;
+}>, SpringRef<{
+    opacity: number;
+}>, () => void];
+
+/** Advance to the next line in the current story. */
+declare function nextLine(): any;
+/** Set a timed wait, optionally skippable. */
+declare function setWaiting(time: number, skippable: boolean): void;
+/**
+ * Custom hook to manage scenario lifecycle (load, start, terminate).
+ * The underlying session is resilient to transient remounts such as Fast Refresh.
+ *
+ * @param {string[]} stories - An array of story names to load.
+ * @param {string} [startName] - The name of the story to start.
+ * @param {string} [entryName] - The entry point within the story to start from.
+ * @param {boolean} [goNextOnLoad=false] - Whether to automatically advance to the next line after loading.
+ */
+declare function useScenario(stories: string[], startName?: string, entryName?: string, goNextOnLoad?: boolean): void;
+
+/**
+ * Used to load a sound effect and provide a function to play it.
+ */
+declare function useSoundEffect(src: string): () => void;
+
 declare module 'zod' {
     interface GlobalMeta {
         title?: string;
@@ -674,4 +773,4 @@ declare module 'zod' {
     }
 }
 
-export { type AnimatedComponent, type AnimatedProps, type AnimationFrameCallbackEvent, type AutoTicketHandle, type AutoTicketOptions, type BeforeUnloadEvent, Command, type CommandHandler, type CustomEvent, type DefaultOverlayName, type DefaultPageName, type FocusEvent, type FocusEventKind, type FullScreenEvent, type FullscreenEventKind, type GameControl, type GameEvent, type Gamepad, type GamepadButton, type GamepadEvent, type GamepadHapticActuator, JSX, type KeyboardLocation, type Literal, MaybePromise, MouseEvent, MoyuEvent, type NavigationState, type Navigator, type NodeEvent, type OverlayConfig, type OverlayDescriptor, type OverlayInfo, OverlayParamsContext, type PageConfig, type PageDescriptor, PageParamsContext, type RegisterNavigator, type ResizeEvent, type ResolvedArgument, type ResolvedCommandLine, type ResolvedSystemCallLine, type RootErrorInfo, type RootHandle, type RootNavigatorList, type RootOptions, type RootUncaughtErrorInfo, type ScenarioCommandBaseType, type ScenarioEvent, type StackNavigatorOptions, StageContextProvider, type StageInstance, type TextLine, type TextLineHandler, type WheelEvent, type WheelEventDeltaMode, type WithAnimated, animated as a, addEventListener, animated, autoState, createRoot, createStackNavigator, createStage, createStaticNavigation, executeNodeCommand, executePluginCommand, getNavigator, globalEventListeners, globalRequestAnimationFrameListeners, moyu, nextLine, setDefaultAutoTailMs, setWaiting, skipState, useAutoBlocker, useAutoTicket, useBeforeHandleCommandCallback, useFadeIn, useFadeInOut, useFadeOut, useInterruptCallback, useIsAutoing, useIsSkipping, useNavigation, useNavigationParams, useNavigationState, useScenario, useSkipBlocker, useSkipCallback, useSoundEffect, useStageContext };
+export { type AnimatedComponent, type AnimatedProps, type AnimationFrameCallbackEvent, type AppStateAdapter, type AutoTicketHandle, type AutoTicketOptions, type BeforeUnloadEvent, type CombinedCheckpoint, Command, type CommandHandler, type CustomEvent, type DebugSessionConfig, type DebugSessionController, type DebugWarpBoundary, type DebugWarpOptions, type DefaultOverlayName, type DefaultPageName, type FastForwardOptions, type FocusEvent, type FocusEventKind, type FullScreenEvent, type FullscreenEventKind, type GameControl, type GameEvent, type Gamepad, type GamepadButton, type GamepadEvent, type GamepadHapticActuator, JSX, type KeyboardLocation, type Literal, MaybePromise, MouseEvent, MoyuEvent, type NavigationState, type Navigator, type NodeEvent, type OverlayConfig, type OverlayDescriptor, type OverlayInfo, OverlayParamsContext, type PageConfig, type PageDescriptor, PageParamsContext, type RegisterNavigator, type ResizeEvent, type ResolvedArgument, type ResolvedCommandLine, type ResolvedSystemCallLine, type RootErrorInfo, type RootHandle, type RootNavigatorList, type RootOptions, type RootUncaughtErrorInfo, type ScenarioCommandBaseType, type ScenarioEvent, type StackNavigatorOptions, StageContextProvider, type StageInstance, type TextLine, type TextLineHandler, type WheelEvent, type WheelEventDeltaMode, type WithAnimated, animated as a, addEventListener, animated, autoState, createRoot, createStackNavigator, createStage, createStaticNavigation, executeNodeCommand, executePluginCommand, fastForwardState, getAppStateAdapter, getNavigator, getSeekingType, globalEventListeners, globalRequestAnimationFrameListeners, moyu, nextLine, registerAppStateAdapter, setDefaultAutoTailMs, setWaiting, skipState, startDebugSession, startRuntimeDebugSession, stopDebugSession, stopRuntimeDebugSession, useAutoBlocker, useAutoTicket, useBeforeHandleCommandCallback, useDebugSession, useFadeIn, useFadeInOut, useFadeOut, useInterruptCallback, useIsAutoing, useIsSeeking, useIsSkipping, useNavigation, useNavigationParams, useNavigationState, useScenario, useSkipBlocker, useSkipCallback, useSoundEffect, useStageContext, warpState };

package/dist/lib.d.ts

@@ -1,13 +1,13 @@
-import * as React$1 from 'react';
-import React__default, { ReactElement, Component, ForwardRefExoticComponent, CSSProperties, FC } from 'react';
-import { M as MouseEvent, a as MoyuEvent, C as Command, b as MaybePromise, J as JSX } from './jsx-dev-runtime-BKsP0hXU.js';
-export { A as AudioCommand, c as AudioSettings, B as BubbleEvent, D as DetailedMoyuProps, E as EffectParams, G as GamepadCommand, K as KeyboardEvent, d as KeyboardEventKind, e as MakeNullOptional, f as MouseEventKind, g as MoyuAnimationAttributes, h as MoyuBackdropAttributes, i as MoyuClipAttributes, j as MoyuContainerAttributes, k as MoyuEventHandler, l as MoyuFilterAttributes, m as MoyuListenerAttributes, n as MoyuNodeAttributes, o as MoyuSpriteAttributes, p as MoyuTextAttributes, q as MoyuVideoAttributes, N as Node, S as ScenarioCommand, r as SystemCommand, T as TextCommand, s as TouchEvent, t as TouchEventKind, u as Tuple2, v as Tuple3, w as Tuple4, W as WindowState, x as createBubbleEvent, y as getStageSize } from './jsx-dev-runtime-BKsP0hXU.js';
+import * as react from 'react';
+import { ReactElement, Component, ForwardRefExoticComponent, CSSProperties, FC, ComponentType } from 'react';
+import { M as MouseEvent, a as MoyuEvent, C as Command, b as MaybePromise, J as JSX } from './jsx-dev-runtime-CFlTWFj5.js';
+export { A as AudioCommand, c as AudioSettings, B as BubbleEvent, D as DetailedMoyuProps, E as EffectParams, G as GamepadCommand, K as KeyboardEvent, d as KeyboardEventKind, e as MakeNullOptional, f as MouseEventKind, g as MoyuAnimationAttributes, h as MoyuBackdropAttributes, i as MoyuClipAttributes, j as MoyuContainerAttributes, k as MoyuEventHandler, l as MoyuFilterAttributes, m as MoyuListenerAttributes, n as MoyuNodeAttributes, o as MoyuSpriteAttributes, p as MoyuTextAttributes, q as MoyuVideoAttributes, N as Node, S as ScenarioCommand, r as SystemCommand, T as TextCommand, s as TouchEvent, t as TouchEventKind, u as Tuple2, v as Tuple3, w as Tuple4, W as WindowState, x as createBubbleEvent, y as getStageSize } from './jsx-dev-runtime-CFlTWFj5.js';
 import { FluidValue } from '@react-spring/shared';
 import { ElementType, AssignableKeys, ComponentPropsWithRef } from '@react-spring/types';
 import { Snapshot } from 'valtio';
+import { ZodType } from 'zod';
 import { SpringValues, SpringRef } from '@react-spring/core';
 export * from '@react-spring/core';
-import { ZodType } from 'zod';
 import 'react/jsx-runtime';
 import 'react/jsx-dev-runtime';
 
@@ -217,7 +217,13 @@ type TextLine = {
     tailing: string | null;
 };
 
-type ScenarioEvent = ResolvedCommandLine | ResolvedSystemCallLine | TextLine | null | null | null;
+type MarkerEnter = {
+    markerId: string;
+    story: string;
+    paragraph: string;
+};
+
+type ScenarioEvent = MarkerEnter | ResolvedCommandLine | ResolvedSystemCallLine | TextLine | null | null | null | null;
 
 type WheelEventDeltaMode = 'pixel' | 'line' | 'page';
 
@@ -342,18 +348,16 @@ declare global {
     function queueMicrotask(callback: () => void): void;
 }
 
-/** biome-ignore-all lint/suspicious/noExplicitAny: too tight for this file */
-
 /**
  * Context for page parameters
  * Used to provide params to page components via React tree
  */
-declare const PageParamsContext: React__default.Context<Record<string, any> | undefined>;
+declare const PageParamsContext: react.Context<Record<string, any> | undefined>;
 /**
  * Context for overlay parameters
  * Used to provide params to overlay components via React tree
  */
-declare const OverlayParamsContext: React__default.Context<Record<string, any> | undefined>;
+declare const OverlayParamsContext: react.Context<Record<string, any> | undefined>;
 /**
  * Placeholder for global navigation types.
  * Projects can augment this interface to provide type safety for the global navigator.
@@ -384,12 +388,12 @@ type GetOverlays<T> = T extends {
 type DefaultPageName = GetPages<RootNavigatorList>;
 type DefaultOverlayName = GetOverlays<RootNavigatorList>;
 interface PageDescriptor {
-    component: React__default.ComponentType<any>;
+    component: ComponentType<any>;
     options?: Record<string, any>;
     requiredParams?: string[];
 }
 interface OverlayDescriptor {
-    component: React__default.ComponentType<any>;
+    component: ComponentType<any>;
     options?: Record<string, any>;
     requiredParams?: string[];
 }
@@ -407,6 +411,10 @@ interface Navigator<PageName extends string = DefaultPageName, OverlayName exten
      * @param params Parameters to pass to the page (optional)
      */
     navigate: (page: PageName, params?: Record<string, any>) => void;
+    /**
+     * Check whether a page exists in the navigator configuration.
+     */
+    hasPage: (page: string) => boolean;
     /**
      * Go back to the previous page (not implemented yet)
      */
@@ -471,7 +479,7 @@ declare function createStackNavigator<Pages extends Record<string, PageConfig>,
  * @param navigator The navigator instance
  * @returns A React component that renders the navigation state
  */
-declare function createStaticNavigation(navigator: Navigator<any, any>): React__default.FC;
+declare function createStaticNavigation(navigator: Navigator<any, any>): FC;
 /**
  * Get the navigator instance (stable reference)
  * Can be used in both components and state logic
@@ -503,41 +511,11 @@ declare function useNavigationState(): Snapshot<NavigationState>;
  */
 declare function useNavigationParams<T = Record<string, any>>(): T;
 
-declare function useFadeInOut(inTime: number, _keepTime: number, _outTime: number, pause?: boolean, onFinished?: () => void): [SpringValues<{
-    opacity: number;
-}>, SpringRef<{
-    opacity: number;
-}>, () => void];
-declare function useFadeIn(inTime: number, pause?: boolean, onFinished?: () => void): [SpringValues<{
-    opacity: number;
-}>, SpringRef<{
-    opacity: number;
-}>, () => void];
-declare function useFadeOut(outTime: number, pause?: boolean, onFinished?: () => void): [SpringValues<{
-    opacity: number;
-}>, SpringRef<{
-    opacity: number;
-}>, () => void];
-
-/** Advance to the next line in the current story. */
-declare function nextLine(): any;
-/** Set a timed wait, optionally skippable. */
-declare function setWaiting(time: number, skippable: boolean): void;
-/**
- * Custom hook to manage scenario lifecycle (load, start, terminate).
- * The underlying session is resilient to transient remounts such as Fast Refresh.
- *
- * @param {string[]} stories - An array of story names to load.
- * @param {string} [startName] - The name of the story to start.
- * @param {string} [entryName] - The entry point within the story to start from.
- * @param {boolean} [goNextOnLoad=false] - Whether to automatically advance to the next line after loading.
- */
-declare function useScenario(stories: string[], startName?: string, entryName?: string, goNextOnLoad?: boolean): void;
-
-/**
- * Used to load a sound effect and provide a function to play it.
- */
-declare function useSoundEffect(src: string): () => void;
+type ExecutionCursor = {
+    story: string;
+    paragraph: string;
+    markerId?: string;
+};
 
 /** Flow control interface passed to every handler. */
 interface GameControl {
@@ -568,6 +546,12 @@ interface AutoTicketHandle {
     done(): void;
     cancel(): void;
 }
+interface FastForwardOptions {
+    stepLimit?: number;
+    timeLimitMs?: number;
+    onAbort?: (error: Error) => void;
+    warp?: boolean;
+}
 /** Reactive skip state. Actors read via useIsSkipping(). */
 declare const skipState: {
     active: boolean;
@@ -576,10 +560,22 @@ declare const skipState: {
 declare const autoState: {
     active: boolean;
 };
+/** Reactive fast-forward state. Actors read via useIsSeeking(). */
+declare const fastForwardState: {
+    active: boolean;
+};
+/** Reactive warp state. Handlers use this to suppress live-only behavior during warp. */
+declare const warpState: {
+    active: boolean;
+};
 /** Reactively returns whether skip (Ctrl fast-forward) is active. */
 declare function useIsSkipping(): boolean;
 /** Reactively returns whether auto mode is active. */
 declare function useIsAutoing(): boolean;
+/** Reactively returns whether any seek (fast-forward or warp) is active. */
+declare function useIsSeeking(): boolean;
+/** Returns the current seek type, or null when no seek is active. */
+declare function getSeekingType(): 'warp' | 'fast-forward' | null;
 /** Set the default tail delay in milliseconds for newly created auto tickets. */
 declare function setDefaultAutoTailMs(ms: number): void;
 declare function createStage(): {
@@ -599,6 +595,10 @@ declare function createStage(): {
     startAuto: () => void;
     stopAuto: () => void;
     isAutoing: () => boolean;
+    startFastForward: (options?: FastForwardOptions) => void;
+    stopFastForward: () => void;
+    isFastForwarding: () => boolean;
+    resetRuntimeState: () => void;
     bindEvents: () => () => void;
 };
 type StageInstance = ReturnType<typeof createStage>;
@@ -607,7 +607,7 @@ declare function useStageContext(): StageInstance;
 declare function StageContextProvider({ stage, children }: {
     stage: StageInstance;
     children: React.ReactNode;
-}): React$1.FunctionComponentElement<React$1.ProviderProps<{
+}): react.FunctionComponentElement<react.ProviderProps<{
     registerCommandSchema: <T extends ZodType>(schema: T) => () => void;
     registerCommand: <T extends ScenarioCommandBaseType>(commands: string | string[], handler: CommandHandler<T>) => () => void;
     registerTextLine: (handler: TextLineHandler) => () => void;
@@ -624,6 +624,10 @@ declare function StageContextProvider({ stage, children }: {
     startAuto: () => void;
     stopAuto: () => void;
     isAutoing: () => boolean;
+    startFastForward: (options?: FastForwardOptions) => void;
+    stopFastForward: () => void;
+    isFastForwarding: () => boolean;
+    resetRuntimeState: () => void;
     bindEvents: () => () => void;
 } | null>>;
 /**
@@ -664,6 +668,101 @@ declare function useAutoTicket(): (options?: AutoTicketOptions) => AutoTicketHan
  */
 declare function useBeforeHandleCommandCallback(callback: (upcomingCommand: ResolvedCommandLine) => void): void;
 
+interface AppStateAdapter<TState = unknown> {
+    capture(): TState | Promise<TState>;
+    restore(state: TState): void | Promise<void>;
+    switchPage?(page: string, params?: Record<string, unknown>): void | Promise<void>;
+    enterFastForwardMode?(options?: FastForwardOptions): void | Promise<void>;
+    exitFastForwardMode?(): void | Promise<void>;
+    restartCurrentStoryFromHead?(): void | Promise<void>;
+}
+type CombinedCheckpoint<TState = unknown> = {
+    cursor: ExecutionCursor;
+    appState: TState;
+};
+interface DebugSessionConfig {
+    onMarkerEnter?: (checkpoint: CombinedCheckpoint<unknown>) => void | Promise<void>;
+    onError?: (error: unknown) => void | Promise<void>;
+}
+interface DebugSessionController {
+    restoreCheckpoint(markerId: string): Promise<boolean>;
+    warp(options: DebugWarpOptions): Promise<void>;
+    switchPage(page: string, params?: Record<string, unknown>): Promise<void>;
+}
+type DebugWarpBoundary = 'before' | 'after';
+interface DebugWarpOptions {
+    markerId: string;
+    boundary?: DebugWarpBoundary;
+}
+declare function registerAppStateAdapter<TState = unknown>(adapter: AppStateAdapter<TState> | null): void;
+declare function getAppStateAdapter<TState = unknown>(): AppStateAdapter<TState> | null;
+declare function startDebugSession(config?: DebugSessionConfig): Promise<DebugSessionController>;
+declare function stopDebugSession(): Promise<void>;
+declare function useDebugSession(): {
+    startDebugSession: typeof startDebugSession;
+    stopDebugSession: typeof stopDebugSession;
+    restoreCheckpoint: (markerId: string) => Promise<boolean>;
+    warp: (options: DebugWarpOptions) => Promise<void>;
+    switchPage: (page: string, params?: Record<string, unknown>) => Promise<void>;
+    active: boolean;
+    checkpoints: {
+        readonly [x: string]: {
+            readonly cursor: {
+                readonly story: string;
+                readonly paragraph: string;
+                readonly markerId?: string | undefined;
+            };
+            readonly appState: unknown;
+        };
+    };
+    currentCursor: {
+        readonly story: string;
+        readonly paragraph: string;
+        readonly markerId?: string | undefined;
+    } | null;
+    restoring: boolean;
+    lastError: string | null;
+};
+
+declare function stopRuntimeDebugSession(): Promise<void>;
+declare function startRuntimeDebugSession(): Promise<void>;
+
+declare function useFadeInOut(inTime: number, _keepTime: number, _outTime: number, pause?: boolean, onFinished?: () => void): [SpringValues<{
+    opacity: number;
+}>, SpringRef<{
+    opacity: number;
+}>, () => void];
+declare function useFadeIn(inTime: number, pause?: boolean, onFinished?: () => void): [SpringValues<{
+    opacity: number;
+}>, SpringRef<{
+    opacity: number;
+}>, () => void];
+declare function useFadeOut(outTime: number, pause?: boolean, onFinished?: () => void): [SpringValues<{
+    opacity: number;
+}>, SpringRef<{
+    opacity: number;
+}>, () => void];
+
+/** Advance to the next line in the current story. */
+declare function nextLine(): any;
+/** Set a timed wait, optionally skippable. */
+declare function setWaiting(time: number, skippable: boolean): void;
+/**
+ * Custom hook to manage scenario lifecycle (load, start, terminate).
+ * The underlying session is resilient to transient remounts such as Fast Refresh.
+ *
+ * @param {string[]} stories - An array of story names to load.
+ * @param {string} [startName] - The name of the story to start.
+ * @param {string} [entryName] - The entry point within the story to start from.
+ * @param {boolean} [goNextOnLoad=false] - Whether to automatically advance to the next line after loading.
+ */
+declare function useScenario(stories: string[], startName?: string, entryName?: string, goNextOnLoad?: boolean): void;
+
+/**
+ * Used to load a sound effect and provide a function to play it.
+ */
+declare function useSoundEffect(src: string): () => void;
+
 declare module 'zod' {
     interface GlobalMeta {
         title?: string;
@@ -674,4 +773,4 @@ declare module 'zod' {
     }
 }
 
-export { type AnimatedComponent, type AnimatedProps, type AnimationFrameCallbackEvent, type AutoTicketHandle, type AutoTicketOptions, type BeforeUnloadEvent, Command, type CommandHandler, type CustomEvent, type DefaultOverlayName, type DefaultPageName, type FocusEvent, type FocusEventKind, type FullScreenEvent, type FullscreenEventKind, type GameControl, type GameEvent, type Gamepad, type GamepadButton, type GamepadEvent, type GamepadHapticActuator, JSX, type KeyboardLocation, type Literal, MaybePromise, MouseEvent, MoyuEvent, type NavigationState, type Navigator, type NodeEvent, type OverlayConfig, type OverlayDescriptor, type OverlayInfo, OverlayParamsContext, type PageConfig, type PageDescriptor, PageParamsContext, type RegisterNavigator, type ResizeEvent, type ResolvedArgument, type ResolvedCommandLine, type ResolvedSystemCallLine, type RootErrorInfo, type RootHandle, type RootNavigatorList, type RootOptions, type RootUncaughtErrorInfo, type ScenarioCommandBaseType, type ScenarioEvent, type StackNavigatorOptions, StageContextProvider, type StageInstance, type TextLine, type TextLineHandler, type WheelEvent, type WheelEventDeltaMode, type WithAnimated, animated as a, addEventListener, animated, autoState, createRoot, createStackNavigator, createStage, createStaticNavigation, executeNodeCommand, executePluginCommand, getNavigator, globalEventListeners, globalRequestAnimationFrameListeners, moyu, nextLine, setDefaultAutoTailMs, setWaiting, skipState, useAutoBlocker, useAutoTicket, useBeforeHandleCommandCallback, useFadeIn, useFadeInOut, useFadeOut, useInterruptCallback, useIsAutoing, useIsSkipping, useNavigation, useNavigationParams, useNavigationState, useScenario, useSkipBlocker, useSkipCallback, useSoundEffect, useStageContext };
+export { type AnimatedComponent, type AnimatedProps, type AnimationFrameCallbackEvent, type AppStateAdapter, type AutoTicketHandle, type AutoTicketOptions, type BeforeUnloadEvent, type CombinedCheckpoint, Command, type CommandHandler, type CustomEvent, type DebugSessionConfig, type DebugSessionController, type DebugWarpBoundary, type DebugWarpOptions, type DefaultOverlayName, type DefaultPageName, type FastForwardOptions, type FocusEvent, type FocusEventKind, type FullScreenEvent, type FullscreenEventKind, type GameControl, type GameEvent, type Gamepad, type GamepadButton, type GamepadEvent, type GamepadHapticActuator, JSX, type KeyboardLocation, type Literal, MaybePromise, MouseEvent, MoyuEvent, type NavigationState, type Navigator, type NodeEvent, type OverlayConfig, type OverlayDescriptor, type OverlayInfo, OverlayParamsContext, type PageConfig, type PageDescriptor, PageParamsContext, type RegisterNavigator, type ResizeEvent, type ResolvedArgument, type ResolvedCommandLine, type ResolvedSystemCallLine, type RootErrorInfo, type RootHandle, type RootNavigatorList, type RootOptions, type RootUncaughtErrorInfo, type ScenarioCommandBaseType, type ScenarioEvent, type StackNavigatorOptions, StageContextProvider, type StageInstance, type TextLine, type TextLineHandler, type WheelEvent, type WheelEventDeltaMode, type WithAnimated, animated as a, addEventListener, animated, autoState, createRoot, createStackNavigator, createStage, createStaticNavigation, executeNodeCommand, executePluginCommand, fastForwardState, getAppStateAdapter, getNavigator, getSeekingType, globalEventListeners, globalRequestAnimationFrameListeners, moyu, nextLine, registerAppStateAdapter, setDefaultAutoTailMs, setWaiting, skipState, startDebugSession, startRuntimeDebugSession, stopDebugSession, stopRuntimeDebugSession, useAutoBlocker, useAutoTicket, useBeforeHandleCommandCallback, useDebugSession, useFadeIn, useFadeInOut, useFadeOut, useInterruptCallback, useIsAutoing, useIsSeeking, useIsSkipping, useNavigation, useNavigationParams, useNavigationState, useScenario, useSkipBlocker, useSkipCallback, useSoundEffect, useStageContext, warpState };