@lingfan-engine/create 0.0.0-stage → 0.1.4

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

@@ -0,0 +1,181 @@
+/**
+ * 启动装配：端口 → 工程 → 引擎 → 视图 → 订阅 → 帧循环 → 开跑。
+ *
+ * 顺序是有约束的，不是随手排的：
+ * 1. 端口先于引擎（引擎构造要吃存档端口）；
+ * 2. 层级表先落一次 DOM（此时视频端口还没建，视频层不参与）；
+ * 3. 视图先于订阅（订阅一建立就会回调，视图必须已经能接住）；
+ * 4. `engine.start()` 最后（此前任何一次状态回调都还没有订阅者，也不该有）。
+ *
+ * 可配置项都走具名选项，缺省值即本宿主的现状取值：宿主换一个工程或换一套节律时
+ * 只改组合根传进来的值，不动本文件。
+ */
+
+import {
+  SYS,
+  StoryEngine,
+  resolveLayerZ,
+  type AudioPort,
+  type ProjectFilesPort,
+  type ResourcePort,
+  type SavePort,
+  type Story,
+  type VideoPort,
+} from "@lingfan-engine/core";
+import {
+  createFetchProjectFilesPort,
+  createStaticResourcePort,
+  createWebAudioPort,
+  createWebStorageSavePort,
+  createWebVideoPort,
+  loadProject,
+} from "@lingfan-engine/adapters";
+import {
+  DEFAULT_TEXT_CPS,
+  DEFAULT_TOAST_MS,
+  createAudioRenderer,
+  createVideoRenderer,
+  type TypingSetting,
+} from "@lingfan-engine/ui";
+import { createErrorReporter, type StageDom } from "./stage-dom";
+import { createHostLayerZ } from "./layer-z";
+import { fillSaveSlots, wireSaveSlots } from "./save-slots";
+import { createToast } from "./toast";
+import { createDialogueView } from "./dialogue-view";
+import { createHostEffects } from "./effects";
+import { wireEngine } from "./engine-wiring";
+import { startHostFrameLoop } from "./frame-loop";
+import { wireInput } from "./input-map";
+import { installStoryFonts } from "./theme-fonts";
+
+/**
+ * 装配输入：节点句柄表、资源根内的清单与故事表，以及两项可配置节律。
+ * 取值全部由组合根给定——本文件不含宿主特有的字面量。
+ */
+export interface HostBootOptions {
+  /** 常驻节点句柄表（由组合根解析 `#id` 得到） */
+  dom: StageDom;
+  /** 工程清单的逻辑路径（相对资源根） */
+  manifestFile: string;
+  /** 故事文件的逻辑路径表（相对资源根；新增故事必须同步此表） */
+  stories: readonly string[];
+  /** 故事未声明字速时的兜底（可见字符 / 秒）；缺省 = 展示层给出的默认字速 */
+  defaultCps?: number;
+  /** 提示条驻留毫秒数；缺省 = 展示层给出的默认时长 */
+  toastDurationMs?: number;
+  /**
+   * 端口覆盖：换平台形态时由组合根传入原生实现，装配顺序与接线一行不改。
+   * 缺省走 Web 形态（静态资源根 + localStorage 存档 + fetch 取工程文件）。
+   */
+  ports?: BootPortOverrides;
+}
+
+/**
+ * 端口覆盖表：换平台形态时由组合根传入原生实现，装配顺序与接线一行不改。
+ * 三个端口都可单独覆盖——缺哪一个就用该端口的 Web 形态。
+ */
+export interface BootPortOverrides {
+  /** 工程文件供给（缺省走 fetch 取资源根下的静态文件） */
+  files?: ProjectFilesPort;
+  /** 资源 URL 解析（缺省走 WebView 源根静态资源） */
+  resources?: ResourcePort;
+  /** 存档（桌面壳换成 Rust 命令：WebView 的 localStorage 会被清缓存带走） */
+  saves?: SavePort;
+}
+
+/**
+ * 装配并启动本宿主。失败时抛出（组合根负责把失败写进页面），
+ * 中途失败不会留下半启动的宿主：所有接线都在本函数内完成，抛出即放弃。
+ */
+export async function bootHost(options: HostBootOptions): Promise<void> {
+  const { dom } = options;
+
+  // 字体装配（纯展示，boot 一次性）：@font-face 注入 + 项目默认字体主题面，
+  // 先于一切视图建立——首个对话帧渲染时 CSS 变量已就位
+  installStoryFonts();
+
+  // —— 工程文件：清单与故事同走 ProjectFilesPort（组装归引擎纯函数，宿主不预解析）——
+  const filesPort: ProjectFilesPort =
+    options.ports?.files ??
+    createFetchProjectFilesPort({
+      manifest: options.manifestFile,
+      stories: options.stories,
+    });
+  const manifest: unknown = await filesPort.manifest();
+  const story: Story = await loadProject(filesPort);
+
+  // —— 适配器装配（Web 形态为缺省；原生形态经 ports 换掉资源与存档，契约不变）——
+  const reportError = createErrorReporter(dom);
+  const resourcePort: ResourcePort =
+    options.ports?.resources ?? createStaticResourcePort();
+  const audioPort: AudioPort = createWebAudioPort({ onError: reportError });
+  const savePort: SavePort = options.ports?.saves ?? createWebStorageSavePort();
+
+  // —— 层级（z 序）：内建默认 × 工程覆盖（project.json 的 shell.layers）——
+  const layerZ = resolveLayerZ(manifest);
+  // 视频端口的 z 在端口内部（与 DOM 层不同），故端口晚于首次落 DOM 建立，
+  // 由 getter 交给层级视图按需下发。
+  let videoPort: VideoPort | null = null;
+  const layers = createHostLayerZ({
+    dom,
+    layerZ,
+    readVideoPort: () => videoPort,
+  });
+  layers.apply();
+
+  videoPort = createWebVideoPort({
+    onError: reportError,
+    zIndex: layerZ.video,
+  });
+
+  // —— 存档壳配置：槽位（project.json 的 shell.saves.slots 可覆盖）——
+  fillSaveSlots(dom, manifest);
+
+  const engine = new StoryEngine(story, { historyLimit: 200, savePort });
+  const audio = createAudioRenderer(engine, audioPort, resourcePort, {
+    onError: reportError,
+  });
+  const video = createVideoRenderer(engine, videoPort, resourcePort, {
+    onError: reportError,
+    onVideoFinished: () => engine.videoFinished(), // 播放结束 → 引擎解除 video 等待
+  });
+
+  const toast = createToast({
+    dom,
+    durationMs: options.toastDurationMs ?? DEFAULT_TOAST_MS,
+  });
+  const dialogue = createDialogueView({
+    dom,
+    engine,
+    defaultCps: options.defaultCps ?? DEFAULT_TEXT_CPS,
+  });
+
+  wireEngine({
+    dom,
+    engine,
+    layers,
+    dialogue,
+    resources: resourcePort,
+    toast,
+    reportError,
+    // 故事级打字机设置（`text_typewriter` 命令）；未设置时按默认字速走
+    readTypingSetting: () =>
+      engine.get(SYS.typewriter) as TypingSetting | undefined,
+    // 读档后媒体位置需显式对齐：引擎只回状态，播放位置由渲染器自己同步
+    syncMedia: () => {
+      audio.sync();
+      video.sync();
+    },
+  });
+
+  const driveEffects = createHostEffects({ dom, engine });
+  startHostFrameLoop({
+    dialogue,
+    onMediaTick: () => audio.pollPosition(), // 媒体位置帧级回写
+    onFrame: driveEffects,
+  });
+  wireInput({ dom, engine, dialogue });
+  wireSaveSlots(dom, engine);
+
+  engine.start();
+}

package/template/__PROJECT__/src/host/dialogue-view.ts

@@ -0,0 +1,235 @@
+/**
+ * 对话与等待态渲染：说话人 / 正文 / NVL / 菜单 / 输入 / 等待六个等待态落到 DOM 上。
+ *
+ * 「每个等待态都必须有可推进出口」是本模块的硬要求——引擎能进入的等待态一个都不能少，
+ * 少了就是故事永久停滞。菜单与输入在渲染的同时挂好推进回调（`choose` / `input`），
+ * 等待态与视频态给可跳过的可见提示，小游戏态给 fail-closed 提示（本模板不带注册表，
+ * 不伪造完成）。
+ *
+ * 打字机实例与「当前已上屏的文本」都由本模块持有：帧循环每帧把可见文本交上来，
+ * 是否重写 DOM 由这里判定——文本没变就不碰 DOM，否则每帧一次 innerHTML 会把
+ * 行内标记重建成新节点。
+ *
+ * 显隐判定不在这里自算：NVL 是否接管、对话层是否让位都是展示层的纯函数
+ * （`isNvlActive` / `isDialogueSuppressed`），本模块只把结果写成样式。
+ */
+
+import { SYS } from "@lingfan-engine/core";
+import {
+  DEFAULT_TEXT_CPS,
+  Typewriter,
+  isDialogueSuppressed,
+  isNvlActive,
+  isTypingEnabled,
+  renderInlineMarkup,
+  resolveTypingCps,
+  sanitizeFont,
+  type TypingSetting,
+} from "@lingfan-engine/ui";
+import type { StageDom } from "./stage-dom";
+
+/** 对话视图要用到的引擎能力：读状态、推进菜单与输入 */
+export interface DialogueEngine {
+  /** 读一个状态键的当前值 */
+  get(key: string): unknown;
+  /** 选中一个菜单项（推进 menu 等待态） */
+  choose(optionId: string): void;
+  /** 提交输入（推进 input 等待态） */
+  input(value: string): void;
+}
+
+/**
+ * 对话视图的输入：节点句柄表、引擎能力面与字速兜底。
+ * 故事自己声明了打字机速度时以故事为准，`defaultCps` 只在故事未声明时生效。
+ */
+export interface DialogueViewOptions {
+  /** 常驻节点句柄表 */
+  dom: StageDom;
+  /** 引擎能力面 */
+  engine: DialogueEngine;
+  /** 故事未声明字速时的兜底（可见字符 / 秒）；缺省 = 展示层给出的默认字速 */
+  defaultCps?: number;
+}
+
+/** 对话视图句柄：状态键的每条意图各有一个落点，另有两个帧循环用的钩子 */
+export interface DialogueView {
+  /** 等待态切换：提示符、对话层让位与选项区形态一起更新 */
+  setWaiting(waiting: string): void;
+  /** 对话框显隐（`window show|hide`） */
+  setDialogVisible(hidden: boolean): void;
+  /** NVL 模式切换 */
+  setNvlMode(mode: string): void;
+  /** NVL 缓冲行整体替换 */
+  setNvlBuffer(lines: readonly string[]): void;
+  /** 菜单选项或输入提示变了：选项区整体重建 */
+  setMenuChanged(): void;
+  /** 新的一句正文：按故事级打字机设置决定整句直出还是逐字上屏 */
+  setDialogText(text: string, setting: TypingSetting | undefined): void;
+  /** 小游戏接管：提示里带上 game 名，便于作者定位 */
+  setMinigame(game: string): void;
+  /** 读当前打字机（整句直出时为 null） */
+  readTypewriter(): Typewriter | null;
+  /** 上交本帧的可见文本（未变化时不重写 DOM） */
+  onText(visible: string): void;
+}
+
+/**
+ * 造一个对话视图。六个等待态与两个显隐开关的状态都收在闭包里，每实例一份——
+ * 放在模块级会让同一页面的两个宿主互相串扰。
+ */
+export function createDialogueView(options: DialogueViewOptions): DialogueView {
+  const { dom, engine } = options;
+  const defaultCps = options.defaultCps ?? DEFAULT_TEXT_CPS;
+
+  /** 当前打字机；整句直出时为 null */
+  let typewriter: Typewriter | null = null;
+  /** 已上屏的文本：帧循环据此判断要不要重写 */
+  let shown = "";
+  /** 故事显式隐藏对话框（`window hide`） */
+  let dialogHidden = false;
+  /** NVL 模式（`"none"` = 关闭） */
+  let nvlMode = "none";
+  /** NVL 缓冲行（整体替换） */
+  let nvlLines: readonly string[] = [];
+  /** 当前等待态（决定对话层让位与选项区形态） */
+  let waiting = "none";
+  /** 小游戏接管名（提示文案用） */
+  let minigameId = "";
+
+  /**
+   * 对话层与 NVL 层的显隐。
+   * 两个让位理由独立：NVL 接管、故事显式隐藏、以及视频等待期——视频要占满舞台，
+   * 压不住底部对话框会很难看。NVL 内容每次重算，因为模式与缓冲行是分开到达的两条状态。
+   */
+  function applyDialogueVisibility(): void {
+    const nvl = isNvlActive(nvlMode, nvlLines);
+    const suppressed = isDialogueSuppressed({
+      nvlActive: nvl,
+      hidden: dialogHidden,
+      waiting,
+    });
+    dom.dialogue.style.display = suppressed ? "none" : "";
+    dom.nvl.style.display = nvl ? "block" : "none";
+    if (nvl) {
+      dom.nvl.innerHTML = nvlLines
+        .map((line) => renderInlineMarkup(line))
+        .join("<br>");
+    }
+  }
+
+  /**
+   * 本句字体落 DOM（随每句正文调用）：引擎分辨链结果（SYS.dialogFont）过字符集
+   * 白名单后上正文元素；空或非法名回落 CSS 变量（--lf-story-font，项目默认字体档）。
+   */
+  function applySentenceFont(): void {
+    const raw = engine.get(SYS.dialogFont);
+    const font = typeof raw === "string" ? sanitizeFont(raw) : null;
+    if (font !== null) dom.text.style.fontFamily = `'${font}'`;
+    else dom.text.style.removeProperty("font-family");
+  }
+
+  /** 等待态 UI：**每个等待态都必须有可推进出口**（否则故事停滞） */
+  function renderChoices(): void {
+    dom.choices.replaceChildren();
+    if (waiting === "menu") {
+      const prompt = document.createElement("p");
+      prompt.className = "prompt";
+      prompt.textContent = String(engine.get(SYS.menuPrompt) ?? "");
+      dom.choices.append(prompt);
+      const texts = (engine.get(SYS.menuOptions) as string[] | undefined) ?? [];
+      const targets =
+        (engine.get(SYS.menuTargets) as string[] | undefined) ?? [];
+      texts.forEach((label, i) => {
+        const button = document.createElement("button");
+        button.className = "choice";
+        button.type = "button";
+        button.textContent = label;
+        button.addEventListener("click", () => engine.choose(targets[i] ?? ""));
+        dom.choices.append(button);
+      });
+    } else if (waiting === "input") {
+      const prompt = document.createElement("p");
+      prompt.className = "prompt";
+      prompt.textContent = String(engine.get(SYS.inputPrompt) ?? "");
+      const row = document.createElement("form");
+      row.className = "input-row";
+      const input = document.createElement("input");
+      input.type = "text";
+      input.maxLength = 20;
+      const ok = document.createElement("button");
+      ok.type = "submit";
+      ok.textContent = "确定";
+      row.append(input, ok);
+      row.addEventListener("submit", (event) => {
+        event.preventDefault();
+        const value = input.value.trim();
+        if (value === "") return;
+        engine.input(value);
+      });
+      dom.choices.append(prompt, row);
+      input.focus();
+    } else if (waiting === "wait" || waiting === "video") {
+      const note = document.createElement("p");
+      note.className = "note";
+      note.textContent =
+        waiting === "video"
+          ? "视频播放中……（点击或空格跳过）"
+          : "等待中……（点击或空格跳过）";
+      dom.choices.append(note);
+    } else if (waiting === "minigame") {
+      const banner = document.createElement("p");
+      banner.className = "banner";
+      banner.textContent =
+        `故事进入了小游戏等待${minigameId === "" ? "" : `：${minigameId}`}。` +
+        "本模板不带小游戏注册表（fail-closed：不伪造完成）——要在宿主里支持，" +
+        "请用 `createMinigameRegistry` 注册，并在 mount 事件后调用 engine.resolveMinigame(result)。";
+      dom.choices.append(banner);
+    }
+  }
+
+  return {
+    setWaiting(next: string): void {
+      waiting = next;
+      dom.hint.textContent = waiting === "dialog" ? "▼" : "";
+      applyDialogueVisibility();
+      renderChoices();
+    },
+    setDialogVisible(hidden: boolean): void {
+      dialogHidden = hidden;
+      applyDialogueVisibility();
+    },
+    setNvlMode(mode: string): void {
+      nvlMode = mode;
+      applyDialogueVisibility();
+    },
+    setNvlBuffer(lines: readonly string[]): void {
+      nvlLines = lines;
+      applyDialogueVisibility();
+    },
+    setMenuChanged(): void {
+      renderChoices();
+    },
+    setDialogText(text: string, setting: TypingSetting | undefined): void {
+      // 故事级打字机设置（`text_typewriter` 命令）；enabled=false = 整句即时
+      const cps = resolveTypingCps(setting, defaultCps);
+      typewriter = isTypingEnabled(setting) ? new Typewriter(text, cps) : null;
+      applySentenceFont();
+      if (typewriter === null) {
+        shown = text;
+        dom.text.innerHTML = renderInlineMarkup(text);
+      }
+    },
+    setMinigame(game: string): void {
+      minigameId = game;
+      renderChoices();
+    },
+    readTypewriter(): Typewriter | null {
+      return typewriter;
+    },
+    onText(visible: string): void {
+      if (visible === shown) return;
+      shown = visible;
+      dom.text.innerHTML = renderInlineMarkup(visible);
+    },
+  };
+}

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

@@ -0,0 +1,68 @@
+/**
+ * 帧驱动表现：把引擎里的动画描述逐帧写成 DOM。
+ *
+ * 机制（累计、插值、播毕时机）在展示层（`createVisualEffects`），本文件只做两件本宿主
+ * 独有的事：把引擎与本宿主的 DOM 接上，以及把数值属性落成 CSS 声明。
+ *
+ * 元素动画**必须交回引擎**（`animationFinished`）：否则动画队列只增不减（长会话泄漏），
+ * 元素也永远到不了终值——终值是引擎在播毕后写回元素属性的。
+ */
+
+import { SYS, type StoryEngine } from "@lingfan-engine/core";
+import { createVisualEffects, resolveAnimatedStyle } from "@lingfan-engine/ui";
+import type { StageDom } from "./stage-dom";
+
+/** 逐帧驱动函数的输入：节点句柄表与引擎（三个播毕交回都直连引擎） */
+export interface HostEffectsOptions {
+  /** 常驻节点句柄表 */
+  dom: StageDom;
+  /** 引擎：动画队列、转场与震动的启动键、三个播毕交回 */
+  engine: StoryEngine;
+}
+
+/** 造本宿主的逐帧驱动函数：宿主每帧调用一次，传入距上一帧的秒数 */
+export function createHostEffects(
+  options: HostEffectsOptions,
+): (dt: number) => void {
+  const { dom, engine } = options;
+  return createVisualEffects({
+    source: {
+      animations: () => engine.animations(),
+      transition: () =>
+        engine.get(SYS.transition) as { duration: number } | undefined,
+      shake: () =>
+        engine.get(SYS.shake) as
+          { intensity: number; duration: number } | undefined,
+      animationFinished: (seq) => engine.animationFinished(seq),
+      transitionFinished: () => engine.transitionFinished(),
+      shakeFinished: () => engine.shakeFinished(),
+    },
+    animation: {
+      // 动画节点在舞台层里按 data-lf-id 找（元素渲染器写入的定位锚）
+      onAnimatedProperty: (target, property, value) => {
+        const node = dom.stage.querySelector<HTMLElement>(
+          `[data-lf-id="${target}"]`,
+        );
+        if (node === null) return;
+        const style = resolveAnimatedStyle(property, value);
+        // 未识别的属性跳过：写一个空声明会把元素已有样式抹掉
+        if (style !== null) Object.assign(node.style, style);
+      },
+    },
+    surface: {
+      onTransitionFrame: (opacity) => {
+        dom.transition.style.display = "block";
+        dom.transition.style.opacity = String(opacity);
+      },
+      onTransitionDone: () => {
+        dom.transition.style.display = "none";
+      },
+      onShakeFrame: (x, y) => {
+        dom.root.style.transform = `translate(${x}px, ${y}px)`;
+      },
+      onShakeDone: () => {
+        dom.root.style.transform = "";
+      },
+    },
+  });
+}

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

@@ -0,0 +1,206 @@
+/**
+ * 引擎订阅：把状态变更与出站事件翻译成本宿主的视图调用，并管好舞台元素层。
+ *
+ * 状态键怎么解读、缺省怎么回退，收在展示层的状态分发器里（`createStateView`）——
+ * 本文件只做两件事：给出本宿主订阅的键表，以及把每条**视图意图**落到自己的视图上。
+ *
+ * 元素层（`SYS.elements`）一并在此：它是同一路状态变更的落点，且两处都要 fail-closed
+ * 上报——**元素类型未注册**与**元素命令未注册**都不静默跳过，作者写了却看不见效果，
+ * 比报一行错难查得多。
+ *
+ * 出站事件按 `payload.kind` 分派：致命错误写错误条，提示类走 toast，存档类给回执，
+ * 小游戏挂载换一条可见的 fail-closed 提示（模板不带注册表，不伪造完成）。
+ */
+
+import {
+  SYS,
+  instanceZLayer,
+  type ElementInstance,
+  type OutboundPayload,
+  type ResourcePort,
+  type StoryEngine,
+} from "@lingfan-engine/core";
+import {
+  createCommandRegistry,
+  createElementRegistry,
+  createElementResourceResolver,
+  createDomRenderPort,
+  createStateView,
+  registerBuiltinElementRenderers,
+  renderElementTree,
+  resolveElementAction,
+  type LayerView,
+  type StateIntent,
+  type TypingSetting,
+} from "@lingfan-engine/ui";
+import type { StageDom } from "./stage-dom";
+import type { DialogueView } from "./dialogue-view";
+
+/** 宿主订阅的状态键表：与引擎的键名一一对应，换键名只改这里 */
+const STATE_KEYS = {
+  speaker: SYS.currentDialogSpeaker,
+  dialogText: SYS.currentDialogText,
+  waiting: SYS.waiting,
+  nvlMode: SYS.nvlMode,
+  nvlBuffer: SYS.nvlBuffer,
+  menuOptions: SYS.menuOptions,
+  menuTargets: SYS.menuTargets,
+  dialogVisible: SYS.dialogVisible,
+  elements: SYS.elements,
+} as const;
+
+/**
+ * 订阅接线的输入：节点句柄表、引擎、以及本宿主已有的几个视图与出口。
+ * 本文件只做「引擎说什么 → 谁去落 DOM」的分发，不自己实现任何渲染。
+ */
+export interface HostWiringOptions {
+  /** 常驻节点句柄表 */
+  dom: StageDom;
+  /** 引擎：订阅、状态读取与元素命令面的落地 */
+  engine: StoryEngine;
+  /** 层级视图：实例级 z 的收纳 */
+  layers: LayerView;
+  /** 对话视图：对话 / 等待 / 选项 / NVL 的落点 */
+  dialogue: DialogueView;
+  /** 资源端口：元素资源的逻辑寻址 */
+  resources: ResourcePort;
+  /** 提示条 */
+  toast(text: string): void;
+  /** 诊断出口（页面错误条 + 控制台） */
+  reportError(message: string): void;
+  /** 读当前故事级打字机设置 */
+  readTypingSetting(): TypingSetting | undefined;
+  /** 存档 / 读档完成后的显式对齐（音频与视频渲染器） */
+  syncMedia(): void;
+}
+
+/** 接线状态订阅、元素层与出站事件 */
+export function wireEngine(options: HostWiringOptions): void {
+  const { dom, engine, layers, dialogue, resources, reportError } = options;
+
+  // —— 舞台元素层：注册内建渲染器，装配命令表与资源解析 ——
+  const elementRegistry = createElementRegistry();
+  registerBuiltinElementRenderers(elementRegistry);
+  // 元素 `cmd` 的业务命令注册表：未注册 fail-closed（不静默吞掉）
+  const commands = createCommandRegistry();
+  let elements: readonly ElementInstance[] = [];
+
+  // 资源解析缓存 = @lingfan-engine/ui 共用实现（宿主只提供端口与重渲染回调）
+  const elementResources = createElementResourceResolver({
+    resolve: (path) => resources.resolve(path),
+    onResolved: () => renderElements(),
+  });
+
+  /** 意图 → 命令：`nav` → 核心 navigate；`cmd` → 宿主命令注册表（`value` 点击时插值） */
+  function activateElement(element: ElementInstance): void {
+    const action = resolveElementAction(element.props);
+    if (action.kind === "nav") {
+      engine.navigate(action.target);
+      return;
+    }
+    if (action.kind !== "cmd") return;
+    const handler = commands.get(action.name);
+    if (handler === undefined) {
+      reportError(`元素命令未注册：${action.name}（宿主需经命令注册表提供）`);
+      return;
+    }
+    handler(
+      action.value === undefined ? undefined : engine.interpolate(action.value),
+      element,
+    );
+  }
+
+  function renderElements(): void {
+    renderElementTree({
+      registry: elementRegistry,
+      port: createDomRenderPort(dom.stage),
+      elements,
+      activate: activateElement,
+      resolveResource: elementResources.resolveForElement,
+      onUnknownType: (type) => reportError(`元素类型未注册：${type}`),
+    });
+  }
+
+  // —— 状态变更 → 视图意图 → 本宿主的落点 ——
+  const toIntent = createStateView({
+    keys: STATE_KEYS,
+    resolveLayer: (key) => instanceZLayer(key),
+    readTypingSetting: () => options.readTypingSetting(),
+    readCharacterColor: (name) => {
+      const color = engine.getCharacter(name)?.color;
+      return typeof color === "string" ? color : null;
+    },
+  });
+
+  /** 一条视图意图落到本宿主（分支与状态键一一对应） */
+  function applyIntent(intent: StateIntent): void {
+    switch (intent.kind) {
+      case "layer":
+        layers.setOverride(intent.layer, intent.z);
+        layers.apply();
+        if (intent.layer === "video") layers.applyVideo(); // 视频层在端口内部
+        return;
+      case "speaker":
+        dom.speaker.textContent = intent.text;
+        dom.speaker.style.color = intent.color ?? "";
+        return;
+      case "dialog-text":
+        dialogue.setDialogText(intent.text, intent.setting);
+        return;
+      case "waiting":
+        dialogue.setWaiting(intent.waiting);
+        return;
+      case "nvl-mode":
+        dialogue.setNvlMode(intent.mode);
+        return;
+      case "nvl-buffer":
+        dialogue.setNvlBuffer(intent.lines);
+        return;
+      case "choices":
+        dialogue.setMenuChanged();
+        return;
+      case "dialog-visible":
+        dialogue.setDialogVisible(intent.hidden);
+        return;
+      case "elements":
+        elements = intent.elements;
+        renderElements();
+        return;
+      case "none":
+        return;
+    }
+  }
+
+  engine.onStateChanged(({ key, value }) => {
+    applyIntent(toIntent(key, value));
+  });
+
+  /** 出站事件：致命错误 / 提示 / 小游戏挂载 / 存档回执 */
+  function applyEvent(payload: OutboundPayload): void {
+    switch (payload.kind) {
+      case "engine.error":
+        dom.error.textContent = `[${payload.code}] ${payload.message}`;
+        console.error(`[engine] ${payload.code}: ${payload.message}`);
+        return;
+      case "notify":
+        options.toast(payload.text);
+        return;
+      case "minigame.mount":
+        dialogue.setMinigame(payload.game);
+        return;
+      case "save.done":
+        options.toast(`已保存到 ${payload.slot}`);
+        return;
+      case "load.done":
+        options.toast(`已读取 ${payload.slot}`);
+        options.syncMedia();
+        return;
+      default:
+        return;
+    }
+  }
+
+  engine.onEvent(({ payload }) => {
+    applyEvent(payload);
+  });
+}