@lingfan-engine/core 0.1.5 → 0.3.0

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/interaction.ts

@@ -26,7 +26,13 @@ const INTERACTION_FIELDS = new Set([
   "z", // 实例级 z（与 minigame 同层：外部系统整屏接管）
 ]);
 
-/** input（prompt + store）→ 进入 input 等待；options 选项式输入延后（解析层拒绝） */
+/**
+ * input（prompt + store，可选 options 候选）→ 进入 input 等待。
+ *
+ * 候选值 `{ text, value }[]`：`text` 走翻译表（显示），`value` 原样进状态（玩家点选后
+ * 由命令面按普通输入提交）。没有候选时也写一个空数组，**不能跳过**——否则上一次输入
+ * 留下的候选会被这一轮读到（状态是跨命令持久的）。
+ */
 export function execInput(
   ctx: OpContext,
   frame: Frame,
@@ -41,6 +47,13 @@ export function execInput(
     SYS.inputPrompt,
     typeof cmd.prompt === "string" ? ctx.translate(cmd.prompt) : "",
   );
+  const candidates = Array.isArray(cmd.options)
+    ? (cmd.options as Array<{ text: string; value: string }>).map((o) => ({
+        text: ctx.translate(o.text),
+        value: o.value,
+      }))
+    : [];
+  ctx.setSystem(SYS.inputOptions, candidates);
   ctx.inputStore = cmd.store as string;
   ctx.setInstanceZ(SYS.choicesZ, cmd.z); // 输入形态的实例 z（choices 层）
   ctx.setSystem(SYS.waiting, "input");

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

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

@@ -0,0 +1,312 @@
+/**
+ * 音频实例族：`audio_play` / `audio_stop` / `audio_volume`。
+ *
+ * 实例与四通道**并存**，不是替换：通道是叙事语义（bgm / se / ambient / voice，
+ * 各有一档玩家偏好），实例是作者的编排单元（数量不定、名字自起、各自独立叠放）。
+ * 实例靠状态里的 `channel` 决定偏好归口，读侧乘的是同一个 `effectiveVolume`。
+ */
+import {
+  AUDIO_INSTANCE_ID_PATTERN,
+  MAX_AUDIO_INSTANCES,
+  SYS,
+  isAudioChannel,
+  isAudioInstanceId,
+  isAudioInstanceTable,
+  type AudioChannel,
+  type AudioChannelState,
+  type AudioInstanceTable,
+  type AudioInstanceState,
+  type StoryCommand,
+} from "../../../contracts/index.ts";
+import type { OpContext } from "../../internal/index.ts";
+import {
+  AUDIO_FIELDS,
+  audioFade,
+  audioVolume,
+  isPlayState,
+  readPausedPlayStates,
+} from "./shared.ts";
+
+/**
+ * 暂停记账里实例项的键前缀。
+ *
+ * 实例 id 与通道名同字符集（`bgm` / `se` / `ambient` / `voice` 都是合法实例名），
+ * 两者共用一张记账表时不能拿裸 id 当键：通道恢复会读到某个同名实例的播放态，
+ * 把别人的资源写回自己的通道。
+ */
+const PAUSE_KEY_PREFIX = "inst:";
+
+/** 读实例表：形状不合（外部改坏）按空表处理，不让一条脏值卡死整个音频域 */
+function instanceTableOf(ctx: OpContext): AudioInstanceTable {
+  const value = ctx.get(SYS.audioInstances);
+  return isAudioInstanceTable(value) ? value : {};
+}
+
+/** 整表新建后写回：**不得原地改** `table[id].state`，否则回溯会拿到被污染的值 */
+function writeInstance(
+  ctx: OpContext,
+  table: AudioInstanceTable,
+  instanceId: string,
+  channel: AudioChannel,
+  state: AudioChannelState,
+): void {
+  const next: Record<string, AudioInstanceState> = { ...table };
+  next[instanceId] = { channel, state };
+  ctx.setSystem(SYS.audioInstances, next satisfies AudioInstanceTable);
+}
+
+/**
+ * 音频实例 op 的执行：`audio_play` / `audio_stop` / `audio_volume`。
+ *
+ * 实例与四通道**并存**，不是替换：通道是叙事语义（bgm / se / ambient / voice，
+ * 各有一档玩家偏好），实例是作者的编排单元（数量不定、名字自起、各自独立叠放）。
+ * 实例靠状态里的 `channel` 决定偏好归口，读侧乘的是同一个 `effectiveVolume`。
+ *
+ * 三个 op 的分工：`audio_play` 创建或更新；`audio_stop` 停一个（缺 `inst` = 停全部）；
+ * `audio_volume` **只改音量，不重播也不递增 seq**——音量的变化由值比较感知，
+ * 递增序号会让渲染层误判成一次重播，把正在放的那一轨打断。
+ */
+export function execAudioInstance(ctx: OpContext, cmd: StoryCommand): boolean {
+  const known = AUDIO_FIELDS[cmd.op]!;
+  const unknown = Object.keys(cmd).filter((k) => !known.has(k));
+  if (unknown.length > 0) {
+    ctx.fail(
+      `${cmd.op}-unknown-field`,
+      `${cmd.op} 未知负载字段：${unknown.join(", ")}`,
+    );
+    return false;
+  }
+  const table = instanceTableOf(ctx);
+  if (cmd.op === "audio_stop") return stopInstance(ctx, table, cmd);
+  if (cmd.op === "audio_volume") return setInstanceVolume(ctx, table, cmd);
+  return playInstance(ctx, table, cmd);
+}
+
+/** `audio_play`：创建或更新一个实例（同资源 = 更新，换资源 = 重播） */
+function playInstance(
+  ctx: OpContext,
+  table: AudioInstanceTable,
+  cmd: StoryCommand,
+): boolean {
+  const instanceId = cmd.inst;
+  if (!isAudioInstanceId(instanceId)) {
+    ctx.fail(
+      "audio_play-invalid-instance",
+      `audio_play 的 inst 不合法：${JSON.stringify(instanceId)}（须匹配 ${AUDIO_INSTANCE_ID_PATTERN.source}）`,
+    );
+    return false;
+  }
+  const channel = cmd.channel;
+  if (!isAudioChannel(channel)) {
+    ctx.fail(
+      "audio_play-invalid-channel",
+      `audio_play 的 channel 不合法：${JSON.stringify(channel)}（须为 bgm / se / ambient / voice 之一）`,
+    );
+    return false;
+  }
+  if (typeof cmd.resource !== "string" || cmd.resource === "") {
+    ctx.fail(
+      "audio_play-invalid-resource",
+      "audio_play 需要非空 resource 字符串",
+    );
+    return false;
+  }
+  const previous = table[instanceId];
+  if (
+    previous === undefined &&
+    Object.keys(table).length >= MAX_AUDIO_INSTANCES
+  ) {
+    // 上限在这里先拦一次（判据里也有，但那时已经写进存档了，错误发现得太晚）
+    ctx.fail(
+      "audio_play-instance-limit",
+      `音频实例已达上限 ${MAX_AUDIO_INSTANCES}：${instanceId} 无处安放（先 audio_stop 掉不用的实例）`,
+    );
+    return false;
+  }
+  const volume = audioVolume(ctx, cmd.volume, "audio_play", channel);
+  if (volume === null) return false;
+  const fade = audioFade(ctx, cmd.fade, "audio_play");
+  if (fade === null) return false;
+  const restart = cmd.restart === true;
+  const sameTrack =
+    previous !== undefined &&
+    previous.state.kind === "play" &&
+    previous.state.resource === cmd.resource;
+  const state: AudioChannelState = {
+    kind: "play",
+    resource: cmd.resource,
+    volume,
+    loop: cmd.loop !== false,
+    fadeMs: fade,
+  };
+  if (restart || !sameTrack) {
+    // 新实例 / 换资源 / 显式重播都要给一个新序号：渲染层据此判定「这是一次新的起播」
+    ctx.mediaSeq += 1;
+    state.seq = ctx.mediaSeq;
+    if (restart) state.restart = true;
+  } else if (
+    previous.state.kind === "play" &&
+    previous.state.seq !== undefined
+  ) {
+    // 同资源原地更新：**沿用旧序号**。沿用而不是省掉，是为了让「这一轨还是那一轨」
+    // 在状态里始终可辨认；不递增则保证渲染层不会把它当成一次新起播。
+    state.seq = previous.state.seq;
+  }
+  writeInstance(ctx, table, instanceId, channel, state);
+  return true;
+}
+
+/** `audio_stop`：停一个实例；缺 `inst` = 停全部实例 */
+function stopInstance(
+  ctx: OpContext,
+  table: AudioInstanceTable,
+  cmd: StoryCommand,
+): boolean {
+  const fade = audioFade(ctx, cmd.fade, "audio_stop");
+  if (fade === null) return false;
+  const ids = Object.keys(table);
+  if (cmd.inst === undefined) {
+    if (ids.length === 0) return true; // 没有实例可停：不是错误
+    const next: Record<string, AudioInstanceState> = { ...table };
+    for (const id of ids) {
+      ctx.mediaSeq += 1;
+      next[id] = {
+        channel: table[id]!.channel,
+        // 每个实例各领一个序号：连续两次全停必须是两次独立事件
+        state: { kind: "stop", fadeMs: fade, seq: ctx.mediaSeq },
+      };
+    }
+    ctx.setSystem(SYS.audioInstances, next satisfies AudioInstanceTable);
+    return true;
+  }
+  const instanceId = cmd.inst;
+  if (!isAudioInstanceId(instanceId)) {
+    ctx.fail(
+      "audio_stop-invalid-instance",
+      `audio_stop 的 inst 不合法：${JSON.stringify(instanceId)}（须匹配 ${AUDIO_INSTANCE_ID_PATTERN.source}）`,
+    );
+    return false;
+  }
+  const previous = table[instanceId];
+  if (previous === undefined) {
+    ctx.fail(
+      "audio_stop-unknown-instance",
+      `audio_stop 找不到实例 ${instanceId}（当前实例：${ids.join(", ") || "无"}）`,
+    );
+    return false;
+  }
+  ctx.mediaSeq += 1;
+  writeInstance(ctx, table, instanceId, previous.channel, {
+    kind: "stop",
+    fadeMs: fade,
+    seq: ctx.mediaSeq,
+  });
+  return true;
+}
+
+/** `audio_volume`：只改音量（双向闭环入口），不重播、不递增 seq */
+function setInstanceVolume(
+  ctx: OpContext,
+  table: AudioInstanceTable,
+  cmd: StoryCommand,
+): boolean {
+  const instanceId = cmd.inst;
+  if (!isAudioInstanceId(instanceId)) {
+    ctx.fail(
+      "audio_volume-invalid-instance",
+      `audio_volume 的 inst 不合法：${JSON.stringify(instanceId)}（须匹配 ${AUDIO_INSTANCE_ID_PATTERN.source}）`,
+    );
+    return false;
+  }
+  const previous = table[instanceId];
+  if (previous === undefined) {
+    ctx.fail(
+      "audio_volume-unknown-instance",
+      `audio_volume 找不到实例 ${instanceId}（当前实例：${Object.keys(table).join(", ") || "无"}）`,
+    );
+    return false;
+  }
+  if (cmd.volume === undefined) {
+    ctx.fail("audio_volume-missing-volume", "audio_volume 需要 volume");
+    return false;
+  }
+  if (previous.state.kind !== "play") {
+    ctx.fail(
+      "audio_volume-instance-stopped",
+      `实例 ${instanceId} 当前是停止状态：先 audio_play 起播再调音量`,
+    );
+    return false;
+  }
+  const volume = audioVolume(ctx, cmd.volume, "audio_volume", previous.channel);
+  if (volume === null) return false;
+  writeInstance(ctx, table, instanceId, previous.channel, {
+    ...previous.state,
+    volume,
+  });
+  return true;
+}
+
+/**
+ * 暂停全部实例：正在出声的实例转 `pause` 态，暂停前的播放态进 `SYS.audioPaused`。
+ *
+ * 常驻四通道由 `audio_pause` 覆盖，实例是另一张表，必须单独走一遍——否则
+ * 「引擎暂停」只让 BGM 收声，故事里正在放的环境音实例照旧出声。
+ * 记账与通道共用同一张表（同一概念一处声明），实例键加 `inst:` 前缀区分归属。
+ *
+ * 不经 op、直接改状态：这是引擎级暂停的内部步骤，不产生命令面的语义
+ * （作者手写的 `audio_pause` 只作用于四通道，暂停态仍由同一把「引擎已暂停」的闸门拦住推进）。
+ */
+export function pauseAudioInstances(ctx: OpContext): void {
+  const table = instanceTableOf(ctx);
+  const ids = Object.keys(table);
+  if (ids.length === 0) return;
+  const paused = readPausedPlayStates(ctx);
+  const next: Record<string, AudioInstanceState> = { ...table };
+  let changed = false;
+  for (const id of ids) {
+    const entry = table[id];
+    if (entry === undefined || !isPlayState(entry.state)) continue;
+    ctx.mediaSeq += 1;
+    paused[PAUSE_KEY_PREFIX + id] = entry.state;
+    next[id] = {
+      channel: entry.channel,
+      state: { kind: "pause", seq: ctx.mediaSeq } satisfies AudioChannelState,
+    };
+    changed = true;
+  }
+  if (!changed) return;
+  ctx.setSystem(SYS.audioInstances, next satisfies AudioInstanceTable);
+  ctx.setSystem(SYS.audioPaused, paused);
+}
+
+/**
+ * 恢复全部实例：按记账写回暂停前的播放态并递增 `seq`。
+ *
+ * 只认 `pause` 态：暂停期间被命令改成 `stop` 的实例不复活——留着一条「该出声却
+ * 永远不出声」的实例比让它停着更糟，与通道恢复同一口径。
+ */
+export function resumeAudioInstances(ctx: OpContext): void {
+  const table = instanceTableOf(ctx);
+  const ids = Object.keys(table);
+  if (ids.length === 0) return;
+  const paused = readPausedPlayStates(ctx);
+  const next: Record<string, AudioInstanceState> = { ...table };
+  let changed = false;
+  for (const id of ids) {
+    const entry = table[id];
+    if (entry === undefined || entry.state.kind !== "pause") continue;
+    const key = PAUSE_KEY_PREFIX + id;
+    const resumed = paused[key];
+    if (resumed === undefined) continue;
+    delete paused[key];
+    ctx.mediaSeq += 1;
+    next[id] = {
+      channel: entry.channel,
+      state: { ...resumed, seq: ctx.mediaSeq },
+    };
+    changed = true;
+  }
+  if (!changed) return;
+  ctx.setSystem(SYS.audioInstances, next satisfies AudioInstanceTable);
+  ctx.setSystem(SYS.audioPaused, paused);
+}

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

@@ -0,0 +1,32 @@
+/**
+ * 出站通知：`notify` 只发事件，不碰状态（覆盖层的 toast 归宿主渲染）。
+ */
+import {
+  SYS,
+  type OutboundEvent,
+  type OutboundPayload,
+  type StoryCommand,
+} from "../../../contracts/index.ts";
+import { interpolateText } from "../../expr/index.ts";
+import type { OpContext } from "../../internal/index.ts";
+
+/** notify：出站 toast 事件（覆盖层）；文本插值与 say 同语义 */
+export function execNotify(ctx: OpContext, cmd: StoryCommand): void {
+  if (ctx.rejectBadInstanceZ(cmd)) return; // 先拒非法 z（不动状态）
+  const { text, errors } = interpolateText(
+    ctx.translate(cmd.text as string),
+    ctx.resolveName,
+    ctx.draw,
+  );
+  for (const e of errors)
+    ctx.fail(e.code, ctx.texts.interpolationFallback(e.message));
+  ctx.setInstanceZ(SYS.notificationsZ, cmd.z); // 本条通知的实例 z（notifications 层）
+  const payload: OutboundPayload = {
+    kind: "notify",
+    text,
+    ...(typeof cmd.type === "string" ? { notifyType: cmd.type } : {}),
+    ...(typeof cmd.duration === "number" ? { duration: cmd.duration } : {}),
+  };
+  const event: OutboundEvent = { v: 1, kind: "event", payload };
+  for (const listener of ctx.eventListeners) listener(event);
+}