@momoyu-ink/kit 0.6.1 → 0.7.1

package/dist/lib.cjs

@@ -31,6 +31,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/lib.ts
 var lib_exports = {};
 __export(lib_exports, {
+  DEBUG_EMPTY_PAGE: () => DEBUG_EMPTY_PAGE,
   OverlayParamsContext: () => OverlayParamsContext,
   PageParamsContext: () => PageParamsContext,
   StageContextProvider: () => StageContextProvider,
@@ -43,6 +44,7 @@ __export(lib_exports, {
   createStackNavigator: () => createStackNavigator,
   createStage: () => createStage,
   createStaticNavigation: () => createStaticNavigation,
+  ensureArchiveVariableDefaults: () => ensureArchiveVariableDefaults,
   executeNodeCommand: () => executeNodeCommand,
   executePluginCommand: () => executePluginCommand,
   fastForwardState: () => fastForwardState,
@@ -50,11 +52,16 @@ __export(lib_exports, {
   getNavigator: () => getNavigator,
   getSeekingType: () => getSeekingType,
   getStageSize: () => getStageSize,
+  getUiData: () => getUiData,
   globalEventListeners: () => globalEventListeners,
   globalRequestAnimationFrameListeners: () => globalRequestAnimationFrameListeners,
+  initGlobalVariableDefaults: () => initGlobalVariableDefaults,
+  initUiData: () => initUiData,
+  loadVariablesDocument: () => loadVariablesDocument,
   moyu: () => moyu_exports,
   nextLine: () => nextLine,
   registerAppStateAdapter: () => registerAppStateAdapter,
+  replaceUiData: () => replaceUiData,
   setDefaultAutoTailMs: () => setDefaultAutoTailMs,
   setWaiting: () => setWaiting,
   skipState: () => skipState,
@@ -81,6 +88,7 @@ __export(lib_exports, {
   useSkipCallback: () => useSkipCallback,
   useSoundEffect: () => useSoundEffect,
   useStageContext: () => useStageContext,
+  useUiData: () => useUiData,
   warpState: () => warpState
 });
 module.exports = __toCommonJS(lib_exports);
@@ -406,6 +414,259 @@ function createRoot(options) {
   };
 }
 
+// src/variables.ts
+var VARIABLES_DATA_ASSET_PATH = "assets:///data/variables.json";
+function normalizeVariableDefinitions(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.flatMap((entry) => {
+    if (!entry || typeof entry !== "object") {
+      return [];
+    }
+    const definition = entry;
+    if (typeof definition.id !== "string" || definition.id.length === 0) {
+      return [];
+    }
+    return [{ id: definition.id, defaultValue: definition.defaultValue }];
+  });
+}
+async function loadVariablesDocument() {
+  let rawText;
+  try {
+    rawText = await executePluginCommand("system", {
+      subCommand: "readFile",
+      path: VARIABLES_DATA_ASSET_PATH
+    });
+  } catch {
+    return null;
+  }
+  let rawData;
+  try {
+    rawData = JSON.parse(rawText);
+  } catch (error) {
+    console.error("Failed to parse variable defaults data:", error);
+    return null;
+  }
+  if (!rawData || typeof rawData !== "object") {
+    return {
+      archive: [],
+      global: []
+    };
+  }
+  const document = rawData;
+  return {
+    archive: normalizeVariableDefinitions(document.archive),
+    global: normalizeVariableDefinitions(document.global)
+  };
+}
+function toVariableRecord(value) {
+  if (value instanceof Map) {
+    return Object.fromEntries(value);
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return {};
+  }
+  return value;
+}
+async function ensureVariableDefaults(scope) {
+  const document = await loadVariablesDocument();
+  if (!document) {
+    return;
+  }
+  const definitions = document[scope];
+  if (definitions.length === 0) {
+    return;
+  }
+  const currentVariables = toVariableRecord(
+    await executePluginCommand(
+      "scenario",
+      scope === "global" ? { subCommand: "getPermanentVariables" } : { subCommand: "getVariables" }
+    )
+  );
+  const missingVariables = {};
+  for (const definition of definitions) {
+    if (!Object.hasOwn(currentVariables, definition.id)) {
+      missingVariables[definition.id] = definition.defaultValue;
+    }
+  }
+  if (Object.keys(missingVariables).length === 0) {
+    return;
+  }
+  await executePluginCommand(
+    "scenario",
+    scope === "global" ? {
+      subCommand: "setPermanentVariables",
+      variables: missingVariables
+    } : {
+      subCommand: "setVariables",
+      variables: missingVariables
+    }
+  );
+  reportRuntimeDebugVariablesSet(scope, missingVariables);
+}
+async function initGlobalVariableDefaults() {
+  await ensureVariableDefaults("global");
+}
+async function ensureArchiveVariableDefaults() {
+  await ensureVariableDefaults("archive");
+}
+
+// src/debug/variableMonitor.ts
+var sendRuntimeDebugVariableMessage = null;
+var allowlistCache = null;
+var allowlistPromise = null;
+var variableEmissionSuspended = false;
+function createEmptyAllowlist() {
+  return {
+    archive: /* @__PURE__ */ new Set(),
+    global: /* @__PURE__ */ new Set()
+  };
+}
+function isJsonValue(value) {
+  if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return true;
+  }
+  if (Array.isArray(value)) {
+    return value.every((item) => isJsonValue(item));
+  }
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  return Object.values(value).every((item) => isJsonValue(item));
+}
+async function loadRuntimeDebugVariableAllowlist() {
+  const document = await loadVariablesDocument();
+  if (!document) {
+    return createEmptyAllowlist();
+  }
+  return {
+    archive: new Set(document.archive.map((def) => def.id)),
+    global: new Set(document.global.map((def) => def.id))
+  };
+}
+function toJsonValueRecord(value) {
+  if (value instanceof Map) {
+    return Object.fromEntries(
+      Array.from(value.entries()).flatMap(([key, entryValue]) => {
+        if (typeof key !== "string" || !isJsonValue(entryValue)) {
+          return [];
+        }
+        return [[key, entryValue]];
+      })
+    );
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return {};
+  }
+  return Object.fromEntries(
+    Object.entries(value).flatMap(([key, entryValue]) => {
+      if (!isJsonValue(entryValue)) {
+        return [];
+      }
+      return [[key, entryValue]];
+    })
+  );
+}
+function filterVariablesByAllowlist(scope, values, allowlist) {
+  const allowedIds = allowlist[scope];
+  if (allowedIds.size === 0) {
+    return {};
+  }
+  return Object.fromEntries(
+    Object.entries(values).flatMap(([key, value]) => allowedIds.has(key) ? [[key, value]] : [])
+  );
+}
+function hasRecordEntries(value) {
+  return !!value && Object.keys(value).length > 0;
+}
+async function ensureRuntimeDebugVariableAllowlist() {
+  if (allowlistCache) {
+    return allowlistCache;
+  }
+  if (!allowlistPromise) {
+    allowlistPromise = loadRuntimeDebugVariableAllowlist().then((allowlist) => {
+      allowlistCache = allowlist;
+      return allowlist;
+    }).finally(() => {
+      allowlistPromise = null;
+    });
+  }
+  return allowlistPromise;
+}
+async function emitRuntimeDebugVariablesChanged(scope, variables) {
+  const sender = sendRuntimeDebugVariableMessage;
+  if (!sender || variableEmissionSuspended) {
+    return;
+  }
+  const allowlist = await ensureRuntimeDebugVariableAllowlist();
+  if (!sendRuntimeDebugVariableMessage || sendRuntimeDebugVariableMessage !== sender || variableEmissionSuspended) {
+    return;
+  }
+  const filtered = filterVariablesByAllowlist(scope, variables, allowlist);
+  if (!hasRecordEntries(filtered)) {
+    return;
+  }
+  sender({
+    type: "variables:changed",
+    archiveSet: scope === "archive" ? filtered : void 0,
+    globalSet: scope === "global" ? filtered : void 0
+  });
+}
+function setRuntimeDebugVariableMessageSender(sender) {
+  sendRuntimeDebugVariableMessage = sender;
+  if (sender) {
+    void ensureRuntimeDebugVariableAllowlist();
+  }
+}
+function setRuntimeDebugVariableEmissionSuspended(suspended) {
+  variableEmissionSuspended = suspended;
+}
+function resetRuntimeDebugVariableMonitor() {
+  sendRuntimeDebugVariableMessage = null;
+  allowlistCache = null;
+  allowlistPromise = null;
+  variableEmissionSuspended = false;
+}
+function reportRuntimeDebugVariableSet(scope, key, value) {
+  if (key.length === 0) {
+    return;
+  }
+  void emitRuntimeDebugVariablesChanged(scope, {
+    [key]: value
+  });
+}
+function reportRuntimeDebugVariablesSet(scope, variables) {
+  if (Object.keys(variables).length === 0) {
+    return;
+  }
+  void emitRuntimeDebugVariablesChanged(scope, variables);
+}
+async function syncRuntimeDebugVariablesSnapshot(reason) {
+  const sender = sendRuntimeDebugVariableMessage;
+  if (!sender) {
+    return;
+  }
+  const [allowlist, archiveVariables2, globalVariables2] = await Promise.all([
+    ensureRuntimeDebugVariableAllowlist(),
+    executePluginCommand("scenario", {
+      subCommand: "getVariables"
+    }),
+    executePluginCommand("scenario", {
+      subCommand: "getPermanentVariables"
+    })
+  ]);
+  if (!sendRuntimeDebugVariableMessage || sendRuntimeDebugVariableMessage !== sender) {
+    return;
+  }
+  sender({
+    type: "variables:snapshot",
+    reason,
+    archive: filterVariablesByAllowlist("archive", toJsonValueRecord(archiveVariables2), allowlist),
+    global: filterVariablesByAllowlist("global", toJsonValueRecord(globalVariables2), allowlist)
+  });
+}
+
 // src/sandbox.ts
 var JS_GLOBAL_KEYS = new Set(Object.getOwnPropertyNames(globalThis));
 var JS_GLOBAL_KEYS_EXCLUDED = /* @__PURE__ */ new Set(["window", "globalThis", "LOCAL", "ARCHIVE", "GLOBAL"]);
@@ -456,6 +717,7 @@ var archiveVariables = new Proxy(
           name: key,
           value
         });
+        reportRuntimeDebugVariableSet("archive", key, value);
         return true;
       }
       return false;
@@ -481,6 +743,7 @@ var globalVariables = new Proxy(
           key,
           value
         });
+        reportRuntimeDebugVariableSet("global", key, value);
         return true;
       }
       return false;
@@ -488,7 +751,7 @@ var globalVariables = new Proxy(
   }
 );
 function safeEval(code, sandbox) {
-  const proxy4 = new Proxy(sandbox, {
+  const proxy5 = new Proxy(sandbox, {
     has(target, key) {
       if (typeof key === "string" && JS_GLOBAL_KEYS.has(key)) {
         return false;
@@ -496,7 +759,7 @@ function safeEval(code, sandbox) {
       return key in target || key === "LOCAL" || key === "ARCHIVE" || key === "GLOBAL" || key === "window" || key === "globalThis";
     },
     get(target, key) {
-      if (key === "window" || key === "globalThis") return proxy4;
+      if (key === "window" || key === "globalThis") return proxy5;
       if (key === "LOCAL") return localVariables;
       if (key === "ARCHIVE") return archiveVariables;
       if (key === "GLOBAL") return globalVariables;
@@ -508,7 +771,7 @@ function safeEval(code, sandbox) {
       return true;
     }
   });
-  return new Function("sandbox", `with(sandbox) { return (${code}) }`).bind(proxy4)(proxy4);
+  return new Function("sandbox", `with(sandbox) { return (${code}) }`).bind(proxy5)(proxy5);
 }
 globalThis.__moyu_eval_sandbox = (code) => {
   try {
@@ -695,6 +958,7 @@ var import_valtio = require("valtio");
 var import_jsx_runtime = require("react/jsx-runtime");
 var PageParamsContext = (0, import_react2.createContext)(void 0);
 var OverlayParamsContext = (0, import_react2.createContext)(void 0);
+var DEBUG_EMPTY_PAGE = "debug-empty";
 var overlayIdCounter = 0;
 var generateOverlayId = () => {
   return `overlay-${++overlayIdCounter}-${Date.now()}`;
@@ -722,6 +986,12 @@ function createStackNavigator(options) {
   for (const [key, config] of Object.entries(options.pages)) {
     normalizedPages[key] = normalizeDescriptor(config);
   }
+  if (normalizedPages[DEBUG_EMPTY_PAGE]) {
+    throw new Error(`Navigation Error: Page name "${DEBUG_EMPTY_PAGE}" is reserved.`);
+  }
+  normalizedPages[DEBUG_EMPTY_PAGE] = {
+    component: () => null
+  };
   const normalizedOverlays = {};
   if (options.overlays) {
     for (const [key, config] of Object.entries(options.overlays)) {
@@ -751,6 +1021,9 @@ function createStackNavigator(options) {
     hasPage: (page) => {
       return normalizedPages[page] !== void 0;
     },
+    hasOverlay: (overlay) => {
+      return normalizedOverlays[overlay] !== void 0;
+    },
     goBack: () => {
       console.warn("goBack() not implemented yet");
     },
@@ -838,6 +1111,7 @@ var debugState = (0, import_valtio2.proxy)({
   active: false,
   checkpoints: {},
   currentCursor: null,
+  currentStory: null,
   restoring: false,
   lastError: null
 });
@@ -881,9 +1155,37 @@ function reportDebugSessionError(error) {
 function clearLocalRuntimeState() {
   debugState.checkpoints = {};
   debugState.currentCursor = null;
+  debugState.currentStory = null;
   debugState.restoring = false;
   debugState.lastError = null;
 }
+async function restartJumpStoryFromHead(targetStory, currentStory) {
+  debugState.checkpoints = {};
+  debugState.currentCursor = null;
+  debugState.currentStory = null;
+  if (targetStory) {
+    if (appStateAdapter?.restartStoryFromHead) {
+      await appStateAdapter.restartStoryFromHead({
+        story: targetStory,
+        entry: "entry"
+      });
+    } else if (currentStory === targetStory && appStateAdapter?.restartCurrentStoryFromHead) {
+      await appStateAdapter.restartCurrentStoryFromHead();
+    } else {
+      throw new Error("Restarting the target story from head is not supported by the app state adapter");
+    }
+    debugState.currentCursor = await executeScenarioCommand({
+      subCommand: "getExecutionCursor"
+    });
+    debugState.currentStory = debugState.currentCursor?.story ?? targetStory;
+    return;
+  }
+  if (!appStateAdapter?.restartCurrentStoryFromHead) {
+    throw new Error("Restarting the current story from head is not supported by the app state adapter");
+  }
+  await appStateAdapter.restartCurrentStoryFromHead();
+  debugState.currentCursor = null;
+}
 async function doSettleActiveSeek(op, clearSlot, error) {
   if (!op) {
     return;
@@ -912,6 +1214,11 @@ 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" });
 }
@@ -936,6 +1243,7 @@ async function syncLocalWarpCheckpoint(targetMarkerId) {
     appState: appStateAdapter ? await appStateAdapter.capture() : void 0
   };
   debugState.currentCursor = checkpointCursor;
+  debugState.currentStory = checkpointCursor.story;
   debugState.checkpoints[targetMarkerId] = checkpoint;
   await currentConfig.onMarkerEnter(checkpoint);
 }
@@ -959,9 +1267,16 @@ function notifyMarkerEnter(checkpoint) {
     reportDebugSessionError(error);
   }
 }
-async function prepareJumpStart(markerId) {
+async function prepareJumpStart(markerId, options) {
+  const currentStory = debugState.currentStory ?? debugState.currentCursor?.story ?? null;
+  const targetStory = options?.story;
+  let restartedFromHead = false;
+  if (targetStory && targetStory !== currentStory) {
+    await restartJumpStoryFromHead(targetStory, currentStory);
+    restartedFromHead = true;
+  }
   const checkpoint = debugState.checkpoints[markerId];
-  if (checkpoint) {
+  if (!restartedFromHead && checkpoint && (!targetStory || checkpoint.cursor.story === targetStory)) {
     const restored2 = await executeScenarioCommand({
       subCommand: "restoreCheckpoint",
       key: markerId
@@ -973,6 +1288,7 @@ async function prepareJumpStart(markerId) {
       await appStateAdapter.restore(checkpoint.appState);
     }
     debugState.currentCursor = checkpoint.cursor;
+    debugState.currentStory = checkpoint.cursor.story;
     return false;
   }
   const lookup = await executeScenarioCommand({
@@ -980,16 +1296,15 @@ async function prepareJumpStart(markerId) {
     key: markerId
   });
   if (!lookup.markerExists) {
-    throw new Error(`Marker ${markerId} is not available in the current story`);
+    throw new Error(
+      targetStory ? `Marker ${markerId} is not available in story ${targetStory}` : `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");
+    if (!restartedFromHead) {
+      await restartJumpStoryFromHead(targetStory, currentStory);
     }
-    await appStateAdapter.restartCurrentStoryFromHead();
-    debugState.checkpoints = {};
-    debugState.currentCursor = null;
     return true;
   }
   const startCheckpoint = debugState.checkpoints[startCheckpointKey];
@@ -1007,6 +1322,7 @@ async function prepareJumpStart(markerId) {
     await appStateAdapter.restore(startCheckpoint.appState);
   }
   debugState.currentCursor = startCheckpoint.cursor;
+  debugState.currentStory = startCheckpoint.cursor.story;
   return true;
 }
 function handleMarkerEnter(marker) {
@@ -1019,6 +1335,7 @@ function handleMarkerEnter(marker) {
     appState: captureCheckpointAppStateSync()
   };
   debugState.currentCursor = checkpoint.cursor;
+  debugState.currentStory = checkpoint.cursor.story;
   debugState.checkpoints[marker.markerId] = checkpoint;
   notifyMarkerEnter(checkpoint);
   if (activeFastForward?.targetMarkerId === marker.markerId) {
@@ -1079,11 +1396,11 @@ async function runWarp(options) {
   await completion;
 }
 var debugSessionController = {
-  async restoreCheckpoint(markerId) {
+  async restoreCheckpoint(markerId, options) {
     debugState.restoring = true;
     debugState.lastError = null;
     try {
-      const needsFastForward = await enqueueDebugOperation(async () => prepareJumpStart(markerId));
+      const needsFastForward = await enqueueDebugOperation(async () => prepareJumpStart(markerId, options));
       if (needsFastForward) {
         await runFastForwardToMarker(markerId);
       }
@@ -1099,7 +1416,7 @@ var debugSessionController = {
     debugState.restoring = true;
     debugState.lastError = null;
     try {
-      const needsWarp = await enqueueDebugOperation(async () => prepareJumpStart(options.markerId));
+      const needsWarp = await enqueueDebugOperation(async () => prepareJumpStart(options.markerId, options));
       if (needsWarp) {
         await runWarp(options);
       }
@@ -1110,14 +1427,26 @@ var debugSessionController = {
       debugState.restoring = false;
     }
   },
-  async switchPage(page, params) {
+  async switchRoute(routeName, params) {
     return enqueueDebugOperation(async () => {
       debugState.lastError = null;
       try {
-        if (!appStateAdapter?.switchPage) {
-          throw new Error("Page switching is not supported by the app state adapter");
+        const navigator = getNavigator();
+        if (navigator.hasPage(routeName)) {
+          if (!appStateAdapter?.switchPage) {
+            throw new Error("Page switching is not supported by the app state adapter");
+          }
+          await appStateAdapter.switchPage(routeName, params);
+          return;
+        }
+        if (navigator.hasOverlay(routeName)) {
+          if (!appStateAdapter?.switchOverlay) {
+            throw new Error("Overlay switching is not supported by the app state adapter");
+          }
+          await appStateAdapter.switchOverlay(routeName, params);
+          return;
         }
-        await appStateAdapter.switchPage(page, params);
+        throw new Error(`Route "${routeName}" not found`);
       } catch (error) {
         debugState.lastError = toErrorMessage(error);
         throw error;
@@ -1182,6 +1511,7 @@ async function startDebugSession(config = {}) {
     debugState.currentCursor = await executeScenarioCommand({
       subCommand: "getExecutionCursor"
     });
+    debugState.currentStory = debugState.currentCursor?.story ?? null;
   } catch (error) {
     debugState.active = false;
     clearLocalRuntimeState();
@@ -1218,22 +1548,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 {
@@ -1242,10 +1556,83 @@ function useDebugSession() {
     stopDebugSession,
     restoreCheckpoint: debugSessionController.restoreCheckpoint,
     warp: debugSessionController.warp,
-    switchPage: debugSessionController.switchPage
+    switchRoute: debugSessionController.switchRoute
   };
 }
 
+// src/ui.ts
+var import_valtio3 = require("valtio");
+var UI_DATA_ASSET_PATH = "assets:///data/ui.json";
+var activeUiSchema = null;
+var uiDataState = (0, import_valtio3.proxy)({});
+var uiRuntimeState = (0, import_valtio3.proxy)({
+  initialized: false,
+  error: null
+});
+function applyUiData(nextData) {
+  for (const key of Object.keys(uiDataState)) {
+    delete uiDataState[key];
+  }
+  Object.assign(uiDataState, nextData);
+  uiRuntimeState.initialized = true;
+  uiRuntimeState.error = null;
+}
+async function initUiData(schema) {
+  uiRuntimeState.initialized = false;
+  uiRuntimeState.error = null;
+  activeUiSchema = schema;
+  let rawData;
+  try {
+    const rawText = await Promise.resolve(
+      executePluginCommand("system", {
+        subCommand: "readFile",
+        path: UI_DATA_ASSET_PATH
+      })
+    );
+    rawData = JSON.parse(rawText);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    uiRuntimeState.error = message;
+    throw new Error(`Failed to initialize UI data: ${message}`);
+  }
+  const parsed = schema.safeParse(rawData);
+  if (!parsed.success) {
+    uiRuntimeState.error = parsed.error.message;
+    throw new Error(`Invalid UI data: ${parsed.error.message}`);
+  }
+  applyUiData(parsed.data);
+}
+function replaceUiData(rawData) {
+  if (!activeUiSchema) {
+    throw new Error("UI data schema has not been initialized. Call initUiData() first.");
+  }
+  const parsed = activeUiSchema.safeParse(rawData);
+  if (!parsed.success) {
+    uiRuntimeState.error = parsed.error.message;
+    throw new Error(`Invalid replacement UI data: ${parsed.error.message}`);
+  }
+  applyUiData(parsed.data);
+}
+function getUiData(name) {
+  if (!uiRuntimeState.initialized) {
+    throw new Error("UI data has not been initialized. Call initUiData() before reading it.");
+  }
+  if (!(name in uiDataState)) {
+    throw new Error(`UI data "${name}" is not available.`);
+  }
+  return uiDataState[name];
+}
+function useUiData(name) {
+  if (!uiRuntimeState.initialized) {
+    throw new Error("UI data has not been initialized. Call initUiData() before rendering UI pages.");
+  }
+  const snapshot = (0, import_valtio3.useSnapshot)(uiDataState);
+  if (!(name in snapshot)) {
+    throw new Error(`UI data "${name}" is not available.`);
+  }
+  return snapshot[name];
+}
+
 // src/debug/runtime.ts
 var currentConnection = null;
 var currentController = null;
@@ -1254,11 +1641,14 @@ 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");
+  return message.type === "jump:request" && typeof message.sessionId === "string" && typeof message.requestId === "number" && typeof message.markerId === "string" && (message.story === void 0 || typeof message.story === "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 isUiReplaceMessage(message) {
+  return message.type === "ui:replace" && typeof message.sessionId === "string";
+}
 function sendRuntimeDebugMessage(socket, message) {
   const RuntimeWebSocket = getRuntimeWebSocket();
   if (!RuntimeWebSocket || socket.readyState !== RuntimeWebSocket.OPEN) {
@@ -1279,18 +1669,37 @@ function flushBufferedRequestMessages(socket, sessionId) {
     handleRuntimeDebugRequest(socket, sessionId, message);
   }
 }
+async function syncRuntimeDebugVariablesSnapshotSafe(reason) {
+  try {
+    await syncRuntimeDebugVariablesSnapshot(reason);
+  } catch (error) {
+    console.error("[debug] failed to sync runtime variables snapshot:", error);
+  }
+}
 function handleRuntimeDebugRequest(socket, sessionId, message) {
+  if (isUiReplaceMessage(message)) {
+    try {
+      replaceUiData(message.data);
+    } catch (error) {
+      console.error("[debug] failed to replace runtime UI data:", error);
+    }
+    return;
+  }
   const controller = currentController;
   if (!controller) {
     bufferRequestMessage(message);
     return;
   }
   if (isJumpRequestMessage(message)) {
+    setRuntimeDebugVariableEmissionSuspended(true);
     const runJump = message.strategy === "warp" ? controller.warp({
       markerId: message.markerId,
+      story: message.story,
       boundary: message.boundary
-    }).then(() => true) : controller.restoreCheckpoint(message.markerId);
-    void runJump.then((restored) => {
+    }).then(() => true) : controller.restoreCheckpoint(message.markerId, {
+      story: message.story
+    });
+    void runJump.then(async (restored) => {
       if (!restored) {
         sendRuntimeDebugMessage(socket, {
           type: "jump:error",
@@ -1299,6 +1708,7 @@ function handleRuntimeDebugRequest(socket, sessionId, message) {
           markerId: message.markerId,
           error: "Checkpoint not found"
         });
+        await syncRuntimeDebugVariablesSnapshotSafe("jump-error");
         return;
       }
       sendRuntimeDebugMessage(socket, {
@@ -1307,7 +1717,8 @@ function handleRuntimeDebugRequest(socket, sessionId, message) {
         requestId: message.requestId,
         markerId: message.markerId
       });
-    }).catch((error) => {
+      await syncRuntimeDebugVariablesSnapshotSafe("jump-done");
+    }).catch(async (error) => {
       sendRuntimeDebugMessage(socket, {
         type: "jump:error",
         sessionId,
@@ -1315,17 +1726,22 @@ function handleRuntimeDebugRequest(socket, sessionId, message) {
         markerId: message.markerId,
         error: error instanceof Error ? error.message : String(error)
       });
+      await syncRuntimeDebugVariablesSnapshotSafe("jump-error");
+    }).finally(() => {
+      setRuntimeDebugVariableEmissionSuspended(false);
     });
     return;
   }
-  void controller.switchPage(message.page, message.params).then(() => {
+  setRuntimeDebugVariableEmissionSuspended(true);
+  void controller.switchRoute(message.page, message.params).then(async () => {
     sendRuntimeDebugMessage(socket, {
       type: "route:done",
       sessionId,
       requestId: message.requestId,
       page: message.page
     });
-  }).catch((error) => {
+    await syncRuntimeDebugVariablesSnapshotSafe("route-done");
+  }).catch(async (error) => {
     sendRuntimeDebugMessage(socket, {
       type: "route:error",
       sessionId,
@@ -1333,6 +1749,9 @@ function handleRuntimeDebugRequest(socket, sessionId, message) {
       page: message.page,
       error: error instanceof Error ? error.message : String(error)
     });
+    await syncRuntimeDebugVariablesSnapshotSafe("route-error");
+  }).finally(() => {
+    setRuntimeDebugVariableEmissionSuspended(false);
   });
 }
 async function readDebugParams() {
@@ -1357,6 +1776,7 @@ async function stopRuntimeDebugSession() {
   const connection = currentConnection;
   currentConnection = null;
   currentController = null;
+  resetRuntimeDebugVariableMonitor();
   clearBufferedRequestMessages();
   const RuntimeWebSocket = getRuntimeWebSocket();
   await stopDebugSession();
@@ -1403,6 +1823,13 @@ async function startRuntimeDebugSession() {
       }
     }).then((controller) => {
       currentController = controller;
+      setRuntimeDebugVariableMessageSender((message) => {
+        sendRuntimeDebugMessage(socket, {
+          ...message,
+          sessionId
+        });
+      });
+      void syncRuntimeDebugVariablesSnapshotSafe("init");
       flushBufferedRequestMessages(socket, sessionId);
     }).catch((error) => {
       console.error("[debug] failed to start runtime debug session:", error);
@@ -1415,6 +1842,7 @@ async function startRuntimeDebugSession() {
     }
     currentConnection = null;
     currentController = null;
+    resetRuntimeDebugVariableMonitor();
     clearBufferedRequestMessages();
     void stopDebugSession();
   };
@@ -1441,6 +1869,10 @@ async function startRuntimeDebugSession() {
         handleRuntimeDebugRequest(socket, sessionId, message);
         return;
       }
+      if (isUiReplaceMessage(message)) {
+        handleRuntimeDebugRequest(socket, sessionId, message);
+        return;
+      }
       if (message.type && message.type !== "session:init") {
         console.debug("[debug] runtime received message:", message);
       }
@@ -1552,13 +1984,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 {
@@ -1674,49 +2106,31 @@ function useScenario(stories, startName, entryName, goNextOnLoad = false) {
 
 // src/hooks/useSoundEffect.ts
 var import_react4 = require("react");
-var LOADED_SOUNDS = /* @__PURE__ */ new Set();
 function useSoundEffect(src) {
   (0, import_react4.useEffect)(() => {
-    const loadSound = async () => {
-      try {
-        await executePluginCommand("audio", {
-          subCommand: "load",
-          name: src,
-          src
-        });
-      } catch (error) {
-        console.error(`Failed to load sound effect ${src}:`, error);
-      }
-      LOADED_SOUNDS.add(src);
-    };
-    let needRelease = false;
-    if (!LOADED_SOUNDS.has(src)) {
-      void loadSound();
-      needRelease = true;
-    }
     return () => {
-      const releaseSound = () => {
-        try {
+      try {
+        if (src) {
           executePluginCommand("audio", {
             subCommand: "release",
-            name: src
+            name: src,
+            silentFail: true
           });
-        } catch (error) {
-          console.error(`Failed to release sound effect ${src}:`, error);
         }
-        LOADED_SOUNDS.delete(src);
-      };
-      if (needRelease) {
-        releaseSound();
+      } catch (error) {
+        console.error(`Failed to release sound effect ${src}:`, error);
       }
     };
   }, [src]);
   return (0, import_react4.useCallback)(() => {
     try {
-      executePluginCommand("audio", {
-        subCommand: "play",
-        name: src
-      });
+      if (src) {
+        executePluginCommand("audio", {
+          subCommand: "loadAndPlay",
+          name: src,
+          src
+        });
+      }
     } catch (error) {
       console.error(`Failed to play sound effect ${src}:`, error);
     }
@@ -1725,25 +2139,25 @@ function useSoundEffect(src) {
 
 // src/hooks/useStage.ts
 var import_react5 = require("react");
-var import_valtio3 = require("valtio");
+var import_valtio4 = require("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 = (0, import_valtio3.proxy)({ active: false });
-var autoState = (0, import_valtio3.proxy)({ active: false });
-var fastForwardState = (0, import_valtio3.proxy)({ active: false });
-var warpState = (0, import_valtio3.proxy)({ active: false });
+var skipState = (0, import_valtio4.proxy)({ active: false });
+var autoState = (0, import_valtio4.proxy)({ active: false });
+var fastForwardState = (0, import_valtio4.proxy)({ active: false });
+var warpState = (0, import_valtio4.proxy)({ active: false });
 function useIsSkipping() {
-  return (0, import_valtio3.useSnapshot)(skipState).active;
+  return (0, import_valtio4.useSnapshot)(skipState).active;
 }
 function useIsAutoing() {
-  return (0, import_valtio3.useSnapshot)(autoState).active;
+  return (0, import_valtio4.useSnapshot)(autoState).active;
 }
 function useIsSeeking() {
-  return (0, import_valtio3.useSnapshot)(fastForwardState).active;
+  return (0, import_valtio4.useSnapshot)(fastForwardState).active;
 }
 function getSeekingType() {
   if (warpState.active) return "warp";