@momoyu-ink/kit 0.5.5 → 0.6.1

package/dist/lib.mjs

@@ -33,23 +33,33 @@ __export(lib_exports, {
   createStaticNavigation: () => createStaticNavigation,
   executeNodeCommand: () => executeNodeCommand,
   executePluginCommand: () => executePluginCommand,
+  fastForwardState: () => fastForwardState,
+  getAppStateAdapter: () => getAppStateAdapter,
   getNavigator: () => getNavigator,
+  getSeekingType: () => getSeekingType,
   getStageSize: () => getStageSize,
   globalEventListeners: () => globalEventListeners,
   globalRequestAnimationFrameListeners: () => globalRequestAnimationFrameListeners,
   moyu: () => moyu_exports,
   nextLine: () => nextLine,
+  registerAppStateAdapter: () => registerAppStateAdapter,
   setDefaultAutoTailMs: () => setDefaultAutoTailMs,
   setWaiting: () => setWaiting,
   skipState: () => skipState,
+  startDebugSession: () => startDebugSession,
+  startRuntimeDebugSession: () => startRuntimeDebugSession,
+  stopDebugSession: () => stopDebugSession,
+  stopRuntimeDebugSession: () => stopRuntimeDebugSession,
   useAutoBlocker: () => useAutoBlocker,
   useAutoTicket: () => useAutoTicket,
   useBeforeHandleCommandCallback: () => useBeforeHandleCommandCallback,
+  useDebugSession: () => useDebugSession,
   useFadeIn: () => useFadeIn,
   useFadeInOut: () => useFadeInOut,
   useFadeOut: () => useFadeOut,
   useInterruptCallback: () => useInterruptCallback,
   useIsAutoing: () => useIsAutoing,
+  useIsSeeking: () => useIsSeeking,
   useIsSkipping: () => useIsSkipping,
   useNavigation: () => useNavigation,
   useNavigationParams: () => useNavigationParams,
@@ -58,7 +68,8 @@ __export(lib_exports, {
   useSkipBlocker: () => useSkipBlocker,
   useSkipCallback: () => useSkipCallback,
   useSoundEffect: () => useSoundEffect,
-  useStageContext: () => useStageContext
+  useStageContext: () => useStageContext,
+  warpState: () => warpState
 });
 
 // src/react.ts
@@ -384,8 +395,35 @@ function createRoot(options) {
 
 // src/sandbox.ts
 var JS_GLOBAL_KEYS = new Set(Object.getOwnPropertyNames(globalThis));
-var JS_GLOBAL_KEYS_EXCLUDED = /* @__PURE__ */ new Set(["window", "globalThis", "ARCHIVE", "GLOBAL"]);
-JS_GLOBAL_KEYS_EXCLUDED.forEach((key) => JS_GLOBAL_KEYS.delete(key));
+var JS_GLOBAL_KEYS_EXCLUDED = /* @__PURE__ */ new Set(["window", "globalThis", "LOCAL", "ARCHIVE", "GLOBAL"]);
+JS_GLOBAL_KEYS_EXCLUDED.forEach((key) => {
+  JS_GLOBAL_KEYS.delete(key);
+});
+var localVariables = new Proxy(
+  {},
+  {
+    get(_, key) {
+      if (typeof key === "string") {
+        return executePluginCommand("scenario", {
+          subCommand: "getLocalVariable",
+          name: key
+        });
+      }
+      return void 0;
+    },
+    set(_, key, value) {
+      if (typeof key === "string") {
+        executePluginCommand("scenario", {
+          subCommand: "setLocalVariable",
+          name: key,
+          value
+        });
+        return true;
+      }
+      return false;
+    }
+  }
+);
 var archiveVariables = new Proxy(
   {},
   {
@@ -437,15 +475,16 @@ var globalVariables = new Proxy(
   }
 );
 function safeEval(code, sandbox) {
-  const proxy3 = new Proxy(sandbox, {
+  const proxy4 = new Proxy(sandbox, {
     has(target, key) {
       if (typeof key === "string" && JS_GLOBAL_KEYS.has(key)) {
         return false;
       }
-      return key in target || key === "ARCHIVE" || key === "GLOBAL" || key === "window" || key === "globalThis";
+      return key in target || key === "LOCAL" || key === "ARCHIVE" || key === "GLOBAL" || key === "window" || key === "globalThis";
     },
     get(target, key) {
-      if (key === "window" || key === "globalThis") return proxy3;
+      if (key === "window" || key === "globalThis") return proxy4;
+      if (key === "LOCAL") return localVariables;
       if (key === "ARCHIVE") return archiveVariables;
       if (key === "GLOBAL") return globalVariables;
       if (key === Symbol.unscopables) return void 0;
@@ -456,7 +495,7 @@ function safeEval(code, sandbox) {
       return true;
     }
   });
-  return new Function("sandbox", `with(sandbox) { return (${code}) }`).bind(proxy3)(proxy3);
+  return new Function("sandbox", `with(sandbox) { return (${code}) }`).bind(proxy4)(proxy4);
 }
 globalThis.__moyu_eval_sandbox = (code) => {
   try {
@@ -639,9 +678,9 @@ function getStageSize() {
 }
 
 // src/components/navigation.tsx
-import React2 from "react";
 import { createContext, useContext } from "react";
 import { proxy, useSnapshot } from "valtio";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 var PageParamsContext = createContext(void 0);
 var OverlayParamsContext = createContext(void 0);
 var overlayIdCounter = 0;
@@ -697,6 +736,9 @@ function createStackNavigator(options) {
         delete navigationState.pageParams[page];
       }
     },
+    hasPage: (page) => {
+      return normalizedPages[page] !== void 0;
+    },
     goBack: () => {
       console.warn("goBack() not implemented yet");
     },
@@ -752,11 +794,14 @@ function createStaticNavigation(navigator) {
     const { pages, overlays } = navigator._descriptors;
     const pageDescriptor = pages[navState.currentPage];
     const Page = pageDescriptor?.component || (() => null);
-    return /* @__PURE__ */ React2.createElement(React2.Fragment, null, /* @__PURE__ */ React2.createElement(PageParamsContext.Provider, { value: navState.pageParams[navState.currentPage] }, /* @__PURE__ */ React2.createElement(Page, null)), navState.overlayStack.map((overlay) => {
-      const overlayDescriptor = overlays[overlay.type];
-      const OverlayComponent = overlayDescriptor?.component || (() => null);
-      return /* @__PURE__ */ React2.createElement(OverlayParamsContext.Provider, { key: overlay.id, value: navState.overlayParams[overlay.id] }, /* @__PURE__ */ React2.createElement(OverlayComponent, null));
-    }));
+    return /* @__PURE__ */ jsxs(Fragment, { children: [
+      /* @__PURE__ */ jsx(PageParamsContext.Provider, { value: navState.pageParams[navState.currentPage], children: /* @__PURE__ */ jsx(Page, {}) }),
+      navState.overlayStack.map((overlay) => {
+        const overlayDescriptor = overlays[overlay.type];
+        const OverlayComponent = overlayDescriptor?.component || (() => null);
+        return /* @__PURE__ */ jsx(OverlayParamsContext.Provider, { value: navState.overlayParams[overlay.id], children: /* @__PURE__ */ jsx(OverlayComponent, {}) }, overlay.id);
+      })
+    ] });
   };
 }
 function getNavigator() {
@@ -775,6 +820,624 @@ function useNavigationParams() {
   return overlayParams ?? pageParams ?? {};
 }
 
+// src/debug/session.ts
+import { useSnapshot as useSnapshot2, proxy as proxy2 } from "valtio";
+var debugState = proxy2({
+  active: false,
+  checkpoints: {},
+  currentCursor: null,
+  restoring: false,
+  lastError: null
+});
+var appStateAdapter = null;
+var currentConfig = {
+  onMarkerEnter: () => {
+  },
+  onError: () => {
+  }
+};
+var disposeMarkerListener = null;
+var disposeFinishedListener = null;
+var disposeWarpFinishedListener = null;
+var debugOperationQueue = Promise.resolve();
+var activeFastForward = null;
+var activeWarp = null;
+function enqueueDebugOperation(task) {
+  const nextTask = debugOperationQueue.then(task, task);
+  debugOperationQueue = nextTask.then(
+    () => void 0,
+    () => void 0
+  );
+  return nextTask;
+}
+function executeScenarioCommand(payload) {
+  return Promise.resolve(executePluginCommand("scenario", payload));
+}
+function toErrorMessage(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}
+function isPromiseLike(value) {
+  return !!value && typeof value.then === "function";
+}
+function reportDebugSessionError(error) {
+  debugState.lastError = toErrorMessage(error);
+  void Promise.resolve(currentConfig.onError(error));
+}
+function clearLocalRuntimeState() {
+  debugState.checkpoints = {};
+  debugState.currentCursor = null;
+  debugState.restoring = false;
+  debugState.lastError = null;
+}
+async function doSettleActiveSeek(op, clearSlot, error) {
+  if (!op) {
+    return;
+  }
+  clearSlot();
+  try {
+    await appStateAdapter?.exitFastForwardMode?.();
+  } catch (exitError) {
+    if (error === void 0) {
+      error = exitError;
+    }
+  }
+  if (error === void 0) {
+    op.resolve();
+    return;
+  }
+  op.reject(error);
+}
+async function settleActiveFastForward(error) {
+  await doSettleActiveSeek(activeFastForward, () => {
+    activeFastForward = null;
+  }, error);
+}
+async function settleActiveWarp(error) {
+  await doSettleActiveSeek(activeWarp, () => {
+    activeWarp = null;
+  }, error);
+}
+async function clearRemoteCheckpoints() {
+  await executeScenarioCommand({ subCommand: "clearCheckpoints" });
+}
+async function syncLocalWarpCheckpoint(targetMarkerId) {
+  const cursor = await executeScenarioCommand({
+    subCommand: "getExecutionCursor"
+  });
+  const checkpointCursor = cursor ? {
+    story: cursor.story,
+    paragraph: cursor.paragraph,
+    markerId: targetMarkerId
+  } : debugState.currentCursor ? {
+    story: debugState.currentCursor.story,
+    paragraph: debugState.currentCursor.paragraph,
+    markerId: targetMarkerId
+  } : null;
+  if (!checkpointCursor) {
+    return;
+  }
+  const checkpoint = {
+    cursor: checkpointCursor,
+    appState: appStateAdapter ? await appStateAdapter.capture() : void 0
+  };
+  debugState.currentCursor = checkpointCursor;
+  debugState.checkpoints[targetMarkerId] = checkpoint;
+  await currentConfig.onMarkerEnter(checkpoint);
+}
+function captureCheckpointAppStateSync() {
+  if (!appStateAdapter) {
+    return void 0;
+  }
+  const appState = appStateAdapter.capture();
+  if (isPromiseLike(appState)) {
+    throw new Error("Async app state capture is not supported for debug checkpoints");
+  }
+  return appState;
+}
+function notifyMarkerEnter(checkpoint) {
+  try {
+    const result = currentConfig.onMarkerEnter(checkpoint);
+    if (isPromiseLike(result)) {
+      void result.catch(reportDebugSessionError);
+    }
+  } catch (error) {
+    reportDebugSessionError(error);
+  }
+}
+async function prepareJumpStart(markerId) {
+  const checkpoint = debugState.checkpoints[markerId];
+  if (checkpoint) {
+    const restored2 = await executeScenarioCommand({
+      subCommand: "restoreCheckpoint",
+      key: markerId
+    });
+    if (!restored2) {
+      throw new Error(`Failed to restore checkpoint ${markerId}`);
+    }
+    if (appStateAdapter) {
+      await appStateAdapter.restore(checkpoint.appState);
+    }
+    debugState.currentCursor = checkpoint.cursor;
+    return false;
+  }
+  const lookup = await executeScenarioCommand({
+    subCommand: "getFastForwardCheckpoint",
+    key: markerId
+  });
+  if (!lookup.markerExists) {
+    throw new Error(`Marker ${markerId} is not available in the current story`);
+  }
+  const startCheckpointKey = lookup.checkpointKey ?? null;
+  if (!startCheckpointKey) {
+    if (!appStateAdapter?.restartCurrentStoryFromHead) {
+      throw new Error("Restarting the current story from head is not supported by the app state adapter");
+    }
+    await appStateAdapter.restartCurrentStoryFromHead();
+    debugState.checkpoints = {};
+    debugState.currentCursor = null;
+    return true;
+  }
+  const startCheckpoint = debugState.checkpoints[startCheckpointKey];
+  if (!startCheckpoint) {
+    throw new Error(`Local checkpoint ${startCheckpointKey} not found`);
+  }
+  const restored = await executeScenarioCommand({
+    subCommand: "restoreCheckpoint",
+    key: startCheckpointKey
+  });
+  if (!restored) {
+    throw new Error(`Failed to restore checkpoint ${startCheckpointKey}`);
+  }
+  if (appStateAdapter) {
+    await appStateAdapter.restore(startCheckpoint.appState);
+  }
+  debugState.currentCursor = startCheckpoint.cursor;
+  return true;
+}
+function handleMarkerEnter(marker) {
+  const checkpoint = {
+    cursor: {
+      story: marker.story,
+      paragraph: marker.paragraph,
+      markerId: marker.markerId
+    },
+    appState: captureCheckpointAppStateSync()
+  };
+  debugState.currentCursor = checkpoint.cursor;
+  debugState.checkpoints[marker.markerId] = checkpoint;
+  notifyMarkerEnter(checkpoint);
+  if (activeFastForward?.targetMarkerId === marker.markerId) {
+    void settleActiveFastForward();
+  }
+}
+async function runFastForwardToMarker(markerId) {
+  if (!appStateAdapter?.enterFastForwardMode || !appStateAdapter?.exitFastForwardMode) {
+    throw new Error("Fast-forward mode is not supported by the app state adapter");
+  }
+  if (activeFastForward !== null || activeWarp !== null) {
+    throw new Error("A debug seek operation is already active");
+  }
+  await appStateAdapter.enterFastForwardMode({
+    onAbort: (error) => {
+      void settleActiveFastForward(error);
+    }
+  });
+  const completion = new Promise((resolve, reject) => {
+    activeFastForward = {
+      targetMarkerId: markerId,
+      resolve,
+      reject
+    };
+  });
+  try {
+    await executeScenarioCommand({ subCommand: "nextLine" });
+  } catch (error) {
+    await settleActiveFastForward(error);
+  }
+  await completion;
+}
+async function runWarp(options) {
+  if (!appStateAdapter?.enterFastForwardMode || !appStateAdapter?.exitFastForwardMode) {
+    throw new Error("Warp mode is not supported by the app state adapter");
+  }
+  if (activeFastForward !== null || activeWarp !== null) {
+    throw new Error("A debug seek operation is already active");
+  }
+  const boundary = options.boundary ?? "before";
+  await appStateAdapter.enterFastForwardMode({ warp: true });
+  const completion = new Promise((resolve, reject) => {
+    activeWarp = {
+      targetMarkerId: options.markerId,
+      resolve,
+      reject
+    };
+  });
+  try {
+    await executeScenarioCommand({
+      subCommand: "warp",
+      markerId: options.markerId,
+      boundary
+    });
+  } catch (error) {
+    await settleActiveWarp(error);
+  }
+  await completion;
+}
+var debugSessionController = {
+  async restoreCheckpoint(markerId) {
+    debugState.restoring = true;
+    debugState.lastError = null;
+    try {
+      const needsFastForward = await enqueueDebugOperation(async () => prepareJumpStart(markerId));
+      if (needsFastForward) {
+        await runFastForwardToMarker(markerId);
+      }
+      return true;
+    } catch (error) {
+      debugState.lastError = toErrorMessage(error);
+      throw error;
+    } finally {
+      debugState.restoring = false;
+    }
+  },
+  async warp(options) {
+    debugState.restoring = true;
+    debugState.lastError = null;
+    try {
+      const needsWarp = await enqueueDebugOperation(async () => prepareJumpStart(options.markerId));
+      if (needsWarp) {
+        await runWarp(options);
+      }
+    } catch (error) {
+      debugState.lastError = toErrorMessage(error);
+      throw error;
+    } finally {
+      debugState.restoring = false;
+    }
+  },
+  async switchPage(page, params) {
+    return enqueueDebugOperation(async () => {
+      debugState.lastError = null;
+      try {
+        if (!appStateAdapter?.switchPage) {
+          throw new Error("Page switching is not supported by the app state adapter");
+        }
+        await appStateAdapter.switchPage(page, params);
+      } catch (error) {
+        debugState.lastError = toErrorMessage(error);
+        throw error;
+      }
+    });
+  }
+};
+function registerAppStateAdapter(adapter) {
+  appStateAdapter = adapter;
+}
+function getAppStateAdapter() {
+  return appStateAdapter;
+}
+async function startDebugSession(config = {}) {
+  await stopDebugSession();
+  currentConfig = {
+    onMarkerEnter: config.onMarkerEnter ?? (() => {
+    }),
+    onError: config.onError ?? (() => {
+    })
+  };
+  clearLocalRuntimeState();
+  debugState.active = true;
+  disposeMarkerListener = addEventListener("scenariomarkerenter", (event) => {
+    const marker = event;
+    try {
+      handleMarkerEnter(marker);
+    } catch (error) {
+      reportDebugSessionError(error);
+    }
+  });
+  disposeFinishedListener = addEventListener("scenariofinished", () => {
+    debugState.currentCursor = null;
+    if (activeFastForward) {
+      void settleActiveFastForward(
+        new Error(`Marker ${activeFastForward.targetMarkerId} was not reached before the scenario finished`)
+      );
+    }
+    if (activeWarp) {
+      const targetMarkerId = activeWarp.targetMarkerId;
+      void settleActiveWarp(new Error(`Marker ${targetMarkerId} was not reached before the scenario finished`));
+    }
+  });
+  disposeWarpFinishedListener = addEventListener("scenariowarpfinished", () => {
+    const warp = activeWarp;
+    if (!warp) {
+      return;
+    }
+    void enqueueDebugOperation(async () => {
+      try {
+        await syncLocalWarpCheckpoint(warp.targetMarkerId);
+        await settleActiveWarp();
+      } catch (error) {
+        debugState.lastError = toErrorMessage(error);
+        await settleActiveWarp(error);
+        await currentConfig.onError(error);
+      }
+    });
+  });
+  try {
+    await clearRemoteCheckpoints();
+    debugState.currentCursor = await executeScenarioCommand({
+      subCommand: "getExecutionCursor"
+    });
+  } catch (error) {
+    debugState.active = false;
+    clearLocalRuntimeState();
+    disposeMarkerListener?.();
+    disposeFinishedListener?.();
+    disposeWarpFinishedListener?.();
+    disposeMarkerListener = null;
+    disposeFinishedListener = null;
+    disposeWarpFinishedListener = null;
+    await currentConfig.onError(error);
+    throw error;
+  }
+  return debugSessionController;
+}
+async function stopDebugSession() {
+  disposeMarkerListener?.();
+  disposeFinishedListener?.();
+  disposeWarpFinishedListener?.();
+  disposeMarkerListener = null;
+  disposeFinishedListener = null;
+  disposeWarpFinishedListener = null;
+  await settleActiveFastForward(new Error("Debug session stopped"));
+  await settleActiveWarp(new Error("Debug session stopped"));
+  if (debugState.active) {
+    await enqueueDebugOperation(async () => {
+      try {
+        await clearRemoteCheckpoints();
+      } catch (error) {
+        debugState.lastError = toErrorMessage(error);
+        await currentConfig.onError(error);
+      }
+    });
+  }
+  debugState.active = false;
+  clearLocalRuntimeState();
+}
+function clearDebugSessionRuntimeState() {
+  clearLocalRuntimeState();
+  void settleActiveFastForward(new Error("Debug session runtime state cleared"));
+  void settleActiveWarp(new Error("Debug session runtime state cleared"));
+  if (!debugState.active) {
+    return;
+  }
+  void enqueueDebugOperation(async () => {
+    try {
+      await clearRemoteCheckpoints();
+    } catch (error) {
+      debugState.lastError = toErrorMessage(error);
+      await currentConfig.onError(error);
+    }
+  });
+}
+function useDebugSession() {
+  const snapshot = useSnapshot2(debugState);
+  return {
+    ...snapshot,
+    startDebugSession,
+    stopDebugSession,
+    restoreCheckpoint: debugSessionController.restoreCheckpoint,
+    warp: debugSessionController.warp,
+    switchPage: debugSessionController.switchPage
+  };
+}
+
+// src/debug/runtime.ts
+var currentConnection = null;
+var currentController = null;
+var bufferedRequestMessages = [];
+function getRuntimeWebSocket() {
+  return globalThis.WebSocket ?? null;
+}
+function isJumpRequestMessage(message) {
+  return message.type === "jump:request" && typeof message.sessionId === "string" && typeof message.requestId === "number" && typeof message.markerId === "string" && (message.boundary === void 0 || message.boundary === "before" || message.boundary === "after") && (message.strategy === void 0 || message.strategy === "fast-forward" || message.strategy === "warp");
+}
+function isRouteRequestMessage(message) {
+  return message.type === "route:request" && typeof message.sessionId === "string" && typeof message.requestId === "number" && typeof message.page === "string" && (message.params === void 0 || typeof message.params === "object" && message.params !== null && !Array.isArray(message.params));
+}
+function sendRuntimeDebugMessage(socket, message) {
+  const RuntimeWebSocket = getRuntimeWebSocket();
+  if (!RuntimeWebSocket || socket.readyState !== RuntimeWebSocket.OPEN) {
+    return;
+  }
+  socket.send(JSON.stringify(message));
+}
+function clearBufferedRequestMessages() {
+  bufferedRequestMessages = [];
+}
+function bufferRequestMessage(message) {
+  bufferedRequestMessages.push(message);
+}
+function flushBufferedRequestMessages(socket, sessionId) {
+  const messages = bufferedRequestMessages;
+  bufferedRequestMessages = [];
+  for (const message of messages) {
+    handleRuntimeDebugRequest(socket, sessionId, message);
+  }
+}
+function handleRuntimeDebugRequest(socket, sessionId, message) {
+  const controller = currentController;
+  if (!controller) {
+    bufferRequestMessage(message);
+    return;
+  }
+  if (isJumpRequestMessage(message)) {
+    const runJump = message.strategy === "warp" ? controller.warp({
+      markerId: message.markerId,
+      boundary: message.boundary
+    }).then(() => true) : controller.restoreCheckpoint(message.markerId);
+    void runJump.then((restored) => {
+      if (!restored) {
+        sendRuntimeDebugMessage(socket, {
+          type: "jump:error",
+          sessionId,
+          requestId: message.requestId,
+          markerId: message.markerId,
+          error: "Checkpoint not found"
+        });
+        return;
+      }
+      sendRuntimeDebugMessage(socket, {
+        type: "jump:done",
+        sessionId,
+        requestId: message.requestId,
+        markerId: message.markerId
+      });
+    }).catch((error) => {
+      sendRuntimeDebugMessage(socket, {
+        type: "jump:error",
+        sessionId,
+        requestId: message.requestId,
+        markerId: message.markerId,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    });
+    return;
+  }
+  void controller.switchPage(message.page, message.params).then(() => {
+    sendRuntimeDebugMessage(socket, {
+      type: "route:done",
+      sessionId,
+      requestId: message.requestId,
+      page: message.page
+    });
+  }).catch((error) => {
+    sendRuntimeDebugMessage(socket, {
+      type: "route:error",
+      sessionId,
+      requestId: message.requestId,
+      page: message.page,
+      error: error instanceof Error ? error.message : String(error)
+    });
+  });
+}
+async function readDebugParams() {
+  const rawParams = await executePluginCommand("system", {
+    subCommand: "getParams"
+  });
+  if (!rawParams) {
+    return {};
+  }
+  try {
+    const parsed = JSON.parse(rawParams);
+    return {
+      debug: parsed.debug === true,
+      debugSessionId: typeof parsed.debugSessionId === "string" ? parsed.debugSessionId : void 0,
+      debugWsUrl: typeof parsed.debugWsUrl === "string" ? parsed.debugWsUrl : void 0
+    };
+  } catch {
+    return {};
+  }
+}
+async function stopRuntimeDebugSession() {
+  const connection = currentConnection;
+  currentConnection = null;
+  currentController = null;
+  clearBufferedRequestMessages();
+  const RuntimeWebSocket = getRuntimeWebSocket();
+  await stopDebugSession();
+  if (!connection) {
+    return;
+  }
+  if (RuntimeWebSocket && (connection.socket.readyState === RuntimeWebSocket.OPEN || connection.socket.readyState === RuntimeWebSocket.CONNECTING)) {
+    connection.socket.close();
+  }
+}
+async function startRuntimeDebugSession() {
+  await stopRuntimeDebugSession();
+  const params = await readDebugParams();
+  if (params.debug !== true || !params.debugSessionId || !params.debugWsUrl) {
+    return;
+  }
+  const RuntimeWebSocket = getRuntimeWebSocket();
+  if (!RuntimeWebSocket) {
+    return;
+  }
+  const socket = new RuntimeWebSocket(params.debugWsUrl);
+  const sessionId = params.debugSessionId;
+  currentConnection = { sessionId, socket };
+  socket.onopen = () => {
+    if (currentConnection?.socket !== socket) {
+      socket.close();
+      return;
+    }
+    void startDebugSession({
+      onMarkerEnter(checkpoint) {
+        if (!checkpoint.cursor.markerId) {
+          return;
+        }
+        sendRuntimeDebugMessage(socket, {
+          type: "marker:enter",
+          sessionId,
+          markerId: checkpoint.cursor.markerId,
+          story: checkpoint.cursor.story,
+          paragraph: checkpoint.cursor.paragraph
+        });
+      },
+      onError(error) {
+        console.error("[debug] runtime debug session error:", error);
+      }
+    }).then((controller) => {
+      currentController = controller;
+      flushBufferedRequestMessages(socket, sessionId);
+    }).catch((error) => {
+      console.error("[debug] failed to start runtime debug session:", error);
+      socket.close();
+    });
+  };
+  socket.onclose = () => {
+    if (currentConnection?.socket !== socket) {
+      return;
+    }
+    currentConnection = null;
+    currentController = null;
+    clearBufferedRequestMessages();
+    void stopDebugSession();
+  };
+  socket.onerror = (event) => {
+    if (currentConnection?.socket !== socket) {
+      return;
+    }
+    console.error("[debug] runtime websocket error:", event);
+  };
+  socket.onmessage = (event) => {
+    if (currentConnection?.socket !== socket) {
+      return;
+    }
+    try {
+      const message = JSON.parse(String(event.data));
+      if (message.sessionId && message.sessionId !== sessionId) {
+        return;
+      }
+      if (isJumpRequestMessage(message)) {
+        handleRuntimeDebugRequest(socket, sessionId, message);
+        return;
+      }
+      if (isRouteRequestMessage(message)) {
+        handleRuntimeDebugRequest(socket, sessionId, message);
+        return;
+      }
+      if (message.type && message.type !== "session:init") {
+        console.debug("[debug] runtime received message:", message);
+      }
+    } catch (error) {
+      console.error("[debug] failed to parse runtime debug message:", error);
+    }
+  };
+}
+
 // src/hooks/useFadeInOut.ts
 function useFadeInOut(inTime, _keepTime, _outTime, pause = false, onFinished) {
   const [style, api] = (0, spring_exports.useSpring)(
@@ -877,11 +1540,13 @@ async function terminateCurrentScenario() {
     await executePluginCommand("scenario", {
       subCommand: "terminateStory"
     });
+    clearDebugSessionRuntimeState();
   } catch (error) {
     console.error("Failed to terminate scenario:", error);
   }
 }
 async function startScenarioSession(session, config) {
+  clearDebugSessionRuntimeState();
   for (const story of config.stories) {
     if (!isCurrentScenarioSession(session)) return;
     try {
@@ -1048,18 +1713,30 @@ function useSoundEffect(src) {
 
 // src/hooks/useStage.ts
 import { createContext as createContext2, useContext as useContext2, useEffect as useEffect3, createElement, useCallback as useCallback2 } from "react";
-import { proxy as proxy2, useSnapshot as useSnapshot2 } from "valtio";
+import { proxy as proxy3, useSnapshot as useSnapshot3 } from "valtio";
 var SKIP_INTERVAL_MS = 80;
+var DEFAULT_FAST_FORWARD_STEP_LIMIT = 1e4;
+var DEFAULT_FAST_FORWARD_TIME_LIMIT_MS = 3e3;
 var autoRuntime = {
   defaultTailMs: 0
 };
-var skipState = proxy2({ active: false });
-var autoState = proxy2({ active: false });
+var skipState = proxy3({ active: false });
+var autoState = proxy3({ active: false });
+var fastForwardState = proxy3({ active: false });
+var warpState = proxy3({ active: false });
 function useIsSkipping() {
-  return useSnapshot2(skipState).active;
+  return useSnapshot3(skipState).active;
 }
 function useIsAutoing() {
-  return useSnapshot2(autoState).active;
+  return useSnapshot3(autoState).active;
+}
+function useIsSeeking() {
+  return useSnapshot3(fastForwardState).active;
+}
+function getSeekingType() {
+  if (warpState.active) return "warp";
+  if (fastForwardState.active) return "fast-forward";
+  return null;
 }
 function setDefaultAutoTailMs(ms) {
   if (!Number.isFinite(ms)) {
@@ -1167,6 +1844,101 @@ function createStage() {
   let _autoBarrierSeq = 0;
   let _autoTicketSeq = 0;
   const _pendingAutoTickets = /* @__PURE__ */ new Map();
+  let _fastForwardRuntime = null;
+  let _managedAdvanceInFlight = false;
+  let _managedAdvancePending = false;
+  function resetManagedAdvanceState() {
+    _managedAdvanceInFlight = false;
+    _managedAdvancePending = false;
+  }
+  function clearFastForwardRuntime() {
+    _fastForwardRuntime = null;
+    resetManagedAdvanceState();
+  }
+  function stopFastForwardInternal() {
+    fastForwardState.active = false;
+    warpState.active = false;
+    clearFastForwardRuntime();
+  }
+  function abortFastForward(error) {
+    const runtime = _fastForwardRuntime;
+    stopFastForwardInternal();
+    if (!runtime?.onAbort) {
+      return;
+    }
+    try {
+      runtime.onAbort(error);
+    } catch (abortError) {
+      console.error("Error in fast-forward abort callback:", abortError);
+    }
+  }
+  function canAdvanceFastForward() {
+    if (!fastForwardState.active || _fastForwardRuntime === null) {
+      return true;
+    }
+    const elapsedMs = Date.now() - _fastForwardRuntime.startedAt;
+    if (elapsedMs > _fastForwardRuntime.timeLimitMs) {
+      abortFastForward(new Error(`Fast forward exceeded time limit (${_fastForwardRuntime.timeLimitMs}ms)`));
+      return false;
+    }
+    _fastForwardRuntime.stepCount += 1;
+    if (_fastForwardRuntime.stepCount > _fastForwardRuntime.stepLimit) {
+      abortFastForward(new Error(`Fast forward exceeded step limit (${_fastForwardRuntime.stepLimit})`));
+      return false;
+    }
+    return true;
+  }
+  function normalizeAdvanceError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+  }
+  function isManagedAdvanceActive() {
+    return fastForwardState.active || skipState.active || autoState.active;
+  }
+  function canScheduleManagedAdvance() {
+    if (fastForwardState.active) {
+      return canAdvanceFastForward();
+    }
+    return true;
+  }
+  function handleManagedAdvanceError(error) {
+    console.error("Failed to advance scenario:", error);
+    if (fastForwardState.active) {
+      abortFastForward(normalizeAdvanceError(error));
+    }
+  }
+  function scheduleManagedAdvance() {
+    if (!isManagedAdvanceActive()) {
+      _managedAdvancePending = false;
+      return;
+    }
+    if (_managedAdvanceInFlight) {
+      _managedAdvancePending = true;
+      return;
+    }
+    if (!canScheduleManagedAdvance()) {
+      _managedAdvancePending = false;
+      return;
+    }
+    _managedAdvanceInFlight = true;
+    _managedAdvancePending = false;
+    void Promise.resolve(nextLine()).catch(handleManagedAdvanceError).finally(() => {
+      _managedAdvanceInFlight = false;
+      if (!isManagedAdvanceActive()) {
+        _managedAdvancePending = false;
+        return;
+      }
+      if (_managedAdvancePending) {
+        scheduleManagedAdvance();
+      }
+    });
+  }
+  function requestNextLine() {
+    if (isManagedAdvanceActive()) {
+      scheduleManagedAdvance();
+      return;
+    }
+    void Promise.resolve(nextLine()).catch(handleManagedAdvanceError);
+  }
   function clearAutoResumeTimer() {
     if (_autoResumeTimer !== null) {
       clearTimeout(_autoResumeTimer);
@@ -1201,7 +1973,7 @@ function createStage() {
       if (!autoState.active) return;
       if (_autoBarrier === null || _autoBarrier.id !== barrierId) return;
       _autoBarrier = null;
-      void nextLine();
+      requestNextLine();
     }, safeDelayMs);
   }
   function trySettleAutoBarrier(barrier) {
@@ -1337,7 +2109,7 @@ function createStage() {
         return;
       }
       if (_autoBarrier === null) {
-        void nextLine();
+        requestNextLine();
       }
     }, autoRuntime.defaultTailMs);
   }
@@ -1345,11 +2117,12 @@ function createStage() {
     if (_skipTimer !== null) clearTimeout(_skipTimer);
     _skipTimer = setTimeout(() => {
       _skipTimer = null;
-      if (skipState.active) nextLine();
+      if (skipState.active) requestNextLine();
     }, SKIP_INTERVAL_MS);
   }
   function startSkip() {
     if (skipState.active) return;
+    if (fastForwardState.active) return;
     if (isAnyBlockerActive()) return;
     skipState.active = true;
     invokeSkipCallbacks();
@@ -1361,7 +2134,7 @@ function createStage() {
     if (_skipTimer !== null) {
       clearTimeout(_skipTimer);
       _skipTimer = null;
-      nextLine();
+      requestNextLine();
     }
   }
   function isSkipping() {
@@ -1369,6 +2142,7 @@ function createStage() {
   }
   function startAuto() {
     if (autoState.active) return;
+    if (fastForwardState.active) return;
     if (isAnyAutoBlockerActive()) return;
     autoState.active = true;
     tryInterrupt();
@@ -1386,12 +2160,58 @@ function createStage() {
   function isAutoing() {
     return autoState.active;
   }
+  function startFastForward(options) {
+    if (fastForwardState.active) return;
+    resetRuntimeState();
+    _fastForwardRuntime = {
+      stepLimit: Math.max(1, options?.stepLimit ?? DEFAULT_FAST_FORWARD_STEP_LIMIT),
+      timeLimitMs: Math.max(1, options?.timeLimitMs ?? DEFAULT_FAST_FORWARD_TIME_LIMIT_MS),
+      stepCount: 0,
+      startedAt: Date.now(),
+      onAbort: options?.onAbort,
+      warp: options?.warp === true
+    };
+    fastForwardState.active = true;
+    warpState.active = _fastForwardRuntime.warp;
+  }
+  function stopFastForward() {
+    stopFastForwardInternal();
+  }
+  function isFastForwarding() {
+    return fastForwardState.active;
+  }
+  function resetRuntimeState() {
+    skipState.active = false;
+    autoState.active = false;
+    fastForwardState.active = false;
+    warpState.active = false;
+    clearFastForwardRuntime();
+    if (_skipTimer !== null) {
+      clearTimeout(_skipTimer);
+      _skipTimer = null;
+    }
+    if (_autoTimer !== null) {
+      clearTimeout(_autoTimer);
+      _autoTimer = null;
+    }
+    clearAutoBarrier();
+    clearPendingAutoTickets();
+  }
   function buildControl() {
-    let handled = false;
+    const warpActive = warpState.active;
+    let handled = warpActive;
     let unskippableFlag = false;
+    const inertRecordId = "__warp__";
     const control = {
       setWaiting(time, skippable) {
         handled = true;
+        if (warpActive) {
+          return;
+        }
+        if (fastForwardState.active) {
+          requestNextLine();
+          return;
+        }
         if (skipState.active) {
           invokeSkipCallbacks();
           scheduleSkipNextLine();
@@ -1408,6 +2228,13 @@ function createStage() {
       },
       hold() {
         handled = true;
+        if (warpActive) {
+          return;
+        }
+        if (fastForwardState.active) {
+          requestNextLine();
+          return;
+        }
         if (skipState.active && !unskippableFlag) {
           if (isAnyBlockerActive()) {
             stopSkip();
@@ -1426,12 +2253,21 @@ function createStage() {
       },
       nextLine() {
         handled = true;
-        void nextLine();
+        if (warpActive) {
+          return;
+        }
+        requestNextLine();
       },
       unskippable() {
+        if (warpActive) {
+          return;
+        }
         unskippableFlag = true;
       },
       record(meta) {
+        if (warpActive) {
+          return inertRecordId;
+        }
         const result = executePluginCommand("scenario", {
           subCommand: "record",
           meta
@@ -1470,19 +2306,19 @@ function createStage() {
       cmd = transformCommand(e);
     } catch (err) {
       console.error("Failed to transform scenario command:", err);
-      void nextLine();
+      requestNextLine();
       return;
     }
     const handler = commandHandlers.get(cmd.command);
     if (!handler) {
       console.warn(`[Stage] No handler registered for command "${cmd.command}". Auto-advancing.`);
-      void nextLine();
+      requestNextLine();
       return;
     }
     const { control, wasHandled } = buildControl();
     handler(cmd, control);
     if (!wasHandled()) {
-      void nextLine();
+      requestNextLine();
     }
   }
   function dispatchTextLine(e) {
@@ -1491,7 +2327,7 @@ function createStage() {
       handler(e, control);
     }
     if (!wasHandled()) {
-      void nextLine();
+      requestNextLine();
     }
   }
   function invokeSkipCallbacks() {
@@ -1539,6 +2375,10 @@ function createStage() {
     startAuto,
     stopAuto,
     isAutoing,
+    startFastForward,
+    stopFastForward,
+    isFastForwarding,
+    resetRuntimeState,
     bindEvents
   };
 }
@@ -1611,23 +2451,33 @@ export {
   createStaticNavigation,
   executeNodeCommand,
   executePluginCommand,
+  fastForwardState,
+  getAppStateAdapter,
   getNavigator,
+  getSeekingType,
   getStageSize,
   globalEventListeners,
   globalRequestAnimationFrameListeners,
   moyu_exports as moyu,
   nextLine,
+  registerAppStateAdapter,
   setDefaultAutoTailMs,
   setWaiting,
   skipState,
+  startDebugSession,
+  startRuntimeDebugSession,
+  stopDebugSession,
+  stopRuntimeDebugSession,
   useAutoBlocker,
   useAutoTicket,
   useBeforeHandleCommandCallback,
+  useDebugSession,
   useFadeIn,
   useFadeInOut,
   useFadeOut,
   useInterruptCallback,
   useIsAutoing,
+  useIsSeeking,
   useIsSkipping,
   useNavigation,
   useNavigationParams,
@@ -1636,5 +2486,6 @@ export {
   useSkipBlocker,
   useSkipCallback,
   useSoundEffect,
-  useStageContext
+  useStageContext,
+  warpState
 };