@lingfan-engine/core 0.1.5 → 0.3.0

package/src/data/text/generate/command/media.ts

@@ -4,7 +4,9 @@ import type { StoryCommand } from "../../../../contracts/index.ts";
 import type { GenerateContext } from "../context.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` `video` `cutscene` `seek_video` `pause_video`
+ * `resume_video` `stop_video` `video_skipable`）。
  *
  * 入参是分发骨架建好的 `GenerateContext`：`pad` 是本行缩进前缀（块体逐层加深），
  * `out` 是输出缓冲，投影出的行直接推入，不留空行。
@@ -33,12 +35,32 @@ export function generateMediaCommand(
     }
     case "stop_bgm":
     case "stop_ambient":
-    case "stop_voice": {
+    case "stop_voice":
+    case "stop_se": {
       let line = `${pad}${cmd.op}`;
       if (cmd.fade !== undefined) line += ` fade=${cmd.fade}`;
       out.push(line);
       return;
     }
+    case "audio_play": {
+      let line = `${pad}audio_play ${cmd.inst as string} ${cmd.channel as string} ${quoteForText(cmd.resource as string)}`;
+      if (cmd.volume !== undefined) line += ` volume=${cmd.volume}`;
+      if (cmd.loop !== undefined) line += ` loop=${cmd.loop}`;
+      if (cmd.fade !== undefined) line += ` fade=${cmd.fade}`;
+      if (cmd.restart !== undefined) line += ` restart=${cmd.restart}`;
+      out.push(line);
+      return;
+    }
+    case "audio_stop": {
+      let line = `${pad}audio_stop`;
+      if (cmd.inst !== undefined) line += ` ${cmd.inst as string}`;
+      if (cmd.fade !== undefined) line += ` fade=${cmd.fade}`;
+      out.push(line);
+      return;
+    }
+    case "audio_volume":
+      out.push(`${pad}audio_volume ${cmd.inst as string} volume=${cmd.volume}`);
+      return;
     case "video":
     case "cutscene": {
       let line = `${pad}${cmd.op} ${quoteForText(cmd.resource as string)}`;
@@ -61,6 +83,15 @@ export function generateMediaCommand(
     case "stop_video":
       out.push(`${pad}stop_video`);
       return;
+    case "audio_pause":
+    case "audio_resume":
+      // channel 省略即「全部常驻通道」，不能补默认值——写出来会变成只暂停某一个
+      out.push(
+        cmd.channel === undefined
+          ? `${pad}${cmd.op}`
+          : `${pad}${cmd.op} ${cmd.channel as string}`,
+      );
+      return;
     case "video_skipable":
       out.push(
         `${pad}video_skipable ${cmd.value === false ? "false" : "true"}`,

package/src/data/text/generate/command/ui.ts

@@ -0,0 +1,29 @@
+/** ui 族的文本投影。 */
+import { generateDictLiteral } from "../../literals.ts";
+import type { StoryCommand } from "../../../../contracts/index.ts";
+import type { GenerateContext } from "../context.ts";
+
+/**
+ * 投影本族的 op 行（`mount`）。
+ *
+ * 入参是分发骨架建好的 `GenerateContext`：`pad` 是本行缩进前缀（块体逐层加深），
+ * `out` 是输出缓冲，投影出的行直接推入，不留空行。
+ * 无返回值，结果通过 `out` 交付。
+ * 失败表现：字段无法投影（`props` 不是对象等）时抛 `TextFormatError`，不是静默跳过——
+ * 由上层按命令粒度捕获后降级为 issue，使整棵树的其余部分照常输出。
+ *
+ * 形态：`mount <UI 名> <true|false> [props={…}]`。UI 名是短标识（不含引号也不含空白），
+ * 显隐写成字面 `true` / `false`——不写「切换」，文本形态与状态语义一样确定。
+ */
+export function generateUiCommand(cmd: StoryCommand, c: GenerateContext): void {
+  const { pad, out } = c;
+  switch (cmd.op) {
+    case "mount": {
+      let line = `${pad}mount ${cmd.name as string} ${cmd.visible === true ? "true" : "false"}`;
+      if (cmd.props !== undefined)
+        line += ` props=${generateDictLiteral(cmd.props as Record<string, unknown>)}`;
+      out.push(line);
+      return;
+    }
+  }
+}

package/src/data/text/generate/command.ts

@@ -13,6 +13,7 @@ import {
   generateMediaCommand,
   generatePresentCommand,
   generateSaveCommand,
+  generateUiCommand,
   generateVariablesCommand,
 } from "./command/index.ts";
 import { tryProjectToText } from "./projection.ts";
@@ -88,6 +89,12 @@ export function generateCommand(
     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":
@@ -120,6 +127,9 @@ export function generateCommand(
     case "text_typewriter":
       generatePresentCommand(cmd, ctx);
       return;
+    case "mount":
+      generateUiCommand(cmd, ctx);
+      return;
     default: {
       // 扩展投影：声明了 toText 的自定义 op 交给投影器；否则 fail-closed（不静默）
       const toText = projections?.get(cmd.op)?.toText;

package/src/data/text/literals.ts

@@ -110,6 +110,146 @@ export function extractKeyedDictLiteral(
   };
 }
 
+/**
+ * 提取 `key=[…]` 形式的数组字面量（方括号计数，引号内的括号不算）。
+ *
+ * 与 `extractKeyedDictLiteral` 同法，只是括号类型不同；`key` 只认**字符串外**且前面是空白
+ * 或行首的那一处（避免提示语里恰好出现 `options=` 被误当参数）。
+ * 返回字面量与剥离后的余文；找不到或不闭合返回 `null`。
+ */
+export function extractKeyedArrayLiteral(
+  source: string,
+  key: string,
+): { literal: string; remainder: string } | null {
+  const at = findKeyOutsideString(source, key);
+  if (at < 0) return null;
+  const bracketAt = source.indexOf("[", at + key.length + 1);
+  if (bracketAt < 0) return null;
+  let depth = 0;
+  let end = -1;
+  let inString = false;
+  for (let i = bracketAt; i < source.length; i += 1) {
+    const ch = source[i]!;
+    if (inString) {
+      if (ch === "\\") {
+        i += 1;
+        continue;
+      }
+      if (ch === '"') inString = false;
+      continue;
+    }
+    if (ch === '"') {
+      inString = true;
+      continue;
+    }
+    if (ch === "[") depth += 1;
+    else if (ch === "]") {
+      depth -= 1;
+      if (depth === 0) {
+        end = i;
+        break;
+      }
+    }
+  }
+  if (end < 0) return null;
+  return {
+    literal: source.slice(bracketAt, end + 1),
+    remainder: `${source.slice(0, at)} ${source.slice(end + 1)}`,
+  };
+}
+
+/** 找 `key=` 在字符串外、且位于行首或空白之后的位置；找不到返回 -1 */
+function findKeyOutsideString(source: string, key: string): number {
+  let inString = false;
+  for (let i = 0; i < source.length; i += 1) {
+    const ch = source[i]!;
+    if (inString) {
+      if (ch === "\\") {
+        i += 1;
+        continue;
+      }
+      if (ch === '"') inString = false;
+      continue;
+    }
+    if (ch === '"') {
+      inString = true;
+      continue;
+    }
+    if (
+      source.startsWith(`${key}=`, i) &&
+      (i === 0 || /\s/.test(source[i - 1]!))
+    ) {
+      return i;
+    }
+  }
+  return -1;
+}
+
+/**
+ * `[{"text": …, "value": …}, …]` 数组字面量 → 输入候选表。
+ *
+ * 与 `generateInputOptions` 严格互逆（往返字节级一致）；字段不是字符串的项原样保留为
+ * `undefined` 之外的空串，交由校验层报错——解析器不替作者猜。
+ */
+export function parseInputOptionsLiteral(
+  raw: string,
+): Array<{ text: string; value: string }> {
+  const inner = raw.trim().replace(/^\[/, "").replace(/\]$/, "");
+  const parts: string[] = [];
+  let cur = "";
+  let inString = false;
+  let depth = 0;
+  for (let i = 0; i < inner.length; i += 1) {
+    const ch = inner[i]!;
+    if (inString) {
+      cur += ch;
+      if (ch === "\\") {
+        cur += inner[i + 1] ?? "";
+        i += 1;
+        continue;
+      }
+      if (ch === '"') inString = false;
+      continue;
+    }
+    if (ch === '"') {
+      inString = true;
+      cur += ch;
+      continue;
+    }
+    if (ch === "{") depth += 1;
+    if (ch === "}") depth -= 1;
+    if (ch === "," && depth === 0) {
+      if (cur.trim() !== "") parts.push(cur);
+      cur = "";
+      continue;
+    }
+    cur += ch;
+  }
+  if (cur.trim() !== "") parts.push(cur);
+  return parts.map((part) => {
+    const dict = parseDictLiteral(part);
+    return {
+      text: typeof dict.text === "string" ? dict.text : "",
+      value: typeof dict.value === "string" ? dict.value : "",
+    };
+  });
+}
+
+/**
+ * 输入候选表的文本投影：`[{"text": "…", "value": "…"}, …]`。
+ *
+ * 与 `parseInputOptionsLiteral` 严格互逆；每项经 `generateDictLiteral`（键序 text → value，
+ * 插入序确定，故同一份数据两次投影字节相同）。
+ */
+export function generateInputOptions(
+  options: readonly { text: string; value: string }[],
+): string {
+  const items = options.map((item) =>
+    generateDictLiteral({ text: item.text, value: item.value }),
+  );
+  return `[${items.join(", ")}]`;
+}
+
 /** {"f":v} 字典字面量 → 对象（字段值走 parseValueLiteral 语义） */
 export function parseDictLiteral(raw: string): Record<string, unknown> {
   const inner = raw.trim().replace(/^\{/, "").replace(/\}$/, "");

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

@@ -1,6 +1,10 @@
 /** dialog 族的读向解析。 */
 import { parseSay } from "../say.ts";
 import { unquote } from "../../lexer.ts";
+import {
+  extractKeyedArrayLiteral,
+  parseInputOptionsLiteral,
+} from "../../literals.ts";
 import type { StoryCommand } from "../../../../contracts/index.ts";
 import type { StatementContext } from "../state.ts";
 
@@ -89,6 +93,21 @@ export function parseDialogStatement(c: StatementContext): StoryCommand | null {
         prompt: unquote(prompt),
         store: unquote(storeEq.slice(6)),
       };
+      // 候选快捷值：`input "提示" store="k" options=[{"text": "…", "value": "…"}]`
+      // 从整行里摘（不能只搜 token——数组内部有空格，会被切词拆散）
+      const optionsLiteral = extractKeyedArrayLiteral(rest, "options");
+      if (optionsLiteral !== null) {
+        const candidates = parseInputOptionsLiteral(optionsLiteral.literal);
+        // 缺字段的项在字面量层会落成空串；这里补一条带定位的 issue，
+        // 不让它悄悄变成「点了候选写入空值」（与 JSON 侧的 requireNonEmptyString 同口径）
+        const broken = candidates.findIndex(
+          (item) => item.text === "" || item.value === "",
+        );
+        if (broken >= 0) {
+          return fail(`input 候选 options[${broken}] 需要 text 与 value`);
+        }
+        cmd.options = candidates;
+      }
       const zEq = tokens.find(
         (t) => t.startsWith("z=") || t.startsWith("z-index="),
       );

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,
+    }),
+  );
+}