@lingfan-engine/core 0.1.5 → 0.3.0

package/src/runtime/session/pause.ts

@@ -0,0 +1,114 @@
+/**
+ * 引擎级暂停与恢复：把「停住」与「中断」分成两件事。
+ *
+ * 暂停只做三件事——挂起等待定时器、让正在出声的媒体收声、记下暂停标记；
+ * 外部接管（小游戏 / 玩法系统 / 扩展 op 等待）**保持挂载**，它们只是不再收到推进输入。
+ * 所以这里不调 `abortExternalTakeovers`：那是中断的语义（销毁、导航、读档、回溯），
+ * 调了之后宿主会卸载接管面板，再恢复就不是「接着玩」而是「重进」。
+ *
+ * 恢复按暂停时记下的剩余毫秒续上原来的等待，媒体按**当前状态**逐个恢复——
+ * 暂停期间被命令改成 stop 的通道不复活（留着一条「该出声却永远不出声」的通道更糟）。
+ */
+import { SYS, type VideoCommand } from "../../contracts/index.ts";
+import {
+  armWaitTimer,
+  nowMs,
+  pausedSession,
+  type OpContext,
+} from "../internal/index.ts";
+import {
+  execAudioPause,
+  execAudioResume,
+  pauseAudioInstances,
+  resumeAudioInstances,
+} from "../ops/index.ts";
+
+/** 视频命令流里「正在播」的形态判定（暂停只对正在播的过场有意义） */
+function playingVideo(value: unknown): value is VideoCommand {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    (value as { kind?: unknown }).kind === "play"
+  );
+}
+
+/** 视频命令流里「已暂停」的形态判定（恢复只对暂停过的过场有意义） */
+function pausedVideo(value: unknown): value is VideoCommand {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    (value as { kind?: unknown }).kind === "pause"
+  );
+}
+
+/**
+ * 挂起等待定时器：记下剩余毫秒并取消，等恢复时按剩余量重排。
+ *
+ * 剩余量靠到期时刻与当前时刻相减——`clear` 之后句柄再也问不出「还剩多久」。
+ * 没有到期时刻（非本模块建立的定时器）就退回「不知道剩余量」，
+ * 恢复时宁可丢弃这段等待，也不排一个凭空多出来的完整时长。
+ */
+function suspendWaitTimer(ctx: OpContext): void {
+  const handle = ctx.pendingTimer;
+  if (handle === null) return;
+  const dueAt = ctx.pendingTimerDueAt;
+  ctx.pausedTimerRemainingMs =
+    dueAt === null ? null : Math.max(0, dueAt - nowMs(ctx));
+  ctx.timerPort.clear(handle);
+  ctx.pendingTimer = null;
+  ctx.pendingTimerDueAt = null;
+}
+
+/**
+ * 引擎级暂停：幂等，重复调用不改状态、不重复发事件。
+ *
+ * 常驻音频复用 `audio_pause` 的执行语义（只暂停 play 态、把暂停前的播放态记账），
+ * 引擎级暂停与作者手写 `audio_pause` 因此是同一件事，恢复时走同一条路。
+ * 实例族另走一遍：它们是另一张表（`SYS.audioInstances`），不受通道暂停覆盖，
+ * 漏掉就会留下「引擎已暂停、作者编排的环境音还在放」的状态。
+ */
+export function pauseSession(ctx: OpContext): void {
+  if (pausedSession(ctx)) return;
+  ctx.setSystem(SYS.paused, true);
+  suspendWaitTimer(ctx);
+  execAudioPause(ctx, { op: "audio_pause" });
+  pauseAudioInstances(ctx);
+  const video = ctx.get(SYS.video);
+  if (playingVideo(video)) {
+    ctx.videoSeq += 1;
+    ctx.setSystem(SYS.video, {
+      kind: "pause",
+      seq: ctx.videoSeq,
+    } satisfies VideoCommand);
+  }
+}
+
+/**
+ * 解除引擎级暂停：未暂停时幂等空操作。
+ *
+ * 续起等待前先确认故事仍停在同一个 wait 上——暂停期间可能读过档或导航过，
+ * 那时剩余毫秒属于一段已经不存在的等待，排出来只会提前解除别的等待。
+ */
+export function resumeSession(ctx: OpContext): void {
+  if (!pausedSession(ctx)) return;
+  ctx.setSystem(SYS.paused, false);
+  const remaining = ctx.pausedTimerRemainingMs;
+  ctx.pausedTimerRemainingMs = null;
+  if (
+    remaining !== null &&
+    ctx.pendingTimer === null &&
+    ctx.get(SYS.waiting) === "wait"
+  ) {
+    armWaitTimer(ctx, remaining);
+  }
+  execAudioResume(ctx, { op: "audio_resume" });
+  resumeAudioInstances(ctx);
+  const video = ctx.get(SYS.video);
+  if (pausedVideo(video)) {
+    ctx.videoSeq += 1;
+    ctx.setSystem(SYS.video, {
+      kind: "resume",
+      seq: ctx.videoSeq,
+    } satisfies VideoCommand);
+  }
+}

package/src/runtime/{waitingOps.ts → session/waitingOps.ts}

@@ -16,7 +16,7 @@
  * 块体（if/while/switch/func 体）内的等待点：其检查点坐标按 `checkpointCoord` 的块帧回退语义
  * 落在**块进入命令**上——故静态切分时「块体内含等待 ⇒ 该块命令本身即边界」，无需逐 op 特判。
  */
-import type { OpExtension, WaitingState } from "../contracts/index.ts";
+import type { OpExtension, WaitingState } from "../../contracts/index.ts";
 
 /** 单个 op 的等待规格：等待态 + 是否硬等待（`pause` = 不可跳过） */
 export interface WaitSpec {

package/src/runtime/shell.ts

@@ -10,12 +10,16 @@
  */
 
 import {
+  AUDIO_CHANNELS,
+  DEFAULT_AUDIO_CONFIG,
   DEFAULT_LAYER_Z,
   DEFAULT_SAVES_CONFIG,
   DEFAULT_STAGE_CONFIG,
   isOrientationMode,
   LAYER_IDS,
   SYS,
+  type AudioChannel,
+  type AudioConfig,
   type LayerId,
   type LayerZTable,
   type OrientationMode,
@@ -32,12 +36,14 @@ import {
  * 后续并入包出口时统一改走包出口。
  */
 export {
+  DEFAULT_AUDIO_CONFIG,
   DEFAULT_LAYER_Z,
   DEFAULT_SAVES_CONFIG,
   DEFAULT_STAGE_CONFIG,
   LAYER_IDS,
 } from "../contracts/index.ts";
 export type {
+  AudioConfig,
   LayerId,
   LayerZOverrides,
   LayerZTable,
@@ -145,6 +151,26 @@ export function slotIds(count: number): string[] {
   return Array.from({ length: count }, (_, i) => `slot_${i + 1}`);
 }
 
+/** 取清单里一个非空字符串字段；不是字符串或是空串一律返回 null，由调用方决定回落 */
+function nonEmptyText(value: unknown): string | null {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+/**
+ * 解析工程展示名：`name` → `id` → 空串。
+ *
+ * 展示名是**给玩家看的**那一行字，与工程 id 是两个用途：id 是存储与引用目标（不可随意改），
+ * name 才是可随时换的招牌。缺 name 时退回 id 是为了让工程至少有个名字可显示；
+ * 两者都没有才算没名字（空串），由调用方决定怎么兜。
+ *
+ * 入参与其他壳配置解析同口径：`unknown`、不猜不抛——清单是外部文件，畸形是常态不是异常。
+ */
+export function resolveProjectName(manifest: unknown): string {
+  if (manifest === null || typeof manifest !== "object") return "";
+  const record = manifest as Record<string, unknown>;
+  return nonEmptyText(record.name) ?? nonEmptyText(record.id) ?? "";
+}
+
 /** 解析存档壳配置：内建默认 × 工程覆盖（`shell.saves`，逐键合并；非法值/越界忽略） */
 export function resolveSavesConfig(manifest: unknown): SavesConfig {
   const resolved: SavesConfig = {
@@ -173,6 +199,48 @@ export function resolveSavesConfig(manifest: unknown): SavesConfig {
   return resolved;
 }
 
+/* ============================ 音频壳配置 ============================ */
+
+/** 通道音量：有限数按物理范围钳制；其余（含缺键）回 null，由调用方保持默认 */
+function channelVolume(value: unknown): number | null {
+  if (typeof value !== "number" || !Number.isFinite(value)) return null;
+  return Math.min(1, Math.max(0, value));
+}
+
+/**
+ * 解析音频壳配置：内建默认（四通道皆 1）× 工程覆盖（`shell.audio.volumes`）。
+ *
+ * 与 `resolveSavesConfig` 同一口径（清单入参 `unknown`、不猜不抛），差别在越界处理：
+ * 越界值**钳制后采纳**（`1.5` ⇒ `1`）而不是丢弃——与命令面 `volume=` 的行为一致，
+ * 作者手滑写个越界数不该让音量悄悄回满。非有限数（`NaN`/`Infinity`/字符串）仍忽略，
+ * 它们不是「差一点」而是「不是数」。
+ *
+ * 真正的畸形在组装期就 fail-closed 了（`project.json: shell.audio.volumes.<通道>
+ * 必须为 0..1 的有限数字`），这里的宽松只是不让解析函数自己抛。
+ */
+export function resolveAudioConfig(
+  manifest: unknown,
+  defaults: AudioConfig = DEFAULT_AUDIO_CONFIG,
+): AudioConfig {
+  const resolved: Record<AudioChannel, number> = { ...defaults.volumes };
+  if (manifest === null || typeof manifest !== "object") {
+    return { volumes: resolved };
+  }
+  const shell = (manifest as { shell?: unknown }).shell;
+  if (shell === null || typeof shell !== "object") return { volumes: resolved };
+  const audio = (shell as { audio?: unknown }).audio;
+  if (audio === null || typeof audio !== "object") return { volumes: resolved };
+  const volumes = (audio as { volumes?: unknown }).volumes;
+  if (volumes === null || typeof volumes !== "object") {
+    return { volumes: resolved };
+  }
+  for (const channel of AUDIO_CHANNELS) {
+    const value = channelVolume((volumes as Record<string, unknown>)[channel]);
+    if (value !== null) resolved[channel] = value;
+  }
+  return { volumes: resolved };
+}
+
 /* ============================ 舞台适配配置 ============================ */
 
 /** 取 [min,max] 闭区间内的有限数（尺寸/倍率允许小数）；越界或非有限一律 null */

package/src/runtime/state/index.ts

@@ -1,5 +1,5 @@
 /**
- * 状态子层出口：写入通道、实例 z、表达式求值、出站面与状态读口。
+ * 状态子层出口：写入通道、写入契约守卫、实例 z、表达式求值、出站面与状态读口。
  *
  * 执行器与运行层内部模块从这里取状态相关成员；子层各文件之间仍按需直接引用。
  * 这里只做转发，不放任何实现。
@@ -9,3 +9,4 @@ export { rejectBadInstanceZ, setInstanceZ } from "./instance-z.ts";
 export { evalValue, readVariable, resolveName } from "./evaluate.ts";
 export { emitChange, emitErrorEvent, publishEvent } from "./notify.ts";
 export { createStateReader } from "./reader.ts";
+export { findJsonValueError, jsonUnsafeReason } from "./stateContract.ts";

package/src/runtime/state/reader.ts

@@ -11,12 +11,15 @@
  */
 import {
   SYS,
+  sceneTypeOf,
   type AudioChannel,
   type AudioChannelState,
   type ElementInstance,
+  type InputCandidate,
   type LayerId,
   type LayerZOverrides,
   type MenuChoice,
+  type SceneType,
   type StateReader,
   type StateSource,
   type VideoCommand,
@@ -43,7 +46,7 @@ function inUnitRange(value: unknown, fallback: number): number {
 }
 
 /**
- * 音频通道状态收窄：`stop` 只认淡出参数，`play` 缺资源或资源为空串即视为「无媒体」。
+ * 音频通道状态收窄：`stop` 只认淡出参数，`pause` 只认序号，`play` 缺资源或资源为空串即视为「无媒体」。
  *
  * `fadeMs` 非正数按 0（无淡出）算；`volume` 非有限数按 1 并钳到 0..1；
  * `autoStop` / `restart` 只在显式为 `true` 时保留（缺字段与 `false` 同义）；
@@ -64,6 +67,10 @@ function channelStateOf(value: unknown): AudioChannelState | null {
   const fade = finiteNumber(state.fadeMs);
   const fadeMs = fade !== null && fade > 0 ? fade : 0;
   if (state.kind === "stop") return { kind: "stop", fadeMs };
+  if (state.kind === "pause") {
+    const pauseSeq = finiteNumber(state.seq);
+    return { kind: "pause", ...(pauseSeq === null ? {} : { seq: pauseSeq }) };
+  }
   if (state.kind !== "play") return null;
   if (typeof state.resource !== "string" || state.resource === "") return null;
   const seq = finiteNumber(state.seq);
@@ -132,6 +139,27 @@ function textOf(value: unknown): string {
 /** 见契约 `StateReader`：各方法的降级口径写在契约的字段注释里。 */
 export function createStateReader(source: StateSource): StateReader {
   const get = (key: string): unknown => source.get(key);
+
+  /**
+   * 当前列 id：非字符串一律当空串（与 `textOf` 同口径）。
+   *
+   * 空串同时表达「还没进列」与「值被改坏」——两者对界面是同一件事：没有当前位置。
+   */
+  const currentColumnId = (): string => textOf(get(SYS.currentSceneColumn));
+
+  /**
+   * 当前列类型：从列清单里查 id 对应的类型，查不到即缺省。
+   *
+   * 「查不到」有三种来源，对界面是同一件事（没有可用的当前列）：启动期尚未进列、
+   * 读口拿不到列清单、id 已失效（热重载后坐标过期）。三种都交给 `sceneTypeOf` 归一，
+   * 缺省口径因此只有一处——与列清单、与可回溯判定同源，这里不另判一遍。
+   */
+  const currentColumnType = (): SceneType => {
+    const id = currentColumnId();
+    const columns = source.columns?.() ?? [];
+    return sceneTypeOf(columns.find((column) => column.id === id) ?? {});
+  };
+
   return {
     audioChannel(channel: AudioChannel): AudioChannelState | null {
       return channelStateOf(get(AUDIO_CHANNEL_KEY[channel]));
@@ -159,6 +187,20 @@ export function createStateReader(source: StateSource): StateReader {
       }));
     },
 
+    inputCandidates(): InputCandidate[] {
+      // 候选是单条目里的对象数组：畸形项整项丢弃（不猜字段），全部丢弃即等于「无候选」
+      const raw = get(SYS.inputOptions);
+      if (!Array.isArray(raw)) return [];
+      const out: InputCandidate[] = [];
+      for (const item of raw) {
+        if (item === null || typeof item !== "object") continue;
+        const { text, value } = item as { text?: unknown; value?: unknown };
+        if (typeof text !== "string" || typeof value !== "string") continue;
+        out.push({ text, value });
+      }
+      return out;
+    },
+
     dialogSpeaker(): string {
       return textOf(get(SYS.currentDialogSpeaker));
     },
@@ -219,5 +261,9 @@ export function createStateReader(source: StateSource): StateReader {
       }
       return overrides;
     },
+
+    currentColumnId,
+
+    currentColumnType,
   };
 }

package/src/runtime/state/writer.ts

@@ -6,7 +6,7 @@ import {
   RESERVED_STATE_KEYS,
 } from "../../contracts/index.ts";
 import type { OpContext } from "../internal/index.ts";
-import { findJsonValueError } from "../stateContract.ts";
+import { findJsonValueError } from "./stateContract.ts";
 
 /**
  * 全局层写入（作者 `set`/`define` / 小游戏奖励 / 数组族 op 的唯一汇聚点）。

package/src/shared/audio.ts

@@ -0,0 +1,106 @@
+/**
+ * 音频实例表的读入判据：把运行期到手的 `unknown` 收窄成契约里的实例表。
+ *
+ * 契约层只声明形态，实例表却可能来自存档、来自扩展、来自被改坏的工程文件，
+ * 所以每次读入都得先判后用（与 `guards.ts` 同一套纪律：判不过就由调用方
+ * fail-closed，这里不抛错也不猜默认值）。
+ *
+ * 三条规则一次判清，缺一条都会让坏数据漏进状态：
+ * - 表是普通对象（数组与 `null` 不算——数组会把下标当实例 id）
+ * - 实例 id 合 `AUDIO_INSTANCE_ID_PATTERN`（作者要按名字点名，形态必须统一）
+ * - 实例数不超 `MAX_AUDIO_INSTANCES`（整表进快照与存档，无上限存档会写到写不动）
+ */
+import {
+  AUDIO_INSTANCE_ID_PATTERN,
+  MAX_AUDIO_INSTANCES,
+  type AudioChannel,
+  type AudioChannelState,
+  type AudioInstanceState,
+  type AudioInstanceTable,
+} from "../contracts/media/index.ts";
+import { isPlainObject } from "./guards.ts";
+
+const AUDIO_CHANNELS: readonly string[] = ["bgm", "se", "ambient", "voice"];
+
+/** 是否是已知的音频通道（`bgm` / `se` / `ambient` / `voice`） */
+export function isAudioChannel(value: unknown): value is AudioChannel {
+  return typeof value === "string" && AUDIO_CHANNELS.includes(value);
+}
+
+/** 是否是合形态的实例 id（与扩展 / 玩法系统同一份短 id 规则） */
+export function isAudioInstanceId(value: unknown): value is string {
+  return typeof value === "string" && AUDIO_INSTANCE_ID_PATTERN.test(value);
+}
+
+/**
+ * 通道状态判据：按 `kind` 分支判各自字段。
+ *
+ * 不能先统一要求 `fadeMs` 存在——`pause` 态不带淡出参数，那样会把合法的暂停
+ * 判成坏数据（读入 fail-closed 后暂停就丢了）。淡出只在 `play` / `stop` 分支里判。
+ */
+function isChannelState(value: unknown): value is AudioChannelState {
+  if (!isPlainObject(value)) return false;
+  if (value.kind === "pause") {
+    return value.seq === undefined || isOptionalSeq(value.seq);
+  }
+  if (typeof value.fadeMs !== "number" || !Number.isFinite(value.fadeMs)) {
+    return false;
+  }
+  const fadeMs = value.fadeMs;
+  if (value.kind === "stop") {
+    return value.seq === undefined || isOptionalSeq(value.seq);
+  }
+  if (value.kind !== "play") return false;
+  return (
+    typeof value.resource === "string" &&
+    value.resource !== "" &&
+    typeof value.volume === "number" &&
+    Number.isFinite(value.volume) &&
+    typeof value.loop === "boolean" &&
+    fadeMs >= 0 &&
+    (value.autoStop === undefined || typeof value.autoStop === "boolean") &&
+    (value.restart === undefined || typeof value.restart === "boolean") &&
+    (value.seq === undefined || isOptionalSeq(value.seq))
+  );
+}
+
+function isOptionalSeq(value: unknown): boolean {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+/** 是否是合形态的单个实例状态：通道已知 + 播放状态合形态 */
+export function isAudioInstanceState(
+  value: unknown,
+): value is AudioInstanceState {
+  if (!isPlainObject(value)) return false;
+  return isAudioChannel(value.channel) && isChannelState(value.state);
+}
+
+/**
+ * 是否是合形态的实例表：普通对象 + 键合 id + 值合形态 + 条数不超上限。
+ *
+ * **上限在这里判**而不是在写入 op 里判：读入与写入都走同一个判据，
+ * 存档里被人改成 100 个实例时也能在装载阶段挡下来。
+ */
+export function isAudioInstanceTable(
+  value: unknown,
+): value is AudioInstanceTable {
+  if (!isPlainObject(value)) return false;
+  const ids = Object.keys(value);
+  if (ids.length > MAX_AUDIO_INSTANCES) return false;
+  for (const id of ids) {
+    if (!isAudioInstanceId(id)) return false;
+    if (!isAudioInstanceState(value[id])) return false;
+  }
+  return true;
+}
+
+/**
+ * 取实例表的 id 清单（字典序）：不合形态的表按空表处理。
+ *
+ * 渲染层按 id 排序后下发才能保证「同一份状态 → 同一串播放动作」，
+ * 否则对象键序会让同一存档在两台机器上叠出不同顺序的音轨。
+ */
+export function audioInstanceIds(value: unknown): readonly string[] {
+  return isAudioInstanceTable(value) ? Object.keys(value).sort() : [];
+}

package/src/shared/guards.ts

@@ -61,17 +61,51 @@ export function isPlainObject(
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-/** 是否是已知的场景类型（非法值由解析层 fail-closed，这里只做收窄） */
+/**
+ * 是否是契约承认的场景类型（**只认 `game` / `ui`**）。
+ *
+ * 调用点都在「拒绝非法输入」的位置：故事文件里写别的值一律 fail-closed 报错，
+ * 不静默当剧情——那种错要等存档/回溯出问题才发现，代价极高。
+ */
 export function isSceneType(value: unknown): value is SceneType {
-  return value === "game" || value === "menu" || value === "ui";
+  return value === "game" || value === "ui";
+}
+
+/**
+ * 把外部输入的场景类型拼写归一为契约值：`game` / `ui`。
+ *
+ * **单一归一函数**：解析层已用 `isSceneType` fail-closed 拒绝非法值，
+ * 这里只负责「缺省」这一种合法输入——`undefined` → `game`。
+ *
+ * 为什么仍单独成函数：`type` 的缺省语义（不写 = 剧情）在 JSON 解析、DSL 解析、
+ * 读侧兜底三处都要用，散写三份 `?? "game"` 会让「缺省是什么」出现三个答案。
+ *
+ * 注意：**归一是读侧兜底，不是校验**。故事文件里的非法 `type` 要 fail-closed 报错，
+ * 那是解析层（`columnShapeDefect`）的职责，不靠这里静默吃掉。
+ */
+export function normalizeSceneType(raw: unknown): SceneType {
+  return isSceneType(raw) ? raw : "game";
 }
 
 /**
- * 该列是否参与历史与存档：`type` 缺省按 `game` 算，`menu` / `ui` 不参与。
+ * 该列是否参与历史与存档：`type` 缺省按 `game` 算，`ui` 不参与。
  *
  * **单一判定点**——引擎的写入守卫与编辑器的章节分组都调用这里，谁都不许另写一份，
  * 否则两侧对「哪些列进存档」的理解会分叉。
  */
 export function isReplayableColumn(column: Pick<StoryColumn, "type">): boolean {
-  return (column.type ?? "game") === "game";
+  return sceneTypeOf(column) === "game";
+}
+
+/**
+ * 列的**归一化**运行语义类型：缺省（以及解析层已 fail-closed 的非法值）一律取 `game`。
+ *
+ * **为什么需要它**：`isReplayableColumn` 只回答「参不参与存档」，回答不了「是哪一种」。
+ * 宿主列清单与状态读口要的是具体类型，若各自写 `column.type ?? "game"`，
+ * 缺省口径就分叉了。归一口径本身归 `normalizeSceneType`，这里只是它的列级入口。
+ *
+ * 注意：**这是读侧归一**。故事文件里的非法 `type` 由解析层拒收，不靠这里兜底。
+ */
+export function sceneTypeOf(column: Pick<StoryColumn, "type">): SceneType {
+  return normalizeSceneType(column.type);
 }

package/src/shared/index.ts

@@ -2,6 +2,9 @@
  * 通用出口：没有业务含义的取值判据与小工具，不依赖包内其他层，任何层都可以引用。
  * 实现按用途分文件，消费方只从这里取。
  */
+export * from "./audio.ts";
 export * from "./guards.ts";
+export * from "./mounts.ts";
 export * from "./numbers.ts";
 export * from "./ordering.ts";
+export * from "./ui-name.ts";

package/src/shared/mounts.ts

@@ -0,0 +1,42 @@
+/**
+ * 挂载表的读入判据：把运行期到手的 `unknown` 收窄成契约里的挂载表。
+ *
+ * 契约层只声明形态，挂载表却可能来自存档、来自被改坏的工程文件，
+ * 所以每次读入都得先判后用（与 `audio.ts` 的实例表同一套纪律：判不过就由调用方
+ * fail-closed，这里不抛错也不猜默认值）。
+ *
+ * 三条规则一次判清，缺一条都会让坏数据漏进渲染层：
+ * - 表是普通对象（数组与 `null` 不算——数组会把下标当 UI 名）
+ * - 键合 UI 名形态（名字同时是宿主预加载键与目录名，形态必须统一）
+ * - 值只有 `visible: boolean` 与 `props: 普通对象` 两项
+ */
+import type { MountEntry, MountTable } from "../contracts/runtime/index.ts";
+import { isPlainObject } from "./guards.ts";
+import { isUiName } from "./ui-name.ts";
+
+/** 是否是合形态的挂载记录 */
+export function isMountEntry(value: unknown): value is MountEntry {
+  if (!isPlainObject(value)) return false;
+  if (typeof value.visible !== "boolean") return false;
+  return isPlainObject(value.props);
+}
+
+/** 是否是合形态的挂载表：普通对象 + 键合 UI 名 + 值合记录 */
+export function isMountTable(value: unknown): value is MountTable {
+  if (!isPlainObject(value)) return false;
+  for (const name of Object.keys(value)) {
+    if (!isUiName(name)) return false;
+    if (!isMountEntry(value[name])) return false;
+  }
+  return true;
+}
+
+/**
+ * 取挂载表的 UI 名清单（码点序）：不合形态的表按空表处理。
+ *
+ * 渲染层按名字排序后下发才能保证「同一份状态 → 同一串挂载动作」，
+ * 否则对象键序会让同一存档在两台机器上挂出不同顺序的组件。
+ */
+export function mountNames(value: unknown): readonly string[] {
+  return isMountTable(value) ? Object.keys(value).sort() : [];
+}

package/src/shared/ui-name.ts

@@ -0,0 +1,41 @@
+/**
+ * 列级 UI 名字的形态与定序：名字 = `src/ui/<名>/` 的目录名。
+ *
+ * 为什么名字要卡形态：名字同时是**产物里的字符串**、宿主的**预加载键**、以及
+ * 目录/文件名的来源。不卡形态的话，`Hub` 与 `hub` 会在不同文件系统上落到同一个目录、
+ * 却成为两个不同的产物键，产物与实现就对不上了。
+ *
+ * 形态与扩展 id / 玩法系统 id 同源（`SHORT_ID_PATTERN`）：同一个系统不出现两种写法，
+ * 且名字作为产物字段时仍然短小可读。
+ */
+import { SHORT_ID_PATTERN } from "../contracts/identifiers.ts";
+import { compareOrdinal } from "./ordering.ts";
+
+/** 合法 UI 名：小写字母开头，其后小写字母 / 数字 / `_` / `-`，总长 1..32 */
+export const UI_NAME_PATTERN = SHORT_ID_PATTERN;
+
+/** 是否为合法 UI 名（类型收窄到 `string`，可直接用于过滤未校验的 JSON 数组） */
+export function isUiName(value: unknown): value is string {
+  return typeof value === "string" && UI_NAME_PATTERN.test(value);
+}
+
+/**
+ * 归一列级 `uis`：**去重 + 按名字码点序**。
+ *
+ * 为什么必须归一：`uis` 是产物字节的一部分，而它的来源（导入语句的书写顺序、
+ * 文件系统的目录枚举顺序）在不同机器上不一样。不归一的产物会「同源不同字节」，
+ * 缓存与逐字节比对全部失效。码点序（而非 locale 序）才与运行环境的语言无关。
+ *
+ * 这是全链路唯一的定序点：解析、汇编、写出三处都调这里，不各写一份比较器。
+ */
+export function normalizeUiNames(names: readonly string[]): string[] {
+  const seen = new Set<string>();
+  const unique: string[] = [];
+  for (const name of names) {
+    if (seen.has(name)) continue;
+    seen.add(name);
+    unique.push(name);
+  }
+  unique.sort(compareOrdinal);
+  return unique;
+}