@lingfan-engine/core 0.2.0 → 0.3.0

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 位），保证注册表键空间可控 */

package/src/runtime/ops/dialog.ts

@@ -11,6 +11,7 @@ import {
   type StoryCommand,
 } from "../../contracts/index.ts";
 import { interpolateText } from "../expr/index.ts";
+import { armWaitTimer } from "../internal/index.ts";
 import type { Frame, OpContext } from "../internal/index.ts";
 
 /** say 的已知负载字段；未知字段 fail-closed */
@@ -232,17 +233,7 @@ export function execWait(
   ctx.liveCheckpointed = true;
   ctx.autoSaveAtCheckpoint(); // wait 等待画面建立 = auto_save 消费点
   frame.index += 1;
-  ctx.pendingTimer = ctx.timerPort.set(
-    () => {
-      ctx.pendingTimer = null;
-      ctx.waitSkipable = false;
-      if (ctx.get(SYS.waiting) !== "wait") return; // dispose 等场景防御
-      ctx.setSystem(SYS.waiting, "none");
-      ctx.liveCheckpointed = false; // live 已越过该检查点
-      ctx.run();
-    },
-    Math.max(0, (cmd.seconds as number) * 1000),
-  );
+  armWaitTimer(ctx, Math.max(0, (cmd.seconds as number) * 1000));
 }
 
 /** NVL：进入/清屏/退出累积层；累积文本进核心状态（回溯/存档自动一致） */

package/src/runtime/ops/flow.ts

@@ -21,7 +21,7 @@ import {
   type LoopState,
   type OpContext,
 } from "../internal/index.ts";
-import { findJsonValueError } from "../stateContract.ts";
+import { findJsonValueError } from "../state/stateContract.ts";
 
 /** if/elif/else：条件执行期求值；分支体 = 块帧 + 块级作用域 */
 export function execIf(

package/src/runtime/ops/index.ts

@@ -39,7 +39,16 @@ export {
   execRandom,
   execUndef,
 } from "./variables.ts";
-export { execAudio, execNotify, execVideo } from "./media.ts";
+export {
+  execAudio,
+  execAudioInstance,
+  execAudioPause,
+  execAudioResume,
+  execNotify,
+  execVideo,
+  pauseAudioInstances,
+  resumeAudioInstances,
+} from "./media/index.ts";
 export {
   execAnimate,
   execElementVisual,
@@ -54,6 +63,7 @@ export {
   execSaveDeleteOp,
   execSaveOp,
 } from "./save.ts";
+export { execMount } from "./ui.ts";
 export {
   abortInteraction,
   execInput,

package/src/runtime/ops/media/audio.ts

@@ -0,0 +1,230 @@
+/**
+ * 音频通道族：四通道（bgm / se / ambient / voice）的起播、停止与可恢复暂停。
+ *
+ * 核心只写通道状态，播放交给宿主适配器：状态回答「该不该出声、放什么」，
+ * 位置留在播放器里。`se` 是一次性触发（带单调 seq），常驻通道写状态对象
+ * （随快照 / 存档 / 回溯随行）。
+ */
+import {
+  SYS,
+  isAudioChannel,
+  type AudioChannel,
+  type AudioChannelState,
+  type StoryCommand,
+} from "../../../contracts/index.ts";
+import type { OpContext } from "../../internal/index.ts";
+import {
+  AUDIO_CHANNEL_KEY,
+  AUDIO_FIELDS,
+  AUDIO_STOP_KEY,
+  audioFade,
+  audioVolume,
+  isPlayState,
+  readPausedPlayStates,
+} from "./shared.ts";
+
+/**
+ * 四音频通道：核心只写状态，播放由 UI 适配器落地。
+ * - bgm/ambient/voice 为常驻通道（写状态对象，随快照/存档随行）；se 为一次性触发（单调 seq）
+ * - 同资源重写保留播放位置：重放不打断当前曲目（回滚 seek / 读档续播）
+ * - stop_* 写 stop 形态（带淡出参数）；未知字段/非法负载 fail-closed
+ */
+export function execAudio(ctx: OpContext, cmd: StoryCommand): boolean {
+  const unknown = Object.keys(cmd).filter(
+    (k) => !(AUDIO_FIELDS[cmd.op]?.has(k) ?? false),
+  );
+  if (unknown.length > 0) {
+    ctx.fail(
+      `${cmd.op}-unknown-field`,
+      `${cmd.op} 未知负载字段：${unknown.join(", ")}`,
+    );
+    return false;
+  }
+  const fade = audioFade(ctx, cmd.fade, cmd.op);
+  if (fade === null) return false;
+  if (cmd.op === "stop_se") {
+    // 音效是「一次性触发 + 可停止」：停止也要带单调序号，
+    // 否则连续两次 stop_se 在渲染层看来是「状态没变」，第二次停不掉新触发的音效
+    ctx.mediaSeq += 1;
+    ctx.setSystem(SYS.audioSe, {
+      kind: "stop",
+      fadeMs: fade,
+      seq: ctx.mediaSeq,
+    } satisfies AudioChannelState);
+    return true;
+  }
+  if (
+    cmd.op === "stop_bgm" ||
+    cmd.op === "stop_ambient" ||
+    cmd.op === "stop_voice"
+  ) {
+    // 清通道为停止形态（淡出参数随状态走，不被丢弃）
+    const stopKey = AUDIO_STOP_KEY[cmd.op]!;
+    ctx.setSystem(stopKey, {
+      kind: "stop",
+      fadeMs: fade,
+    } satisfies AudioChannelState);
+    // 停止背景乐：播放位置归零（帧级键静默写）
+    if (cmd.op === "stop_bgm") ctx.state.set(SYS.bgmPosition, 0);
+    return true;
+  }
+  if (typeof cmd.resource !== "string" || cmd.resource === "") {
+    ctx.fail(
+      `${cmd.op}-invalid-resource`,
+      `${cmd.op} 需要非空 resource 字符串`,
+    );
+    return false;
+  }
+  // 走到这里 op 只剩四个起播命令（stop_* 已在前面的分支返回）⇒ 通道就是 op 本身
+  const channel = cmd.op as AudioChannel;
+  const volume = audioVolume(ctx, cmd.volume, channel, channel);
+  if (volume === null) return false;
+  if (cmd.op === "se") {
+    ctx.mediaSeq += 1;
+    ctx.setSystem(SYS.audioSe, {
+      kind: "play",
+      resource: cmd.resource,
+      volume,
+      loop: false,
+      fadeMs: 0,
+      seq: ctx.mediaSeq,
+    } satisfies AudioChannelState);
+    return true;
+  }
+  const channelKey = AUDIO_CHANNEL_KEY[cmd.op]!;
+  const previous = ctx.get(channelKey) as AudioChannelState | null | undefined;
+  const restart = cmd.restart === true;
+  if (cmd.op === "bgm") {
+    // 首播/换曲/显式重播归零；同曲静默续播（回滚 seek / 读档续播）。
+    // 帧级键静默写（高频键不进事件流），UI 经通道事件重读位置。
+    const sameTrack =
+      previous?.kind === "play" && previous.resource === cmd.resource;
+    if (!sameTrack || restart) ctx.state.set(SYS.bgmPosition, 0);
+  }
+  const state: AudioChannelState = {
+    kind: "play",
+    resource: cmd.resource,
+    volume,
+    loop: cmd.op === "voice" ? false : cmd.loop !== false,
+    fadeMs: fade,
+  };
+  if (cmd.op === "voice") state.autoStop = cmd.auto_stop !== false;
+  if (restart) {
+    // 单调序号：同曲连续两次 restart 也是两次独立事件（渲染层据此重播）
+    ctx.mediaSeq += 1;
+    state.restart = true;
+    state.seq = ctx.mediaSeq;
+  }
+  ctx.setSystem(channelKey, state);
+  return true;
+}
+
+/** 可暂停的常驻通道：`se` 是一次性触发，暂停它没有可恢复的东西 */
+const PAUSABLE_CHANNELS = ["bgm", "ambient", "voice"] as const;
+type PausableChannel = (typeof PAUSABLE_CHANNELS)[number];
+
+/**
+ * 暂停目标通道：不传 `channel` = 全部常驻通道（`se` 除外）。
+ * 显式传 `se` 返回空集——一次性触发没有「暂停后从原位置继续」这回事，
+ * 静默不动作而不是报错（作者写了也不算坏数据）。
+ */
+function pauseTargets(
+  ctx: OpContext,
+  cmd: StoryCommand,
+): readonly PausableChannel[] | null {
+  if (cmd.channel === undefined) return PAUSABLE_CHANNELS;
+  const raw = cmd.channel;
+  if (!isAudioChannel(raw)) {
+    ctx.fail(
+      `${cmd.op}-invalid-channel`,
+      `${cmd.op} 的 channel 不合法：${JSON.stringify(raw)}（须为 bgm / se / ambient / voice 之一）`,
+    );
+    return null;
+  }
+  if (raw === "se") return [];
+  return [raw];
+}
+
+/**
+ * `audio_pause`：把常驻通道从 play 改成 pause，播放器实例与位置留给端口。
+ *
+ * 三条纪律：
+ * - 只暂停 play 态——`stop` / 从未播放的通道不写，否则「从未触碰」会变成「暂停」，
+ *   恢复时无实例可续，stop 的淡出参数也跟着丢；
+ * - 已在 pause 态不重复写也不递增序号（幂等：连按两次暂停只有第一次是事件）；
+ * - 暂停前的 play 态记进 `SYS.audioPaused`——`pause` 态本身不带资源，
+ *   `audio_resume` 靠这份记账写回「从哪继续」（随快照 / 存档随行，读档后仍能恢复）。
+ */
+export function execAudioPause(ctx: OpContext, cmd: StoryCommand): boolean {
+  const unknown = Object.keys(cmd).filter(
+    (k) => !(AUDIO_FIELDS[cmd.op]?.has(k) ?? false),
+  );
+  if (unknown.length > 0) {
+    ctx.fail(
+      `${cmd.op}-unknown-field`,
+      `${cmd.op} 未知负载字段：${unknown.join(", ")}`,
+    );
+    return false;
+  }
+  const channels = pauseTargets(ctx, cmd);
+  if (channels === null) return false;
+  for (const channel of channels) {
+    const key = AUDIO_CHANNEL_KEY[channel]!;
+    const previous = ctx.get(key);
+    if (!isPlayState(previous)) continue;
+    ctx.mediaSeq += 1;
+    ctx.setSystem(key, {
+      kind: "pause",
+      seq: ctx.mediaSeq,
+    } satisfies AudioChannelState);
+    const paused: Record<string, AudioChannelState> = {
+      ...readPausedPlayStates(ctx),
+    };
+    paused[channel] = previous;
+    ctx.setSystem(SYS.audioPaused, paused);
+  }
+  return true;
+}
+
+/**
+ * `audio_resume`：把 pause 态的通道写回暂停前的 play 态。
+ *
+ * 写回的是**同一个 play 态**（资源 / 音量 / 循环 / 淡出参数原样），所以渲染层
+ * 看到的是「pause → 同资源 play」，走 `resume` 而不是重新 `play`——从暂停位置续播，
+ * 不从头播。`play` / `stop` 态的通道不动作（幂等）。
+ *
+ * 没有记账可续（例如手工改过档）时落成 `stop`：留一个永远无法恢复的 pause 态
+ * 比停掉更糟——那条通道会一直「该出声但不出声」。
+ */
+export function execAudioResume(ctx: OpContext, cmd: StoryCommand): boolean {
+  const unknown = Object.keys(cmd).filter(
+    (k) => !(AUDIO_FIELDS[cmd.op]?.has(k) ?? false),
+  );
+  if (unknown.length > 0) {
+    ctx.fail(
+      `${cmd.op}-unknown-field`,
+      `${cmd.op} 未知负载字段：${unknown.join(", ")}`,
+    );
+    return false;
+  }
+  const channels = pauseTargets(ctx, cmd);
+  if (channels === null) return false;
+  for (const channel of channels) {
+    const key = AUDIO_CHANNEL_KEY[channel]!;
+    const current = ctx.get(key);
+    if (current === null || typeof current !== "object") continue;
+    if ((current as { kind?: unknown }).kind !== "pause") continue;
+    const paused = readPausedPlayStates(ctx);
+    const resumed = paused[channel];
+    ctx.setSystem(
+      key,
+      resumed ?? ({ kind: "stop", fadeMs: 0 } satisfies AudioChannelState),
+    );
+    if (resumed !== undefined) {
+      const next: Record<string, AudioChannelState> = { ...paused };
+      delete next[channel];
+      ctx.setSystem(SYS.audioPaused, next);
+    }
+  }
+  return true;
+}

package/src/runtime/ops/media/index.ts

@@ -0,0 +1,18 @@
+/**
+ * 媒体命令的执行：音频通道、视频命令流、出站通知。
+ *
+ * 这一族的共同点是「核心只写状态，播放交给宿主」——音频写四通道的通道对象，
+ * 视频写单调递增的命令流，通知只发出站事件。渲染器按状态与事件执行，
+ * 核心不持有播放器，也不关心播放是否成功。
+ *
+ * 按「音频通道 / 视频 / 音频实例 / 通知」分文件，域内共用部分在 `shared.ts`；
+ * 这里只做转发，不放任何实现。
+ */
+export { execAudio, execAudioPause, execAudioResume } from "./audio.ts";
+export { execVideo } from "./video.ts";
+export {
+  execAudioInstance,
+  pauseAudioInstances,
+  resumeAudioInstances,
+} from "./instances.ts";
+export { execNotify } from "./notify.ts";