@lingfan-engine/core 0.1.5 → 0.3.0

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";

package/src/runtime/history/rollback.ts

@@ -53,14 +53,24 @@ export function columnFrame(ctx: OpContext): Frame | undefined {
   return undefined;
 }
 
-/** 按坐标重建列帧（存档不进帧栈——块/列级作用域不进档，读档后确定性重放重建） */
-export function columnFrameAt(ctx: OpContext, coord: ColumnCoordinate): Frame {
+/**
+ * 按坐标重建列帧。
+ *
+ * 列级作用域由调用方给：读档时必须带上存档里的 `scope`（列级声明都在存档坐标
+ * 之前，重放不会回到那些命令）；回溯用检查点自带的帧栈，不走这里。
+ * 块级帧一律不重建——它们由重放重入块体重建。
+ */
+export function columnFrameAt(
+  ctx: OpContext,
+  coord: ColumnCoordinate,
+  scope?: readonly (readonly [string, unknown])[],
+): Frame {
   const column = ctx.columnById(coord.columnId)!;
   return {
     columnId: coord.columnId,
     commands: column.kind === "flow" ? column.commands! : (column.entry ?? []),
     index: coord.index,
-    scope: Scope.root(),
+    scope: scope === undefined ? Scope.root() : Scope.fromEntries(scope),
   };
 }
 
@@ -168,18 +178,23 @@ export function forward(ctx: OpContext): void {
 }
 
 /**
- * 历史面板数据（前端职责的可视化皮）：对话类检查点带说话者与文本；
- * NVL 检查点额外带 `nvl` 标记与**累积行快照**（nvlLines = 该时刻玩家已见的整块文本）——
- * 宿主按「段聚合」呈现（历史不灌水），回溯粒度不变（逐检查点仍全在 history 里）。
+ * 历史面板的一条记录：对话类检查点带说话者与文本；
+ * NVL 检查点额外带 `nvl` 标记与**累积行快照**（nvlLines = 该时刻玩家已见的整块文本）。
  */
-export function historyView(ctx: OpContext): Array<{
+export interface HistoryViewEntry {
   index: number;
   coord: ColumnCoordinate;
   speaker: string;
   text: string;
   nvl: boolean;
   nvlLines: string[];
-}> {
+}
+
+/**
+ * 历史面板数据（前端职责的可视化皮）：宿主按「段聚合」呈现（历史不灌水），
+ * 回溯粒度不变（逐检查点仍全在 history 里）。
+ */
+export function historyView(ctx: OpContext): HistoryViewEntry[] {
   return ctx.history.map((cp, index) => {
     const mode = cp.snapshot.state.find(([k]) => k === SYS.nvlMode)?.[1];
     const buffer = cp.snapshot.state.find(([k]) => k === SYS.nvlBuffer)?.[1];

package/src/runtime/index.ts

@@ -3,11 +3,12 @@
  * 写入契约守卫 / op 注册表 / 等待声明表 / 扩展装载 / 表达式求值 / 状态读口）。
  *
  * 这是包出口（`src/index.ts`）取运行层符号的唯一入口——包出口不再逐个深入实现文件；
- * 运行层内部各模块之间仍按需直接引用（`./resolver` 属内部零件，不经此出口；
+ * 运行层内部各模块之间仍按需直接引用（`./expr/resolver.ts` 属表达式域内部零件；
  * `./scope` 供 `tests/engine/runtime/scope.test.ts` 的白盒用例经域出口取用）。
  */
 export { StoryEngine } from "./engine.ts";
 export type { EngineOptions, GuardContext, GuardFn } from "./engine.ts";
+export { columnSummaries } from "./engine/index.ts";
 export { isValidSayColor } from "./ops/index.ts";
 export { resolveHost } from "./host.ts";
 export { mergeOverlayFiles } from "./i18n/index.ts";
@@ -15,6 +16,7 @@ export { PlayerPreferences } from "./preferences.ts";
 export { createStateReader } from "./state/index.ts";
 export { Scope } from "./scope.ts";
 export {
+  DEFAULT_AUDIO_CONFIG,
   DEFAULT_LAYER_Z,
   DEFAULT_SAVES_CONFIG,
   DEFAULT_STAGE_CONFIG,
@@ -22,14 +24,17 @@ export {
   instanceZLayer,
   LAYER_IDS,
   manifestOrientation,
+  resolveAudioConfig,
   resolveInstanceZ,
   resolveLayerZ,
   resolveOrientationMode,
+  resolveProjectName,
   resolveSavesConfig,
   resolveStageConfig,
   slotIds,
 } from "./shell.ts";
 export type {
+  AudioConfig,
   LayerId,
   LayerZOverrides,
   LayerZTable,
@@ -40,7 +45,7 @@ export type {
   StageFit,
   StageScalePolicy,
 } from "./shell.ts";
-export { findJsonValueError, jsonUnsafeReason } from "./stateContract.ts";
+export { findJsonValueError, jsonUnsafeReason } from "./state/index.ts";
 export { collectGuardNames, findMissingGuards } from "./guardNames.ts";
 export {
   BUILTIN_OP_NAMES,
@@ -53,7 +58,7 @@ export {
   WAITING_OPS,
   waitingStateOfOp,
   type WaitSpec,
-} from "./waitingOps.ts";
+} from "./session/index.ts";
 export {
   loadDeclaredExtensions,
   type ExtensionModuleLoader,
@@ -64,3 +69,4 @@ export {
   interpolateText,
   type NameResolver,
 } from "./expr/index.ts";
+export { directionOf } from "./paramDirection.ts";

package/src/runtime/internal/context.ts

@@ -16,6 +16,7 @@
  * 本接口只在运行层内部流转，不进包出口。
  */
 import type {
+  AudioConfig,
   EngineTexts,
   I18nPort,
   AnimationSpec,
@@ -59,6 +60,11 @@ export interface OpContext {
   /** 写系统键（不进用户存档） */
   setSystem(key: string, value: unknown): void;
 
+  // —— 工程级配置（非状态：来自 project.json，不进存档） ——
+
+  /** 工程默认音量（`shell.audio.volumes`，组装期解析；命令未写 volume 时取它） */
+  audioConfig: AudioConfig;
+
   // —— 帧栈与坐标 ——
 
   frames: Frame[];
@@ -73,8 +79,11 @@ export interface OpContext {
   columnById(id: string): StoryColumn | undefined;
   /** 当前列帧（自栈顶向下第一个列帧） */
   columnFrame(): Frame | undefined;
-  /** 按坐标造一个「未执行」的列帧（读档重建用） */
-  columnFrameAt(coord: ColumnCoordinate): Frame;
+  /** 按坐标造一个「未执行」的列帧（读档/回溯重建用）；`scope` 给定时作为列级层内容 */
+  columnFrameAt(
+    coord: ColumnCoordinate,
+    scope?: readonly (readonly [string, unknown])[],
+  ): Frame;
   /** 进入一条列：重置帧栈、装载元素、记账菜单返回点 */
   enterColumn(columnId: string): boolean;
 
@@ -177,6 +186,20 @@ export interface OpContext {
   started: boolean;
   waitSkipable: boolean;
   pendingTimer: TimerHandle | null;
+  /**
+   * 挂起定时器的到期时刻（毫秒时间轴）。
+   *
+   * 定时器一旦被 `clear` 就无法再问「还剩多久」，所以起定时器时把到期时刻记下来，
+   * 暂停时用它与当前时刻相减得到剩余量。`null` = 当前没有在跑的等待定时器。
+   */
+  pendingTimerDueAt: number | null;
+  /**
+   * 暂停时挂起定时器的剩余毫秒。
+   *
+   * 恢复要接着原来的节奏走，而不是从头再等一遍；`null` = 没有待续起的定时器
+   * （未暂停、定时器已到期、或导航/读档/回溯已把它丢弃）。
+   */
+  pausedTimerRemainingMs: number | null;
   inputStore: string | null;
   /** 清掉等待定时器 */
   clearTimer(): void;

package/src/runtime/internal/helpers.ts

@@ -68,6 +68,24 @@ export function parseMenuReturn(
   };
 }
 
+/**
+ * 解析存档里的列级作用域（`SaveDataV1.scope`）。
+ *
+ * **fail-closed**：形状不符 ⇒ 返回 `null`（调用方按空列级层处理，不中断读档——
+ * 旧档本来就没有这个字段，把它当错误会让存量档读不了）。
+ */
+export function parseScopeEntries(raw: unknown): [string, unknown][] | null {
+  if (!Array.isArray(raw)) return null;
+  const out: [string, unknown][] = [];
+  for (const item of raw) {
+    if (!Array.isArray(item) || item.length !== 2) return null;
+    const [key, value] = item as [unknown, unknown];
+    if (typeof key !== "string" || key === "") return null;
+    out.push([key, value]);
+  }
+  return out;
+}
+
 /** 快照状态中的字符串键值（缺省/非字符串 = 空串） */
 export function snapshotText(cp: Checkpoint, key: string): string {
   const found = cp.snapshot.state.find(([k]) => k === key)?.[1];

package/src/runtime/internal/index.ts

@@ -7,6 +7,7 @@ export {
   cloneFrame,
   GuardFailure,
   parseMenuReturn,
+  parseScopeEntries,
   sameCoord,
   snapshotText,
   validSlot,
@@ -31,7 +32,14 @@ export {
   setLanguage,
   start,
 } from "./session.ts";
-export { abortExternalTakeovers, clearTimer, input } from "./waiting.ts";
+export {
+  abortExternalTakeovers,
+  armWaitTimer,
+  clearTimer,
+  input,
+  nowMs,
+  pausedSession,
+} from "./waiting.ts";
 export {
   animationFinished,
   animations,

package/src/runtime/internal/session.ts

@@ -18,6 +18,7 @@ import {
 } from "../../contracts/index.ts";
 import { mergeOverlayFiles } from "../i18n/index.ts";
 import { validSlot } from "./helpers.ts";
+import { pausedSession } from "./waiting.ts";
 import type { OpContext } from "./context.ts";
 
 /**
@@ -53,6 +54,10 @@ export function advance(ctx: OpContext): void {
     ctx.fail("advance-invalid", "故事尚未启动");
     return;
   }
+  if (pausedSession(ctx)) {
+    ctx.fail("pause-active", "引擎处于暂停中，advance 被拒绝");
+    return;
+  }
   const waiting = ctx.get(SYS.waiting);
   if (waiting === "dialog") {
     ctx.setSystem(SYS.dialogComplete, true);
@@ -128,6 +133,10 @@ export function choose(ctx: OpContext, optionId: string): void {
     );
     return;
   }
+  if (pausedSession(ctx)) {
+    ctx.fail("pause-active", "引擎处于暂停中，choose 被拒绝");
+    return;
+  }
   const targets = ctx.get(SYS.menuTargets);
   if (!Array.isArray(targets)) {
     ctx.fail("menu-state-corrupt", "__menu_targets 缺失或非数组");
@@ -279,6 +288,8 @@ export function dispose(ctx: OpContext): void {
   ctx.clearTimer();
   ctx.abortExternalTakeovers(); // 挂载 signal abort → 宿主卸载外部接管
   ctx.waitSkipable = false;
+  // 暂停标记随销毁一起退场：留下真值会让复用同一实例的宿主继续看到「暂停中」
+  if (pausedSession(ctx)) ctx.setSystem(SYS.paused, false);
 }
 
 /**

package/src/runtime/internal/waiting.ts

@@ -1,6 +1,7 @@
 /**
- * 等待态零件：输入回填、定时器清理与外部接管中断。
- * 等待的建立分散在各自的命令处理器里，这里只收解除侧。
+ * 等待态零件：输入回填、等待定时器的建立与清理、外部接管中断。
+ * 等待的建立分散在各自的命令处理器里，这里收「定时器」这一件的两端（建立与解除）
+ * 以及解除侧的回填与中断。
  *
  * 只在运行层内部使用，不进包出口。
  */
@@ -31,12 +32,59 @@ export function input(ctx: OpContext, value: string): void {
   ctx.run();
 }
 
-/** 清掉挂起的等待定时器（导航、销毁、读档与回溯前调用，避免旧计时器醒来改状态） */
+/**
+ * 当前时刻（毫秒时间轴）。
+ *
+ * 走定时器端口而不是直接读宿主时钟：没有 JS 运行时的宿主（原生编译目标）
+ * 可以自己给时刻，核心就不必假设全局 `Date` 存在。
+ */
+export function nowMs(ctx: OpContext): number {
+  return ctx.timerPort.now?.() ?? Date.now();
+}
+
+/**
+ * 安排等待定时器：到点解除 wait 等待并继续执行。
+ *
+ * 回调体与等待建立是同一件事，所以建立与「暂停后按剩余量重排」共用本函数——
+ * 两处各写一份的话，漏掉 `__waiting` 判定就会推进一个已经结束的等待。
+ * 到期时刻一并记账，暂停靠它算出还剩多少毫秒。
+ */
+export function armWaitTimer(ctx: OpContext, ms: number): void {
+  ctx.pendingTimerDueAt = nowMs(ctx) + ms;
+  ctx.pendingTimer = ctx.timerPort.set(() => {
+    ctx.pendingTimer = null;
+    ctx.pendingTimerDueAt = null;
+    ctx.waitSkipable = false;
+    if (ctx.get(SYS.waiting) !== "wait") return; // dispose 等场景防御
+    ctx.setSystem(SYS.waiting, "none");
+    ctx.liveCheckpointed = false; // live 已越过该检查点
+    ctx.run();
+  }, ms);
+}
+
+/**
+ * 清掉挂起的等待定时器（导航、销毁、读档与回溯前调用，避免旧计时器醒来改状态）。
+ *
+ * 暂停记账一并抹掉：这些入口都意味着「这一段等待作废」，留着剩余毫秒只会在
+ * 恢复时排出一个属于旧等待的定时器。
+ */
 export function clearTimer(ctx: OpContext): void {
   if (ctx.pendingTimer !== null) {
     ctx.timerPort.clear(ctx.pendingTimer);
     ctx.pendingTimer = null;
   }
+  ctx.pendingTimerDueAt = null;
+  ctx.pausedTimerRemainingMs = null;
+}
+
+/**
+ * 引擎是否处于暂停态：`SYS.paused` 的唯一读口。
+ *
+ * 暂停标记只由 `pause()` / `resume()` 写；推进类命令据此 fail-closed，
+ * 别的模块不要自己 `get` 一次再判——判据分叉后「谁能推进」就会有两套答案。
+ */
+export function pausedSession(ctx: OpContext): boolean {
+  return ctx.get(SYS.paused) === true;
 }
 
 /**

package/src/runtime/opRegistry.ts

@@ -79,6 +79,12 @@ export const BUILTIN_OP_NAMES: ReadonlySet<string> = new Set([
   "stop_ambient",
   "voice",
   "stop_voice",
+  "stop_se",
+  "audio_play",
+  "audio_stop",
+  "audio_volume",
+  "audio_pause",
+  "audio_resume",
   "video",
   "seek_video",
   "pause_video",
@@ -100,6 +106,7 @@ export const BUILTIN_OP_NAMES: ReadonlySet<string> = new Set([
   "transition",
   "shake",
   "text_typewriter",
+  "mount",
 ]);
 
 /** op 名须匹配扩展短 id 形态（小写字母开头、1..32 位），保证注册表键空间可控 */