@momoyu-ink/kit 0.7.1 → 0.8.1

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

@@ -1027,13 +1027,20 @@ function createStackNavigator(options) {
     goBack: () => {
       console.warn("goBack() not implemented yet");
     },
-    pushOverlay: (overlay, params) => {
+    hasActiveOverlay: (overlay, id) => {
+      if (id) {
+        console.log(navigationState.overlayStack.some((o) => o.type === overlay && o.id === id));
+        return navigationState.overlayStack.some((o) => o.type === overlay && o.id === id);
+      }
+      return navigationState.overlayStack.some((o) => o.type === overlay);
+    },
+    pushOverlay: (overlay, params, _id) => {
       if (!normalizedOverlays[overlay]) {
         console.error(`Navigation Error: Overlay "${overlay}" not found in navigator configuration.`);
         return;
       }
       validateParams("overlay", overlay, normalizedOverlays[overlay], params);
-      const id = generateOverlayId();
+      const id = _id ?? generateOverlayId();
       const overlayInfo = { type: overlay, id };
       navigationState.overlayStack.push(overlayInfo);
       if (params !== void 0) {
@@ -1222,6 +1229,36 @@ async function clearLocalDebugSessionRuntimeState() {
 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"
@@ -1281,15 +1318,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",
@@ -1309,7 +1348,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",
@@ -1452,6 +1492,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) {
@@ -1556,7 +1636,8 @@ function useDebugSession() {
     stopDebugSession,
     restoreCheckpoint: debugSessionController.restoreCheckpoint,
     warp: debugSessionController.warp,
-    switchRoute: debugSessionController.switchRoute
+    switchRoute: debugSessionController.switchRoute,
+    replaceStory: debugSessionController.replaceStory
   };
 }
 
@@ -1646,6 +1727,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";
 }
@@ -1732,6 +1816,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, {
@@ -1869,6 +1982,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;

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';
@@ -424,12 +424,19 @@ interface Navigator<PageName extends string = DefaultPageName, OverlayName exten
      * Go back to the previous page (not implemented yet)
      */
     goBack: () => void;
+    /**
+     * Check whether an overlay has been pushed, optionally by ID
+     * @param overlay Overlay name
+     * @param id Optional unique ID to check for specific overlay instance
+     */
+    hasActiveOverlay: (overlay: OverlayName, id?: string) => boolean;
     /**
      * Push an overlay to the overlay stack
      * @param overlay Overlay name
      * @param params Parameters to pass to the overlay (optional)
+     * @param id Unique ID for the overlay (optional)
      */
-    pushOverlay: (overlay: OverlayName, params?: Record<string, any>) => void;
+    pushOverlay: (overlay: OverlayName, params?: Record<string, any>, id?: string) => void;
     /**
      * Pop the top overlay from the stack
      */
@@ -522,6 +529,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 +730,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 +759,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';
@@ -424,12 +424,19 @@ interface Navigator<PageName extends string = DefaultPageName, OverlayName exten
      * Go back to the previous page (not implemented yet)
      */
     goBack: () => void;
+    /**
+     * Check whether an overlay has been pushed, optionally by ID
+     * @param overlay Overlay name
+     * @param id Optional unique ID to check for specific overlay instance
+     */
+    hasActiveOverlay: (overlay: OverlayName, id?: string) => boolean;
     /**
      * Push an overlay to the overlay stack
      * @param overlay Overlay name
      * @param params Parameters to pass to the overlay (optional)
+     * @param id Unique ID for the overlay (optional)
      */
-    pushOverlay: (overlay: OverlayName, params?: Record<string, any>) => void;
+    pushOverlay: (overlay: OverlayName, params?: Record<string, any>, id?: string) => void;
     /**
      * Pop the top overlay from the stack
      */
@@ -522,6 +529,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 +730,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 +759,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

@@ -1015,13 +1015,20 @@ function createStackNavigator(options) {
     goBack: () => {
       console.warn("goBack() not implemented yet");
     },
-    pushOverlay: (overlay, params) => {
+    hasActiveOverlay: (overlay, id) => {
+      if (id) {
+        console.log(navigationState.overlayStack.some((o) => o.type === overlay && o.id === id));
+        return navigationState.overlayStack.some((o) => o.type === overlay && o.id === id);
+      }
+      return navigationState.overlayStack.some((o) => o.type === overlay);
+    },
+    pushOverlay: (overlay, params, _id) => {
       if (!normalizedOverlays[overlay]) {
         console.error(`Navigation Error: Overlay "${overlay}" not found in navigator configuration.`);
         return;
       }
       validateParams("overlay", overlay, normalizedOverlays[overlay], params);
-      const id = generateOverlayId();
+      const id = _id ?? generateOverlayId();
       const overlayInfo = { type: overlay, id };
       navigationState.overlayStack.push(overlayInfo);
       if (params !== void 0) {
@@ -1210,6 +1217,36 @@ async function clearLocalDebugSessionRuntimeState() {
 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"
@@ -1269,15 +1306,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",
@@ -1297,7 +1336,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",
@@ -1440,6 +1480,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) {
@@ -1544,7 +1624,8 @@ function useDebugSession() {
     stopDebugSession,
     restoreCheckpoint: debugSessionController.restoreCheckpoint,
     warp: debugSessionController.warp,
-    switchRoute: debugSessionController.switchRoute
+    switchRoute: debugSessionController.switchRoute,
+    replaceStory: debugSessionController.replaceStory
   };
 }
 
@@ -1634,6 +1715,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";
 }
@@ -1720,6 +1804,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, {
@@ -1857,6 +1970,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;

package/package.json

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