@momoyu-ink/kit 0.7.0 → 0.8.0

package/dist/{jsx-dev-runtime-CKclO27C.d.mts → jsx-dev-runtime-BCxm528Z.d.mts}

@@ -134,6 +134,10 @@ type JsonValue = number | string | boolean | Array<JsonValue> | {
 type ScenarioCommand = {
     subCommand: 'addStory';
     name: string;
+} | {
+    subCommand: 'replaceStoryData';
+    name: string;
+    content: string;
 } | {
     subCommand: 'removeStory';
     name: string;

package/dist/{jsx-dev-runtime-CKclO27C.d.ts → jsx-dev-runtime-BCxm528Z.d.ts}

@@ -134,6 +134,10 @@ type JsonValue = number | string | boolean | Array<JsonValue> | {
 type ScenarioCommand = {
     subCommand: 'addStory';
     name: string;
+} | {
+    subCommand: 'replaceStoryData';
+    name: string;
+    content: string;
 } | {
     subCommand: 'removeStory';
     name: string;

package/dist/jsx-dev-runtime.d.mts

@@ -1,4 +1,4 @@
 export { Fragment, jsxDEV } from 'react/jsx-dev-runtime';
-export { J as JSX } from './jsx-dev-runtime-CKclO27C.mjs';
+export { J as JSX } from './jsx-dev-runtime-BCxm528Z.mjs';
 import 'react/jsx-runtime';
 import 'react';

package/dist/jsx-dev-runtime.d.ts

@@ -1,4 +1,4 @@
 export { Fragment, jsxDEV } from 'react/jsx-dev-runtime';
-export { J as JSX } from './jsx-dev-runtime-CKclO27C.js';
+export { J as JSX } from './jsx-dev-runtime-BCxm528Z.js';
 import 'react/jsx-runtime';
 import 'react';

package/dist/jsx-runtime.d.mts

@@ -1,4 +1,4 @@
 export { Fragment, jsx, jsxs } from 'react/jsx-runtime';
-export { J as JSX } from './jsx-dev-runtime-CKclO27C.mjs';
+export { J as JSX } from './jsx-dev-runtime-BCxm528Z.mjs';
 import 'react/jsx-dev-runtime';
 import 'react';

package/dist/jsx-runtime.d.ts

@@ -1,4 +1,4 @@
 export { Fragment, jsx, jsxs } from 'react/jsx-runtime';
-export { J as JSX } from './jsx-dev-runtime-CKclO27C.js';
+export { J as JSX } from './jsx-dev-runtime-BCxm528Z.js';
 import 'react/jsx-dev-runtime';
 import 'react';

package/dist/lib.cjs

@@ -1214,9 +1214,44 @@ async function settleActiveWarp(error) {
     activeWarp = null;
   }, error);
 }
+async function clearLocalDebugSessionRuntimeState() {
+  await settleActiveFastForward(new Error("Debug session runtime state cleared"));
+  await settleActiveWarp(new Error("Debug session runtime state cleared"));
+  clearLocalRuntimeState();
+}
 async function clearRemoteCheckpoints() {
   await executeScenarioCommand({ subCommand: "clearCheckpoints" });
 }
+function pruneLocalStoryCheckpoints(story, preserved) {
+  debugState.checkpoints = Object.fromEntries(
+    Object.entries(debugState.checkpoints).filter(([key, checkpoint]) => {
+      if (checkpoint.cursor.story !== story) {
+        return true;
+      }
+      return preserved.has(key);
+    })
+  );
+}
+async function syncCurrentExecutionCursor(fallbackStory = null) {
+  debugState.currentCursor = await executeScenarioCommand({
+    subCommand: "getExecutionCursor"
+  });
+  debugState.currentStory = debugState.currentCursor?.story ?? fallbackStory;
+}
+async function executeRestartBoundary(boundary, story) {
+  if (boundary.kind === "checkpoint") {
+    await debugSessionController.restoreCheckpoint(boundary.checkpointKey, { story });
+    return;
+  }
+  if (!appStateAdapter?.restartStoryFromHead) {
+    throw new Error("Restarting a story from an explicit entry is not supported by the app state adapter");
+  }
+  await appStateAdapter.restartStoryFromHead({
+    story: boundary.story,
+    entry: boundary.kind === "restart-story" ? boundary.entry : boundary.paragraph
+  });
+  await syncCurrentExecutionCursor(boundary.story);
+}
 async function syncLocalWarpCheckpoint(targetMarkerId) {
   const cursor = await executeScenarioCommand({
     subCommand: "getExecutionCursor"
@@ -1276,15 +1311,17 @@ async function prepareJumpStart(markerId, options) {
       subCommand: "restoreCheckpoint",
       key: markerId
     });
-    if (!restored2) {
-      throw new Error(`Failed to restore checkpoint ${markerId}`);
-    }
-    if (appStateAdapter) {
-      await appStateAdapter.restore(checkpoint.appState);
+    if (restored2) {
+      if (appStateAdapter) {
+        await appStateAdapter.restore(checkpoint.appState);
+      }
+      debugState.currentCursor = checkpoint.cursor;
+      debugState.currentStory = checkpoint.cursor.story;
+      return false;
     }
-    debugState.currentCursor = checkpoint.cursor;
-    debugState.currentStory = checkpoint.cursor.story;
-    return false;
+    debugState.checkpoints = Object.fromEntries(
+      Object.entries(debugState.checkpoints).filter(([key]) => key !== markerId)
+    );
   }
   const lookup = await executeScenarioCommand({
     subCommand: "getFastForwardCheckpoint",
@@ -1304,7 +1341,8 @@ async function prepareJumpStart(markerId, options) {
   }
   const startCheckpoint = debugState.checkpoints[startCheckpointKey];
   if (!startCheckpoint) {
-    throw new Error(`Local checkpoint ${startCheckpointKey} not found`);
+    await restartJumpStoryFromHead(targetStory, currentStory);
+    return true;
   }
   const restored = await executeScenarioCommand({
     subCommand: "restoreCheckpoint",
@@ -1447,6 +1485,46 @@ var debugSessionController = {
         throw error;
       }
     });
+  },
+  async replaceStory(options) {
+    debugState.restoring = true;
+    debugState.lastError = null;
+    try {
+      const outcome = await enqueueDebugOperation(
+        async () => executeScenarioCommand({
+          subCommand: "replaceStoryData",
+          name: options.story,
+          content: options.content
+        })
+      );
+      if (outcome.plan.mode === "invalidate-only") {
+        pruneLocalStoryCheckpoints(options.story, /* @__PURE__ */ new Set());
+      }
+      if (outcome.plan.mode === "reposition") {
+        if (!outcome.plan.boundary) {
+          throw new Error("Story replace outcome is missing an executable boundary");
+        }
+        const seekMode = options.seekMode ?? "warp";
+        const replaceTargetMarkerId = options.targetMarkerId ?? outcome.plan.targetMarkerId;
+        await executeRestartBoundary(outcome.plan.boundary, options.story);
+        if (replaceTargetMarkerId && !(outcome.plan.boundary.kind === "checkpoint" && outcome.plan.boundary.checkpointKey === replaceTargetMarkerId)) {
+          if (seekMode === "warp") {
+            await runWarp({
+              markerId: replaceTargetMarkerId,
+              boundary: "after"
+            });
+          } else if (seekMode === "fast-forward") {
+            await runFastForwardToMarker(replaceTargetMarkerId);
+          }
+        }
+      }
+      return outcome;
+    } catch (error) {
+      debugState.lastError = toErrorMessage(error);
+      throw error;
+    } finally {
+      debugState.restoring = false;
+    }
   }
 };
 function registerAppStateAdapter(adapter) {
@@ -1543,22 +1621,6 @@ async function stopDebugSession() {
   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 = (0, import_valtio2.useSnapshot)(debugState);
   return {
@@ -1567,7 +1629,8 @@ function useDebugSession() {
     stopDebugSession,
     restoreCheckpoint: debugSessionController.restoreCheckpoint,
     warp: debugSessionController.warp,
-    switchRoute: debugSessionController.switchRoute
+    switchRoute: debugSessionController.switchRoute,
+    replaceStory: debugSessionController.replaceStory
   };
 }
 
@@ -1657,6 +1720,9 @@ function isJumpRequestMessage(message) {
 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 isStoryReplaceMessage(message) {
+  return message.type === "story:replace" && typeof message.sessionId === "string" && typeof message.requestId === "number" && typeof message.story === "string" && typeof message.content === "string" && (message.seekMode === void 0 || message.seekMode === "off" || message.seekMode === "fast-forward" || message.seekMode === "warp") && (message.targetMarkerId === void 0 || typeof message.targetMarkerId === "string");
+}
 function isUiReplaceMessage(message) {
   return message.type === "ui:replace" && typeof message.sessionId === "string";
 }
@@ -1743,6 +1809,35 @@ function handleRuntimeDebugRequest(socket, sessionId, message) {
     });
     return;
   }
+  if (isStoryReplaceMessage(message)) {
+    setRuntimeDebugVariableEmissionSuspended(true);
+    void controller.replaceStory({
+      story: message.story,
+      content: message.content,
+      seekMode: message.seekMode,
+      targetMarkerId: message.targetMarkerId
+    }).then(async () => {
+      sendRuntimeDebugMessage(socket, {
+        type: "story:replace:done",
+        sessionId,
+        requestId: message.requestId,
+        story: message.story
+      });
+      await syncRuntimeDebugVariablesSnapshotSafe("story-replace-done");
+    }).catch(async (error) => {
+      sendRuntimeDebugMessage(socket, {
+        type: "story:replace:error",
+        sessionId,
+        requestId: message.requestId,
+        story: message.story,
+        error: error instanceof Error ? error.message : String(error)
+      });
+      await syncRuntimeDebugVariablesSnapshotSafe("story-replace-error");
+    }).finally(() => {
+      setRuntimeDebugVariableEmissionSuspended(false);
+    });
+    return;
+  }
   setRuntimeDebugVariableEmissionSuspended(true);
   void controller.switchRoute(message.page, message.params).then(async () => {
     sendRuntimeDebugMessage(socket, {
@@ -1880,6 +1975,10 @@ async function startRuntimeDebugSession() {
         handleRuntimeDebugRequest(socket, sessionId, message);
         return;
       }
+      if (isStoryReplaceMessage(message)) {
+        handleRuntimeDebugRequest(socket, sessionId, message);
+        return;
+      }
       if (isUiReplaceMessage(message)) {
         handleRuntimeDebugRequest(socket, sessionId, message);
         return;
@@ -1995,13 +2094,13 @@ async function terminateCurrentScenario() {
     await executePluginCommand("scenario", {
       subCommand: "terminateStory"
     });
-    clearDebugSessionRuntimeState();
+    await clearLocalDebugSessionRuntimeState();
   } catch (error) {
     console.error("Failed to terminate scenario:", error);
   }
 }
 async function startScenarioSession(session, config) {
-  clearDebugSessionRuntimeState();
+  await clearLocalDebugSessionRuntimeState();
   for (const story of config.stories) {
     if (!isCurrentScenarioSession(session)) return;
     try {

package/dist/lib.d.mts

@@ -1,7 +1,7 @@
 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, c as JsonValue } from './jsx-dev-runtime-CKclO27C.mjs';
-export { A as AudioCommand, d as AudioSettings, B as BubbleEvent, D as DetailedMoyuProps, E as EffectParams, G as GamepadCommand, K as KeyboardEvent, e as KeyboardEventKind, f as MakeNullOptional, g as MouseEventKind, h as MoyuAnimationAttributes, i as MoyuBackdropAttributes, j as MoyuClipAttributes, k as MoyuContainerAttributes, l as MoyuEventHandler, m as MoyuFilterAttributes, n as MoyuListenerAttributes, o as MoyuNodeAttributes, p as MoyuSpriteAttributes, q as MoyuTextAttributes, r as MoyuVideoAttributes, N as Node, S as ScenarioCommand, s as SystemCommand, T as TextCommand, t as TouchEvent, u as TouchEventKind, v as Tuple2, w as Tuple3, x as Tuple4, W as WindowState, y as createBubbleEvent, z as getStageSize } from './jsx-dev-runtime-CKclO27C.mjs';
+import { M as MouseEvent, a as MoyuEvent, C as Command, b as MaybePromise, J as JSX, c as JsonValue } from './jsx-dev-runtime-BCxm528Z.mjs';
+export { A as AudioCommand, d as AudioSettings, B as BubbleEvent, D as DetailedMoyuProps, E as EffectParams, G as GamepadCommand, K as KeyboardEvent, e as KeyboardEventKind, f as MakeNullOptional, g as MouseEventKind, h as MoyuAnimationAttributes, i as MoyuBackdropAttributes, j as MoyuClipAttributes, k as MoyuContainerAttributes, l as MoyuEventHandler, m as MoyuFilterAttributes, n as MoyuListenerAttributes, o as MoyuNodeAttributes, p as MoyuSpriteAttributes, q as MoyuTextAttributes, r as MoyuVideoAttributes, N as Node, S as ScenarioCommand, s as SystemCommand, T as TextCommand, t as TouchEvent, u as TouchEventKind, v as Tuple2, w as Tuple3, x as Tuple4, W as WindowState, y as createBubbleEvent, z as getStageSize } from './jsx-dev-runtime-BCxm528Z.mjs';
 import { FluidValue } from '@react-spring/shared';
 import { ElementType, AssignableKeys, ComponentPropsWithRef } from '@react-spring/types';
 import { Snapshot } from 'valtio';
@@ -522,6 +522,34 @@ type ExecutionCursor = {
     markerId?: string;
 };
 
+type ExecutableRestartBoundary = {
+    kind: 'checkpoint';
+    checkpointKey: string;
+} | {
+    kind: 'restart-story';
+    story: string;
+    entry: string;
+} | {
+    kind: 'restart-paragraph';
+    story: string;
+    paragraph: string;
+};
+
+type StoryReplaceMode = 'noop' | 'reposition' | 'invalidate-only';
+
+type StoryReplaceExecutionPlan = {
+    mode: StoryReplaceMode;
+    boundary?: ExecutableRestartBoundary;
+    targetMarkerId?: string;
+    changedControlFlow: boolean;
+};
+
+type StoryReplaceOutcome = {
+    story: string;
+    currentStoryAffected: boolean;
+    plan: StoryReplaceExecutionPlan;
+};
+
 /** Flow control interface passed to every handler. */
 interface GameControl {
     /** Timed wait — blocks auto-advance. Engine fires scenariowaitingcancelled on timeout or skip. */
@@ -695,6 +723,12 @@ interface DebugSessionController {
     restoreCheckpoint(markerId: string, options?: DebugJumpTargetOptions): Promise<boolean>;
     warp(options: DebugWarpOptions): Promise<void>;
     switchRoute(routeName: string, params?: Record<string, unknown>): Promise<void>;
+    replaceStory(options: {
+        story: string;
+        content: string;
+        seekMode?: 'off' | 'fast-forward' | 'warp';
+        targetMarkerId?: string;
+    }): Promise<StoryReplaceOutcome>;
 }
 interface DebugStoryStartOptions {
     story: string;
@@ -718,6 +752,12 @@ declare function useDebugSession(): {
     restoreCheckpoint: (markerId: string, options?: DebugJumpTargetOptions) => Promise<boolean>;
     warp: (options: DebugWarpOptions) => Promise<void>;
     switchRoute: (routeName: string, params?: Record<string, unknown>) => Promise<void>;
+    replaceStory: (options: {
+        story: string;
+        content: string;
+        seekMode?: "off" | "fast-forward" | "warp";
+        targetMarkerId?: string;
+    }) => Promise<StoryReplaceOutcome>;
     active: boolean;
     checkpoints: {
         readonly [x: string]: {

package/dist/lib.d.ts

@@ -1,7 +1,7 @@
 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, c as JsonValue } from './jsx-dev-runtime-CKclO27C.js';
-export { A as AudioCommand, d as AudioSettings, B as BubbleEvent, D as DetailedMoyuProps, E as EffectParams, G as GamepadCommand, K as KeyboardEvent, e as KeyboardEventKind, f as MakeNullOptional, g as MouseEventKind, h as MoyuAnimationAttributes, i as MoyuBackdropAttributes, j as MoyuClipAttributes, k as MoyuContainerAttributes, l as MoyuEventHandler, m as MoyuFilterAttributes, n as MoyuListenerAttributes, o as MoyuNodeAttributes, p as MoyuSpriteAttributes, q as MoyuTextAttributes, r as MoyuVideoAttributes, N as Node, S as ScenarioCommand, s as SystemCommand, T as TextCommand, t as TouchEvent, u as TouchEventKind, v as Tuple2, w as Tuple3, x as Tuple4, W as WindowState, y as createBubbleEvent, z as getStageSize } from './jsx-dev-runtime-CKclO27C.js';
+import { M as MouseEvent, a as MoyuEvent, C as Command, b as MaybePromise, J as JSX, c as JsonValue } from './jsx-dev-runtime-BCxm528Z.js';
+export { A as AudioCommand, d as AudioSettings, B as BubbleEvent, D as DetailedMoyuProps, E as EffectParams, G as GamepadCommand, K as KeyboardEvent, e as KeyboardEventKind, f as MakeNullOptional, g as MouseEventKind, h as MoyuAnimationAttributes, i as MoyuBackdropAttributes, j as MoyuClipAttributes, k as MoyuContainerAttributes, l as MoyuEventHandler, m as MoyuFilterAttributes, n as MoyuListenerAttributes, o as MoyuNodeAttributes, p as MoyuSpriteAttributes, q as MoyuTextAttributes, r as MoyuVideoAttributes, N as Node, S as ScenarioCommand, s as SystemCommand, T as TextCommand, t as TouchEvent, u as TouchEventKind, v as Tuple2, w as Tuple3, x as Tuple4, W as WindowState, y as createBubbleEvent, z as getStageSize } from './jsx-dev-runtime-BCxm528Z.js';
 import { FluidValue } from '@react-spring/shared';
 import { ElementType, AssignableKeys, ComponentPropsWithRef } from '@react-spring/types';
 import { Snapshot } from 'valtio';
@@ -522,6 +522,34 @@ type ExecutionCursor = {
     markerId?: string;
 };
 
+type ExecutableRestartBoundary = {
+    kind: 'checkpoint';
+    checkpointKey: string;
+} | {
+    kind: 'restart-story';
+    story: string;
+    entry: string;
+} | {
+    kind: 'restart-paragraph';
+    story: string;
+    paragraph: string;
+};
+
+type StoryReplaceMode = 'noop' | 'reposition' | 'invalidate-only';
+
+type StoryReplaceExecutionPlan = {
+    mode: StoryReplaceMode;
+    boundary?: ExecutableRestartBoundary;
+    targetMarkerId?: string;
+    changedControlFlow: boolean;
+};
+
+type StoryReplaceOutcome = {
+    story: string;
+    currentStoryAffected: boolean;
+    plan: StoryReplaceExecutionPlan;
+};
+
 /** Flow control interface passed to every handler. */
 interface GameControl {
     /** Timed wait — blocks auto-advance. Engine fires scenariowaitingcancelled on timeout or skip. */
@@ -695,6 +723,12 @@ interface DebugSessionController {
     restoreCheckpoint(markerId: string, options?: DebugJumpTargetOptions): Promise<boolean>;
     warp(options: DebugWarpOptions): Promise<void>;
     switchRoute(routeName: string, params?: Record<string, unknown>): Promise<void>;
+    replaceStory(options: {
+        story: string;
+        content: string;
+        seekMode?: 'off' | 'fast-forward' | 'warp';
+        targetMarkerId?: string;
+    }): Promise<StoryReplaceOutcome>;
 }
 interface DebugStoryStartOptions {
     story: string;
@@ -718,6 +752,12 @@ declare function useDebugSession(): {
     restoreCheckpoint: (markerId: string, options?: DebugJumpTargetOptions) => Promise<boolean>;
     warp: (options: DebugWarpOptions) => Promise<void>;
     switchRoute: (routeName: string, params?: Record<string, unknown>) => Promise<void>;
+    replaceStory: (options: {
+        story: string;
+        content: string;
+        seekMode?: "off" | "fast-forward" | "warp";
+        targetMarkerId?: string;
+    }) => Promise<StoryReplaceOutcome>;
     active: boolean;
     checkpoints: {
         readonly [x: string]: {

package/dist/lib.mjs

@@ -1202,9 +1202,44 @@ async function settleActiveWarp(error) {
     activeWarp = null;
   }, error);
 }
+async function clearLocalDebugSessionRuntimeState() {
+  await settleActiveFastForward(new Error("Debug session runtime state cleared"));
+  await settleActiveWarp(new Error("Debug session runtime state cleared"));
+  clearLocalRuntimeState();
+}
 async function clearRemoteCheckpoints() {
   await executeScenarioCommand({ subCommand: "clearCheckpoints" });
 }
+function pruneLocalStoryCheckpoints(story, preserved) {
+  debugState.checkpoints = Object.fromEntries(
+    Object.entries(debugState.checkpoints).filter(([key, checkpoint]) => {
+      if (checkpoint.cursor.story !== story) {
+        return true;
+      }
+      return preserved.has(key);
+    })
+  );
+}
+async function syncCurrentExecutionCursor(fallbackStory = null) {
+  debugState.currentCursor = await executeScenarioCommand({
+    subCommand: "getExecutionCursor"
+  });
+  debugState.currentStory = debugState.currentCursor?.story ?? fallbackStory;
+}
+async function executeRestartBoundary(boundary, story) {
+  if (boundary.kind === "checkpoint") {
+    await debugSessionController.restoreCheckpoint(boundary.checkpointKey, { story });
+    return;
+  }
+  if (!appStateAdapter?.restartStoryFromHead) {
+    throw new Error("Restarting a story from an explicit entry is not supported by the app state adapter");
+  }
+  await appStateAdapter.restartStoryFromHead({
+    story: boundary.story,
+    entry: boundary.kind === "restart-story" ? boundary.entry : boundary.paragraph
+  });
+  await syncCurrentExecutionCursor(boundary.story);
+}
 async function syncLocalWarpCheckpoint(targetMarkerId) {
   const cursor = await executeScenarioCommand({
     subCommand: "getExecutionCursor"
@@ -1264,15 +1299,17 @@ async function prepareJumpStart(markerId, options) {
       subCommand: "restoreCheckpoint",
       key: markerId
     });
-    if (!restored2) {
-      throw new Error(`Failed to restore checkpoint ${markerId}`);
-    }
-    if (appStateAdapter) {
-      await appStateAdapter.restore(checkpoint.appState);
+    if (restored2) {
+      if (appStateAdapter) {
+        await appStateAdapter.restore(checkpoint.appState);
+      }
+      debugState.currentCursor = checkpoint.cursor;
+      debugState.currentStory = checkpoint.cursor.story;
+      return false;
     }
-    debugState.currentCursor = checkpoint.cursor;
-    debugState.currentStory = checkpoint.cursor.story;
-    return false;
+    debugState.checkpoints = Object.fromEntries(
+      Object.entries(debugState.checkpoints).filter(([key]) => key !== markerId)
+    );
   }
   const lookup = await executeScenarioCommand({
     subCommand: "getFastForwardCheckpoint",
@@ -1292,7 +1329,8 @@ async function prepareJumpStart(markerId, options) {
   }
   const startCheckpoint = debugState.checkpoints[startCheckpointKey];
   if (!startCheckpoint) {
-    throw new Error(`Local checkpoint ${startCheckpointKey} not found`);
+    await restartJumpStoryFromHead(targetStory, currentStory);
+    return true;
   }
   const restored = await executeScenarioCommand({
     subCommand: "restoreCheckpoint",
@@ -1435,6 +1473,46 @@ var debugSessionController = {
         throw error;
       }
     });
+  },
+  async replaceStory(options) {
+    debugState.restoring = true;
+    debugState.lastError = null;
+    try {
+      const outcome = await enqueueDebugOperation(
+        async () => executeScenarioCommand({
+          subCommand: "replaceStoryData",
+          name: options.story,
+          content: options.content
+        })
+      );
+      if (outcome.plan.mode === "invalidate-only") {
+        pruneLocalStoryCheckpoints(options.story, /* @__PURE__ */ new Set());
+      }
+      if (outcome.plan.mode === "reposition") {
+        if (!outcome.plan.boundary) {
+          throw new Error("Story replace outcome is missing an executable boundary");
+        }
+        const seekMode = options.seekMode ?? "warp";
+        const replaceTargetMarkerId = options.targetMarkerId ?? outcome.plan.targetMarkerId;
+        await executeRestartBoundary(outcome.plan.boundary, options.story);
+        if (replaceTargetMarkerId && !(outcome.plan.boundary.kind === "checkpoint" && outcome.plan.boundary.checkpointKey === replaceTargetMarkerId)) {
+          if (seekMode === "warp") {
+            await runWarp({
+              markerId: replaceTargetMarkerId,
+              boundary: "after"
+            });
+          } else if (seekMode === "fast-forward") {
+            await runFastForwardToMarker(replaceTargetMarkerId);
+          }
+        }
+      }
+      return outcome;
+    } catch (error) {
+      debugState.lastError = toErrorMessage(error);
+      throw error;
+    } finally {
+      debugState.restoring = false;
+    }
   }
 };
 function registerAppStateAdapter(adapter) {
@@ -1531,22 +1609,6 @@ async function stopDebugSession() {
   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 {
@@ -1555,7 +1617,8 @@ function useDebugSession() {
     stopDebugSession,
     restoreCheckpoint: debugSessionController.restoreCheckpoint,
     warp: debugSessionController.warp,
-    switchRoute: debugSessionController.switchRoute
+    switchRoute: debugSessionController.switchRoute,
+    replaceStory: debugSessionController.replaceStory
   };
 }
 
@@ -1645,6 +1708,9 @@ function isJumpRequestMessage(message) {
 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 isStoryReplaceMessage(message) {
+  return message.type === "story:replace" && typeof message.sessionId === "string" && typeof message.requestId === "number" && typeof message.story === "string" && typeof message.content === "string" && (message.seekMode === void 0 || message.seekMode === "off" || message.seekMode === "fast-forward" || message.seekMode === "warp") && (message.targetMarkerId === void 0 || typeof message.targetMarkerId === "string");
+}
 function isUiReplaceMessage(message) {
   return message.type === "ui:replace" && typeof message.sessionId === "string";
 }
@@ -1731,6 +1797,35 @@ function handleRuntimeDebugRequest(socket, sessionId, message) {
     });
     return;
   }
+  if (isStoryReplaceMessage(message)) {
+    setRuntimeDebugVariableEmissionSuspended(true);
+    void controller.replaceStory({
+      story: message.story,
+      content: message.content,
+      seekMode: message.seekMode,
+      targetMarkerId: message.targetMarkerId
+    }).then(async () => {
+      sendRuntimeDebugMessage(socket, {
+        type: "story:replace:done",
+        sessionId,
+        requestId: message.requestId,
+        story: message.story
+      });
+      await syncRuntimeDebugVariablesSnapshotSafe("story-replace-done");
+    }).catch(async (error) => {
+      sendRuntimeDebugMessage(socket, {
+        type: "story:replace:error",
+        sessionId,
+        requestId: message.requestId,
+        story: message.story,
+        error: error instanceof Error ? error.message : String(error)
+      });
+      await syncRuntimeDebugVariablesSnapshotSafe("story-replace-error");
+    }).finally(() => {
+      setRuntimeDebugVariableEmissionSuspended(false);
+    });
+    return;
+  }
   setRuntimeDebugVariableEmissionSuspended(true);
   void controller.switchRoute(message.page, message.params).then(async () => {
     sendRuntimeDebugMessage(socket, {
@@ -1868,6 +1963,10 @@ async function startRuntimeDebugSession() {
         handleRuntimeDebugRequest(socket, sessionId, message);
         return;
       }
+      if (isStoryReplaceMessage(message)) {
+        handleRuntimeDebugRequest(socket, sessionId, message);
+        return;
+      }
       if (isUiReplaceMessage(message)) {
         handleRuntimeDebugRequest(socket, sessionId, message);
         return;
@@ -1983,13 +2082,13 @@ async function terminateCurrentScenario() {
     await executePluginCommand("scenario", {
       subCommand: "terminateStory"
     });
-    clearDebugSessionRuntimeState();
+    await clearLocalDebugSessionRuntimeState();
   } catch (error) {
     console.error("Failed to terminate scenario:", error);
   }
 }
 async function startScenarioSession(session, config) {
-  clearDebugSessionRuntimeState();
+  await clearLocalDebugSessionRuntimeState();
   for (const story of config.stories) {
     if (!isCurrentScenarioSession(session)) return;
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@momoyu-ink/kit",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Software Development Kit of Moyu Visual Novel Engine",
   "main": "dist/lib.cjs",
   "module": "dist/lib.mjs",