@lingfan-engine/core 0.2.0 → 0.3.0

package/src/data/text/parse/statement/flow.ts

@@ -113,7 +113,7 @@ export function parseFlowStatement(c: StatementContext): StoryCommand | null {
       // ——若一律落到「暂不支持的语句」，整个工程就打不开。
       //
       // 语义对齐：`scene "x"`（跳转）≡ `navigate "x"`（坐标切换命令）。
-      // 区别于**列声明**的 `scene "名" type=menu`（那个在顶层解析，见 `parseTextStory`）。
+      // 区别于**列声明**的 `scene "名" type=ui`（那个在顶层解析，见 `parseTextStory`）。
       // `tokens[0]` 是 op 本身，目标名在 `tokens[1]`（`splitTokens` 的口径）
       const target = quoted(0);
       if (target === "") return fail("scene 需要目标场景名");

package/src/data/text/parse/statement/index.ts

@@ -1,7 +1,7 @@
 /**
  * 语句解析族出口：按命令族分片的语句解析器。
  *
- * 轴 = 命令族（集合 / 对话 / 流程 / 媒体 / 表演 / 存档 / 变量），每片只认自己那族的关键字。
+ * 轴 = 命令族（集合 / 对话 / 流程 / 媒体 / 表演 / 存档 / UI / 变量），每片只认自己那族的关键字。
  */
 export { parseCollectionsStatement } from "./collections.ts";
 export { parseDialogStatement } from "./dialog.ts";
@@ -9,4 +9,5 @@ export { parseFlowStatement } from "./flow.ts";
 export { parseMediaStatement } from "./media.ts";
 export { parsePresentStatement } from "./present.ts";
 export { parseSaveStatement } from "./save.ts";
+export { parseUiStatement } from "./ui.ts";
 export { parseVariablesStatement } from "./variables.ts";

package/src/data/text/parse/statement/media.ts

@@ -1,10 +1,13 @@
 /** media 族的读向解析。 */
 import { unquote } from "../../lexer.ts";
+import { isAudioChannel } from "../../../../shared/index.ts";
 import type { StoryCommand } from "../../../../contracts/index.ts";
 import type { StatementContext } from "../state.ts";
 
 /**
- * 解析本族的 op 行（`bgm` `se` `ambient` `voice` `stop_bgm` `stop_ambient` `stop_voice` `video` `cutscene` `seek_video` `pause_video` `resume_video` `stop_video` `video_skipable`）。
+ * 解析本族的 op 行（`bgm` `se` `ambient` `voice` `stop_bgm` `stop_ambient` `stop_voice` `stop_se`
+ * `audio_play` `audio_stop` `audio_volume` `audio_pause` `audio_resume` `video` `cutscene`
+ * `seek_video` `pause_video` `resume_video` `stop_video` `video_skipable`）。
  *
  * 入参是分发骨架建好的 `StatementContext`（已切好的词表、定位前缀、issue 出口与警告通道）。
  * 只处理本族的 op，不匹配时落到末尾 `return null`，由骨架决定后续。
@@ -51,7 +54,8 @@ export function parseMediaStatement(c: StatementContext): StoryCommand | null {
     }
     case "stop_bgm":
     case "stop_ambient":
-    case "stop_voice": {
+    case "stop_voice":
+    case "stop_se": {
       const cmd: StoryCommand = { op };
       for (const token of tokens) {
         const eq = token.indexOf("=");
@@ -65,6 +69,79 @@ export function parseMediaStatement(c: StatementContext): StoryCommand | null {
       }
       return cmd;
     }
+    // 音频实例族：位置参数是 id（与 resource 的引号形态区分开，作者一眼能看出哪个是名字）
+    case "audio_play": {
+      const inst = tokens[0];
+      const channel = tokens[1];
+      const resource = tokens.find((t) => t.startsWith('"'));
+      if (inst === undefined) return fail("audio_play 需要实例 id");
+      if (channel === undefined) return fail("audio_play 需要 channel");
+      if (resource === undefined) return fail("audio_play 需要 resource");
+      const cmd: StoryCommand = {
+        op: "audio_play",
+        inst,
+        channel,
+        resource: unquote(resource),
+      };
+      for (const token of tokens) {
+        if (token === inst || token === channel || token.startsWith('"'))
+          continue;
+        const eq = token.indexOf("=");
+        const key = eq < 0 ? token : token.slice(0, eq);
+        const raw = eq < 0 ? "" : token.slice(eq + 1);
+        if (key === "volume" || key === "fade") {
+          const num = Number(raw);
+          if (eq < 0 || raw === "" || Number.isNaN(num))
+            return fail(`audio_play 的 ${key} 需要数字`);
+          cmd[key] = num;
+        } else if (key === "loop" || key === "restart") {
+          if (raw !== "true" && raw !== "false")
+            return fail(`audio_play 的 ${key} 需要 true|false`);
+          cmd[key] = raw === "true";
+        } else {
+          return fail(`audio_play 未知参数：${token}`);
+        }
+      }
+      return cmd;
+    }
+    case "audio_stop": {
+      const cmd: StoryCommand = { op: "audio_stop" };
+      for (const token of tokens) {
+        const eq = token.indexOf("=");
+        if (eq < 0) {
+          // 唯一的无等号位置参数是目标实例；重复给就是写错
+          if (cmd.inst !== undefined)
+            return fail(`audio_stop 只有一个实例位置参数：${token}`);
+          cmd.inst = token;
+          continue;
+        }
+        const key = token.slice(0, eq);
+        const raw = token.slice(eq + 1);
+        if (key !== "fade") return fail(`audio_stop 未知参数：${token}`);
+        const num = Number(raw);
+        if (raw === "" || Number.isNaN(num))
+          return fail("audio_stop 的 fade 需要数字");
+        cmd.fade = num;
+      }
+      return cmd;
+    }
+    case "audio_volume": {
+      const inst = tokens[0];
+      let volume: number | undefined;
+      for (const token of tokens.slice(1)) {
+        const eq = token.indexOf("=");
+        const key = eq < 0 ? token : token.slice(0, eq);
+        const raw = eq < 0 ? "" : token.slice(eq + 1);
+        if (key !== "volume") return fail(`audio_volume 未知参数：${token}`);
+        const num = Number(raw);
+        if (eq < 0 || raw === "" || Number.isNaN(num))
+          return fail("audio_volume 的 volume 需要数字");
+        volume = num;
+      }
+      if (inst === undefined) return fail("audio_volume 需要实例 id");
+      if (volume === undefined) return fail("audio_volume 需要 volume");
+      return { op: "audio_volume", inst, volume };
+    }
     // 视频族：resource 位置参数（video/cutscene）；seek_video 为秒数
     case "video":
     case "cutscene": {
@@ -102,6 +179,18 @@ export function parseMediaStatement(c: StatementContext): StoryCommand | null {
     }
     case "pause_video":
       return { op: "pause_video" } as StoryCommand;
+    case "audio_pause":
+    case "audio_resume": {
+      // 位置参数可选：不写 channel = 全部常驻通道（se 除外），由执行期展开
+      const raw = tokens[0];
+      if (tokens.length > 1) return fail(`${op} 只接受一个 channel 参数`);
+      if (raw === undefined) return { op } as StoryCommand;
+      if (!isAudioChannel(raw))
+        return fail(
+          `${op} 的 channel 不合法：${raw}（须为 bgm / se / ambient / voice 之一）`,
+        );
+      return { op, channel: raw } as StoryCommand;
+    }
     case "resume_video":
       return { op: "resume_video" } as StoryCommand;
     case "stop_video":

package/src/data/text/parse/statement/ui.ts

@@ -0,0 +1,47 @@
+/** ui 族的读向解析。 */
+import { parseDictLiteral, extractKeyedDictLiteral } from "../../literals.ts";
+import { splitTokens } from "../../lexer.ts";
+import type { StoryCommand } from "../../../../contracts/index.ts";
+import type { StatementContext } from "../state.ts";
+
+/**
+ * 解析本族的 op 行（`mount`）。
+ *
+ * 入参是分发骨架建好的 `StatementContext`（已切好的词表、定位前缀、issue 出口与警告通道）。
+ * 只处理本族的 op，不匹配时落到末尾 `return null`，由骨架决定后续。
+ * 失败表现：不抛异常；语法或参数不符时用 `c.fail` 记一条带定位的 issue 并返回 `null`，
+ * 由调用方按 issues 非空整次拒绝。
+ *
+ * 形态：`mount <UI 名> <true|false> [props={…}]`。UI 名不带引号（短标识，与 `id=`/`name=`
+ * 等位置参同形）；显隐只认字面 `true` / `false`——没有「切换」写法，避免文本形态与状态语义
+ * 各说一套。
+ */
+export function parseUiStatement(c: StatementContext): StoryCommand | null {
+  const { op, rest, tokens, fail } = c;
+  switch (op) {
+    case "mount": {
+      const name = tokens[0];
+      if (name === undefined) return fail("mount 需要 UI 名");
+      const visible = tokens[1];
+      if (visible !== "true" && visible !== "false")
+        return fail("mount 需要 true|false（显隐必填，没有切换写法）");
+      const cmd: StoryCommand = {
+        op: "mount",
+        name,
+        visible: visible === "true",
+      };
+      const dict = extractKeyedDictLiteral(rest, "props");
+      if (dict !== null) {
+        const extra = splitTokens(dict.remainder).filter(
+          (t) => t !== name && t !== visible,
+        );
+        if (extra.length > 0) return fail(`mount 未知参数：${extra[0]}`);
+        cmd.props = parseDictLiteral(dict.literal);
+        return cmd;
+      }
+      if (tokens.length > 2) return fail(`mount 未知参数：${tokens[2]}`);
+      return cmd;
+    }
+  }
+  return null;
+}

package/src/data/text/parse/statement.ts

@@ -12,6 +12,7 @@ import {
   parseMediaStatement,
   parsePresentStatement,
   parseSaveStatement,
+  parseUiStatement,
   parseVariablesStatement,
 } from "./statement/index.ts";
 import { unquote } from "../lexer.ts";
@@ -97,6 +98,12 @@ export function parseSimpleStatement(
     case "stop_bgm":
     case "stop_ambient":
     case "stop_voice":
+    case "stop_se":
+    case "audio_play":
+    case "audio_stop":
+    case "audio_volume":
+    case "audio_pause":
+    case "audio_resume":
     case "video":
     case "cutscene":
     case "seek_video":
@@ -118,6 +125,8 @@ export function parseSimpleStatement(
     case "shake":
     case "text_typewriter":
       return parsePresentStatement(ctx);
+    case "mount":
+      return parseUiStatement(ctx);
     default:
       return fail(`文本投影暂不支持的语句：${op}`);
   }

package/src/index.ts

@@ -4,7 +4,7 @@
  * 内部按功能域归类，每个域有自己的出口，包出口只转发这些出口：
  * `contracts/`（契约，全量转发）、`runtime/index.ts`（执行器与运行期支撑）、
  * `data/index.ts`（故事文件解析·工程组装·文本投影·元素装载）。
- * 包出口不逐个深入实现文件；域内零件（`runtime/scope`、`runtime/resolver` 等）不经这里暴露。
+ * 包出口不逐个深入实现文件；域内零件（`runtime/scope`、`runtime/expr/resolver.ts` 等）不经这里暴露。
  */
 export * from "./contracts/index.ts";
 /**
@@ -35,7 +35,9 @@ export {
   collectGuardNames,
   collectTextProjections,
   collectWaitSpecs,
+  columnSummaries,
   createStateReader,
+  DEFAULT_AUDIO_CONFIG,
   DEFAULT_LAYER_Z,
   DEFAULT_SAVES_CONFIG,
   DEFAULT_STAGE_CONFIG,
@@ -53,10 +55,12 @@ export {
   manifestOrientation,
   mergeOverlayFiles,
   PlayerPreferences,
+  resolveAudioConfig,
   resolveHost,
   resolveInstanceZ,
   resolveLayerZ,
   resolveOrientationMode,
+  resolveProjectName,
   resolveSavesConfig,
   resolveStageConfig,
   slotIds,
@@ -64,6 +68,8 @@ export {
   WAITING_OPS,
   waitSpecOfOp,
   waitingStateOfOp,
+  directionOf,
+  type AudioConfig,
   type EngineOptions,
   type ExtensionModuleLoader,
   type GuardContext,
@@ -112,6 +118,7 @@ export {
   ProjectSerializationError,
   projectText,
   removeElements,
+  RESOURCES_DIR,
   serializeColumnDocument,
   serializeProject,
   STORIES_DIR,

package/src/runtime/dispatch.ts

@@ -13,6 +13,9 @@ import {
   execAssert,
   execAssign,
   execAudio,
+  execAudioInstance,
+  execAudioPause,
+  execAudioResume,
   execAutoSaveOp,
   execCall,
   execCharacter,
@@ -31,6 +34,7 @@ import {
   execLoadOp,
   execMenu,
   execMinigame,
+  execMount,
   execNavigate,
   execNotify,
   execNvl,
@@ -253,9 +257,24 @@ export function runDispatch(ctx: OpContext): void {
       case "stop_ambient":
       case "voice":
       case "stop_voice":
+      case "stop_se":
         if (!execAudio(ctx, cmd)) return;
         frame.index += 1;
         continue;
+      case "audio_play":
+      case "audio_stop":
+      case "audio_volume":
+        if (!execAudioInstance(ctx, cmd)) return;
+        frame.index += 1;
+        continue;
+      case "audio_pause":
+        if (!execAudioPause(ctx, cmd)) return;
+        frame.index += 1;
+        continue;
+      case "audio_resume":
+        if (!execAudioResume(ctx, cmd)) return;
+        frame.index += 1;
+        continue;
       case "video":
       case "seek_video":
       case "pause_video":
@@ -306,6 +325,11 @@ export function runDispatch(ctx: OpContext): void {
         if (!execTextTypewriter(ctx, cmd)) return;
         frame.index += 1;
         continue;
+      case "mount":
+        // 挂载 UI 显隐：写 SYS.mounts（宿主据此挂载/卸载渲染树上的组件）
+        if (!execMount(ctx, cmd)) return;
+        frame.index += 1;
+        continue;
       default:
         // fail-closed：未知/未实现 op 不静默跳过
         ctx.fail("unknown-op", `未知或未实现的命令：${cmd.op}`);

package/src/runtime/engine/columns.ts

@@ -0,0 +1,31 @@
+/**
+ * 列清单投影：故事定义 → 宿主可读的只读摘要。
+ *
+ * **为什么要这一层而不是让宿主读 `story.columns`**：宿主一旦拿到整份 `StoryColumn`，
+ * 就能拿到 `commands` / `elements` / `entry`——那是引擎的解释输入。宿主自己解释一遍
+ * 命令流，等于在引擎之外再造一套解释器，两套必然漂移。这里只交出宿主真正用得上的
+ * 三件事：列 id、归一后的类型、内容形态。
+ *
+ * **写时复制**：每次调用都新建数组与对象并冻结。摘要一旦可写，宿主改一个 `type`
+ * 就会让「引擎认为的列类型」和「宿主认为的」分叉，而引擎那边毫不知情。
+ * 冻结把这种改动静默变成立即报错（严格模式下赋值抛 TypeError）。
+ */
+import { sceneTypeOf } from "../../shared/guards.ts";
+import type { ColumnSummary } from "../../contracts/runtime/column-summary.ts";
+import type { Story } from "../../contracts/story/entities.ts";
+
+/**
+ * 造一份列摘要表（顺序与 `story.columns` 一致）。
+ *
+ * 顺序即呈现顺序：宿主列章节时按这个次序，跳转与「下一列」也据此推断，
+ * 所以**不排序、不去重**——故事里的顺序就是作者写的顺序。
+ */
+export function columnSummaries(story: Story): readonly ColumnSummary[] {
+  return story.columns.map((column) =>
+    Object.freeze<ColumnSummary>({
+      id: column.id,
+      type: sceneTypeOf(column),
+      kind: column.kind,
+    }),
+  );
+}

package/src/runtime/engine/forwarders.ts

@@ -63,7 +63,7 @@ import {
   restoreSaveExtensions,
   tryMigrateSave,
 } from "../save/index.ts";
-import { type NameResolver } from "../resolver.ts";
+import { type NameResolver } from "../expr/resolver.ts";
 import type {
   ColumnCoordinate,
   ElementInstance,
@@ -204,9 +204,12 @@ export abstract class EngineForwarders extends EngineCore {
   protected columnFrame(): Frame | undefined {
     return columnFrame(this.ctx);
   }
-  /** 内部转发 → ./internal：按坐标取执行帧（回溯重建用） */
-  protected columnFrameAt(coord: ColumnCoordinate): Frame {
-    return columnFrameAt(this.ctx, coord);
+  /** 内部转发 → ./internal：按坐标取执行帧（回溯重建用）；`scope` 给定时作为列级层内容 */
+  protected columnFrameAt(
+    coord: ColumnCoordinate,
+    scope?: readonly (readonly [string, unknown])[],
+  ): Frame {
+    return columnFrameAt(this.ctx, coord, scope);
   }
   /** 内部转发 → ./save：旧版本存档迁移；未注入迁移钩子时拒绝 */
   protected tryMigrateSave(data: SaveDataV1): SaveDataV1 | null {

package/src/runtime/engine/game-state.ts

@@ -0,0 +1,29 @@
+/**
+ * 外部玩法系统的状态写入面：把「作用域化键」与「是否触发观察事件」的四种组合
+ * 收成 `GameStateWriter` 契约要求的五个方法。
+ *
+ * 两个入参是引擎侧的两条既有通道（外部写入 + 只读取值），这里只做组合，
+ * 不复制键校验与值契约——那两条规则的唯一实现在 `../state/writer.ts`。
+ */
+import { gameScopedKey, type GameStateWriter } from "../../contracts/index.ts";
+
+export function createGameState(
+  write: (
+    key: string,
+    value: unknown,
+    emitChange: boolean,
+    systemId?: string,
+  ) => boolean,
+  read: (key: string) => unknown,
+): GameStateWriter {
+  return {
+    set: (key: string, value: unknown): boolean => write(key, value, true),
+    setSilent: (key: string, value: unknown): boolean =>
+      write(key, value, false),
+    setScoped: (systemId: string, key: string, value: unknown): boolean =>
+      write(gameScopedKey(systemId, key), value, true, systemId),
+    setScopedSilent: (systemId: string, key: string, value: unknown): boolean =>
+      write(gameScopedKey(systemId, key), value, false, systemId),
+    get: (key: string): unknown => read(key),
+  };
+}

package/src/runtime/engine/index.ts

@@ -6,3 +6,5 @@
  */
 export { EngineCore } from "./state.ts";
 export { EngineForwarders } from "./forwarders.ts";
+export { createGameState } from "./game-state.ts";
+export { columnSummaries } from "./columns.ts";

package/src/runtime/engine/state.ts

@@ -9,6 +9,7 @@
  * 改字段含义看本层；改行为去 `./internal`、`./state`、`./history`、`./save`、`./ops`、`./i18n`。
  */
 import type {
+  AudioConfig,
   CharacterDef,
   ColumnCoordinate,
   EngineOptions,
@@ -27,7 +28,11 @@ import type {
   GuardFn,
   SaveDataV1,
 } from "../../contracts/index.ts";
-import { defaultEngineTexts, hostTimer } from "../../contracts/index.ts";
+import {
+  DEFAULT_AUDIO_CONFIG,
+  defaultEngineTexts,
+  hostTimer,
+} from "../../contracts/index.ts";
 import {
   buildMinigameRegistry,
   buildOpRegistry,
@@ -59,6 +64,10 @@ export class EngineCore {
   protected started = false;
   /** 等待型命令的定时器句柄；换列、回溯、读档、热重载、销毁时必须清掉，否则会推进已失效的等待 */
   protected pendingTimer: TimerHandle | null = null;
+  /** 挂起定时器的到期时刻；`clear` 之后句柄再也问不出剩余量，只能靠它算 */
+  protected pendingTimerDueAt: number | null = null;
+  /** 暂停时挂起定时器的剩余毫秒；恢复按它续上原来的节奏，`null` = 无待续起定时器 */
+  protected pausedTimerRemainingMs: number | null = null;
   /** 定时器端口（wait/pause 的延迟回调来源；缺省 hostTimer = 宿主全局定时器） */
   protected readonly timerPort: TimerPort;
   /** 用户可见文案表（缺省 defaultEngineTexts；宿主经 EngineOptions.texts 部分覆盖） */
@@ -136,6 +145,8 @@ export class EngineCore {
   protected savePort: SavePort | undefined;
   /** 存档模式：决定存档可否跨设备读取，也决定 DEK 封装方式（本机绑定 = 用 OS 凭据封存；可携带 = 明文随档）；构造期注入，运行期不变 */
   protected saveMode: SaveMode;
+  /** 工程默认音量（非状态：来自 project.json，不进存档 / 不进快照 / 不进回溯） */
+  protected audioConfig: AudioConfig;
   /** save op 的一次性存档声明：载荷在下一玩家所见等待画面落档（coord = 等待点） */
   protected pendingSave: { slot: string; title?: string } | null = null;
   /** I18N 端口与当前语言译文表（null = 原文直出；切换 = 整表重建并清缓存） */
@@ -181,6 +192,7 @@ export class EngineCore {
     this.rngState = (options?.rngSeed ?? Date.now()) | 0;
     this.savePort = options?.savePort;
     this.saveMode = options?.saveMode ?? "machine-bound";
+    this.audioConfig = options?.audioConfig ?? DEFAULT_AUDIO_CONFIG;
     this.i18nPort = options?.i18nPort;
     this.timerPort = options?.timerPort ?? hostTimer;
     this.texts = { ...defaultEngineTexts, ...options?.texts };

package/src/runtime/engine.ts

@@ -7,6 +7,7 @@ import type {
   AnimationSpec,
   CharacterDef,
   ColumnCoordinate,
+  ColumnSummary,
   ElementInstance,
   EngineOptions,
   EventListener,
@@ -17,7 +18,6 @@ import type {
   SaveOptions,
 } from "../contracts/index.ts";
 import {
-  gameScopedKey,
   type ExtensionOpResult,
   type GameStateWriter,
   type InteractionResult,
@@ -35,8 +35,11 @@ import {
   historyLength,
   historyView,
   rollbackTo,
+  type HistoryViewEntry,
 } from "./history/index.ts";
 import { exportSave, importSave } from "./save/index.ts";
+import { pauseSession, resumeSession } from "./session/index.ts";
+import { columnSummaries } from "./engine/columns.ts";
 import {
   advance,
   animationFinished,
@@ -53,6 +56,7 @@ import {
   navigate,
   onEvent,
   onStateChanged,
+  pausedSession,
   reloadStory,
   reportMediaPosition,
   save,
@@ -63,7 +67,7 @@ import {
   videoFinished,
   type OpContext,
 } from "./internal/index.ts";
-import { EngineForwarders } from "./engine/index.ts";
+import { EngineForwarders, createGameState } from "./engine/index.ts";
 
 /**
  * 装配契约（构造选项与守卫）定义在契约层，此处按原路径转出，
@@ -168,6 +172,8 @@ export class StoryEngine extends EngineForwarders {
       this.eventListeners,
       this.started,
       this.pendingTimer,
+      this.pendingTimerDueAt,
+      this.pausedTimerRemainingMs,
       this.waitSkipable,
       this.timerPort,
       this.texts,
@@ -179,6 +185,8 @@ export class StoryEngine extends EngineForwarders {
       this.videoSeq,
       this.savePort,
       this.saveMode,
+      // 工程级配置（非状态）
+      this.audioConfig,
       this.i18nPort,
       this.clearTimer,
       this.abortExternalTakeovers,
@@ -231,6 +239,19 @@ export class StoryEngine extends EngineForwarders {
     return this.state.get(key);
   }
 
+  // —— 列清单 ——
+
+  /**
+   * 故事列清单的只读摘要（顺序同故事定义）：宿主据此列章节、判当前页、决定跳哪。
+   *
+   * **每次调用都返回新数组**，元素是冻结对象——调用方随手 `push` / 改字段都碰不到引擎。
+   * 不含 `commands` / `elements` / `entry`：那部分归引擎解释，宿主不应自己再解释一遍。
+   * 热重载后重新调用即得新清单（不要缓存返回值跨重载使用）。
+   */
+  columns(): readonly ColumnSummary[] {
+    return columnSummaries(this.story);
+  }
+
   // —— 命令面 ——
   // 公开方法都是转交给实现模块的薄壳，语义与错误处理以目标模块为准；夹在其中的
   // private 成员是同一转发模式的内部版本，供迁出的自由函数经 ctx 回调本类私有面。
@@ -267,6 +288,23 @@ export class StoryEngine extends EngineForwarders {
   dispose(): void {
     dispose(this.ctx);
   }
+  /**
+   * 暂停：挂起等待定时器、让正在出声的媒体收声、记下暂停标记。
+   *
+   * 幂等。**不中断外部接管**（小游戏 / 玩法系统 / 扩展 op 等待保持挂载，只是不再收到推进输入），
+   * 否则再恢复就不是「接着玩」而是「重进」。暂停期间 `advance()` / `choose()` fail-closed。
+   */
+  pause(): void {
+    pauseSession(this.ctx);
+  }
+  /** 解除暂停：按剩余毫秒续上原来的等待，媒体按当前状态逐个恢复。未暂停时幂等空操作 */
+  resume(): void {
+    resumeSession(this.ctx);
+  }
+  /** 是否处于暂停中 */
+  paused(): boolean {
+    return pausedSession(this.ctx);
+  }
   /** 当前舞台上的元素实例列表，供宿主渲染 */
   elements(): ElementInstance[] {
     return elements(this.ctx);
@@ -296,17 +334,11 @@ export class StoryEngine extends EngineForwarders {
     return resolveExtensionOp(this.ctx, op, result);
   }
   /** 外部玩法系统的状态写入面：作用域化键与「是否触发观察事件」的四种组合 */
-  readonly gameState: GameStateWriter = {
-    set: (key: string, value: unknown): boolean =>
-      this.writeExternal(key, value, true),
-    setSilent: (key: string, value: unknown): boolean =>
-      this.writeExternal(key, value, false),
-    setScoped: (systemId: string, key: string, value: unknown): boolean =>
-      this.writeExternal(gameScopedKey(systemId, key), value, true, systemId),
-    setScopedSilent: (systemId: string, key: string, value: unknown): boolean =>
-      this.writeExternal(gameScopedKey(systemId, key), value, false, systemId),
-    get: (key: string): unknown => this.state.get(key),
-  };
+  readonly gameState: GameStateWriter = createGameState(
+    (key, value, emitChange, systemId) =>
+      this.writeExternal(key, value, emitChange, systemId),
+    (key) => this.state.get(key),
+  );
   /** 查角色定义（character op 注册；say 的 speaker 按它套样式） */
   getCharacter(key: string): CharacterDef | undefined {
     return getCharacter(this.ctx, key);
@@ -376,14 +408,7 @@ export class StoryEngine extends EngineForwarders {
     reloadStory(this.ctx, story);
   }
   /** 历史浏览视图：逐条给出序号、坐标、说话人与文本（nvl 另带多行） */
-  historyView(): Array<{
-    index: number;
-    coord: ColumnCoordinate;
-    speaker: string;
-    text: string;
-    nvl: boolean;
-    nvlLines: string[];
-  }> {
+  historyView(): HistoryViewEntry[] {
     return historyView(this.ctx);
   }
 }

package/src/runtime/expr/builtins.ts

@@ -6,7 +6,7 @@
  * （配合 `??` 兜底），路径存在但形态不符仍 fail-closed；未知函数 fail-closed。
  */
 import { ExpressionError, type ExprValue } from "./value.ts";
-import type { NameResolver } from "../resolver.ts";
+import type { NameResolver } from "./resolver.ts";
 
 /** 内建函数全集：random/min/max/abs/clamp（算术）+ arrayGet/dictGet/optGet/len（路径读取） */
 export function callBuiltin(

package/src/runtime/expr/evaluate.ts

@@ -1,7 +1,7 @@
 /**
  * 求值入口：解析 + 求值一步完成（求值时机 = 执行到它的时刻）。
  */
-import type { NameResolver } from "../resolver.ts";
+import type { NameResolver } from "./resolver.ts";
 import { tokenize } from "./lexer.ts";
 import { Parser } from "./parser/index.ts";
 import { ExpressionError, type ExprValue } from "./value.ts";

package/src/runtime/expr/index.ts

@@ -12,4 +12,4 @@ export {
 } from "./value.ts";
 export { evaluateExpression } from "./evaluate.ts";
 export { interpolateText, type TextInterpolation } from "./interpolate.ts";
-export type { NameResolver } from "../resolver.ts";
+export type { NameResolver } from "./resolver.ts";

package/src/runtime/expr/interpolate.ts

@@ -3,7 +3,7 @@
  *
  * 行内富文本标记原样透传给渲染层；插值失败保留原文片段并收集错误。
  */
-import type { NameResolver } from "../resolver.ts";
+import type { NameResolver } from "./resolver.ts";
 import { evaluateExpression } from "./evaluate.ts";
 import { ExpressionError, type ExprValue } from "./value.ts";
 

package/src/runtime/expr/parser/cursor.ts

@@ -5,7 +5,7 @@
  * 游标把「只有这里能改 pos」收在一处；peek 在越界时钳到末尾的 eof，
  * 所以上层各层不必各自判边界。
  */
-import type { NameResolver } from "../../resolver.ts";
+import type { NameResolver } from "../resolver.ts";
 import type { Token } from "../lexer.ts";
 import { ExpressionError, type ExprValue } from "../value.ts";
 

package/src/runtime/history/index.ts

@@ -24,3 +24,4 @@ export {
   lastReplayableCursor,
   rollbackTo,
 } from "./rollback.ts";
+export type { HistoryViewEntry } from "./rollback.ts";