@lingfan-engine/ui 0.2.0 → 0.3.0

package/src/element/renderers/controls.ts

@@ -4,7 +4,7 @@
  */
 import { clamp01 } from "@lingfan-engine/core";
 import { bindInteraction, isDisabled } from "./bindings";
-import { createRoot, numProp, withProps, withStyle } from "./base";
+import { createRoot, numProp, withEvents, withProps, withStyle } from "./base";
 import type { ElementRenderContext } from "../registry";
 import type { RenderSpec } from "../spec";
 
@@ -54,7 +54,13 @@ export function renderProgress(ctx: ElementRenderContext): RenderSpec {
   return { ...spec, style, children: [fill] };
 }
 
-/** 滑块：`min`/`max`/`value` 归一后写进原生 input；纵向由 `orientation` 决定书写方向 */
+/**
+ * 滑块：`min`/`max`/`value` 归一后写进原生 input；纵向由 `orientation` 决定书写方向。
+ *
+ * 值回写挂 `change`（值已定才上报，拖动过程中的每帧不刷状态）：控件给的是字符串，
+ * 这里转数字——`min`/`max` 的区间由控件自身保证，本层不再裁剪。
+ * 回写不改节点：滑块自己持有当前值，描述树只在重渲时覆盖它。
+ */
 export function renderSlider(ctx: ElementRenderContext): RenderSpec {
   const spec = createRoot("slider", ctx);
   const withPropsSpec = withProps(spec, {
@@ -67,7 +73,23 @@ export function renderSlider(ctx: ElementRenderContext): RenderSpec {
     ctx.element.props.orientation === "vertical"
       ? withStyle(withPropsSpec, { writingMode: "vertical-lr" })
       : withPropsSpec;
-  return bindInteraction(out, ctx);
+  const bound = bindInteraction(out, ctx);
+  // 禁用即不挂回写（与点击同一条短路：禁用的控件不该改动任何状态）
+  if (isDisabled(ctx)) return bound;
+  return withEvents(bound, [
+    {
+      on: "change",
+      handler: (raw) => {
+        // 空串的 Number() 是 0 而不是 NaN，须先挡掉——「没给值」不等于「值为 0」
+        if (typeof raw === "string" && raw.trim() === "") return undefined;
+        const value = typeof raw === "string" ? Number(raw) : raw;
+        if (typeof value === "number" && Number.isFinite(value)) {
+          ctx.onElementValueChange?.(ctx.element, value);
+        }
+        return undefined;
+      },
+    },
+  ]);
 }
 
 /** 复选框：`checked === true` 才勾上（其余取值一律不勾，不猜真值） */

package/src/element/spec.ts

@@ -32,10 +32,24 @@ export interface RenderEventPatch {
   props?: Readonly<Record<string, RenderPropValue>>;
 }
 
-/** 事件绑定；`handler` 的返回值即触发时要应用的补丁（无返回值 = 不改节点） */
+/**
+ * 事件名：前三个是交互态（进出/点击），后两个带值（表单类控件用）。
+ *
+ * `input` 是「值在变」（连续），`change` 是「值已定」（一次）——滑块拖动时前者每帧都来，
+ * 后者只在松手/提交时来，写回状态一律走 `change`，避免每帧刷引擎。
+ */
+export type RenderEventName =
+  "click" | "mouseenter" | "mouseleave" | "input" | "change";
+
+/**
+ * 事件绑定；`handler` 的返回值即触发时要应用的补丁（无返回值 = 不改节点）。
+ *
+ * `handler` 的可选参数是事件载荷：只有 `input` / `change` 会带（控件当前值），
+ * 其余事件一律 `undefined`。既有 handler 不接参数，多一个可选参数对它们零影响。
+ */
 export interface RenderEvent {
-  on: "click" | "mouseenter" | "mouseleave";
-  handler?: () => RenderEventPatch | void;
+  on: RenderEventName;
+  handler?: (value?: RenderPropValue) => RenderEventPatch | void;
   /** 阻止冒泡（元素点击不应同时触发舞台推进） */
   stopPropagation?: boolean;
 }

package/src/element/writeback.ts

@@ -0,0 +1,125 @@
+/**
+ * 元素值回写的落点路由：元素层只上报「哪个元素变成了什么值」，落到哪里由本模块决定。
+ *
+ * 元素渲染器不认识引擎，也不知道「音量」和「分数」有什么区别——它只把
+ * `(element, value)` 交出来。本模块是**全仓唯一的落点判定点**（模板骨架与
+ * playground 都调它，两处不各判一套，否则作者的同一个 `cmd="volume:bgm"`
+ * 在两个宿主里会得到不同结果）：
+ *
+ * - `cmd="volume:bgm"` / `volume:se` / `volume:ambient` / `volume:voice` → 玩家偏好通道音量；
+ * - `cmd="game.<系统>.<键>"` → 外部玩法系统命名空间（经 `GameStateWriter.setScoped`）；
+ * - 其余（含无 `cmd`）→ 不落，返回 false 由调用方上报。
+ *
+ * **三条硬约束**：
+ * 1. 本模块**不直写 SSOT**——`__` 保留键由 `GameStateWriter` 的保留键门卫物理挡住，
+ *    这里连碰都碰不到（`setVolume` 走偏好、`setScoped` 走 `game.` 前缀）。
+ * 2. 形态判定与落点判定分开：`parseWritebackTarget` 是纯解析（可单测），
+ *    `routeElementValueChange` 只做分发，不重复解析。
+ * 3. 本模块**只做判定与分发**，端口由宿主注入（`ElementWritebackPorts`）——
+ *    UI 层因此仍然不持有引擎引用，`ElementInstance` 之外不 import 任何运行时物。
+ *
+ * 为什么用 `cmd` 当落点而不是新增元素属性：`cmd` 已经是「宿主命名命令」的既有载体
+ * （`packages/core/src/contracts/element.ts` 通用属性表），滑块与按钮共用一套寻址，
+ * 不为回写另开一个属性名——那会让作者要记两套。
+ */
+import type { AudioChannel, ElementInstance } from "@lingfan-engine/core";
+import { GAME_SYSTEM_ID_PATTERN } from "@lingfan-engine/core";
+
+/** 音量落点前缀（`volume:bgm` 形态） */
+const VOLUME_PREFIX = "volume:";
+
+/** 玩法系统落点前缀（`game.<系统>.<键>` 形态，与 `setScoped` 的命名空间同源） */
+const GAME_PREFIX = "game.";
+
+/** 四通道白名单：与 `AudioChannel` 同源，写死在这里是为了运行期可判定 */
+const AUDIO_CHANNELS: ReadonlySet<string> = new Set([
+  "bgm",
+  "se",
+  "ambient",
+  "voice",
+]);
+
+/** 回写落点：解析结果是一个判别联合，不认识的一律 `null` */
+export type WritebackTarget =
+  | { kind: "volume"; channel: AudioChannel }
+  | { kind: "game"; systemId: string; key: string };
+
+/**
+ * 解析元素的回写落点。`cmd` 为空 / 不认识的形态 ⇒ `null`（调用方按「未声明落点」处理）。
+ *
+ * `game.` 形态要求**恰好三段**（`game.<系统>.<键>`）：多段会把点号当分隔符吞进键名，
+ * 少段则系统 id 缺失——两种都是作者的笔误，宁可解析失败上报，也不要猜。
+ */
+export function parseWritebackTarget(
+  props: Readonly<Record<string, unknown>>,
+): WritebackTarget | null {
+  const cmd = props.cmd;
+  if (typeof cmd !== "string" || cmd === "") return null;
+
+  if (cmd.startsWith(VOLUME_PREFIX)) {
+    const channel = cmd.slice(VOLUME_PREFIX.length);
+    if (!AUDIO_CHANNELS.has(channel)) return null;
+    return { kind: "volume", channel: channel as AudioChannel };
+  }
+
+  if (cmd.startsWith(GAME_PREFIX)) {
+    const parts = cmd.split(".");
+    if (parts.length !== 3) return null;
+    const [, systemId, key] = parts;
+    if (systemId === undefined || key === undefined) return null;
+    if (systemId === "" || key === "") return null;
+    // 系统 id 形态与 minigame / interaction 的 `game` 同域（单一形态来源）
+    if (!GAME_SYSTEM_ID_PATTERN.test(systemId)) return null;
+    return { kind: "game", systemId, key };
+  }
+
+  return null;
+}
+
+/** 回写落点需要的能力（宿主组合根注入；两件都是既有闸门，不新开写入面） */
+export interface ElementWritebackPorts {
+  /** 玩家偏好通道音量（内部 clamp01，且触发渲染层重规划） */
+  setVolume(channel: AudioChannel, value: number): void;
+  /** 外部玩法系统命名空间写入（保留键与 JSON 安全由引擎门卫把关） */
+  setScoped(systemId: string, key: string, value: unknown): boolean;
+  /** 落点解析失败或写入被拒时的诊断出口 */
+  reportError(message: string): void;
+}
+
+/**
+ * 把一次元素值回写落到宿主既有闸门上。
+ *
+ * @returns 是否落成功（`false` = 已上报诊断，状态原样）
+ */
+export function routeElementValueChange(
+  element: ElementInstance,
+  value: number | string | boolean,
+  ports: ElementWritebackPorts,
+): boolean {
+  const target = parseWritebackTarget(element.props);
+  if (target === null) {
+    ports.reportError(
+      `元素 ${String(element.id)} 的值回写没有落点：cmd 需为 volume:<通道> 或 game.<系统>.<键>`,
+    );
+    return false;
+  }
+
+  if (target.kind === "volume") {
+    // 音量是 0..1 的实数：控件给的是 min..max 的刻度值，由元素自身的
+    // `min`/`max` 决定量纲，这里不做换算（作者把 min/max 设成 0..1 即是音量）
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+      ports.reportError(`元素 ${String(element.id)} 的音量回写值不是有限数字`);
+      return false;
+    }
+    ports.setVolume(target.channel, value);
+    return true;
+  }
+
+  if (!ports.setScoped(target.systemId, target.key, value)) {
+    ports.reportError(
+      `元素 ${String(element.id)} 的状态回写被拒：${target.systemId}.${target.key}（详见引擎诊断）`,
+    );
+    return false;
+  }
+  return true;
+}

package/src/host/entry.ts

@@ -0,0 +1,32 @@
+/**
+ * 「进入游戏」要走到哪一列。
+ *
+ * 引擎只知道自己停在哪一列、那一列是什么类型：它不认识「启动界面」这种概念。
+ * 所以「开始」这个动作在宿主侧必须翻译成一个具体的列 id，而**不能**写死列名：
+ * 工程换了、入口列改了，写死的名字就会指到不存在的列。
+ *
+ * 判据只两条：入口列本身是 `game` 就直接进它；否则取**列清单里第一个 `game` 列**。
+ * 两条都落空（整个工程没有 `game` 列）返回 `undefined`——调用方据此把按钮置灰，
+ * 而不是让玩家点进一片空白。
+ */
+import type { ColumnSummary } from "@lingfan-engine/core";
+
+/**
+ * 挑出「开始」按钮该导航到的列。
+ *
+ * @param columns 列清单（来自 `engine.columns()`，顺序即工程里的列序）。
+ * @param entry 入口列 id（来自工程清单的 `entry`）。
+ * @returns 目标列 id；没有可进入的 `game` 列时返回 `undefined`。
+ *
+ * 入口列优先：工程可以刻意把入口做成一个 `game` 列（那就没有启动界面这一屏），
+ * 这时「开始」与「继续」都在同一列上，行为与玩家的直觉一致。
+ */
+export function firstGameColumn(
+  columns: readonly ColumnSummary[],
+  entry: string,
+): string | undefined {
+  const entryColumn = columns.find((column) => column.id === entry);
+  if (entryColumn !== undefined && entryColumn.type === "game") return entry;
+  const first = columns.find((column) => column.type === "game");
+  return first === undefined ? undefined : first.id;
+}

package/src/host/index.ts

@@ -29,6 +29,7 @@ export {
   type FrameLoopOptions,
   type FrameSource,
 } from "./frame-loop";
+export { firstGameColumn } from "./entry";
 export {
   createLayerView,
   type LayerView,

package/src/host/layer-view.ts

@@ -4,11 +4,15 @@
  * 一个层最终用哪个 z 由三级链决定（实例 > 工程层默认 > 内建），判定本身在引擎里
  * （`resolveInstanceZ`）；本模块只负责两件事：
  * 1. 记住某层被命令参数覆盖成了什么（`setOverride`），值不是数字时视为「回层默认」；
- * 2. 用注入的 `applyLayerZ` 把六个 DOM 层交给宿主去写。
+ * 2. 用注入的 `applyLayerZ` 把由 DOM 承载的层交给宿主去写。
  *
  * 视频层单独一个方法：它的 z 不在 DOM 上而在视频端口内部，且**只在视频层自己变化时**
  * 才需要下发。合并进 `apply()` 会让「改标题栏层级」也写入一次视频样式——多出来的
  * 那一次写没有任何语义，却足以让「谁在改 DOM」变得难查。
+ *
+ * 历史与偏好两个面板层也在这里下发：它们的槽位在宿主里是**可选节点**（不给就没有面板），
+ * 但既然 `DEFAULT_LAYER_Z` 给它们定了 1500，就必须真的写下去——否则它们的 z 停在
+ * `auto`，会被 z 更小的对话层（999）盖住，表现为「面板打开了却看不见」。
  */
 
 import {
@@ -17,13 +21,15 @@ import {
   type LayerZTable,
 } from "@lingfan-engine/core";
 
-/** 由 DOM 承载的层（顺序即写入顺序；视频/小游戏/历史/偏好不在此表） */
+/** 由 DOM 承载的层（顺序即写入顺序；视频/小游戏不在此表） */
 const DOM_LAYERS: readonly LayerId[] = [
   "stage",
   "dialogue",
   "choices",
   "notifications",
   "toolbar",
+  "history",
+  "prefs",
 ];
 
 /** 层级视图的输入：工程层默认表 + 两个下发出口（视频层可省） */

package/src/index.ts

@@ -61,6 +61,22 @@ export {
   type VideoRendererOptions,
 } from "./video";
 export { createMinigameRegistry, type MinigameRegistry } from "./minigame";
+export {
+  createMountStore,
+  missingMounts,
+  mountEntryOf,
+  mountProps,
+  planMounts,
+  selectMounts,
+  visibleMounts,
+  type MountEntry,
+  type MountPlan,
+  type MountSelection,
+  type MountSource,
+  type MountStore,
+  type MountTable,
+} from "./mount";
+export { continueSlot, latestSave } from "./save";
 export {
   createElementRegistry,
   createElementResourceResolver,
@@ -72,9 +88,11 @@ export {
   hasElementInteraction,
   interpolateAnimation,
   isElementDisabled,
+  parseWritebackTarget,
   registerBuiltinElementRenderers,
   renderElementTree,
   resolveElementAction,
+  routeElementValueChange,
   shakeOffset,
   transitionOpacity,
   type ElementAction,
@@ -84,12 +102,15 @@ export {
   type ElementRenderContext,
   type ElementResourceResolver,
   type ElementTreeRenderOptions,
+  type ElementWritebackPorts,
   type RenderEvent,
+  type RenderEventName,
   type RenderEventPatch,
   type RenderKind,
   type RenderPort,
   type RenderPropValue,
   type RenderSpec,
+  type WritebackTarget,
 } from "./element";
 export {
   createDomOverlaySurface,
@@ -106,6 +127,7 @@ export {
 export {
   GAME_INPUT_BLOCKED_SELECTOR,
   INPUT_SCOPES,
+  UI_ZONE_ATTRIBUTE,
   createInputScopeState,
   isGameInputTarget,
   isInputScope,
@@ -139,6 +161,7 @@ export {
   createLayerView,
   createStateView,
   createVisualEffects,
+  firstGameColumn,
   isDialogueSuppressed,
   isNvlActive,
   isTypingEnabled,

package/src/input/index.ts

@@ -1,6 +1,7 @@
 export {
   GAME_INPUT_BLOCKED_SELECTOR,
   INPUT_SCOPES,
+  UI_ZONE_ATTRIBUTE,
   createInputScopeState,
   isGameInputTarget,
   isInputScope,

package/src/input/scope.ts

@@ -5,7 +5,7 @@
  *
  * 1. **事件目标层面**（[`isGameInputTarget`]）：舞台铺满视口且内部挂着工具条与面板，
  *    事件会从这些控件冒泡上来。命中原生输入控件、或位于标记为 UI 容器的元素内
- *    （`[data-ui-zone]`）即非游戏输入——否则在历史面板里滚动会连带把故事回退，
+ *    （[`UI_ZONE_ATTRIBUTE`]）即非游戏输入——否则在历史面板里滚动会连带把故事回退，
  *    输入框里的空格会被推进逻辑消费。
  * 2. **模式层面**（[`InputScope`]）：外部玩法系统接管期间（方向键行走、战斗、QTE），
  *    推进类按键应整体让位，而不是逐事件判断。
@@ -35,9 +35,17 @@ export function isInputScope(value: unknown): value is InputScope {
   return value === "dialogue" || value === "world" || value === "ui";
 }
 
+/**
+ * 界面区标记：带此属性的节点内的滚轮 / 按键归 UI，不穿透到游戏输入。
+ *
+ * 语义归属在**输入域**这一侧，不归宿主：宿主只负责给面板根打上这个属性，
+ * 「带了它就等于 UI 输入」这条判据由本模块定义。所以常量声明在这里，
+ * 宿主与嵌入方 import 使用——依赖方向是收窄（宿主不再自持一份字面量），不是扩大。
+ */
+export const UI_ZONE_ATTRIBUTE = "data-ui-zone";
+
 /** 原生输入控件 + UI 容器标记；命中即非游戏输入 */
-export const GAME_INPUT_BLOCKED_SELECTOR =
-  'input, textarea, select, [contenteditable]:not([contenteditable="false"]), [data-ui-zone]';
+export const GAME_INPUT_BLOCKED_SELECTOR = `input, textarea, select, [contenteditable]:not([contenteditable="false"]), [${UI_ZONE_ATTRIBUTE}]`;
 
 /** 判定所需的最小事件目标接口（显式入参便于单测；真实值 = DOM Element） */
 export interface ClosestLike {

package/src/mount/index.ts

@@ -0,0 +1,30 @@
+/**
+ * UI 挂载域出口（唯一出口）：把 `SYS.mounts` 翻译成「该渲染谁、带什么入参、和上一帧比变了几件事」。
+ *
+ * 这一域只做纯投影、差量与选择，不碰 DOM、不认识框架——三种宿主形态（原生 DOM / Vue / React）
+ * 各自把结果落到自己的渲染树上。判据因此可以脱离浏览器跑：同一对输入必得同一份结果。
+ *
+ * 三件事刻意分开，因为三种宿主需要的粒度不同：
+ * - `visibleMounts` / `mountProps` / `mountEntryOf` 回答「现在是什么样」，声明式宿主按它渲染即可；
+ * - `selectMounts` / `missingMounts` 再加一层「名字 → 组件」查表与取不到的 fail-closed；
+ * - `planMounts` 回答「比上次变了什么」，命令式宿主需要它才知道卸谁、挂谁；
+ * - `createMountStore` 是订阅通路：三条形态共用同一份值，退订只有一处实现。
+ */
+export {
+  mountEntryOf,
+  mountProps,
+  visibleMounts,
+  type MountEntry,
+  type MountTable,
+} from "./projection.ts";
+export { planMounts, type MountPlan } from "./plan.ts";
+export {
+  missingMounts,
+  selectMounts,
+  type MountSelection,
+} from "./selection.ts";
+export {
+  createMountStore,
+  type MountSource,
+  type MountStore,
+} from "./store.ts";

package/src/mount/plan.ts

@@ -0,0 +1,86 @@
+/**
+ * 挂载差量：两次 `SYS.mounts` 之间该做哪几件事。
+ *
+ * 声明式宿主（Vue / React）靠 `v-for` 加 key 自己就能算出增删，命令式宿主（原生 DOM）
+ * 不能——它必须明确知道「谁要挂、谁要卸、谁只是换了入参」。差量策略放在这里而不是
+ * 渲染器里，是为了让它**可测**：三形态行为一致的判据，最终落成「同一对输入必得同一份差量」。
+ *
+ * 只比可见性，不猜组件内部：`props` 变了就整份重渲染，不做浅合并、不做逐字段下发。
+ * 组件拿到的永远是完整入参——否则「字段被删了」和「字段没传」在组件里无法区分。
+ */
+import { isMountTable, type MountTable } from "@lingfan-engine/core";
+import { visibleMounts } from "./projection.ts";
+
+/** 一份差量：卸载、挂载、换入参三组名字（各自码点序） */
+export interface MountPlan {
+  /** 上一帧可见、这一帧不可见或已消失：从渲染树移除 */
+  readonly unmount: readonly string[];
+  /** 这一帧新出现的可见 UI：新建并挂上 */
+  readonly mount: readonly string[];
+  /** 两帧都可见但入参变了：卸掉旧的、挂上新的（不是改属性） */
+  readonly update: readonly string[];
+}
+
+/** 空差量（首帧之前、或两帧相同） */
+const EMPTY_PLAN: MountPlan = { unmount: [], mount: [], update: [] };
+
+/**
+ * 算两份挂载表之间的差量。
+ *
+ * @param previous 上一帧的 `SYS.mounts` 原始值（首帧传 `undefined`）
+ * @param next 这一帧的原始值
+ */
+export function planMounts(previous: unknown, next: unknown): MountPlan {
+  const before = visibleMounts(previous);
+  const after = visibleMounts(next);
+  if (before.length === 0 && after.length === 0) return EMPTY_PLAN;
+  const beforeSet = new Set(before);
+  const afterSet = new Set(after);
+  const unmount: string[] = [];
+  const update: string[] = [];
+  for (const name of before) {
+    if (!afterSet.has(name)) {
+      unmount.push(name);
+      continue;
+    }
+    if (!sameProps(previous, next, name)) update.push(name);
+  }
+  const mount = after.filter((name) => !beforeSet.has(name));
+  return { unmount, mount, update };
+}
+
+/** 某个名字在两帧里的入参是否等价（名字必须两帧都可见，调用方已判） */
+function sameProps(previous: unknown, next: unknown, name: string): boolean {
+  if (!isMountTable(previous) || !isMountTable(next)) return false;
+  return propsKey(previous, name) === propsKey(next, name);
+}
+
+/**
+ * 入参的稳定序列化：键排序后拼接，用于「换没换」的判定。
+ *
+ * 引擎写入侧已保证 props 是 JSON 安全值，所以这里不会遇到函数、循环引用或 `Map`；
+ * 真遇到（存档被改坏）也只退化成「判定为不同」，重渲染一次而已，不影响正确性。
+ */
+function propsKey(table: MountTable, name: string): string {
+  const props = table[name]?.props;
+  if (props === undefined) return "";
+  try {
+    return stableStringify(props);
+  } catch {
+    return "\u0000";
+  }
+}
+
+/** 键排序的 JSON 序列化（`JSON.stringify` 的键序随插入序变，不能直接比） */
+function stableStringify(value: unknown): string {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+  }
+  const record = value as Record<string, unknown>;
+  const keys = Object.keys(record).sort();
+  const parts = keys.map(
+    (key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`,
+  );
+  return `{${parts.join(",")}}`;
+}

package/src/mount/projection.ts

@@ -0,0 +1,57 @@
+/**
+ * 挂载表投影：把 `SYS.mounts` 的原始值变成「该渲染哪些 UI、各自带什么入参」。
+ *
+ * 三种宿主形态（原生 DOM / Vue / React）共用这一份判定。各写一份的后果不是代码重复，
+ * 而是同一份存档在三种宿主上挂出不同的组件——「三形态行为一致」正是靠这里成面的。
+ *
+ * 表可能来自存档，也可能被改坏（存档是用户可编辑的 JSON）。所以一律先判后用：
+ * 判不过按空表处理，渲染层照常工作——少挂一个 UI 比整屏白掉好，这里不抛错。
+ *
+ * 形态定义不在这里：`MountEntry` / `MountTable` 由引擎契约给出，展示层只消费。
+ */
+import {
+  isMountTable,
+  mountNames,
+  type MountEntry,
+  type MountTable,
+} from "@lingfan-engine/core";
+
+export type { MountEntry, MountTable };
+
+/**
+ * 从 SSOT 原始值投影出可见集合（脏值按空表，不卡死渲染）。
+ *
+ * 顺序是码点序而非对象键序：同一份状态必须投影出同一串挂载动作，
+ * 否则两台机器上的同一存档会挂出不同顺序的组件。
+ */
+export function visibleMounts(raw: unknown): readonly string[] {
+  if (!isMountTable(raw)) return [];
+  return mountNames(raw).filter((name) => raw[name].visible === true);
+}
+
+/**
+ * 取某 UI 的完整挂载记录：不可见或没有这条记录时返回 `undefined`。
+ *
+ * 宿主一次拿全（显隐 + 入参），不必为同一个名字判两遍——判两遍就有两次不一致的机会。
+ */
+export function mountEntryOf(
+  raw: unknown,
+  name: string,
+): MountEntry | undefined {
+  if (!isMountTable(raw)) return undefined;
+  const entry: MountEntry | undefined = raw[name];
+  if (entry === undefined || !entry.visible) return undefined;
+  return entry;
+}
+
+/**
+ * 取某 UI 的 props：不可见时返回 `undefined`。
+ *
+ * 返回的是记录里的那一份引用，不是拷贝——调用方只读。要改就整表新建（写时复制）。
+ */
+export function mountProps(
+  raw: unknown,
+  name: string,
+): Readonly<Record<string, unknown>> | undefined {
+  return mountEntryOf(raw, name)?.props;
+}

package/src/mount/selection.ts

@@ -0,0 +1,61 @@
+/**
+ * 挂载选择：把「可见集合」和「名字 → 组件」表合成一份可直接渲染的清单。
+ *
+ * 三种宿主形态的模板各写一遍「按名字取组件、取不到就跳过」的后果不是代码重复，
+ * 而是同一份存档在三种宿主上挂出不同的组件集合——取不到时一种静默跳过、另一种抛错，
+ * 排查起来就是三套现象。选择逻辑收在这里，模板只负责把清单铺到自己的渲染树上。
+ *
+ * 取不到组件一律 fail-closed：**不渲染**那一条，并**逐条上报**名字。
+ * 静默跳过是这里最坏的选项——作者写了 `mount hub true` 却没看见组件，无从下手；
+ * 抛错则会让一个笔误黑掉整屏。上报走注入的回调，宿主决定写错误条还是打控制台。
+ */
+import { isMountTable } from "@lingfan-engine/core";
+import { mountProps, visibleMounts } from "./projection.ts";
+
+/** 一条可渲染的挂载：名字、组件本身、完整入参 */
+export interface MountSelection {
+  /** UI 名（= `src/ui/` 下的目录名，也是 `SYS.mounts` 的键） */
+  readonly name: string;
+  /** 组件：Vue / React 形态是组件对象，原生形态是工厂函数；本域不解释它 */
+  readonly component: unknown;
+  /** 该 UI 这一帧的完整入参（不可见时不会有这一条） */
+  readonly props: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * 算出这一帧该渲染哪些 UI。
+ *
+ * @param raw `SYS.mounts` 的原始值（脏值按空表，不抛）
+ * @param table 「名字 → 组件」表（生成物 `uis`）
+ * @param onMissing 取不到组件时的上报口；缺省只静默跳过（不建议——见文件头）
+ */
+export function selectMounts(
+  raw: unknown,
+  table: Readonly<Record<string, unknown>>,
+  onMissing?: (name: string) => void,
+): readonly MountSelection[] {
+  const out: MountSelection[] = [];
+  for (const name of visibleMounts(raw)) {
+    const component = table[name];
+    if (component === undefined) {
+      onMissing?.(name);
+      continue;
+    }
+    out.push({ name, component, props: mountProps(raw, name) ?? {} });
+  }
+  return out;
+}
+
+/**
+ * 表里没有这个名字的可见 UI 名单（宿主用它做一次性诊断，避免每帧重复上报）。
+ *
+ * `selectMounts` 的 `onMissing` 是逐帧回调，命令式宿主适合直接接；
+ * 声明式宿主按帧重渲染，重复上报会刷屏——用它算「稳定差集」再自己决定上报时机。
+ */
+export function missingMounts(
+  raw: unknown,
+  table: Readonly<Record<string, unknown>>,
+): readonly string[] {
+  if (!isMountTable(raw)) return [];
+  return visibleMounts(raw).filter((name) => table[name] === undefined);
+}

package/src/mount/store.ts

@@ -0,0 +1,54 @@
+/**
+ * 挂载表订阅：把 `SYS.mounts` 的变化做成一个**宿主无关**的可订阅值。
+ *
+ * 三种宿主形态要的是同一件事——「现在该挂谁、各自带什么入参」，但拿值的方式不同：
+ * 命令式宿主（原生 DOM）要一个回调去算差量，声明式宿主（Vue / React）要一个能进各自
+ * 响应式系统的快照 + 订阅对。这里只提供最小面：`snapshot()` 读当前值、`subscribe()`
+ * 订阅变化、`set()` 由装配处把引擎状态推进来。
+ *
+ * 为什么不让各形态自己订阅引擎：订阅与退订就成了三份实现，任何一份漏掉退订都会在
+ * 页面拆掉之后继续往已销毁的渲染树里写。值在这里只有一条通路。
+ *
+ * 本文件不碰 DOM、不认识框架、没有模块级可变状态——一个 store 的全部状态都在闭包里。
+ */
+
+/** 只读视图：声明式宿主拿它渲染，命令式宿主拿它算差量 */
+export interface MountSource {
+  /** 当前 `SYS.mounts` 原始值；引擎还没写过时是 `undefined` */
+  snapshot(): unknown;
+  /** 订阅变化，返回退订函数。订阅时**不**立刻回调——调用方先自己读一次快照 */
+  subscribe(listener: (raw: unknown) => void): () => void;
+}
+
+/** 可写视图：只有装配处拿得到，写入口不在渲染器手里 */
+export interface MountStore extends MountSource {
+  /** 写入新值；与当前值是同一个引用时不通知（引擎写侧本就是整表新建） */
+  set(raw: unknown): void;
+}
+
+/**
+ * 造一个挂载表 store。
+ *
+ * @param initial 初始值；缺省 `undefined` 即「引擎还没报过」，投影按空表处理
+ */
+export function createMountStore(initial?: unknown): MountStore {
+  let current: unknown = initial;
+  const listeners = new Set<(raw: unknown) => void>();
+  return {
+    snapshot(): unknown {
+      return current;
+    },
+    set(raw: unknown): void {
+      if (Object.is(raw, current)) return;
+      current = raw;
+      // 复制一份再遍历：监听器里退订自己是常见写法，直接遍历 Set 会跳过后一个
+      for (const listener of [...listeners]) listener(current);
+    },
+    subscribe(listener: (raw: unknown) => void): () => void {
+      listeners.add(listener);
+      return (): void => {
+        listeners.delete(listener);
+      };
+    },
+  };
+}