@lingfan-engine/core 0.2.0 → 0.3.1

package/src/contracts/shell.ts

@@ -10,10 +10,31 @@
  * Android 16 起 sw≥600dp 大屏忽略方向限制（游戏凭 `appCategory="game"` 豁免）；
  * iOS 必须在 plist 内声明过该方向且未开启多任务（iPad）才可能生效。
  */
+import type { AudioChannel } from "./media/entities.ts";
 
 /** 方向模式：auto = 跟随系统与用户自动旋转；portrait/landscape = 锁定方向 */
 export type OrientationMode = "auto" | "portrait" | "landscape";
 
+/**
+ * 工程级音频配置（`project.json` 的 `shell.audio`；解析见 `runtime/shell.ts`）。
+ *
+ * **音量的第二级**：命令没写 `volume=` 时取这里，再没有才是内建 1。
+ * 玩家偏好不在这里——偏好是最外层的乘算（`op 音量 × 通道偏好`），
+ * 顺序不能反：工程默认是作者写的、偏好是玩家设的，把作者默认塞进偏好层
+ * 会让「换个工程，玩家设置被这个工程的默认值改掉」。
+ *
+ * 解析结果是**完整表**（四个通道各一个数），缺声明的通道回 1。
+ */
+export interface AudioConfig {
+  /** 各通道的工程默认音量（0..1） */
+  readonly volumes: Readonly<Record<AudioChannel, number>>;
+}
+
+/** 内建默认音频配置：四个通道都是 1（与「未声明 = 满音量」的既有行为一致） */
+export const DEFAULT_AUDIO_CONFIG: AudioConfig = {
+  volumes: { bgm: 1, se: 1, ambient: 1, voice: 1 },
+};
+
 /**
  * 工程级壳配置（project.json `shell` 段）：作者声明的作品形态。
  * 缺省 = auto（跟随系统）；玩家偏好可覆盖（偏好与存档分离）。
@@ -21,6 +42,11 @@ export type OrientationMode = "auto" | "portrait" | "landscape";
 export interface ProjectShellConfig {
   /** 作品默认方向（缺省 = auto） */
   orientation?: OrientationMode;
+  /** 作者声明的通道默认音量（缺省 = 四通道皆 1） */
+  audio?: {
+    /** 通道 → 0..1；未列出的通道回内建 1 */
+    volumes?: Partial<Record<AudioChannel, number>>;
+  };
 }
 
 /**

package/src/contracts/story/entities.ts

@@ -25,16 +25,19 @@ export interface StoryCommand {
  *
  * **与 `kind` 正交，两根轴各管一件事**：
  * - `kind`（scene/flow）= **内容形态**：有没有 `elements[]` / `commands[]`
- * - `type`（game/menu/ui）= **运行语义**：进不进历史与存档、菜单是否自动推进
+ * - `type`（game/ui）= **运行语义**：进不进历史与存档
  *
- * 三态语义：
+ * 两态语义：
  * - `game`：实际游戏场景 —— **存档、进历史、建立检查点**
- * - `menu`：菜单 / 标题 / 设置 —— 不存档、不进历史、不建检查点（**可覆盖**）
- * - `ui`：覆盖层 / 弹窗 —— 同上，且**不改变历史游标**
+ * - `ui`：界面层（菜单 / 标题 / 设置 / 覆盖层 / 弹窗）—— 不存档、不进历史、不建检查点
+ *
+ * **两者在运行期没有行为差异**：唯一的判定只有「进不进历史与存档」。所以不拆成
+ * 「菜单」「界面」两个类型——那点区别不存在于引擎里，多一个取值只会让每个消费者
+ * 都得再判一次。界面内部怎么分类（标题页 / 设置页 / 弹窗）归页面层自己表达。
  *
  * **缺省 = `game`** ⇒ 既有工程零改动。
  */
-export type SceneType = "game" | "menu" | "ui";
+export type SceneType = "game" | "ui";
 
 /** 两类列：scene（空间层）与 flow（纯流程） */
 export interface StoryColumn {
@@ -42,8 +45,8 @@ export interface StoryColumn {
   kind: "scene" | "flow";
   /**
    * 运行语义类型（**缺省 `game`**）。
-   * 决定该列是否进历史/存档/检查点，以及菜单态能否自动推进。
-   * **与 `kind` 正交**：`kind: "flow" + type: "menu"`（纯流程的菜单）是合法组合。
+   * 决定该列是否进历史 / 存档 / 检查点。
+   * **与 `kind` 正交**：`kind: "flow" + type: "ui"`（纯流程的界面层）是合法组合。
    */
   type?: SceneType;
   /**
@@ -66,6 +69,18 @@ export interface StoryColumn {
    * 不设端口、不进存档——只是每列的排版事实。
    */
   font?: string;
+  /**
+   * **列级 UI 声明**（纯展示元数据）：本列引用的 UI 名字，名字 = `src/ui/<名>/` 的目录名。
+   *
+   * 语义要点：
+   * - **静态声明是「告知」不是「加载」**：产物里只有名字，UI 本体住 `src/ui/**`，
+   *   由宿主按名字预加载；引擎不读、不编译、不拷贝那些文件。
+   * - **与 `elements` 是两个概念**：`elements` 是舞台元素，进 `SYS.elements`，
+   *   有 show / hide / animate；`uis` 是挂载界面，进 `SYS.mounts`，只有显隐。
+   * - **未引用不写**：没有 UI 的列不带该字段（与 `font` 同规则）。
+   * - **顺序确定**：按名字码点序去重，构建期即定序，消费方不必再排。
+   */
+  uis?: readonly string[];
   /** scene 专有：舞台元素声明（类型与属性全集 fail-closed）。
    *  进入列时由引擎装载为 `SYS.elements`（声明式空间层，不走命令流） */
   elements?: ElementNode[];
@@ -109,7 +124,7 @@ export interface Story {
  *   纯修复与文档不进位。**禁止**从 git 提交数、时间戳或产物哈希派生——那会让产物
  *   不再可复现，破坏构建的「零差量」幂等守卫。
  */
-export const CAPABILITY_VERSION = "0.9.0";
+export const CAPABILITY_VERSION = "0.10.0";
 
 /** 工程清单（project.json）：结构化/原子化多文件工程的组装契约 */
 export interface ProjectManifest {

package/src/data/format/column.ts

@@ -9,6 +9,9 @@
 import { isPlainObject } from "../../shared/index.ts";
 import {
   isSceneType,
+  isUiName,
+  normalizeSceneType,
+  normalizeUiNames,
   type ElementNode,
   type SceneType,
   type StoryColumn,
@@ -38,8 +41,8 @@ export type ColumnShapeDefect =
 /**
  * 列对象形状判定（缺省校验 `type`）。
  *
- * `type`（运行语义：game/menu/ui）**缺省合法 = game**，但**给了就必须合法**——
- * 非法值 fail-closed（不静默当 game，否则作者以为设了菜单其实是剧情，
+ * `type`（运行语义：game/ui）**缺省合法 = game**，但**给了就必须合法**——
+ * 非法值 fail-closed（不静默当 game，否则作者以为设了界面层其实是剧情，
  * 那种错要等存档/回溯出问题才发现，代价极高）。
  *
  * 已经另行校验过 `type` 的调用点可传 `checkType: false`，避免同一处报两遍。
@@ -98,7 +101,7 @@ export function parseColumn(
       );
     } else if (shape.reason === "bad-type") {
       issues.push(
-        `${at}.type 必须为 "game" / "menu" / "ui"，收到 ${JSON.stringify(shape.received)}`,
+        `${at}.type 必须为 "game" / "ui"，收到 ${JSON.stringify(shape.received)}`,
       );
     } else if (shape.reason === "flow-without-commands") {
       issues.push(`${at}（flow）必须有 commands 数组`);
@@ -107,7 +110,12 @@ export function parseColumn(
     }
     return null;
   }
-  const type = raw.type as SceneType | undefined;
+  // `type` 已在上面按形状判定过（只接受 `game` / `ui`，其余含旧拼写 `menu` 一律
+  // fail-closed 报错），这里只做「缺席 = 不声明」与合法值的归一。归一仍然要调，
+  // 因为它是读侧兜底：非法值到不了这一步，但缺省与空值的收敛口径与它同一处。
+  // 原拼写要不要留（编辑器展示「菜单」还是「界面」）由编辑器自己收，不进故事树。
+  const type: SceneType | undefined =
+    raw.type === undefined ? undefined : normalizeSceneType(raw.type);
   const kind = raw.kind as "scene" | "flow";
   // 列级字体：可选元数据，非空字符串才收（注册表校验在构建期/渲染层闸门，解析只管形状）
   let font: string | undefined;
@@ -120,6 +128,26 @@ export function parseColumn(
     }
     font = raw.font;
   }
+  // 列级 UI 声明：可选元数据，字符串数组且每元素是合法 UI 名（目录名形态）。
+  // 读入即归一（去重 + 码点序）：产物字节要由数据决定，不能由书写顺序决定。
+  // 空数组与缺省等价（`undefined`）——「没有 UI 的列不带该字段」是同一条规则。
+  let uis: readonly string[] | undefined;
+  if (raw.uis !== undefined) {
+    if (!Array.isArray(raw.uis)) {
+      issues.push(`${at}.uis 必须为字符串数组（元素是 UI 目录名）`);
+      return null;
+    }
+    for (const [j, name] of raw.uis.entries()) {
+      if (!isUiName(name)) {
+        issues.push(
+          `${at}.uis[${j}] 不是合法 UI 名：收到 ${JSON.stringify(name)}（小写字母开头，其后小写字母 / 数字 / \`_\` / \`-\`，总长 1..32）`,
+        );
+        return null;
+      }
+    }
+    const normalized = normalizeUiNames(raw.uis as string[]);
+    if (normalized.length > 0) uis = normalized;
+  }
   if (kind === "flow") {
     if (!Array.isArray(raw.commands)) {
       issues.push(`${at}（flow）必须有 commands 数组`);
@@ -165,6 +193,7 @@ export function parseColumn(
     kind,
     type,
     font,
+    uis,
     // `sourcePath` **刻意不解析**：它是编辑期记账（由组装器从实际文件路径回填），
     // 故事文件里不该有这个键——写进去也无效（防止自指：文件描述自己的位置）。
     elements: raw.elements as ElementNode[] | undefined,

package/src/data/index.ts

@@ -16,6 +16,7 @@ export {
   isSafeFileNameSegment,
   MANIFEST_FILE,
   ProjectSerializationError,
+  RESOURCES_DIR,
   serializeColumnDocument,
   serializeProject,
   STORIES_DIR,

package/src/data/project/assemble.ts

@@ -1,5 +1,6 @@
-import { isPlainObject } from "../../shared/index.ts";
+import { compareOrdinal, isPlainObject } from "../../shared/index.ts";
 import {
+  AUDIO_CHANNELS,
   isOrientationMode,
   type DegradedOpen,
   type Story,
@@ -12,7 +13,7 @@ import {
   StoryFormatError,
 } from "../format/index.ts";
 import { ProjectAssemblyError } from "./error.ts";
-import { byPath, isDotPath, MANIFEST_FILE, STORIES_DIR } from "./naming.ts";
+import { isDotPath, MANIFEST_FILE, STORIES_DIR } from "./naming.ts";
 
 /**
  * 工程组装：project.json + Stories/** → Story。
@@ -37,7 +38,7 @@ export function synthesizeDegradedManifest(
   const ids: string[] = [];
   for (const path of [...storyTexts.keys()]
     .filter((p) => !isDotPath(p))
-    .sort(byPath)) {
+    .sort(compareOrdinal)) {
     try {
       const story = parseStoryFile(storyTexts.get(path) ?? "", path);
       for (const column of story.columns) ids.push(column.id);
@@ -118,13 +119,43 @@ export function assembleProject(
     if (!isPlainObject(manifest.shell)) {
       issues.push("project.json: shell 必须为对象");
     } else {
-      const orientation = (manifest.shell as { orientation?: unknown })
-        .orientation;
+      const shell = manifest.shell as {
+        orientation?: unknown;
+        audio?: unknown;
+      };
+      const orientation = shell.orientation;
       if (orientation !== undefined && !isOrientationMode(orientation)) {
         issues.push(
           `project.json: shell.orientation 必须为 auto|portrait|landscape，收到 ${JSON.stringify(orientation)}`,
         );
       }
+      // 工程默认音量：形状错即拒绝；逐个通道只认有限数字（越界钳制，不拒绝）。
+      // 与 resolveAudioConfig 同口径——那里是解析（钳制后采纳），这里是拒绝形状错误，
+      // 两处若口径不同，作者会看到「构建通过但音量不对」。
+      if (shell.audio !== undefined) {
+        if (!isPlainObject(shell.audio)) {
+          issues.push("project.json: shell.audio 必须为对象");
+        } else {
+          const volumes = (shell.audio as { volumes?: unknown }).volumes;
+          if (volumes !== undefined) {
+            if (!isPlainObject(volumes)) {
+              issues.push(
+                "project.json: shell.audio.volumes 必须为对象（键为音频通道）",
+              );
+            } else {
+              for (const channel of AUDIO_CHANNELS) {
+                const raw = (volumes as Record<string, unknown>)[channel];
+                if (raw === undefined) continue;
+                if (typeof raw !== "number" || !Number.isFinite(raw)) {
+                  issues.push(
+                    `project.json: shell.audio.volumes.${channel} 必须为 0..1 的有限数字，收到 ${JSON.stringify(raw)}`,
+                  );
+                }
+              }
+            }
+          }
+        }
+      }
     }
   }
   if (issues.length > 0) throw new ProjectAssemblyError(issues);
@@ -135,7 +166,7 @@ export function assembleProject(
     ...((manifest.defines as Record<string, unknown> | undefined) ?? {}),
   };
 
-  for (const path of [...files.keys()].sort(byPath)) {
+  for (const path of [...files.keys()].sort(compareOrdinal)) {
     // **只处理 `Stories/` 下的文件**。
     //组装器**假定**调用方只喂故事文件，若喂了全量资源根就会组装失败：
     // `Lang/en-US/main.json`（译文表）等全被当故事解析

package/src/data/project/conflict.ts

@@ -1,4 +1,5 @@
-import { byPath, STORIES_DIR, isSafeFileNameSegment } from "./naming.ts";
+import { compareOrdinal } from "../../shared/index.ts";
+import { STORIES_DIR, isSafeFileNameSegment } from "./naming.ts";
 import {
   defaultEngineTexts,
   type EngineTexts,
@@ -84,7 +85,7 @@ export function detectWriteNormalization(
     }
   }
   return {
-    toConvert: toConvert.sort(byPath),
-    toRemove: toRemove.sort(byPath),
+    toConvert: toConvert.sort(compareOrdinal),
+    toRemove: toRemove.sort(compareOrdinal),
   };
 }

package/src/data/project/diff.ts

@@ -1,5 +1,5 @@
-import { isPlainObject } from "../../shared/index.ts";
-import { byPath, STORIES_DIR } from "./naming.ts";
+import { compareOrdinal, isPlainObject } from "../../shared/index.ts";
+import { STORIES_DIR } from "./naming.ts";
 import type { ProjectFileDiff } from "../../contracts/index.ts";
 
 /**
@@ -56,6 +56,6 @@ export function diffProjectFiles(
   }
   const deletes = [...previous.keys()]
     .filter((path) => path.startsWith(`${STORIES_DIR}/`) && !wanted.has(path))
-    .sort(byPath);
+    .sort(compareOrdinal);
   return { changes, deletes };
 }

package/src/data/project/index.ts

@@ -13,7 +13,12 @@ export type {
   WriteNormalizationFinding,
 } from "../../contracts/index.ts";
 export { ProjectAssemblyError, ProjectSerializationError } from "./error.ts";
-export { isSafeFileNameSegment, MANIFEST_FILE, STORIES_DIR } from "./naming.ts";
+export {
+  isSafeFileNameSegment,
+  MANIFEST_FILE,
+  RESOURCES_DIR,
+  STORIES_DIR,
+} from "./naming.ts";
 export { assembleProject, synthesizeDegradedManifest } from "./assemble.ts";
 export { serializeColumnDocument, serializeProject } from "./serialize.ts";
 export { diffProjectFiles } from "./diff.ts";

package/src/data/project/naming.ts

@@ -1,11 +1,9 @@
 /**
- * 工程文件的命名与路径判据：清单名、故事目录名、路径码元序、文件名安全段。
+ * 工程文件的命名与路径判据：清单名、故事目录名、文件名安全段。
  * 组装、写回、差量与冲突检测都依赖同一套判据，这里只声明一份。
+ *
+ * 路径排序不在这里：码元序比较器全仓只有 `shared/ordering.ts` 的 `compareOrdinal` 一处。
  */
-/** 确定性文件顺序（路径码元序）——defines 覆盖与列序不随 Map 构造顺序漂移 */
-export function byPath(a: string, b: string): number {
-  return a < b ? -1 : a > b ? 1 : 0;
-}
 
 /** 清单文件名（清单必须在资源根内——dev/prod 同机制） */
 export const MANIFEST_FILE = "project.json";
@@ -13,6 +11,14 @@ export const MANIFEST_FILE = "project.json";
 /** 故事目录名（Rust `STORIES_DIR` 同名） */
 export const STORIES_DIR = "Stories";
 
+/**
+ * 资源根目录名（相对工程根）：清单、`Stories/**` 与素材都住在它下面。
+ *
+ * 两侧共用同一份声明——引擎侧的资源适配器按它定位资源根（所选目录不含清单时
+ * 下探这一层），构建侧按它落清单与故事产物。改名只改这里，两边不会错位。
+ */
+export const RESOURCES_DIR = "Resources";
+
 /**
  * 点文件/点目录判据（`.gitkeep` / `.gitignore` …）—— **任何一段**以 `.` 开头即是。
  *

package/src/data/project/serialize.ts

@@ -1,14 +1,12 @@
-import { isPlainObject } from "../../shared/index.ts";
+import { compareOrdinal, isPlainObject } from "../../shared/index.ts";
 import { ProjectSerializationError } from "./error.ts";
-import {
-  byPath,
-  MANIFEST_FILE,
-  STORIES_DIR,
-  isSafeFileNameSegment,
-} from "./naming.ts";
+import { MANIFEST_FILE, STORIES_DIR, isSafeFileNameSegment } from "./naming.ts";
 import { columnShapeDefect } from "../format/column.ts";
 import {
   CAPABILITY_VERSION,
+  normalizeSceneType,
+  normalizeUiNames,
+  type SceneType,
   type SerializedProject,
   type Story,
   type StoryColumn,
@@ -23,20 +21,48 @@ function stableJson(value: unknown): string {
   return `${JSON.stringify(value, null, 2)}\n`;
 }
 
-/** 单列原子文件文本：字段序固定（formatVersion, id, kind, type?, font?, commands|elements, entry?） */
+/**
+ * 落盘的 `type` 值（**唯一写出点**）：`undefined` = 不写字段（缺省 game 保持文件干净）。
+ *
+ * 写出恒为契约值 `game` / `ui`：内存故事树里若带旧拼写（编辑期脚本、外部构造），
+ * 也不会把别名写回磁盘 —— 否则存量工程每存一次都可能换一次拼写。
+ */
+function writeBackSceneType(column: StoryColumn): SceneType | undefined {
+  if (column.type === undefined) return undefined;
+  const sceneType = normalizeSceneType(column.type);
+  return sceneType === "game" ? undefined : sceneType;
+}
+
+/**
+ * 落盘的列级 `uis`（**唯一写出点**）：`undefined` / 空数组 = 不写字段，否则写归一后的数组。
+ *
+ * 归一（去重 + 码点序）在写出侧再做一次：内存故事树可能由编辑期脚本或外部工具构造，
+ * 不保证已经排过序。漏了这一步，同一个工程在不同保存路径下会产出不同字节。
+ */
+function writeBackUis(column: StoryColumn): readonly string[] | undefined {
+  if (column.uis === undefined) return undefined;
+  const names = normalizeUiNames(column.uis);
+  return names.length === 0 ? undefined : names;
+}
+
+/** 单列原子文件文本：字段序固定（formatVersion, id, kind, type?, font?, uis?, commands|elements, entry?） */
 function columnFileText(column: StoryColumn): string {
   const ordered: Record<string, unknown> = {
     formatVersion: 1,
     id: column.id,
     kind: column.kind,
   };
-  // `type`（运行语义）**必须写回**：漏了会让 menu/ui 场景在下次打开时
-  // 变成 game（保存 = 悄悄改语义，且**不可逆**——作者下次打开发现菜单能回溯了）。
+  // `type`（运行语义）**必须写回**：漏了会让 ui 场景在下次打开时
+  // 变成 game（保存 = 悄悄改语义，且**不可逆**——作者下次打开发现界面层能回溯了）。
   // 缺省 game 不写（保持文件干净），非缺省才写。
-  if (column.type !== undefined && column.type !== "game")
-    ordered.type = column.type;
+  const sceneType = writeBackSceneType(column);
+  if (sceneType !== undefined) ordered.type = sceneType;
   // 列级字体（纯展示元数据）必须写回：漏了会让保存悄悄抹掉列排版（不可逆）。
   if (column.font !== undefined) ordered.font = column.font;
+  // 列级 UI 声明同理：漏了会让保存把「本列引用哪些挂载 UI」清空，
+  // 宿主下次打开就少预加载（症状是界面闪一下才出现，很难归因到一次保存）。
+  const uis = writeBackUis(column);
+  if (uis !== undefined) ordered.uis = uis;
   if (column.kind === "flow") {
     ordered.commands = column.commands ?? [];
   } else {
@@ -91,7 +117,9 @@ function manifestText(story: Story, manifest: Record<string, unknown>): string {
 
 /** 按路径码元序重排文件表，让写回/比对顺序不随 Map 插入顺序漂移（结果可复现） */
 function sortByCodeUnit(files: Map<string, string>): Map<string, string> {
-  return new Map([...files.entries()].sort((a, b) => byPath(a[0], b[0])));
+  return new Map(
+    [...files.entries()].sort((a, b) => compareOrdinal(a[0], b[0])),
+  );
 }
 
 /**
@@ -150,7 +178,7 @@ export function serializeProject(
       }
       if (shape.reason === "bad-type") {
         issues.push(
-          `列 ${id} 的 type 必须为 "game" / "menu" / "ui"，收到 ${JSON.stringify(shape.received)}`,
+          `列 ${id} 的 type 必须为 "game" / "ui"，收到 ${JSON.stringify(shape.received)}`,
         );
         continue;
       }
@@ -213,9 +241,14 @@ function columnGroupFileText(
         id: column.id,
         kind: column.kind,
       };
-      if (column.type !== undefined && column.type !== "game") {
-        ordered.type = column.type;
+      const sceneType = writeBackSceneType(column);
+      if (sceneType !== undefined) {
+        ordered.type = sceneType;
       }
+      // 多列形态与单列形态的字段集必须一致：同一列换一种文件形态保存，
+      // 字段不该跟着丢（`uis` 丢了宿主就少预加载，且不可逆）。
+      const uis = writeBackUis(column);
+      if (uis !== undefined) ordered.uis = uis;
       if (column.kind === "flow") ordered.commands = column.commands ?? [];
       else {
         ordered.elements = column.elements ?? [];

package/src/data/text/entry.ts

@@ -18,10 +18,12 @@ import type {
   Story,
   StoryColumn,
   StoryCommand,
+  SceneType,
   ElementNode,
   CustomOpProjections,
   TextProjection,
 } from "../../contracts/index.ts";
+import { sceneTypeOf } from "../../shared/index.ts";
 
 /** 文本 → Story（缩进块、注释、全 op 文法；失败整次拒绝并带行列定位）。
  * `projections`（可选）= 扩展自定义 op 的行投影表；缺省 = 现行为逐字节不变。 */
@@ -77,20 +79,18 @@ export function parseTextStory(
       if (name === "" || columns.some((c) => c.id === name)) {
         state.issues.push(`${at}: scene 名为空或重复：${name}`);
       }
-      // `type=menu|ui|game`：**映射到列的运行语义**。
-      // 若「接受但忽略」，作者的 menu 场景**会被当成 game**
-      // ⇒ 保存后菜单会变成可回溯剧情（且不可逆）。
-      let sceneType: "game" | "menu" | "ui" | undefined;
+      // `type=game|ui`：**映射到列的运行语义**。
+      // 若「接受但忽略」，作者的界面层场景**会被当成 game**
+      // ⇒ 保存后界面层会变成可回溯剧情（且不可逆）。
+      // 无从识别的 `type=xxx` 仍走下面的「忽略无法识别的参数」告警，不静默改语义。
+      let sceneType: SceneType | undefined;
       const rest: string[] = [];
       for (let t = 2; t < sceneTokens.length; t += 1) {
         const token = sceneTokens[t]!;
         const eq = token.indexOf("=");
         const key = eq > 0 ? token.slice(0, eq) : "";
         const value = eq > 0 ? unquote(token.slice(eq + 1)) : "";
-        if (
-          key === "type" &&
-          (value === "game" || value === "menu" || value === "ui")
-        ) {
+        if (key === "type" && (value === "game" || value === "ui")) {
           sceneType = value;
           continue;
         }
@@ -194,7 +194,15 @@ export function projectText(
   for (const column of story.columns) {
     if (column.kind === "scene") {
       // scene 列：元素行在前、entry 命令在后（与装载语义一致——先声明空间层再执行）
-      out.push(`scene ${column.id}`);
+      //
+      // `type` 只写非缺省值（`game` 是常态，写进去会让文本噪声变大）；写出的恒是
+      // 契约值 `ui`——旧拼写 `menu` 解析时已归一，投影不还原别名（项目里只允许一种写法）。
+      const sceneType = sceneTypeOf(column);
+      out.push(
+        sceneType === "game"
+          ? `scene ${column.id}`
+          : `scene ${column.id} type=${sceneType}`,
+      );
       for (const node of column.elements ?? []) {
         tolerant(`元素 ${String(node.type ?? "")}`, issues, () =>
           generateElement(node, "  ", out),

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

@@ -1,7 +1,7 @@
 /**
  * 命令文本生成族出口：按命令族分片的生成器。
  *
- * 轴 = 命令族（块体 / 集合 / 对话 / 流程 / 媒体 / 表演 / 存档 / 变量）。缩进与投影器由
+ * 轴 = 命令族（块体 / 集合 / 对话 / 流程 / 媒体 / 表演 / 存档 / UI / 变量）。缩进与投影器由
  * 调用方注入，族文件只认自己那族的字段。
  */
 export { generateBlocksCommand } from "./blocks.ts";
@@ -11,4 +11,5 @@ export { generateFlowCommand } from "./flow.ts";
 export { generateMediaCommand } from "./media.ts";
 export { generatePresentCommand } from "./present.ts";
 export { generateSaveCommand } from "./save.ts";
+export { generateUiCommand } from "./ui.ts";
 export { generateVariablesCommand } from "./variables.ts";

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;