@lingfan-engine/core 0.1.5 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lingfan-engine/core",
-  "version": "0.1.5",
+  "version": "0.3.0",
   "type": "module",
   "description": "灵泛叙事引擎核心：框架无关的叙事语义（格式/执行/回溯/作用域/存档编排）",
   "license": "Apache-2.0",

package/src/contracts/guard.ts

@@ -4,6 +4,7 @@
  * 这些形状被跨包消费（编辑器扩展出口、UI 覆盖层、宿主组合根、生成的故事代码），
  * 且本身不依赖引擎实现，故与其它契约同住契约层；引擎实现只按契约读取它们。
  */
+import type { AudioConfig } from "./shell.ts";
 import type { OpExtension } from "./extension.ts";
 import type { MinigameRegistration } from "./minigame.ts";
 import type { SaveDataV1, SaveMode, SavePort } from "./save.ts";
@@ -21,6 +22,14 @@ export interface EngineOptions {
   savePort?: SavePort;
   /** 存档模式（缺省 machine-bound；与 Rust 层同缺省） */
   saveMode?: SaveMode;
+  /**
+   * 工程默认音量（`project.json` 的 `shell.audio`，宿主经 `resolveAudioConfig` 解析后注入）。
+   *
+   * 它是音量的**第二级**：命令没写 `volume=` 时取这里，再没有才是内建 1。
+   * 缺省 = 四通道皆 1（与「不指定 = 满音量」的既有行为逐字节一致）。
+   * 玩家偏好不在这一层——偏好是渲染层最外层的乘算。
+   */
+  audioConfig?: AudioConfig;
   /** 译文供给端口（setLanguage 按需加载译文；缺省 = 原文直出） */
   i18nPort?: I18nPort;
   /**

package/src/contracts/index.ts

@@ -11,6 +11,7 @@ export * from "./shell.ts";
 export * from "./element.ts";
 export * from "./extension.ts";
 export * from "./game.ts";
+export * from "./param-direction.ts";
 export * from "./guard.ts";
 export * from "./messages.ts";
 export * from "./text.ts";

package/src/contracts/media/entities.ts

@@ -4,13 +4,42 @@
  *
  * 端口（播放器要实现的方法集合）见同目录 `ports.ts`。
  */
+import { SHORT_ID_PATTERN } from "../identifiers.ts";
 
 /** 四通道：bgm 循环 / se 一次性 / ambient 独立循环层 / voice 互斥 */
 export type AudioChannel = "bgm" | "se" | "ambient" | "voice";
 
 /**
- * 通道状态（SSOT 系统键值）：play = 播放或续播，stop = 停止（fadeMs 淡出）；null = 从未触碰。
- * `stop` 独立成形态，避免用哨兵资源名承载「停止」而丢失淡出参数。
+ * 通道全集（顺序即偏好表的书写顺序）。
+ *
+ * 唯一声明处：解析工程默认音量、判通道合法性、渲染层逐通道取状态都读它，
+ * 各处不得自建同名数组——多一份就多一个「新增通道时漏改」的位置。
+ */
+export const AUDIO_CHANNELS: readonly AudioChannel[] = [
+  "bgm",
+  "se",
+  "ambient",
+  "voice",
+];
+
+/**
+ * 常驻通道：跨命令持续存在的三条。
+ *
+ * `se` 是一次性音效，播完即弃——它没有「暂停后从原位置续播」的语义，因此不在其中。
+ * 「不指定通道就作用于全部常驻通道」这类批量语义（引擎的 `audio_pause` 不带通道、
+ * 宿主控制面的整局暂停与恢复）都读这张表，不各自写字面量。
+ */
+export const PERSISTENT_AUDIO_CHANNELS: readonly AudioChannel[] = [
+  "bgm",
+  "ambient",
+  "voice",
+];
+
+/**
+ * 通道状态（SSOT 系统键值）：play = 播放或续播，pause = 暂停（保留播放器与位置、不出声），
+ * stop = 停止（fadeMs 淡出）；null = 从未触碰。
+ * `stop` 独立成形态，避免用哨兵资源名承载「停止」而丢失淡出参数；
+ * `pause` 同样独立成形态——暂停不是「音量归零」，恢复时必须从原位置续播而不是从头播。
  */
 export type AudioChannelState =
   | {
@@ -31,7 +60,60 @@ export type AudioChannelState =
        */
       seq?: number;
     }
-  | { kind: "stop"; fadeMs: number };
+  | {
+      /**
+       * 暂停：不带资源，与视频命令的 `{ kind: "pause"; seq }` 同构。
+       * 恢复时由渲染层回到暂停前的位置续播，故这里不记位置（位置在播放器里）。
+       */
+      kind: "pause";
+      seq?: number;
+    }
+  | {
+      kind: "stop";
+      fadeMs: number;
+      /**
+       * 停止请求的单调序号（仅 `se` 写入，不进快照）：
+       * `se` 是「一次性触发 + 可停止」的通道，连续两次 `stop_se` 也必须是两次独立事件，
+       * 否则渲染层无法分辨「又停了一次」与「状态没变」。
+       */
+      seq?: number;
+    };
+
+/**
+ * 音频实例的 id 形态：与扩展 / 玩法系统的短 id 同源（同一份 `SHORT_ID_PATTERN`）。
+ *
+ * 作者要在故事里按名字点名实例（`audio_play inst="rain"`），所以 id 也是契约的一部分；
+ * 另写一条正则会立刻与短 id 分叉，故这里只是**别名**，改一处即三处生效。
+ */
+export const AUDIO_INSTANCE_ID_PATTERN = SHORT_ID_PATTERN;
+
+/**
+ * 同时存活的音频实例上限。
+ *
+ * 整张表是一个状态值 ⇒ 每加一个实例都进快照、进存档。上限不是为了省内存
+ * （真实瓶颈在解码器那边），而是为了让「存档体积」这件事有界：没有上限时
+ * 一个循环里的 `audio_play` 能把存档撑到无法写盘，而那种错发现得太晚。
+ */
+export const MAX_AUDIO_INSTANCES = 32;
+
+/**
+ * 单个音频实例的状态：**归属哪条通道** + 与通道键同构的播放状态。
+ *
+ * 为什么要记 `channel`：音量偏好是按通道分的（BGM 0.8 / 音效 0.6 …），
+ * 不记归属就没法把偏好乘到实例上，作者也只能靠命名猜。
+ */
+export interface AudioInstanceState {
+  readonly channel: AudioChannel;
+  readonly state: AudioChannelState;
+}
+
+/**
+ * 音频实例表（SSOT 系统键 `__audio_instances` 的值）：实例 id → 状态。
+ *
+ * **写时复制**：整表是一个值，改写时必须新建对象而不是原地改字段——快照与存档
+ * 持有的是同一个引用的历史版本，原地改会让回溯拿到被污染的值。
+ */
+export type AudioInstanceTable = Readonly<Record<string, AudioInstanceState>>;
 
 /** 音频播放参数（端口入参，核心不碰解码器） */
 export interface AudioPlayOptions {

package/src/contracts/media/ports.ts

@@ -12,9 +12,52 @@ import type { AudioChannel, AudioPlayOptions } from "./entities.ts";
 export interface AudioPort {
   play(channel: AudioChannel, url: string, options: AudioPlayOptions): void;
   stop(channel: AudioChannel, fadeMs?: number): void;
+  /**
+   * 暂停通道：保留播放器实例与播放位置，只是不出声。
+   * 通道已停止或从未播放时空操作（不建实例、不改状态）。
+   */
+  pause(channel: AudioChannel): void;
+  /**
+   * 从暂停位置继续播放；未暂停的空操作。
+   * 与 `play` 的区别：不从起点重播、不重建实例。
+   */
+  resume(channel: AudioChannel): void;
   /** 当前播放位置（秒）；未播放返回 0（帧级回写用） */
   position(channel: AudioChannel): number;
   dispose(): void;
+
+  // —— 实例维度（可选能力）——
+  // 四通道是叙事语义，实例是作者的编排单元：两者并存，不是替换。
+  // 三个方法都是**可选**的：老适配器不实现即退化为「实例不发声」，
+  // 调用方用 `?.` 容错并上报一次诊断——不能因为端口没跟上就整段卡住。
+
+  /**
+   * 起播一个实例（`instanceId` 由作者在故事里命名）。
+   *
+   * 与 `play` 的三点差别：入参第一维不是通道（归属通道在状态里，供偏好分档）、
+   * 同一 id 重复起播是「更新」而非叠放、不同 id 各自独立可叠放。
+   */
+  playInstance?(
+    instanceId: string,
+    url: string,
+    options: AudioPlayOptions,
+  ): void;
+  /** 停掉一个实例；`fadeMs` 为淡出毫秒 */
+  stopInstance?(instanceId: string, fadeMs?: number): void;
+  /**
+   * 运行期改一个实例的音量（0..1），**不重播**。
+   *
+   * 专为「拖滑块实时生效」而设：走 `playInstance` 重发也能改音量，
+   * 但那会重设位置、打断正在放的淡入。未实现的适配器只能靠下一次起播生效。
+   */
+  setVolumeInstance?(instanceId: string, volume: number): void;
+  /**
+   * 暂停一个实例：保留播放器与位置，不出声。
+   * 可选能力：未实现者由调用方按整通道 `pause` 降级。
+   */
+  pauseInstance?(instanceId: string): void;
+  /** 从暂停位置继续一个实例；未暂停的空操作。可选能力，同 `pauseInstance`。 */
+  resumeInstance?(instanceId: string): void;
 }
 
 // —— 视频（单通道命令流）：新 video 替换当前；Desktop/Mobile 同契约 ——
@@ -41,4 +84,9 @@ export interface VideoPort {
    * 可选能力：未实现者保持构造期 `zIndex` 行为（调用方用 `?.` 容错）。
    */
   setZIndex?(z: number): void;
+  /**
+   * 运行期改音量（0..1）：偏好滑块拖动时宿主用它，**不重播**——重播会打断过场。
+   * 可选能力：未实现者只能靠下一次 `play` 生效（调用方用 `?.` 容错）。
+   */
+  setVolume?(volume: number): void;
 }

package/src/contracts/param-direction.ts

@@ -0,0 +1,103 @@
+/**
+ * 参数方向档位：谁能写某个状态键。
+ *
+ * **为什么需要这张表**：状态键一律是「一个键 + 一个值」，看不出「宿主能不能改它」。
+ * 结果是「宿主可写」靠口头约定维持——新加一个键时没人知道该不该给写权限，
+ * 而给错了不是小事：`__waiting` 若能写，宿主就能伪造等待态绕过等待状态机；
+ * `__audio_*` 若能直写，就绕过了音量偏好乘算。
+ *
+ * **本表只声明，不实现**。写路径仍归各域既有接缝（`GameStateWriter` / `setVolume` / 命令面）；
+ * 物理闸仍是 `RESERVED_STATE_KEYS`（保留键一律拒直写）。表的作用是让「谁该能写」
+ * 可查、可测、可守——测试据此断言「声明与能力一致」。
+ *
+ * **缺省只读**（fail-closed）：表里没有的键一律 `readonly`。新键默认不给写权限，
+ * 要开放必须显式登记——与「白名单优于黑名单」同一条纪律。
+ */
+import { SYS } from "./runtime/state-keys.ts";
+
+/**
+ * 方向档位：
+ * - `readonly`：引擎独占。宿主读得到，写不生效（直写命中保留键即 fail-closed）
+ * - `write`：单向。宿主可写，引擎不主动改（如外部玩法系统状态）
+ * - `two-way`：双向。引擎写、宿主也可写，冲突按各域既有优先级解析
+ */
+export type ParamDirection = "readonly" | "write" | "two-way";
+
+/**
+ * 键 → 档位。
+ *
+ * 键可以是**精确系统键**（`__waiting`）、**命名空间前缀**（`game.` / `preferences.`）。
+ * 查表走 `runtime/paramDirection.ts` 的 `directionOf`：精确键优先，其次最长前缀，都不命中即 `readonly`。
+ *
+ * 登记纪律：声明为 `two-way` 的系统键**必须有一条专用接缝**（否则声明与实际能力脱节，
+ * 由测试 `param-direction` 锁住）；新增 `SYS` 键时若忘登记，测试会报「未声明方向的系统键」。
+ *
+ * **查表函数不在本文件**：契约层只放类型与数据（本层出现函数声明即违约，
+ * 由 `tests/engine/runtime/scene-type.test.ts` 锁住），实现落在 `runtime/paramDirection.ts`。
+ */
+export const PARAM_DIRECTION: Readonly<Record<string, ParamDirection>> = {
+  // —— 只读：宿主读得到、写不生效（等待状态机与舞台事实归引擎）——
+  [SYS.waiting]: "readonly",
+  [SYS.currentSceneColumn]: "readonly",
+  [SYS.menuPrompt]: "readonly",
+  [SYS.menuOptions]: "readonly",
+  [SYS.menuTargets]: "readonly",
+  [SYS.menuSelected]: "readonly",
+  [SYS.inputPrompt]: "readonly",
+  [SYS.inputOptions]: "readonly",
+  [SYS.currentDialogText]: "readonly",
+  [SYS.currentDialogSpeaker]: "readonly",
+  [SYS.currentDialogColor]: "readonly",
+  [SYS.dialogFont]: "readonly",
+  [SYS.dialogTemplate]: "readonly",
+  [SYS.dialogComplete]: "readonly",
+  [SYS.dialogClickable]: "readonly",
+  [SYS.dialogNoskip]: "readonly",
+  [SYS.dialogVisible]: "readonly",
+  [SYS.elements]: "readonly",
+  [SYS.animations]: "readonly",
+  [SYS.transition]: "readonly",
+  [SYS.shake]: "readonly",
+  [SYS.video]: "readonly",
+  [SYS.videoSkipable]: "readonly",
+  [SYS.nvlMode]: "readonly",
+  [SYS.nvlBuffer]: "readonly",
+  [SYS.rollbackActive]: "readonly",
+  [SYS.currentLanguage]: "readonly",
+  [SYS.autoSave]: "readonly",
+  [SYS.menuReturn]: "readonly",
+  /** 引擎级暂停标记：只由命令面 `pause()` / `resume()` 写，宿主只读 */
+  [SYS.paused]: "readonly",
+  [SYS.minigame]: "readonly",
+  [SYS.interaction]: "readonly",
+  [SYS.typewriter]: "readonly",
+  /** 实例级 z：命令写、宿主按它解析后下发（宿主不改这个值本身） */
+  [SYS.dialogueZ]: "readonly",
+  [SYS.choicesZ]: "readonly",
+  [SYS.notificationsZ]: "readonly",
+  [SYS.minigameZ]: "readonly",
+  [SYS.interactionZ]: "readonly",
+  [SYS.videoZ]: "readonly",
+
+  // —— 单向：宿主写，引擎不主动改 ——
+  /** 外部玩法系统 / 扩展的状态命名空间（写入经 `GameStateWriter` / `ExtensionContext`） */
+  "game.": "write",
+  "ext.": "write",
+
+  // —— 双向：引擎写、宿主可写（各有专用接缝）——
+  /** 玩家偏好：引擎读、宿主写（`PlayerPreferences.setVolume` 等），变化触发渲染层重规划 */
+  "preferences.": "two-way",
+  /** 音频四通道：命令写状态、偏好层再乘算；专用接缝 = 命令面 + `PlayerPreferences` */
+  [SYS.audioBgm]: "two-way",
+  [SYS.audioSe]: "two-way",
+  [SYS.audioAmbient]: "two-way",
+  [SYS.audioVoice]: "two-way",
+  /** 音频实例表：命令写、宿主可按 id 改音量；专用接缝 = 实例命令面 */
+  [SYS.audioInstances]: "two-way",
+  /** 背景乐播放位置：引擎回写、宿主可定位（读档后对齐） */
+  [SYS.bgmPosition]: "two-way",
+  /** 暂停前播放态记账：命令写、`audio_resume` 读回；专用接缝 = `audio_pause` / `audio_resume` */
+  [SYS.audioPaused]: "two-way",
+  /** 挂载 UI 表：命令写显隐与入参、宿主读后挂载/卸载组件；专用接缝 = `mount` op */
+  [SYS.mounts]: "two-way",
+};

package/src/contracts/runtime/column-summary.ts

@@ -0,0 +1,24 @@
+/**
+ * 列摘要：宿主看故事时能看到的那部分列信息。
+ *
+ * **为什么只给这三个字段**：宿主需要的是「有哪些列、各是什么类型、当前在哪列」——
+ * 用来列章节、判当前页、决定跳哪。列里的 `commands` / `elements` / `entry` 归引擎，
+ * 宿主拿到它们只会诱使自己绕过引擎去解释命令流（两套解释器必然漂移）。
+ *
+ * **只读**：字段全部 `readonly`，且引擎给出的实例是冻结的——摘要是引擎状态的镜像，
+ * 不是可写副本。要改列内容走故事文件与热重载，不从这里改。
+ *
+ * 与 `StoryColumn` 的关系：这是它的**投影**，不是精简版故事树。`type` 在这里是
+ * 归一后的值（缺省 `game`），宿主因此不必自己处理「没写 type 算哪种」。
+ */
+import type { SceneType } from "../story/index.ts";
+
+/** 单列的只读摘要：id、归一后的运行语义类型、内容形态 */
+export interface ColumnSummary {
+  /** 列 id（故事内唯一；跳转与当前列判定都用它） */
+  readonly id: string;
+  /** 运行语义类型（**已归一**：`type` 缺省或非法时取 `game`） */
+  readonly type: SceneType;
+  /** 内容形态：`scene` = 空间层（元素 + 入口命令）/ `flow` = 纯流程 */
+  readonly kind: "scene" | "flow";
+}

package/src/contracts/runtime/controls.ts

@@ -0,0 +1,49 @@
+/**
+ * 宿主控制面：宿主与游戏内挂载 UI 操作引擎的**收窄**通道。
+ *
+ * 它不是 `StoryEngine` 的别名——引擎有几十个公开方法，其中大半是「引擎内部推进
+ * 时顺手通知」的接缝（`animationFinished` / `choose` / `rollbackTo` …），跨形态也
+ * 带不进挂载层；这里只留「菜单需要的那几件事」：暂停与恢复、换栏、存读、收摊。
+ *
+ * 与 `props` 是两条不同的通道，别混：
+ * - `props` 来自故事命令的第三参数（`mount(hub, true, {scene: "forest"})`），落在
+ *   `SYS.mounts` 里，随快照存档与回溯，因此**必须 JSON 安全**——函数进不去；
+ * - `controls` 来自组合根，不进 SSOT、不进快照、运行期注入，**可以带函数**。
+ *
+ * 组件两样都拿得到：值走 `props`，操作走 `controls`。
+ */
+import type { AudioChannel } from "../media/entities.ts";
+import type { SaveOptions } from "../save.ts";
+
+/** 宿主控制面：菜单与挂载 UI 共用的操作集合（两条路实现零差异） */
+export interface HostControls {
+  /** 暂停整局：推进、等待计时、音频与视频同停；幂等 */
+  pause(): void;
+  /** 恢复整局：回到暂停前的位置继续；幂等 */
+  resume(): void;
+  /** 当前是否处于暂停态 */
+  paused(): boolean;
+  /**
+   * 暂停媒体；不传通道即全部常驻通道 + 视频。
+   *
+   * `se` 是一次性音效，没有「暂停后从原位置续播」的语义——引擎侧同样不动作，
+   * 这里显式跳过而不是交给端口各自决定。
+   */
+  pauseMedia(channel?: AudioChannel): void;
+  /** 恢复媒体；参数口径同 {@link HostControls.pauseMedia} */
+  resumeMedia(channel?: AudioChannel): void;
+  /** 跳到某一栏（与 `menu` 的选项同义：栏 id） */
+  navigate(columnId: string): void;
+  /**
+   * 存档到某个槽位。
+   *
+   * `options.title` 是玩家给这一档起的名字，写进 `SaveDataV1.title`，槽位列表据此
+   * 显示；不传就是无名档（列表只显示槽位号）。缩略图同理走 `options.screenshot`，
+   * 由宿主合成后交给引擎——截图策略归宿主，引擎只负责把它存进档里。
+   */
+  save(slot: string, options?: SaveOptions): void;
+  /** 从某个槽位读档 */
+  load(slot: string): void;
+  /** 拆掉宿主（等同宿主句柄的拆除；由持有者负责只调一次） */
+  dispose(): void;
+}

package/src/contracts/runtime/entities.ts

@@ -18,6 +18,27 @@ export type WaitingState =
 /** NVL 模式（`__nvl_mode` 取值）：累积层开关与清屏动作 */
 export type NvlMode = "none" | "active" | "clear" | "exit";
 
+/**
+ * 一条挂载记录：某个 UI 组件该不该出现在渲染树上、带什么入参。
+ *
+ * `visible: false` 的语义是**从渲染树移除**（卸载组件），不是 `display: none`——
+ * 隐藏的组件不该继续跑生命周期、计时器与副作用。
+ */
+export interface MountEntry {
+  /** 是否挂在渲染树上 */
+  visible: boolean;
+  /** 传给组件的入参（JSON 安全；缺省 = 空对象） */
+  props: Record<string, unknown>;
+}
+
+/**
+ * 挂载表（`__mounts` 取值）：UI 名 → 挂载记录。
+ *
+ * 核心只认识名字与显隐，不认识组件内部；整表一个值 ⇒ 快照 / 存档 / 回溯零特判随行。
+ * 写时整表新建（写时复制），原地改会与快照共享引用。
+ */
+export type MountTable = Readonly<Record<string, MountEntry>>;
+
 /** 角色定义（character op 注册；say speaker 匹配自动套样式） */
 export interface CharacterDef {
   key: string;

package/src/contracts/runtime/index.ts

@@ -5,4 +5,6 @@ export * from "./events.ts";
 export * from "./state-keys.ts";
 export * from "./entities.ts";
 export * from "./reader.ts";
+export * from "./column-summary.ts";
 export * from "./timer.ts";
+export * from "./controls.ts";

package/src/contracts/runtime/reader.ts

@@ -21,15 +21,28 @@ import type {
   VideoCommand,
 } from "../media/index.ts";
 import type { LayerZOverrides } from "../shell.ts";
+import type { SceneType } from "../story/index.ts";
+import type { ColumnSummary } from "./column-summary.ts";
 
 /**
  * 取值来源：任何能按键读状态的对象都满足。
  *
- * 只要求这一个方法是有意为之——引擎实例满足它，测试替身、只读快照、状态代理也满足，
+ * 只要求 `get` 是有意为之——引擎实例满足它，测试替身、只读快照、状态代理也满足，
  * 于是读口不必依赖 `StoryEngine` 的全部能力，凡是「能读」的地方都能复用同一份校验。
  */
 export interface StateSource {
   get(key: string): unknown;
+  /**
+   * 可选：列清单读数（引擎实例天然满足）。
+   *
+   * **为什么读口需要它**：`currentColumnType()` 要由「当前列 id」查「列类型」，
+   * 而状态里只存 id，不存类型——类型是故事定义的一部分。不提供它时读口退回缺省
+   * `game`，不会抛错：读口只承诺「不撒谎」，不承诺「总能知道」。
+   *
+   * 提供者必须给出**已归一**的 `type`（见 `ColumnSummary`），读口不再自己判一遍，
+   * 否则缺省口径就有两份。
+   */
+  columns?(): readonly ColumnSummary[];
 }
 
 /** 菜单选项：文本与目标列成对（数组顺序即呈现顺序） */
@@ -38,6 +51,17 @@ export interface MenuChoice {
   target: string;
 }
 
+/**
+ * 输入候选：显示文本与要填进变量的值成对（数组顺序即呈现顺序）。
+ *
+ * 与 `MenuChoice` 分开定义：候选是「替玩家填一个值」，不是「跳到另一列」，
+ * 字段名不同是刻意的——把两者混用会在多语言环境下把译文写进变量。
+ */
+export interface InputCandidate {
+  text: string;
+  value: string;
+}
+
 /**
  * 类型化读口：按用途分组读状态。
  *
@@ -53,6 +77,8 @@ export interface StateReader {
   videoCommand(): VideoCommand | null;
   /** 菜单选项（文本与目标列成对；两键分属不同状态条目，任一畸形都按空处理） */
   menuChoices(): MenuChoice[];
+  /** 输入候选（显示文本与要填的值成对；缺省或形状不合 = 空数组，界面只渲染输入框） */
+  inputCandidates(): InputCandidate[];
   /** 当前说话人（缺省空串） */
   dialogSpeaker(): string;
   /** 当前正文（缺省空串） */
@@ -79,4 +105,18 @@ export interface StateReader {
   elements(): ElementInstance[];
   /** 实例级 z 覆盖：只含显式指定过的层（缺省 = 层默认） */
   instanceZOverrides(): LayerZOverrides;
+  /**
+   * 当前所在列 id（**缺省空串** = 尚未进入任何列，或状态被改坏）。
+   *
+   * 空串是「还没有位置」而不是某个真实列：跳转与高亮请按空串当「无当前位置」处理。
+   */
+  currentColumnId(): string;
+  /**
+   * 当前所在列的类型（**缺省 `game`**）。
+   *
+   * 与「可回溯判定」同源：启动期没有当前列时按 `game` 算，与引擎对启动期的既有口径一致；
+   * 当前列 id 在列清单里找不到（热重载后坐标失效等）同样按 `game`。
+   * 读口不知道列清单（`StateSource.columns` 未提供）时也只能给 `game`——它不猜。
+   */
+  currentColumnType(): SceneType;
 }

package/src/contracts/runtime/state-keys.ts

@@ -36,6 +36,14 @@ export const SYS = {
   menuTargets: "__menu_targets",
   menuSelected: "__menu_selected",
   inputPrompt: "__input_prompt",
+  /**
+   * 输入等待的**候选快捷值**（`input options=[…]` 写入）：`{ text, value }[]`。
+   *
+   * 语义：玩家既可以点候选（把该项 `value` 直接当输入值提交），也可以自己打字。
+   * 与 `menuOptions` 分开存，因为两者字段不同（候选是「替玩家填值」不是「跳列」），
+   * 混用一个键会让读口无法判断该按哪种形状解析。缺省 = 无候选。
+   */
+  inputOptions: "__input_options",
   rollbackActive: "__rollback_active",
   /** I18N 当前语言（setLanguage 命令写入，空串 = 默认语言/原文直出） */
   currentLanguage: "__current_language",
@@ -50,10 +58,18 @@ export const SYS = {
    * **用途：在菜单里按存档，存的是「菜单前的游戏进度」**。值形如
    * `{ coord: {columnId, index}, waiting: string }`，缺省 = 不在菜单中。
    *
-   * **不进快照的可见状态**：它是**引擎内部记账**，读取档不依赖它
-   * —— 档里存的坐标已经是菜单前那个。
+   * **属于会话态**（见 `SESSION_STATE_KEYS`）：进快照（回溯要用），
+   * **不进存档**——档里存的坐标已经是菜单前那个，带着它读档会让引擎
+   * 以为「仍在菜单里」。
    */
   menuReturn: "__menu_return",
+  /**
+   * 引擎级暂停标记（`pause()` 置真、`resume()` 清除）。
+   *
+   * **属于会话态**：进快照，**不进存档**——档里的进度就是暂停前那一刻，
+   * 带着它读档会让引擎一开局就停在暂停中（`advance` 直接 `pause-active`）。
+   */
+  paused: "__paused",
   /**
    * 实例级 z：单控件实例显式指定的层级（story 命令上的 `z`）。
    * 进 SSOT → 随快照 / 存档 / 回溯自动随行（重放到同一条命令即重新写入同一值）。
@@ -77,8 +93,31 @@ export const SYS = {
   audioSe: "__audio_se",
   audioAmbient: "__audio_ambient",
   audioVoice: "__audio_voice",
+  /**
+   * 音频实例表：`instanceId → { channel, state }`，与上面四个通道键**并存**。
+   *
+   * 四通道是叙事语义（这段是 BGM / 这句是语音），必须有默认值、随档、被偏好分档乘算；
+   * 实例是作者的编排需要（两段环境音交叉、三段音效各调各的），数量不定、名字作者起。
+   * 两者不是同一件事，所以实例另开一张表，不改四通道的任何形态。
+   *
+   * 整表是一个值 ⇒ 快照 / 存档 / 回溯零特判随行；**写时必须整表新建**（写时复制，
+   * 原地改会与快照共享引用，回溯后旧值被一起改掉）。
+   */
+  audioInstances: "__audio_instances",
   /** 帧级键：UI 每帧回写，不进事件流 */
   bgmPosition: "__bgm_position",
+  /**
+   * **暂停前的播放态记账**：`通道 → 被暂停的那个 play 态`。
+   *
+   * `pause` 态本身不带资源（资源与位置在端口的播放器实例里），而 `audio_resume`
+   * 要把通道写回「该出声」的形态就必须知道放的是什么——这份记账就是那个来源。
+   * 进 SSOT ⇒ 随快照 / 存档 / 回溯随行：读档到暂停期间仍能恢复，回溯到暂停前
+   * 则连记账一起回到未暂停。
+   *
+   * 只在 `audio_pause` 写入、`audio_resume` 消费并删除；通道被 `stop` / 重新
+   * `play` 覆盖时残留项无人读取（`audio_resume` 只认 `pause` 态的通道）。
+   */
+  audioPaused: "__audio_paused",
   // 视频命令流（单通道）：状态入 SSOT → 快照随行
   video: "__video",
   /** video_skipable op 的持久开关（后续 video/cutscene 的缺省 skipable） */
@@ -95,6 +134,19 @@ export const SYS = {
    * 列切换清空（空间层属于列），随快照/存档/回溯自动随行（整体 state Map 快照）。
    */
   elements: "__elements",
+  /**
+   * 挂载到宿主渲染树上的 UI 组件表（`mount` op 写入）：
+   * `Record<string, { visible: boolean; props: Record<string, unknown> }>`。
+   *
+   * 与 `elements` 不是同一件事：`elements` 是核心自己排布的舞台元素，带 animate /
+   * style / zindex 等表现字段，核心知道它们长什么样；`mounts` 只是「哪个 UI 组件该不该
+   * 出现在渲染树上、带什么入参」，核心不认识组件内部，也从不操作 DOM。
+   * `visible: false` 的语义是**从渲染树移除**（不是 `display: none`），宿主据此卸载组件。
+   *
+   * 整表是一个值 ⇒ 快照 / 存档 / 回溯零特判随行；**写时必须整表新建**（写时复制，
+   * 原地改会与快照共享引用，回溯后旧值被一起改掉）。
+   */
+  mounts: "__mounts",
   /**
    * `window auto|show|hide`：对话框显隐三态（UI 层据此控制对话层可见性；
    * 叙事语义归核心层，DOM 操作归 UI）。
@@ -125,3 +177,19 @@ export const SYS = {
 export const RESERVED_STATE_KEYS: ReadonlySet<string> = new Set(
   Object.values(SYS),
 );
+
+/**
+ * 会话态键：进快照（回溯要用），**不进存档**。
+ *
+ * 这些键描述的是「引擎此刻在干什么」而不是「故事进行到哪」——正停着、正停在菜单里、
+ * 正在重放。读档等于会话重开，带着它们会让引擎一开局就停在暂停中（`advance` 直接
+ * `pause-active`），或以为玩家仍在菜单里。
+ *
+ * 落点唯一：`runtime/save/export.ts` 的导出过滤（活状态与档内历史检查点都从这里过一遍）。
+ * 快照不经过滤——回溯要恢复的正是「当时的会话态」。
+ */
+export const SESSION_STATE_KEYS: ReadonlySet<string> = new Set([
+  SYS.paused,
+  SYS.menuReturn,
+  SYS.rollbackActive,
+]);

package/src/contracts/runtime/timer.ts

@@ -10,12 +10,19 @@
 /** 定时器句柄（不透明）：由 {@link TimerPort.set} 返回，只能交回 {@link TimerPort.clear} */
 export type TimerHandle = { readonly brand: unique symbol };
 
-/** 定时器端口：延迟回调 + 取消。实现方保证句柄不可跨实例混用。 */
+/** 定时器端口：延迟回调 + 取消 + 时刻。实现方保证句柄不可跨实例混用。 */
 export interface TimerPort {
   /** 安排 `ms` 毫秒后回调 `fn`；返回取消句柄 */
   set(fn: () => void, ms: number): TimerHandle;
   /** 取消已安排的回调；句柄已触发或已取消时为空操作 */
   clear(handle: TimerHandle): void;
+  /**
+   * 当前时刻（毫秒时间轴，只需单调不减）。
+   *
+   * 暂停要把「还剩多少毫秒」算出来，没有时刻就只能丢掉剩余量从头计。
+   * 可选：不提供时核心退回宿主时钟（`Date.now()`），无 JS 运行时的宿主自行注入。
+   */
+  now?(): number;
 }
 
 /**