@lingfan-engine/create 0.2.0 → 0.3.1

package/template/__PROJECT__/src/host/boot.ts

@@ -13,9 +13,13 @@
 
 import {
   SYS,
+  PlayerPreferences,
   StoryEngine,
+  resolveAudioConfig,
   resolveLayerZ,
   type AudioPort,
+  type HostControls,
+  type PreferencesPort,
   type ProjectFilesPort,
   type ResourcePort,
   type SavePort,
@@ -26,6 +30,7 @@ import {
   createFetchProjectFilesPort,
   createStaticResourcePort,
   createWebAudioPort,
+  createWebStoragePreferencesPort,
   createWebStorageSavePort,
   createWebVideoPort,
   loadProject,
@@ -47,6 +52,10 @@ import { wireEngine } from "./engine-wiring";
 import { startHostFrameLoop } from "./frame-loop";
 import { wireInput } from "./input-map";
 import { installStoryFonts } from "./theme-fonts";
+import { createPreferencesPanel } from "./panels/preferences";
+import { createHistoryPanel } from "./panels/history";
+import { createNativeMountRenderer } from "./mount/index";
+import { createHostControls } from "./controls";
 
 /**
  * 装配输入：节点句柄表、资源根内的清单与故事表，以及两项可配置节律。
@@ -68,11 +77,58 @@ export interface HostBootOptions {
    * 缺省走 Web 形态（静态资源根 + localStorage 存档 + fetch 取工程文件）。
    */
   ports?: BootPortOverrides;
+  /**
+   * 偏好面板的挂载容器（可选）：给了就装配四通道音量 / 静音 / 字速面板，
+   * 不给就不装——页面结构归组合根，宿主不自己造节点，也不往 `body` 里塞。
+   *
+   * 谁给容器谁负责它的 z 序与显隐；面板根自带 `data-ui-zone`（否则滚轮会连带回溯）。
+   */
+  prefsContainer?: HTMLElement | null;
+  /**
+   * 历史面板的挂载容器（可选）：给了就装配「已走过对话」的面板与回溯按钮，
+   * 不给就不装——与 `prefsContainer` 同口径（页面结构归组合根，宿主不造节点）。
+   *
+   * 面板点一条即 `engine.rollbackTo(检查点)`；回溯后媒体位置由本文件接的
+   * `onRollback` 显式对齐（引擎只回状态，不下发端口动作）。
+   */
+  historyContainer?: HTMLElement | null;
+  /**
+   * UI 挂载层容器（可选）：给了就按 `SYS.mounts` 把 `src/ui/` 下的 UI 挂进来。
+   *
+   * 容器由组合根提供并常驻（宿主不新建也不摘除它，变化只动它的子节点）。UI 表来自
+   * 生成物 `src/gen/ui_register.g.ts`——不是 `import.meta.glob`：模板宿主不该绑死构建工具，
+   * 而 glob 会把 `src/ui/` 下的文件全部静态拉进包，删了 UI 忘删文件它就还在。
+   */
+  mountsContainer?: HTMLElement | null;
+  /**
+   * 「名字 → UI 工厂」表（可选）：缺省空表，即 `mount` 只改状态、没有组件出现。
+   *
+   * 表由组合根从生成物取（`./mounts` 是那份生成物在 `src/**` 里的唯一引用点）：
+   * 各框架形态的 UI 是组件对象、原生形态是工厂函数，所以这张表**由形态自己给**，
+   * 宿主只负责把它的项挂进容器。
+   */
+  mountsTable?: Readonly<Record<string, unknown>>;
+  /**
+   * 自己接管 UI 挂载的落法（可选）：给了就不建原生渲染器，只把 `SYS.mounts` 的每个新值
+   * 交给它。框架形态用这条——挂载点的父子关系归框架管，宿主再往同一个容器里写子节点
+   * 会与框架的渲染树打架。
+   *
+   * 与 `mountsContainer` 互斥，容器优先。两样都不给即 `mount` 命令只改状态。
+   */
+  onMounts?: (raw: unknown) => void;
+  /**
+   * 取走宿主控制面（可选）：整局暂停与恢复、媒体暂停与恢复、换栏、存读档、拆除。
+   *
+   * 与 `onMounts` 是两条通道：挂载 UI 的**值**走 `SYS.mounts`（存档随行、必须 JSON 安全），
+   * 操作**句柄**走这里（含函数、运行期注入、不进快照）。框架形态把它存进自己的容器
+   * 再发给挂载组件；原生形态由渲染器直接作为工厂的第二参传下去，不需要这条回调。
+   */
+  onControls?: (controls: HostControls) => void;
 }
 
 /**
  * 端口覆盖表：换平台形态时由组合根传入原生实现，装配顺序与接线一行不改。
- * 三个端口都可单独覆盖——缺哪一个就用该端口的 Web 形态。
+ * 各端口都可单独覆盖——缺哪一个就用该端口的 Web 形态。
  */
 export interface BootPortOverrides {
   /** 工程文件供给（缺省走 fetch 取资源根下的静态文件） */
@@ -81,13 +137,51 @@ export interface BootPortOverrides {
   resources?: ResourcePort;
   /** 存档（桌面壳换成 Rust 命令：WebView 的 localStorage 会被清缓存带走） */
   saves?: SavePort;
+  /** 玩家偏好持久化（缺省走 localStorage；桌面壳换 app_data JSON 文件） */
+  preferences?: PreferencesPort;
+}
+
+/**
+ * 宿主句柄：装配完成后交给组合根的那几样东西。
+ *
+ * **为什么交出引擎**：组合根常需要在装配之外读引擎（调试面板、外部玩法系统、
+ * 宿主自己的页面切换），而引擎是 `bootHost` 的内部变量。让调用方自己 `new StoryEngine`
+ * 等于起第二个引擎，两个引擎订阅同一份存档端口必然互相踩。这里交出**同一个实例**。
+ *
+ * **为什么句柄可省**：现有组合根写的是 `void bootHost(...)` / `await bootHost(...)`，
+ * 不取返回值——返回类型从 `void` 变成句柄不会破坏它们，它们照旧不关心句柄。
+ * 需要句柄的宿主自己接住返回值即可。
+ *
+ * `preferences`：本宿主总是接线偏好层（缺省 localStorage，桌面壳经 `ports.preferences`
+ * 换成 app_data 文件），所以句柄里恒定有它——调用方不需要判空。偏好不进存档，
+ * 整局稳定，宿主的设置页直接读写这个实例即可。
+ */
+export interface HostHandle {
+  /**
+   * 引擎实例（与宿主内部订阅的是同一个）。
+   *
+   * `readonly`：宿主另建一个实例顶替它，两个引擎订阅同一份存档端口必然互相踩。
+   * 句柄交出的是**那一个**实例，不可替换。
+   */
+  readonly engine: StoryEngine;
+  /** 玩家偏好（已 hydrate；读写与订阅都走它）。同为 `readonly`：换实例等于丢掉既有订阅 */
+  readonly preferences: PlayerPreferences;
+  /**
+   * 拆除本宿主：按依赖反序释放渲染器，再销毁引擎。
+   *
+   * 顺序是约束：渲染器订阅引擎状态，先拆引擎会让订阅回调打到已销毁的实例上。
+   * 幂等——重复调用只生效第一次（渲染器的 `dispose` 自身也幂等）。
+   */
+  dispose(): void;
 }
 
 /**
  * 装配并启动本宿主。失败时抛出（组合根负责把失败写进页面），
  * 中途失败不会留下半启动的宿主：所有接线都在本函数内完成，抛出即放弃。
+ *
+ * 返回值是宿主句柄（见 {@link HostHandle}）；不需要句柄的调用方照旧忽略即可。
  */
-export async function bootHost(options: HostBootOptions): Promise<void> {
+export async function bootHost(options: HostBootOptions): Promise<HostHandle> {
   const { dom } = options;
 
   // 字体装配（纯展示，boot 一次性）：@font-face 注入 + 项目默认字体主题面，
@@ -111,6 +205,13 @@ export async function bootHost(options: HostBootOptions): Promise<void> {
   const audioPort: AudioPort = createWebAudioPort({ onError: reportError });
   const savePort: SavePort = options.ports?.saves ?? createWebStorageSavePort();
 
+  // —— 玩家偏好：独立于存档的整局设置（音量 / 静音 / 字速）——
+  // hydrate 失败 = 默认值起航（端口实现负责吞掉畸形数据，绝不因偏好坏掉挡住启动）
+  const preferences = new PlayerPreferences(
+    options.ports?.preferences ?? createWebStoragePreferencesPort(),
+  );
+  await preferences.hydrate();
+
   // —— 层级（z 序）：内建默认 × 工程覆盖（project.json 的 shell.layers）——
   const layerZ = resolveLayerZ(manifest);
   // 视频端口的 z 在端口内部（与 DOM 层不同），故端口晚于首次落 DOM 建立，
@@ -131,13 +232,22 @@ export async function bootHost(options: HostBootOptions): Promise<void> {
   // —— 存档壳配置：槽位（project.json 的 shell.saves.slots 可覆盖）——
   fillSaveSlots(dom, manifest);
 
-  const engine = new StoryEngine(story, { historyLimit: 200, savePort });
+  // 工程默认音量：shell.audio.volumes 是音量的第二级（命令没写 volume 时取它），
+  // 玩家偏好仍是最外层乘算——两者不同层，缺了它「工程统一音量」就只能靠每条命令手写。
+  const engine = new StoryEngine(story, {
+    historyLimit: 200,
+    savePort,
+    audioConfig: resolveAudioConfig(manifest),
+  });
   const audio = createAudioRenderer(engine, audioPort, resourcePort, {
     onError: reportError,
+    // 偏好接线：通道音量 = op 音量 × 通道偏好，偏好变化即时重规划（不重头播）
+    preferences,
   });
   const video = createVideoRenderer(engine, videoPort, resourcePort, {
     onError: reportError,
     onVideoFinished: () => engine.videoFinished(), // 播放结束 → 引擎解除 video 等待
+    preferences,
   });
 
   const toast = createToast({
@@ -150,6 +260,38 @@ export async function bootHost(options: HostBootOptions): Promise<void> {
     defaultCps: options.defaultCps ?? DEFAULT_TEXT_CPS,
   });
 
+  // —— 宿主控制面：引擎与媒体端口就绪后造一次，交出去（挂载 UI 与宿主菜单共用）——
+  // 取用函数每次都读当下实例：`videoPort` 在层级建立后才赋值，故先收窄成常量再交出。
+  const videoReady: VideoPort = videoPort;
+  const controls = createHostControls({
+    engine: () => engine,
+    audio: () => audioPort,
+    video: () => videoReady,
+  });
+  options.onControls?.(controls);
+
+  // —— UI 挂载：`SYS.mounts` → 容器的子节点（不给容器 = mount 只改状态）——
+  // 容器与表都由组合根给：宿主不造节点，也不猜 UI 长什么样（原生是工厂、框架是组件）。
+  // 隐藏即真卸载（不是 display:none）：组件自己的定时器、订阅、媒体元素随拆除一起停。
+  // 框架形态自己接管落法（`onMounts`）：往框架管的容器里写子节点会与它的渲染树打架。
+  const nativeMounts =
+    options.onMounts !== undefined ||
+    options.mountsContainer === undefined ||
+    options.mountsContainer === null
+      ? null
+      : createNativeMountRenderer({
+          container: options.mountsContainer,
+          table: options.mountsTable ?? {},
+          // 值走 props、操作走 controls：原生形态没有响应式系统，工厂直接收下这两样
+          controls,
+          reportError,
+        });
+  const onMounts =
+    options.onMounts ??
+    (nativeMounts === null
+      ? undefined
+      : (raw: unknown) => nativeMounts.sync(raw));
+
   wireEngine({
     dom,
     engine,
@@ -166,16 +308,69 @@ export async function bootHost(options: HostBootOptions): Promise<void> {
       audio.sync();
       video.sync();
     },
+    // 元素回写落点：音量走偏好、玩法状态走 game. 命名空间（都经既有闸门）
+    preferences,
+    gameState: engine.gameState,
+    // UI 挂载落点：没容器也不接管就不订阅（`mount` 命令照常改状态，只是没有组件出现）
+    mounts: onMounts,
   });
 
   const driveEffects = createHostEffects({ dom, engine });
-  startHostFrameLoop({
+
+  // —— 偏好面板：只有组合根给了容器才装（页面结构归组合根，宿主不造节点）——
+  // 面板只读写偏好层，不碰引擎与存档；`destroy` 在拆除时退订并清空容器。
+  const prefsPanel =
+    options.prefsContainer === undefined || options.prefsContainer === null
+      ? null
+      : createPreferencesPanel({
+          preferences,
+          container: options.prefsContainer,
+        });
+  prefsPanel?.mount();
+
+  // —— 历史面板：同样只有组合根给了容器才装 ——
+  // 数据整形在 `@lingfan-engine/shell`（块聚合），本面板只管画与点击；回溯后的媒体
+  // 对齐交回这里——`wireEngine` 的 `syncMedia` 同一件事，引擎不会替宿主跳播放位置。
+  const historyPanel =
+    options.historyContainer === undefined || options.historyContainer === null
+      ? null
+      : createHistoryPanel({
+          engine,
+          container: options.historyContainer,
+          onRollback: () => {
+            audio.sync();
+            video.sync();
+          },
+        });
+  historyPanel?.mount();
+
+  const frameLoop = startHostFrameLoop({
     dialogue,
     onMediaTick: () => audio.pollPosition(), // 媒体位置帧级回写
     onFrame: driveEffects,
   });
   wireInput({ dom, engine, dialogue });
-  wireSaveSlots(dom, engine);
+  wireSaveSlots(dom, engine, manifest);
 
   engine.start();
+
+  // 拆除顺序与装配相反：先停帧（不再有回调进来），再释放订阅引擎的渲染器，最后销毁引擎
+  let disposed = false;
+  const dispose = (): void => {
+    if (disposed) return;
+    disposed = true;
+    frameLoop.stop();
+    // UI 先拆：它可能持有自己那套框架实例或定时器，晚拆会让卸载跑在引擎销毁之后
+    nativeMounts?.dispose();
+    // 面板先拆：它订阅偏好层，偏好 dispose 之后再退订会漏掉末次回填
+    prefsPanel?.destroy();
+    historyPanel?.destroy();
+    audio.dispose();
+    video.dispose();
+    engine.dispose();
+    // 偏好最后收尾：补发防抖窗内未落盘的末次修改（引擎已停，没人再改它了）
+    preferences.dispose();
+  };
+
+  return { engine, preferences, dispose };
 }

package/template/__PROJECT__/src/host/controls.ts

@@ -0,0 +1,77 @@
+/**
+ * 宿主控制面：把引擎与媒体端口收窄成挂载 UI 能拿的那几件事。
+ *
+ * 入参是取用函数而不是实例，因为引擎与媒体端口都可能被整体重建（换故事、重启对局），
+ * 重建后旧实例作废；取用函数每次调用都读当下那一个，控制面对象本身不必跟着换。
+ *
+ * 只在组合根出现：它把「引擎、音频端口、视频端口」这三样宿主装配知识收进一个对象，
+ * 挂载层因此不必知道引擎长什么样。
+ */
+import {
+  PERSISTENT_AUDIO_CHANNELS,
+  type AudioChannel,
+  type AudioPort,
+  type HostControls,
+  type SaveOptions,
+  type StoryEngine,
+  type VideoPort,
+} from "@lingfan-engine/core";
+
+/** 造一个控制面：方法逐个转调，自身不持有任何状态 */
+export function createHostControls(options: {
+  /** 取当下的引擎实例（重建后指向新实例） */
+  engine: () => StoryEngine;
+  /** 取当下的音频端口 */
+  audio: () => AudioPort;
+  /** 取当下的视频端口 */
+  video: () => VideoPort;
+  /** 批量暂停与恢复作用于哪些音频通道；缺省三条常驻通道 */
+  audioChannels?: readonly AudioChannel[];
+}): HostControls {
+  const { engine, audio, video } = options;
+  // `se` 是一次性音效，没有「暂停后从原位置续播」的语义，批量口径里一律剔除
+  const persistent = (
+    options.audioChannels ?? PERSISTENT_AUDIO_CHANNELS
+  ).filter((channel) => channel !== "se");
+  return {
+    pause(): void {
+      engine().pause();
+    },
+    resume(): void {
+      engine().resume();
+    },
+    paused(): boolean {
+      return engine().paused();
+    },
+    pauseMedia(channel?: AudioChannel): void {
+      if (channel === undefined) {
+        for (const each of persistent) audio().pause(each);
+        video().pause();
+        return;
+      }
+      if (channel === "se") return;
+      audio().pause(channel);
+    },
+    resumeMedia(channel?: AudioChannel): void {
+      if (channel === undefined) {
+        for (const each of persistent) audio().resume(each);
+        video().resume();
+        return;
+      }
+      if (channel === "se") return;
+      audio().resume(channel);
+    },
+    navigate(columnId: string): void {
+      engine().navigate(columnId);
+    },
+    save(slot: string, options?: SaveOptions): void {
+      engine().save(slot, options);
+    },
+    load(slot: string): void {
+      engine().load(slot);
+    },
+    dispose(): void {
+      engine().dispose();
+    },
+  };
+}

package/template/__PROJECT__/src/host/engine-wiring.ts

@@ -16,7 +16,9 @@ import {
   SYS,
   instanceZLayer,
   type ElementInstance,
+  type GameStateWriter,
   type OutboundPayload,
+  type PlayerPreferences,
   type ResourcePort,
   type StoryEngine,
 } from "@lingfan-engine/core";
@@ -29,6 +31,7 @@ import {
   registerBuiltinElementRenderers,
   renderElementTree,
   resolveElementAction,
+  routeElementValueChange,
   type LayerView,
   type StateIntent,
   type TypingSetting,
@@ -74,6 +77,30 @@ export interface HostWiringOptions {
   readTypingSetting(): TypingSetting | undefined;
   /** 存档 / 读档完成后的显式对齐（音频与视频渲染器） */
   syncMedia(): void;
+  /**
+   * 玩家偏好：元素 `cmd="volume:<通道>"` 的回写落点。
+   *
+   * 可选——宿主没接偏好层时音量回写无落点（上报诊断，不静默吞），
+   * 与「宿主没接回写通道，控件仍可拖但值不落地」同一口径。
+   */
+  preferences?: PlayerPreferences;
+  /**
+   * 外部玩法状态写入面（引擎实例的 `gameState`）：元素 `cmd="game.<系统>.<键>"` 的落点。
+   *
+   * 只经 `setScoped` 走 `game.` 命名空间——保留键由引擎写入契约物理挡住，
+   * 元素层不可能靠这条通道碰到 `__` 系统状态。
+   */
+  gameState?: GameStateWriter;
+  /**
+   * UI 挂载落点（可选）：`SYS.mounts` 的每次变化都会推给它。
+   *
+   * 与元素层同属「同一路状态变更的另一个落点」，但两者不是一回事：元素是引擎排布的
+   * 舞台节点，UI 是宿主渲染树上的组件。这里只给一个**写入回调**而不是渲染器，
+   * 是因为三种宿主形态的落法完全不同（原生 DOM 自己算差量，Vue / React 进各自的
+   * 响应式系统）——接线的共同点只有「值从哪来」，落法留给装配处。
+   * 不给则 `mount` 命令只改状态，没有任何组件出现——降级是「少功能」，不是错误。
+   */
+  mounts?: (raw: unknown) => void;
 }
 
 /** 接线状态订阅、元素层与出站事件 */
@@ -112,12 +139,49 @@ export function wireEngine(options: HostWiringOptions): void {
     );
   }
 
+  /**
+   * 控件值回写：元素层只交 `(element, value)`，落点判定在 `element-writeback`。
+   *
+   * **本函数不碰状态**——它把两件既有闸门（偏好 `setVolume` / `gameState.setScoped`）
+   * 交给落点路由，保留键与 JSON 安全仍由引擎写入契约把关。
+   */
+  function writeElementValue(
+    element: ElementInstance,
+    value: number | string | boolean,
+  ): void {
+    const preferences = options.preferences;
+    const gameState = options.gameState;
+    routeElementValueChange(element, value, {
+      setVolume: (channel, next) => {
+        // 偏好层没接时音量回写无处可落：宁可报一行诊断，也不假装写成功
+        if (preferences === undefined) {
+          reportError(
+            `元素 ${String(element.id)} 的音量回写没有偏好层：宿主未接线 PlayerPreferences`,
+          );
+          return;
+        }
+        preferences.setVolume(channel, next);
+      },
+      setScoped: (systemId, key, next) => {
+        if (gameState === undefined) {
+          reportError(
+            `元素 ${String(element.id)} 的状态回写没有写入面：宿主未接线 gameState`,
+          );
+          return false;
+        }
+        return gameState.setScoped(systemId, key, next);
+      },
+      reportError,
+    });
+  }
+
   function renderElements(): void {
     renderElementTree({
       registry: elementRegistry,
       port: createDomRenderPort(dom.stage),
       elements,
       activate: activateElement,
+      onElementValueChange: writeElementValue,
       resolveResource: elementResources.resolveForElement,
       onUnknownType: (type) => reportError(`元素类型未注册：${type}`),
     });
@@ -177,6 +241,17 @@ export function wireEngine(options: HostWiringOptions): void {
     applyIntent(toIntent(key, value));
   });
 
+  // UI 挂载单独一路：`SYS.mounts` 不在状态分发器的键表里——那张表是「引擎状态 → 视图意图」
+  // 的翻译，而挂载没有统一的视图意图可译（三形态落法完全不同），只把值原样交出去。
+  // 首帧主动喂一次：订阅不回放历史，引擎可能在接线之前就写过。
+  const onMounts = options.mounts;
+  if (onMounts !== undefined) {
+    onMounts(engine.get(SYS.mounts));
+    engine.onStateChanged(({ key, value }) => {
+      if (key === SYS.mounts) onMounts(value);
+    });
+  }
+
   /** 出站事件：致命错误 / 提示 / 小游戏挂载 / 存档回执 */
   function applyEvent(payload: OutboundPayload): void {
     switch (payload.kind) {

package/template/__PROJECT__/src/host/index.ts

@@ -7,12 +7,19 @@
 
 export {
   must,
+  optional,
   createErrorReporter,
   reportBootFailure,
   type StageDom,
 } from "./stage-dom";
 export { createHostLayerZ, type HostLayerZOptions } from "./layer-z";
 export { fillSaveSlots, wireSaveSlots } from "./save-slots";
+export {
+  captureSaveThumbnail,
+  drawTextOverlay,
+  stripHtml,
+  type SaveThumbnailInput,
+} from "./thumbnails";
 export { createToast, type ToastOptions } from "./toast";
 export {
   createDialogueView,
@@ -21,7 +28,36 @@ export {
   type DialogueViewOptions,
 } from "./dialogue-view";
 export { createHostEffects, type HostEffectsOptions } from "./effects";
+export { createHostControls } from "./controls";
+export {
+  createNativeMountRenderer,
+  resolveNativeFactory,
+  type NativeMountRenderer,
+  type NativeMountRendererOptions,
+  type NativeUiFactory,
+  type NativeUiInstance,
+  type NativeUiTable,
+} from "./mount/index";
 export { wireEngine, type HostWiringOptions } from "./engine-wiring";
 export { startHostFrameLoop, type HostFrameLoopOptions } from "./frame-loop";
 export { wireInput, type HostInputOptions } from "./input-map";
-export { bootHost, type BootPortOverrides, type HostBootOptions } from "./boot";
+export {
+  bootHost,
+  type BootPortOverrides,
+  type HostBootOptions,
+  type HostHandle,
+} from "./boot";
+export {
+  createPreferencesPanel,
+  PREF_CHANNELS,
+  type PreferencesPanel,
+  type PreferencesPanelOptions,
+  type PreferencesPanelView,
+} from "./panels/preferences";
+export {
+  createHistoryPanel,
+  type HistoryEngine,
+  type HistoryPanel,
+  type HistoryPanelOptions,
+  type HistoryPanelView,
+} from "./panels/history";

package/template/__PROJECT__/src/host/input-map.ts

@@ -1,15 +1,21 @@
 /**
  * 输入映射：点击与键盘（空格 / 回车）都汇到同一个 `advance`。
  *
- * 语义归核心层——`advance` 自己处理可跳过性、非等待态与 fail-closed，这里只做映射，
- * 不判断「现在能不能推进」。
+ * 「点击能否推进」按等待态判定：只有对话 / 可跳过的等待 / 可跳过的过场这三态把点击
+ * 映射成 `advance`；菜单、输入、小游戏等交互等待期**不映射**——那些状态的推进出口是
+ * 各自的选择与提交，舞台空白处的点击不该被解释成「继续」。
+ *
+ * 这层判定不能省：引擎对非对话等待的 `advance` 是 fail-closed（发 `advance-invalid`
+ * 并写进错误条），而错误条一旦出现就不会自己消失——玩家在菜单上多点两下舞台就会看到
+ * 一条红字。是否可跳过（`wait` / `video` 的 skipable）仍归引擎裁决，这里只按等待态
+ * 放行，不放行就什么也不做。
  *
  * 两处刻意的不推进：交互层（选项 / 工具条 / 通知）内的点击不推进故事（元素可交互节点
  * 在渲染器内自行 `stopPropagation`，这里再兜一层），输入框内的空格 / 回车不吞键
  * （那是玩家在打字）。
  */
 
-import type { StoryEngine } from "@lingfan-engine/core";
+import { SYS, type StoryEngine } from "@lingfan-engine/core";
 import type { StageDom } from "./stage-dom";
 import type { DialogueView } from "./dialogue-view";
 
@@ -23,6 +29,13 @@ export interface HostInputOptions {
   dialogue: DialogueView;
 }
 
+/** 把点击映射成 `advance` 的等待态：对话、可跳过的等待、可跳过的过场 */
+const ADVANCEABLE_WAITING: ReadonlySet<unknown> = new Set([
+  "dialog",
+  "wait",
+  "video",
+]);
+
 /** 接线点击与键盘 */
 export function wireInput(options: HostInputOptions): void {
   const { dom, engine, dialogue } = options;
@@ -34,6 +47,8 @@ export function wireInput(options: HostInputOptions): void {
       typewriter.click();
       return;
     }
+    // 非可推进等待态直接返回：引擎会 fail-closed 并在错误条上留一条永不消失的红字
+    if (!ADVANCEABLE_WAITING.has(engine.get(SYS.waiting))) return;
     engine.advance();
   }
 

package/template/__PROJECT__/src/host/layer-z.ts

@@ -36,6 +36,12 @@ function writeLayerZ(dom: StageDom, layer: LayerId, z: number): void {
   } else if (layer === "choices") dom.choices.style.zIndex = value;
   else if (layer === "notifications") dom.notifications.style.zIndex = value;
   else if (layer === "toolbar") dom.toolbar.style.zIndex = value;
+  // 历史与偏好两个面板槽位都是可选节点：叠加层可以不给（那时面板本就没装），所以判空
+  else if (layer === "history") {
+    if (dom.history !== null) dom.history.style.zIndex = value;
+  } else if (layer === "prefs") {
+    if (dom.prefs !== null) dom.prefs.style.zIndex = value;
+  }
 }
 
 /** 造本宿主的层级视图：DOM 层写节点，视频层的 z 下发到端口内部 */

package/template/__PROJECT__/src/host/mount/index.ts

@@ -0,0 +1,18 @@
+/**
+ * 原生形态挂载域出口（唯一出口）：组合根只从这里取渲染器与表形状。
+ *
+ * 与 `packages/ui` 的 mount 域分工：那边是框架无关的投影与差量（三形态共用），
+ * 这边是「原生 DOM 怎么落」——一个渲染器、一份工厂表契约。
+ * 框架叠加层不 import 本目录：它们的渲染交给各自的响应式系统。
+ */
+export {
+  createNativeMountRenderer,
+  type NativeMountRenderer,
+  type NativeMountRendererOptions,
+} from "./renderer";
+export {
+  resolveNativeFactory,
+  type NativeUiFactory,
+  type NativeUiInstance,
+  type NativeUiTable,
+} from "./table";