@lingfan-engine/editor 0.1.5 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lingfan-engine/editor",
-  "version": "0.1.5",
+  "version": "0.3.0",
   "type": "module",
   "description": "灵泛叙事作者层：op schema 单一事实源 + 词函数子语言 + 编辑期诊断 + 故事树纯映射器——只读写故事 JSON，不碰运行时与平台",
   "exports": {
@@ -13,7 +13,7 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@lingfan-engine/core": "^0.1.5",
+    "@lingfan-engine/core": "^0.3.0",
     "zod": "^4.6.5"
   },
   "license": "Apache-2.0",

package/src/chapters/build.ts

@@ -65,15 +65,13 @@ export function chapterGroupOf(
 /**
  * 场景类型的**徽标文案**（单一事实源：列侧栏 / 章节树共用，组件不得自写映射）。
  *
- * - `"menu"` → 「菜单」；`"ui"` → 「界面」
+ * - `"ui"` → 「界面」
  * - 缺省（`undefined`）与 `"game"` → `null`（**game 是常态不标**——满屏「剧情」徽标是噪音）
  */
 export function sceneTypeBadgeOf(
   type: StoryColumn["type"],
-): "菜单" | "界面" | null {
-  if (type === "menu") return "菜单";
-  if (type === "ui") return "界面";
-  return null;
+): "界面" | null {
+  return type === "ui" ? "界面" : null;
 }
 
 /** 命令条数（flow 看 commands、scene 看 entry；缺省 0） */

package/src/chapters/index.ts

@@ -25,6 +25,7 @@ export {
   sceneTypeBadgeOf,
 } from "./build.ts";
 
+
 export type {
   ChapterDir,
   ChapterGroup,

package/src/chapters/types.ts

@@ -21,9 +21,8 @@ export interface ChapterNode {
   /** 该章节的场景所属分组（由 `type` 决定，**不按目录猜**） */
   readonly group: ChapterGroup;
   /**
-   * 原始场景类型（列的 `type` 字段原样透传；`undefined` = 缺省 game）。
-   * 分组判定只吃 `group`；要**精确到 菜单/界面** 的展示走 `sceneTypeBadgeOf(node.type)`
-   * （`group=ui` 只说明「不可回溯」，不说明是哪一种）。
+   * 归约后的场景类型（契约值；`undefined` = 缺省 game）。
+   * 分组判定只吃 `group`——`group=ui` 只说明「不可回溯」，不说明作者原本写的是哪一种。
    */
   readonly type: StoryColumn["type"];
   /** 章节在文件树中的位置（逻辑路径，用于联动资源树选中） */

package/src/contracts/forms.ts

@@ -11,7 +11,8 @@ export type OpGroup =
   | "save"
   | "audio"
   | "video"
-  | "minigame";
+  | "minigame"
+  | "ui";
 
 /**
  * 字段呈现语义（驱动诊断扫描面与表单控件选型）：

package/src/contracts/texts.ts

@@ -106,13 +106,13 @@ export interface EditorTexts {
   invalidVarHandlePath(prop: string, prefix: string): string;
   /** script/expr：未注册的变量。 */
   unregisteredVariable(key: string): string;
-  /** script/expr 审计：操作数类型不匹配。 */
+  /** script/expr 检查：操作数类型不匹配。 */
   operandKindMismatch(op: string, side: string, want: string, described: string, note: string): string;
-  /** script/expr 审计：三元条件必须为 boolean。 */
+  /** script/expr 检查：三元条件必须为 boolean。 */
   ternaryCondNotBool(described: string): string;
-  /** script/expr 审计：不支持跨类型比较。 */
+  /** script/expr 检查：不支持跨类型比较。 */
   crossTypeComparison(op: string, left: string, right: string): string;
-  /** script/expr 审计：未知类型的操作数标签。 */
+  /** script/expr 检查：未知类型的操作数标签。 */
   unknownOperandKind(): string;
 
   /** schema/surface：扩展 op 归组不合法。 */

package/src/editing/storyOps.ts

@@ -5,7 +5,7 @@
  * ——「列名即标签」，重命名必须保持全部列的引用图一致。
  */
 
-import type { Story } from "@lingfan-engine/core";
+import type { SceneType, Story } from "@lingfan-engine/core";
 import { isSafeFileNameSegment } from "@lingfan-engine/core";
 import {
   getAtPointer,
@@ -77,11 +77,11 @@ export function addColumn(
     id?: string;
     kind?: "scene" | "flow";
     /**
-     * 运行语义轴（与 `kind` 正交）：game 缺省 / menu 菜单 / ui 覆盖层。
+     * 运行语义轴（与 `kind` 正交）：缺省 = game，非缺省只可能是 ui（界面层）。
      * **缺省与 game 都不写字段**——默认值不显式存储（与写回保真同一口径：
      * 新建列的内存形态必须与重开后的解析形态深等）。
      */
-    type?: "game" | "menu" | "ui";
+    type?: SceneType;
     /** 语义化建议（仅 id 缺省时参与；见 suggestColumnId） */
     hint?: string | null;
   } = {},

package/src/i18n/surfaces.ts

@@ -9,16 +9,17 @@
  * 路径语法：`a.b` 逐段取值；`a[].b` 的 `[]` = 对数组逐项迭代（`options[].text`）。
  */
 
-/** 可翻译原文面（运行期 Translate 挂接：say 文本+说话人 / menu prompt+选项 / input prompt / notify 文本。character.screen 见下——仅入编辑器比对面，运行期不翻） */
+/** 可翻译原文面（运行期 Translate 挂接：say 文本+说话人 / menu prompt+选项 / input prompt+候选文本 / notify 文本。character.screen 见下——仅入编辑器比对面，运行期不翻） */
 export const TRANSLATE_SURFACES: Readonly<Record<string, readonly string[]>> = {
   say: ["text", "speaker"],
   menu: ["prompt", "options[].text"],
-  input: ["prompt"],
+  // 候选只翻显示文本；`value` 是要写进变量的原样值，**不进翻译面**（否则多语言下故事逻辑随语言漂移）
+  input: ["prompt", "options[].text"],
   notify: ["text"],
-  // character.screen 仅入编辑器比对面（原文收集/键抽取），运行期**不翻**：引擎恰好 7 个
-  // translate 调用点（runtime/i18n/translate.ts:31、ops/dialog.ts:92/107/171/175、
-  // ops/interaction.ts:42、ops/media.ts:262），均不含 screen（说话人显示名解析产物
-  // 走 say 的 Translate 挂接，查表见 runtime/ops/dialog.ts execSay；docs concepts/i18n.md 同口径）。
+  // character.screen 仅入编辑器比对面（原文收集/键抽取），运行期**不翻**：引擎的
+  // translate 调用点分布在 runtime/i18n/translate.ts、ops/dialog.ts、ops/interaction.ts
+  // 与 ops/media/notify.ts，均不含 screen（说话人显示名解析产物走 say 的 Translate
+  // 挂接，查表见 runtime/ops/dialog.ts execSay；docs concepts/i18n.md 同口径）。
   character: ["screen"],
 };
 

package/src/index.ts

@@ -63,6 +63,11 @@ export type {
 } from "./schema/index.ts";
 /** 词汇层构建期轻类型校验警告（expr/cond 组装时按引擎类型规则产出；drain 取走） */
 export type { ExpressionWarning } from "./script/index.ts";
+/**
+ * 挂载 UI 句柄的形状：故事源 `import hub from "…/ui/hub/hub.vue"` 拿到的就是这个。
+ * 经包根再导出一次，`stories-build/authoring` 的 ambient 声明才能只 import type 转发。
+ */
+export type { UiHandle } from "./script/index.ts";
 export {
   BUILTIN_OP_SURFACE,
   mergeOpMeta,
@@ -242,6 +247,8 @@ export {
   type ColumnNameRegistry,
   type GuardNameRegistry,
   type InterpolationKeyRegistry,
+  type KnownUiName,
+  type UiNameRegistry,
 } from "./script/index.ts";
 
 /**
@@ -291,6 +298,7 @@ export {
   hide,
   imageElement,
   input,
+  inputCandidate,
   interaction,
   jump,
   letVar,
@@ -298,6 +306,7 @@ export {
   localVar,
   menu,
   minigame,
+  mount,
   navigate,
   newArray,
   notify,
@@ -314,6 +323,11 @@ export {
   say,
   sceneSetup,
   sceneType,
+  audioPlay,
+  audioStop,
+  audioVolume,
+  audioPause,
+  audioResume,
   se,
   seekVideo,
   set,
@@ -323,6 +337,7 @@ export {
   staticFor,
   stopAmbient,
   stopBgm,
+  stopSe,
   stopVideo,
   stopVoice,
   style,

package/src/schema/catalog.ts

@@ -22,6 +22,7 @@ export const OP_GROUP_ORDER: readonly OpGroup[] = [
   "audio",
   "video",
   "minigame",
+  "ui",
 ];
 
 /** op 分组中文标签（单一事实源） */
@@ -34,6 +35,7 @@ export const OP_GROUP_LABELS: Readonly<Record<OpGroup, string>> = {
   audio: "音频",
   video: "视频",
   minigame: "小游戏",
+  ui: "UI",
 };
 
 export const OP_META: readonly OpMeta[] = [
@@ -82,6 +84,12 @@ export const OP_META: readonly OpMeta[] = [
   { op: "stop_ambient", label: "停止环境音", group: "audio" },
   { op: "voice", label: "语音", group: "audio" },
   { op: "stop_voice", label: "停止语音", group: "audio" },
+  { op: "stop_se", label: "停止音效", group: "audio" },
+  { op: "audio_play", label: "起播音频实例", group: "audio" },
+  { op: "audio_stop", label: "停止音频实例", group: "audio" },
+  { op: "audio_volume", label: "调音频实例音量", group: "audio" },
+  { op: "audio_pause", label: "暂停音频通道", group: "audio" },
+  { op: "audio_resume", label: "恢复音频通道", group: "audio" },
   { op: "video", label: "视频", group: "video" },
   { op: "cutscene", label: "过场", group: "video" },
   { op: "seek_video", label: "视频跳转", group: "video" },
@@ -104,6 +112,8 @@ export const OP_META: readonly OpMeta[] = [
   { op: "transition", label: "转场", group: "presentation" },
   { op: "shake", label: "屏幕震动", group: "presentation" },
   { op: "text_typewriter", label: "打字机设置", group: "presentation" },
+  // 挂载 UI
+  { op: "mount", label: "挂载 UI 显隐", group: "ui" },
 ];
 
 interface FieldMeta {
@@ -136,6 +146,9 @@ export const FIELD_META: Readonly<Record<string, FieldMeta>> = {
   "menu.z": { label: "层级（实例）", kind: "number" },
   "input.prompt": { label: "提示语", kind: "text" },
   "input.store": { label: "存入变量", kind: "identifier" },
+  "input.options": { label: "候选值", kind: "array" },
+  "input.options[].text": { label: "候选文本", kind: "text" },
+  "input.options[].value": { label: "填入值", kind: "string" },
   "input.z": { label: "层级（实例）", kind: "number" },
   "notify.text": { label: "文本", kind: "text" },
   "notify.type": { label: "类型", kind: "string" },
@@ -234,6 +247,20 @@ export const FIELD_META: Readonly<Record<string, FieldMeta>> = {
   "voice.auto_stop": { label: "推进即停", kind: "boolean" },
   "voice.restart": { label: "回起点重播", kind: "boolean" },
   "stop_voice.fade": { label: "淡出（毫秒）", kind: "number" },
+  "stop_se.fade": { label: "淡出（毫秒）", kind: "number" },
+  "audio_play.inst": { label: "实例 id", kind: "text" },
+  "audio_play.channel": { label: "归属通道", kind: "text" },
+  "audio_play.resource": { label: "资源", kind: "text" },
+  "audio_play.volume": { label: "音量（0–1）", kind: "number" },
+  "audio_play.loop": { label: "循环", kind: "boolean" },
+  "audio_play.fade": { label: "淡入（毫秒）", kind: "number" },
+  "audio_play.restart": { label: "重新起播", kind: "boolean" },
+  "audio_stop.inst": { label: "实例 id（留空 = 全部）", kind: "text" },
+  "audio_stop.fade": { label: "淡出（毫秒）", kind: "number" },
+  "audio_volume.inst": { label: "实例 id", kind: "text" },
+  "audio_volume.volume": { label: "音量（0–1）", kind: "number" },
+  "audio_pause.channel": { label: "通道（留空 = 全部常驻）", kind: "text" },
+  "audio_resume.channel": { label: "通道（留空 = 全部常驻）", kind: "text" },
   "video.resource": { label: "资源", kind: "resource" },
   "video.volume": { label: "音量", kind: "number" },
   "video.loop": { label: "循环", kind: "boolean" },
@@ -292,6 +319,9 @@ export const FIELD_META: Readonly<Record<string, FieldMeta>> = {
   "shake.duration": { label: "时长（秒）", kind: "number" },
   "text_typewriter.enabled": { label: "启用", kind: "boolean" },
   "text_typewriter.speed": { label: "速度（字符/秒）", kind: "number" },
+  "mount.name": { label: "UI 名", kind: "text" },
+  "mount.visible": { label: "挂载", kind: "boolean" },
+  "mount.props": { label: "入参", kind: "object" },
 };
 
 /** 文本插值面（诊断扫描用）：text kind 字段集合的查询入口 */

package/src/schema/opSchemas/commands.ts

@@ -56,6 +56,10 @@ const menuSchema = z.strictObject({
 const inputSchema = z.strictObject({
   prompt: NonEmpty,
   store: NonEmpty,
+  // 候选快捷值：显示文本 + 要填进 store 的值（与 menu 的 {text,target} 刻意不同名）
+  options: z
+    .array(z.strictObject({ text: NonEmpty, value: NonEmpty }))
+    .optional(),
   z: InstanceZ, // choices 层实例 z
 });
 
@@ -227,6 +231,42 @@ const voiceSchema = z.strictObject({
 });
 const stopSchema = z.strictObject({ fade: Fade.optional() });
 
+/** 音频实例 id：与扩展 / 玩法系统同一条短 id 形态（引擎侧是唯一声明处，此处只校验形态） */
+const AudioInstanceId = z
+  .string()
+  .regex(/^[a-z][a-z0-9_-]{0,31}$/, "须为小写字母开头的短 id（1..32 位）");
+
+const audioChannelSchema = z.enum(["bgm", "se", "ambient", "voice"]);
+
+const audioPlaySchema = z.strictObject({
+  inst: AudioInstanceId,
+  channel: audioChannelSchema,
+  resource: NonEmpty,
+  volume: Finite.optional(),
+  loop: z.boolean().optional(),
+  fade: Fade.optional(),
+  restart: z.boolean().optional(),
+});
+
+const audioStopSchema = z.strictObject({
+  inst: AudioInstanceId.optional(),
+  fade: Fade.optional(),
+});
+
+const audioVolumeSchema = z.strictObject({
+  inst: AudioInstanceId,
+  volume: Finite,
+});
+
+// channel 省略 = 全部常驻通道（se 除外），故是 optional 而非缺省成某个通道
+const audioPauseSchema = z.strictObject({
+  channel: audioChannelSchema.optional(),
+});
+
+const audioResumeSchema = z.strictObject({
+  channel: audioChannelSchema.optional(),
+});
+
 const videoSchema = z.strictObject({
   ...playFields,
   loop: z.boolean().optional(),
@@ -314,6 +354,21 @@ const textTypewriterSchema = z.strictObject({
   speed: z.number().finite().positive().optional(),
 });
 
+/**
+ * `mount`：挂载 / 卸载一个 UI 组件。
+ *
+ * `name` 是 UI 目录名（短标识：小写字母开头，其后小写字母 / 数字 / `_` / `-`，1..32 位）——
+ * 与引擎侧 `UI_NAME_PATTERN` 同一形态，名字同时是产物键与目录名，两处必须一致。
+ * `props` 只收对象；键值是否 JSON 安全由运行期写入点判定（schema 看不见值语义）。
+ */
+const mountSchema = z.strictObject({
+  name: z
+    .string()
+    .regex(/^[a-z][a-z0-9_-]{0,31}$/, "UI 名须小写字母开头，其后小写字母/数字/_/-，1..32 位"),
+  visible: z.boolean(),
+  props: z.record(z.string(), z.unknown()).optional(),
+});
+
 export {
   saySchema,
   menuSchema,
@@ -353,6 +408,11 @@ export {
   seSchema,
   voiceSchema,
   stopSchema,
+  audioPlaySchema,
+  audioStopSchema,
+  audioVolumeSchema,
+  audioPauseSchema,
+  audioResumeSchema,
   videoSchema,
   cutsceneSchema,
   seekVideoSchema,
@@ -371,4 +431,5 @@ export {
   transitionSchema,
   shakeSchema,
   textTypewriterSchema,
+  mountSchema,
 };

package/src/schema/opSchemas/map.ts

@@ -36,6 +36,11 @@ import {
   saveDeleteSchema,
   bgmSchema,
   stopSchema,
+  audioPlaySchema,
+  audioStopSchema,
+  audioVolumeSchema,
+  audioPauseSchema,
+  audioResumeSchema,
   seSchema,
   voiceSchema,
   videoSchema,
@@ -56,6 +61,7 @@ import {
   transitionSchema,
   shakeSchema,
   textTypewriterSchema,
+  mountSchema,
 } from "./commands.ts";
 
 /** op → 负载 schema（不含 op 键本身）；字面量键形态 = `ScriptCommand` 判别联合的派生源。
@@ -106,6 +112,12 @@ export const OP_SCHEMA_MAP = {
   stop_ambient: stopSchema,
   voice: voiceSchema,
   stop_voice: stopSchema,
+  stop_se: stopSchema,
+  audio_play: audioPlaySchema,
+  audio_stop: audioStopSchema,
+  audio_volume: audioVolumeSchema,
+  audio_pause: audioPauseSchema,
+  audio_resume: audioResumeSchema,
   video: videoSchema,
   cutscene: cutsceneSchema,
   seek_video: seekVideoSchema,
@@ -128,6 +140,8 @@ export const OP_SCHEMA_MAP = {
   transition: transitionSchema,
   shake: shakeSchema,
   text_typewriter: textTypewriterSchema,
+  // 挂载 UI
+  mount: mountSchema,
 };
 
 /** 运行期查找面（与 `OP_SCHEMA_MAP` 同一对象，键集恒等）；新增 op 自动可用 */

package/src/script/expr/audit/index.ts

@@ -1,5 +1,5 @@
 /**
- * 审计子模块出口：判类器与它使用的词法词汇。
+ * 检查子模块出口：判类器与它使用的词法词汇。
  *
  * 装配层只从这里取，不引子模块内部文件。
  */

package/src/script/expr/audit/parser.ts

@@ -1,5 +1,5 @@
 /**
- * 表达式审计：把装配时产出的 token 流按引擎的类型规则判类，违规记入警告池。
+ * 表达式检查：把装配时产出的 token 流按引擎的类型规则判类，违规记入警告池。
  *
  * 判类器是一个整体（方法共享游标 `pos` 与警告池），所以实现文件刻意只留一条导入。
  */

package/src/script/index.ts

@@ -51,10 +51,24 @@ export {
   type KnownInterpolationKey,
 } from "./words/index.ts";
 
+// —— 挂载 UI（句柄形状 + 挂载词）——
+export { mount, type KnownUiName, type UiHandle, type UiNameRegistry } from "./words/index.ts";
+
 // —— 叙事 ——
-export { say, option, menu, input, notify, nvl, character, uncharacter } from "./words/index.ts";
+export {
+  say,
+  option,
+  menu,
+  input,
+  inputCandidate,
+  notify,
+  nvl,
+  character,
+  uncharacter,
+} from "./words/index.ts";
 export type {
   MenuOptionSpec,
+  InputCandidateSpec,
   SayOptions,
   NotifyOptions,
   NvlCommandMode,
@@ -101,6 +115,11 @@ export {
 // —— 存档 / 音频 / 视频 / 小游戏 ——
 export { save, load, autoSave, saveDelete } from "./words/index.ts";
 export {
+  audioPlay,
+  audioStop,
+  audioVolume,
+  audioPause,
+  audioResume,
   bgm,
   stopBgm,
   se,
@@ -108,8 +127,12 @@ export {
   stopAmbient,
   voice,
   stopVoice,
+  stopSe,
 } from "./words/index.ts";
 export type {
+  AudioPlayOptions,
+  AudioStopOptions,
+  AudioPauseOptions,
   PlayOptions,
   BgmOptions,
   StopOptions,

package/src/script/vocabulary-gen.ts

@@ -39,6 +39,7 @@ export function selectWordSources(fileNames: readonly string[]): string[] {
  *  未登记的新导出词会让重建失败（见 renderVocabulary 的缺登记核对）。 */
 export const HELPER_WORDS: Readonly<Record<string, string>> = {
   option: "$menu.option",
+  inputCandidate: "$input.candidate",
   whenChain: "$if.chain",
   reward: "$minigame.reward",
   extOp: "$ext.op",

package/src/script/vocabulary.g.ts

@@ -18,6 +18,11 @@ export const VOCABULARY_OPS = [
   "array_pop",
   "array_push",
   "assert",
+  "audio_pause",
+  "audio_play",
+  "audio_resume",
+  "audio_stop",
+  "audio_volume",
   "auto_save",
   "background",
   "bg_switch",
@@ -44,6 +49,7 @@ export const VOCABULARY_OPS = [
   "local",
   "menu",
   "minigame",
+  "mount",
   "navigate",
   "notify",
   "nvl",
@@ -62,6 +68,7 @@ export const VOCABULARY_OPS = [
   "show",
   "stop_ambient",
   "stop_bgm",
+  "stop_se",
   "stop_video",
   "stop_voice",
   "style",
@@ -95,6 +102,12 @@ export const SCRIPT_COVERAGE: Readonly<Record<string, string>> = {
   stopAmbient: "stop_ambient",
   voice: "voice",
   stopVoice: "stop_voice",
+  stopSe: "stop_se",
+  audioPlay: "audio_play",
+  audioStop: "audio_stop",
+  audioVolume: "audio_volume",
+  audioPause: "audio_pause",
+  audioResume: "audio_resume",
   // —— elements.ts ——
   show: "show",
   hide: "hide",
@@ -143,6 +156,8 @@ export const SCRIPT_COVERAGE: Readonly<Record<string, string>> = {
   load: "load",
   autoSave: "auto_save",
   saveDelete: "save_delete",
+  // —— ui.ts ——
+  mount: "mount",
   // —— vars.ts ——
   set: "set",
   define: "define",
@@ -164,6 +179,7 @@ export const SCRIPT_COVERAGE: Readonly<Record<string, string>> = {
   videoSkipable: "video_skipable",
   // —— 辅助词（补充表登记，不产独立 op） ——
   option: "$menu.option",
+  inputCandidate: "$input.candidate",
   whenChain: "$if.chain",
   reward: "$minigame.reward",
   extOp: "$ext.op",

package/src/script/words/audio.ts

@@ -112,3 +112,122 @@ export function voice(
 export function stopVoice(opts?: StopOptions): CommandOf<"stop_voice"> {
   return { op: "stop_voice", ...opts };
 }
+
+/**
+ * 停止在播音效（`fade` 渐出毫秒，缺省立即）。
+ *
+ * 音效是「一次性触发 + 可停止」的通道：`se` 每次触发独立叠放，
+ * 本命令停掉当前在播的全部音效（已淡出完成的不受影响）。
+ */
+export function stopSe(opts?: StopOptions): CommandOf<"stop_se"> {
+  return { op: "stop_se", ...opts };
+}
+
+/** `audio_play` 的可选项：音量、循环、淡入毫秒、显式重播 */
+export type AudioPlayOptions = Omit<
+  CommandOf<"audio_play">,
+  "op" | "inst" | "channel" | "resource"
+>;
+
+/** `audio_stop` 的可选项：目标实例（省略 = 停全部）、淡出毫秒 */
+export type AudioStopOptions = Omit<CommandOf<"audio_stop">, "op">;
+
+/**
+ * 起播（或更新）一个**音频实例**：按名字点名的独立音轨，与四通道并存。
+ *
+ * - `channel` 决定偏好归口（BGM 的音量偏好管 bgm 实例，音效的管 se 实例）。
+ * - 同实例重复起播：同资源 = 更新（保留位置），换资源或 `restart: true` = 重播。
+ * - 与 {@link bgm} / {@link se} 的区别：通道是「叙事语义上的那一路声音」
+ *   （各一条、随存档走），实例是「作者点名的编排单元」（可多个、各自独立叠放）。
+ *
+ * @param inst 实例 id（小写字母开头的短 id，1..32 位）。
+ * @param channel 归属通道：`bgm` / `se` / `ambient` / `voice`。
+ * @param resource 音频资源路径。
+ * @param opts 可选项，见 {@link AudioPlayOptions}。
+ * @returns `audio_play` 故事命令。
+ * @example
+ * audioPlay("rain", "ambient", "audio/rain.ogg", { volume: 0.3 });
+ * audioVolume("rain", 0.6);
+ */
+export function audioPlay(
+  inst: string,
+  channel: "bgm" | "se" | "ambient" | "voice",
+  resource: string,
+  opts?: AudioPlayOptions,
+): CommandOf<"audio_play"> {
+  return { op: "audio_play", inst, channel, resource, ...opts };
+}
+
+/**
+ * 停止音频实例：给了 `inst` 只停那一轨，省略则停掉当前全部实例。
+ * @param inst 目标实例 id（省略 = 停全部）。
+ * @param opts 可选项：淡出毫秒。
+ * @returns `audio_stop` 故事命令。
+ */
+export function audioStop(
+  inst?: string,
+  opts?: AudioStopOptions,
+): CommandOf<"audio_stop"> {
+  return {
+    op: "audio_stop",
+    ...(inst === undefined ? {} : { inst }),
+    ...opts,
+  };
+}
+
+/**
+ * 只改一个音频实例的音量：不动播放位置、不重播。
+ *
+ * 这是「实时调音」的正规入口——拖动滑块时不要用 {@link audioPlay} 重发，
+ * 那会重设位置并打断淡入。
+ *
+ * @param inst 目标实例 id。
+ * @param volume 音量（0–1）。
+ * @returns `audio_volume` 故事命令。
+ */
+export function audioVolume(
+  inst: string,
+  volume: number,
+): CommandOf<"audio_volume"> {
+  return { op: "audio_volume", inst, volume };
+}
+
+/** `audio_pause` / `audio_resume` 的可选项：目标通道（省略 = 全部常驻通道） */
+export type AudioPauseOptions = Omit<CommandOf<"audio_pause">, "op">;
+
+/**
+ * 暂停音频通道：保留播放器与播放位置，只是不出声；恢复从原位置继续。
+ *
+ * - 省略 `channel` = 全部常驻通道（`bgm` / `ambient` / `voice`）。
+ * - `se` 是一次性触发，暂停它没有可恢复的东西——显式传 `se` 不动作。
+ * - 只对正在播放的通道生效；已停止或从未播放的通道不受影响（连按两次只算一次）。
+ *
+ * @param opts 可选项，见 {@link AudioPauseOptions}。
+ * @returns `audio_pause` 故事命令。
+ * @example
+ * audioPause(); // 暂停全部常驻通道
+ * audioPause({ channel: "bgm" });
+ */
+export function audioPause(
+  opts?: AudioPauseOptions,
+): CommandOf<"audio_pause"> {
+  return { op: "audio_pause", ...opts };
+}
+
+/**
+ * 恢复被 {@link audioPause} 暂停的通道：从暂停位置续播，不从头播。
+ *
+ * 恢复用的是暂停前那个播放态（资源、音量、循环原样），因此不会重新起播、
+ * 也不会重设淡入。未处于暂停态的通道不动作。
+ *
+ * @param opts 可选项，见 {@link AudioPauseOptions}。
+ * @returns `audio_resume` 故事命令。
+ * @example
+ * audioResume(); // 恢复全部常驻通道
+ * audioResume({ channel: "ambient" });
+ */
+export function audioResume(
+  opts?: AudioPauseOptions,
+): CommandOf<"audio_resume"> {
+  return { op: "audio_resume", ...opts };
+}

package/src/script/words/cells.ts

@@ -1,7 +1,7 @@
 /**
  * Script 词汇层 · **具名实现槽位**（cell —— build-time 声明词）。
  *
- * cell 声明的实现由构建期扫描收集进生成注册物（`Stories.src/gen/fun_register.g.ts`）：
+ * cell 声明的实现由构建期扫描收集进生成注册物（`src/gen/fun_register.g.ts`）：
  * 故事 JSON 只留名字引用（guard 的 `fn` 字段），实现住生成模块——
  * 「名字在数据、实现在代码、build 做名字闭合」。
  *
@@ -31,7 +31,7 @@ export type KnownGuardName = keyof GuardNameRegistry extends never
   : keyof GuardNameRegistry & string;
 
 /**
- * 列名注册表（类型扩充点）：构建期生成的 `Stories.src/gen/stories.gen.d.ts`
+ * 列名注册表（类型扩充点）：构建期生成的 `src/gen/stories.gen.d.ts`
  * 往本接口塞进工程内每个列 id 的字面量键 ⇒ `jump("…")` 与 `option("…", "…")`
  * 的目标列名获得补全、写错即红。空表退化为普通 string。
  */

package/src/script/words/composite.ts

@@ -2,7 +2,7 @@
  * Script 词汇层 · **复合词**（多 op/元素的高频组合，纯展开）。
  * 复合词不产出新语义：每个函数 = 既有元素的语法糖。
  */
-import type { ElementNode } from "@lingfan-engine/core";
+import type { ElementNode, SceneType } from "@lingfan-engine/core";
 
 export interface ElementOptions {
   id?: string;
@@ -72,7 +72,7 @@ export function buttonElement(
  * @returns 背景与标题元素节点数组（可省略标题）。
  * @example
  * export default scene("square", () => ({
- *   type: "menu",
+ *   type: "ui",
  *   elements: [...sceneSetup("images/square.png", "城镇广场")],
  *   columns: { ... },
  * }));
@@ -117,9 +117,9 @@ export function sceneSetup(
 
 /**
  * 列的 `type` 字段（game 缺省不写——与序列化口径一致）。
- * @param type 列类型：menu（菜单列）或 ui（界面列）。
+ * @param type 列类型：`ui`（界面层：标题 / 设置 / 覆盖层 / 弹窗）。
  * @returns 带类型标记的对象，展开进列定义。
  */
-export function sceneType(type: "menu" | "ui"): { type: "menu" | "ui" } {
+export function sceneType(type: SceneType): { type: SceneType } {
   return { type };
 }

package/src/script/words/index.ts

@@ -1,7 +1,7 @@
 /**
  * Script 词汇层 · 词条实现（作者可用的 builder 与选项类型）。
  * 每个文件对应一族词条：叙事 / 流程 / 变量 / 存档 / 音频 / 视频 / 小游戏 /
- * 元素 / 复合词 / 扩展 / 具名实现槽位 / 交互。
+ * 元素 / 复合词 / 扩展 / 具名实现槽位 / 挂载 UI / 交互。
  * 各文件导出名互不重复，故此处整体转发；对外仍由 `script` 出口按族列出名单。
  *
  * 每个词条函数都是**纯数据构造**：只返回一条 `StoryCommand`（与 JSON 同族），
@@ -19,5 +19,6 @@ export * from "./interaction.ts";
 export * from "./minigame.ts";
 export * from "./narrative.ts";
 export * from "./save.ts";
+export * from "./ui.ts";
 export * from "./vars.ts";
 export * from "./video.ts";

package/src/script/words/narrative.ts

@@ -10,7 +10,7 @@ import type { KnownColumnName, KnownInterpolationKey } from "./cells.ts";
 // —— `{key}` 插值键的编译期校验（纯类型层，零运行期成本）——
 //
 // 只在**字符串字面量**上生效：模板串、变量、宽 string 全部放行（动态文本没法查，
-// 也不该吓唬作者）；键表来自生成物 `Stories.src/gen/stories.gen.d.ts`。
+// 也不该吓唬作者）；键表来自生成物 `src/gen/stories.gen.d.ts`。
 // 富文本行内标记必须豁免——`{b}`/`{color=#FFD700}` 这类与插值共用一个花括号语法，
 // 豁免表对齐引擎 `runtime/expr/interpolate.ts` 的行内标记集。
 type TrimText<S extends string> = S extends ` ${infer R}`
@@ -146,6 +146,31 @@ export function menu(
   };
 }
 
+/** 输入候选：显示文本 + 要填进变量的值（用 {@link inputCandidate} 构造） */
+export type InputCandidateSpec = NonNullable<CommandOf<"input">["options"]>[number];
+
+/**
+ * 构造一个输入候选，配合 {@link input} 使用：玩家点中它，`value` 就直接当输入值提交，
+ * 同时仍然可以自己打字。
+ *
+ * 与菜单的 {@link option} 不同——候选不跳列，只替玩家填一个值。
+ *
+ * @param text 候选上显示的文字（支持翻译；翻译只影响显示）。
+ * @param value 选中后写进 `store` 的原样值（**不进翻译表**，多语言下不变）。
+ * @returns 输入候选数据。
+ * @example
+ * input("你的身份是？", "role", [
+ *   inputCandidate("旅人", "traveler"),
+ *   inputCandidate("商人", "merchant"),
+ * ]);
+ */
+export function inputCandidate(
+  text: string,
+  value: string,
+): InputCandidateSpec {
+  return { text, value };
+}
+
 /**
  * 向玩家要一段文字：弹出输入框显示 `prompt`，玩家提交后，输入内容写进
  * 状态键 `store`，故事从下一句继续。
@@ -154,13 +179,30 @@ export function menu(
  *
  * @param prompt 输入框上方显示的问题/提示语（必填非空）。
  * @param store 收纳玩家输入的状态变量名（写进全局状态，之后可用 `{store}` 插值显示）。
+ * @param options 候选快捷值（可选）：给了就在输入框旁列出，玩家点一项即提交该项的 `value`，
+ *   也可以不理候选自己打字。用 {@link inputCandidate} 构造。
  * @returns `input` 故事命令。
  * @example
  * input("主角叫什么名字？", "playerName");
  * say("你好，{playerName}！");
+ * @example
+ * // 带候选：既能点，也能自己打
+ * input("你的身份是？", "role", [
+ *   inputCandidate("旅人", "traveler"),
+ *   inputCandidate("商人", "merchant"),
+ * ]);
  */
-export function input(prompt: string, store: string): CommandOf<"input"> {
-  return { op: "input", prompt, store };
+export function input(
+  prompt: string,
+  store: string,
+  options?: readonly InputCandidateSpec[],
+): CommandOf<"input"> {
+  return {
+    op: "input",
+    prompt,
+    store,
+    ...(options === undefined ? {} : { options: [...options] }),
+  };
 }
 
 /** type 保持手写的窄联合（schema 是 string）——作者侧补全优于校验面放宽 */

package/src/script/words/ui.ts

@@ -0,0 +1,64 @@
+/**
+ * Script 词汇层 · **挂载 UI**（ui）。
+ *
+ * 故事源用一行 import 拿到一个 UI 的句柄：
+ *
+ * ```ts
+ * import hub from "../../ui/hub/hub.vue";
+ * mount(hub, true);
+ * ```
+ *
+ * 句柄在编译期就退化成一个名字（`"hub"`），运行期没有对象、没有文件加载——
+ * 这正是「静态声明」的含义：写 import 只是告诉编译器「这一列会挂哪个 UI」，
+ * 真正把 UI 挂上舞台是 `mount` op 在运行期做的事。
+ *
+ * 本文件是 `UiHandle` 的**唯一声明处**；`@lingfan-engine/stories-build/authoring`
+ * 只做类型转发，所以故事源不需要额外的 tsconfig 配置就能拿到同一份形状。
+ */
+import type { CommandOf } from "../../schema/index.ts";
+
+export interface UiHandle<N extends string = string> {
+  readonly face: "uis";
+  readonly name: N;
+}
+
+/**
+ * UI 名注册表（类型扩充点）：生成物 `src/gen/ui_register.g.ts` 尾部
+ * `declare module "@lingfan-engine/editor"` 往本接口塞进每个 UI 名的字面量键 ⇒
+ * {@link mount} 的名字参数获得补全与写错即红。空表退化为普通 string。
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type -- 类型扩充点：只有接口可被生成物 declare module 合并（type 别名不能），空体是有意形态
+export interface UiNameRegistry {}
+
+/** 已声明 UI 名（有声明 = 字面量联合；空 = string） */
+export type KnownUiName = keyof UiNameRegistry extends never
+  ? string
+  : keyof UiNameRegistry & string;
+
+/**
+ * 挂载 / 卸载一个 UI 组件：`mount(hub, true)`、`mount(hub, false)`、
+ * `mount(map, true, { scene: "forest" })`。
+ *
+ * 状态写进 `SYS.mounts`，随快照 / 存档 / 回溯自动随行；宿主按这张表决定
+ * 渲染树上有哪些组件。**隐藏 = 从渲染树移除**（卸载组件），不是 `display: none`。
+ *
+ * @param handle UI 句柄（`import hub from "…/hub.vue"`）或其名字字符串。
+ * @param visible 是否挂载。必填：没有「切换」写法，显隐写死才能让回溯读到确定的终值。
+ * @param props 传给组件的入参（JSON 安全）。给了就**整份替换**，不与上一次合并——
+ *   组件的入参集合是它的契约，得能完整指定（含「删掉一个入参」）。
+ * @returns `mount` 故事命令。
+ * @example
+ * import hub from "../../ui/hub/hub.vue";
+ * mount(hub, true);
+ * mount(hub, false);
+ */
+export function mount<const N extends string>(
+  handle: UiHandle<N> | KnownUiName,
+  visible: boolean,
+  props?: Readonly<Record<string, unknown>>,
+): CommandOf<"mount"> {
+  const name = typeof handle === "string" ? handle : handle.name;
+  const cmd: CommandOf<"mount"> = { op: "mount", name, visible };
+  if (props !== undefined) cmd.props = { ...props };
+  return cmd;
+}

package/src/shared/guards.ts

@@ -1,19 +1,12 @@
 /**
- * 通用取值判据：编辑器包多个域（诊断、i18n、布局）都要对「这个值是不是一条记录」下判断。
+ * 通用取值判据的**转发口**：编辑器包多个域（诊断、i18n、布局）都要对「这个值是不是一条记录」下判断。
  *
- * 为什么放在共享层：判据本身不含业务含义，任何层都可以引用；而它一旦分叉，
- * 分叉点就是静默的行为差异——同一棵树，两处判定不同就会出现「这边认、那边不认」。
- * 所以编辑器包只有这一处实现，缺人少写一个 `!Array.isArray` 就是症状的来源。
- */
-
-/**
- * 是否是**普通对象**（JSON 意义上的记录）：`null` 与数组都不算。
+ * **实现只有一处**，在引擎包 `packages/core/src/shared/guards.ts`（经 `@lingfan-engine/core`
+ * 包出口公开，链路由 `core/src/index.ts` → `core/src/contracts/index.ts` → `core/src/shared/index.ts`
+ * 三级转发构成）。此处只做转发，不持有实现体。
  *
- * 关键在最后那个 `!Array.isArray`：数组也是 `typeof === "object"`，
- * 少了它就会让数组通过「记录」校验，下游会拿下标当字段名继续走。
+ * 为什么不在这里留第二份实现：判据本身不含业务含义，任何层都可以引用；而它一旦分叉，
+ * 分叉点就是静默的行为差异——同一棵树，两处判定不同就会出现「这边认、那边不认」。
+ * 缺人少写一个 `!Array.isArray` 就是症状的来源。
  */
-export function isPlainObject(
-  value: unknown,
-): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
+export { isPlainObject } from "@lingfan-engine/core";