@lingfan-engine/ui 0.0.0-stage → 0.1.0

package/src/overlay/notify-view.ts

@@ -0,0 +1,32 @@
+/**
+ * 通知层视图模型：把引擎的 `notify` 事件算成一条 toast 的模型（**不碰节点、不管生命周期**）。
+ *
+ * 停留时长归端口调用的参数（`OverlaySurface.pushNotification(item, durationMs)`）——
+ * 本模块只决定「长什么样」：模板给出语气类名与正文片段。
+ */
+import { builtinNotifyTemplate, toNotifyTone } from "../notify/templates";
+import type { NotifyTemplateRegistry } from "../notify/templates";
+import type { NotifyPayload } from "@lingfan-engine/core";
+import type { NotifyLayerItem } from "./surface";
+
+/** 通知层的装配输入：模板注册表可选 */
+export interface NotifyViewDeps {
+  templates?: NotifyTemplateRegistry;
+}
+
+/**
+ * 算出一条通知模型：正文交给模板上色，本函数只把模板产物搬成模型。
+ *
+ * 与旧版不同的是：这里不再持有定时器——到时移除由宿主的渲染体系负责，
+ * 因此 `clear()`（撤销在排定时器）也一并移到端口（`OverlaySurface.clear()`）。
+ */
+export function notifyLayerItem(
+  payload: NotifyPayload,
+  deps: NotifyViewDeps = {},
+): NotifyLayerItem {
+  const built = (deps.templates?.resolve(null) ?? builtinNotifyTemplate)({
+    text: payload.text,
+    tone: toNotifyTone(payload.notifyType),
+  });
+  return { rootClass: built.rootClass, bodyHtml: built.bodyHtml };
+}

package/src/overlay/projector.ts

@@ -0,0 +1,286 @@
+/**
+ * 渲染状态投影：把引擎的状态读成一份界面直接可用的渲染态。
+ *
+ * **为什么要有这一层**：界面不持有叙事真相，所有渲染态都是引擎状态经读口投影出来的。
+ * 投影分两条入口——引擎的 `ValueChanged` 事件（增量，一次一个键）与 `sync()`
+ * （全量，读档/回溯后整体对齐）——两条入口读的是同一批字段，因此取值口径集中在这里，
+ * 不各写一份。
+ *
+ * 每份投影状态都归实例所有（本模块只导出工厂，不持有任何跨实例的共享变量）：
+ * 两个覆盖层实例各有自己的说话人、等待态与打字机，互不串扰。
+ */
+import { instanceZLayer, SYS } from "@lingfan-engine/core";
+import type {
+  ElementInstance,
+  StateReader,
+  StoryEngine,
+} from "@lingfan-engine/core";
+import { renderDialogueLine } from "../dialogue/textView";
+import { Typewriter } from "../dialogue/typewriter";
+import { setLayerOverride } from "./layer-z";
+import type { LayerZController } from "./layer-z";
+import type { NarrativeOverlayView } from "./types";
+
+/** 需要重渲的渲染目标（顺序即重渲顺序） */
+export type RenderTarget = "dialogue" | "choices" | "elements";
+
+/** 一次状态变更的处理结果：层级键走层级重写，其余键走渲染目标列表 */
+export type ChangeEffect =
+  { kind: "layers" } | { kind: "render"; targets: readonly RenderTarget[] };
+
+/**
+ * 渲染态：全部字段都只由状态投影写入，
+ * 除打字进度（`shownText` / `typewriter`）外一律直接来自读口。
+ */
+export interface RenderState {
+  speaker: string;
+  speakerColor: string;
+  /** 本句对话字体（引擎分辨链解析结果；空串 = 无声明，宿主回落项目默认/浏览器回退） */
+  dialogFont: string;
+  text: string;
+  canAdvance: boolean;
+  waiting: string;
+  menuPrompt: string;
+  menuOptions: Array<{ text: string; target: string }>;
+  inputPrompt: string;
+  nvlMode: string;
+  nvlBuffer: string[];
+  elementList: ElementInstance[];
+  dialogHidden: boolean;
+  typewriter: Typewriter | null;
+  /** 打字机当前可见前缀（与 `text` 一并决定正文 HTML） */
+  shownText: string;
+  /** 实例级层级 z（每实例一份） */
+  layerZ: LayerZController;
+}
+
+/**
+ * 投影器：持有**一个实例**的渲染态，并把状态变更翻译成「该重渲什么」。
+ *
+ * 两条入口（增量 `applyChange` / 全量 `sync`）读同一批字段，因此不会出现
+ * 「读档后与逐条变更后长得不一样」。渲染目标集也是这里算出来的——视图层只负责
+ * 按 `RenderTarget` 重画，不自判该不该画。
+ */
+export interface Projector {
+  readonly state: RenderState;
+  /** 应用一次增量状态变更；层级键返回 `layers`，其余返回需要重渲的目标 */
+  applyChange(key: string, value: unknown): ChangeEffect;
+  /** 全量对齐（读档 / 回溯完成后调用）；返回需要重渲的目标 */
+  sync(): readonly RenderTarget[];
+  /** 当前正文 HTML（打字中 = 可见前缀；打完 = 整句） */
+  lineHtml(): string;
+  /** 渲染投影（只读快照） */
+  view(): NarrativeOverlayView;
+  /** 重建打字机（新句子到达时） */
+  resetTypewriter(): void;
+  /** 推进打字机一帧；返回可见前缀是否变化（变了才需要重渲） */
+  tickTypewriter(dt: number): boolean;
+  /** 瞬间打完当前句；返回是否确实有未完成的打字（false = 直接转推进） */
+  finishTypewriter(): boolean;
+}
+
+/**
+ * 造一个投影器：状态从空投影起步，需调 `sync()` 做首次全量对齐。
+ *
+ * 打字机随句子重建，`textSpeed` 在每次重建时读取（改它不影响正在打的这句）。
+ * 层级 z 控制器由调用方注入——同一份控制器可被多个投影器共享（层级属覆盖层而非投影）。
+ */
+export function createProjector(deps: {
+  reader: StateReader;
+  engine: StoryEngine;
+  layerZ: LayerZController;
+  textSpeed: number;
+}): Projector {
+  const { reader, engine } = deps;
+
+  const state: RenderState = {
+    speaker: "",
+    speakerColor: "",
+    dialogFont: "",
+    text: "",
+    canAdvance: false,
+    waiting: "none",
+    menuPrompt: "",
+    menuOptions: [],
+    inputPrompt: "",
+    nvlMode: "none",
+    nvlBuffer: [],
+    elementList: [],
+    dialogHidden: false,
+    typewriter: null,
+    shownText: "",
+    layerZ: deps.layerZ,
+  };
+
+  /**
+   * 读菜单选项：文本与目标列成对。
+   * 两个键分属不同 SSOT 条目，任一到达都重读**成对数据**（避免只更新一半）。
+   */
+  function readMenuOptions(): void {
+    state.menuOptions = reader.menuChoices();
+  }
+
+  /** 说话人颜色派生（幂等）：命令覆盖色 > 角色定义色 > 空串 */
+  function refreshSpeakerColor(): void {
+    const override = reader.dialogColor();
+    const def = engine.getCharacter(state.speaker);
+    state.speakerColor = (override !== "" ? override : def?.color) ?? "";
+  }
+
+  /**
+   * 重建打字机（新句子到达、或全量对齐时）。
+   * 覆盖色与说话人色同源刷新：引擎写 `color` 与 `speaker` 是两个独立条目，
+   * 派生值不依赖事件到达顺序，重算幂等。
+   */
+  function resetTypewriter(): void {
+    state.typewriter = new Typewriter(state.text, deps.textSpeed);
+    state.shownText = state.typewriter.visible;
+  }
+
+  function applyChange(key: string, value: unknown): ChangeEffect {
+    const zLayer = instanceZLayer(key);
+    if (zLayer !== undefined) {
+      setLayerOverride(
+        state.layerZ,
+        zLayer,
+        typeof value === "number" ? value : undefined,
+      );
+      state.layerZ.apply();
+      return { kind: "layers" };
+    }
+
+    if (key === SYS.currentDialogSpeaker) {
+      state.speaker = reader.dialogSpeaker();
+      refreshSpeakerColor();
+      return { kind: "render", targets: ["dialogue"] };
+    }
+    if (key === SYS.currentDialogColor) {
+      // 覆盖色与说话人色同源刷新（派生值不依赖事件到达顺序，重算幂等）
+      refreshSpeakerColor();
+      return { kind: "render", targets: ["dialogue"] };
+    }
+    if (key === SYS.dialogFont) {
+      state.dialogFont = reader.dialogFont();
+      return { kind: "render", targets: ["dialogue"] };
+    }
+    if (key === SYS.currentDialogText) {
+      state.text = reader.dialogText();
+      resetTypewriter();
+      return { kind: "render", targets: ["dialogue"] };
+    }
+    if (key === SYS.waiting) {
+      const next = reader.waiting();
+      state.waiting = next === "" ? "none" : next;
+      state.canAdvance = state.waiting === "dialog";
+      return { kind: "render", targets: ["dialogue", "choices"] };
+    }
+    if (key === SYS.dialogVisible) {
+      state.dialogHidden = reader.dialogHidden();
+      return { kind: "render", targets: ["dialogue"] };
+    }
+    if (key === SYS.menuPrompt) {
+      state.menuPrompt = reader.menuPrompt();
+      return { kind: "render", targets: ["choices"] };
+    }
+    if (key === SYS.menuOptions || key === SYS.menuTargets) {
+      readMenuOptions();
+      return { kind: "render", targets: ["choices"] };
+    }
+    if (key === SYS.inputPrompt) {
+      state.inputPrompt = reader.inputPrompt();
+      return { kind: "render", targets: ["choices"] };
+    }
+    if (key === SYS.nvlMode) {
+      const next = reader.nvlMode();
+      state.nvlMode = next === "" ? "none" : next;
+      return { kind: "render", targets: [] };
+    }
+    if (key === SYS.nvlBuffer) {
+      state.nvlBuffer = reader.nvlLines();
+      return { kind: "render", targets: [] };
+    }
+    if (key === SYS.elements) {
+      state.elementList = reader.elements();
+      return { kind: "render", targets: ["elements"] };
+    }
+    // 与叙事渲染无关的键：仍通知宿主投影变化，但不触发任何层重渲
+    return { kind: "render", targets: [] };
+  }
+
+  function sync(): readonly RenderTarget[] {
+    state.speaker = reader.dialogSpeaker();
+    refreshSpeakerColor();
+    state.dialogFont = reader.dialogFont();
+    state.text = reader.dialogText();
+    const waitState = reader.waiting();
+    state.waiting = waitState === "" ? "none" : waitState;
+    state.canAdvance = state.waiting === "dialog";
+    state.menuPrompt = reader.menuPrompt();
+    readMenuOptions();
+    state.inputPrompt = reader.inputPrompt();
+    const mode = reader.nvlMode();
+    state.nvlMode = mode === "" ? "none" : mode;
+    state.nvlBuffer = reader.nvlLines();
+    state.dialogHidden = reader.dialogHidden();
+    state.elementList = reader.elements();
+    resetTypewriter();
+    state.layerZ.overrides = reader.instanceZOverrides();
+    state.layerZ.apply();
+    return ["dialogue", "choices", "elements"];
+  }
+
+  function lineHtml(): string {
+    return renderDialogueLine({
+      text: state.text,
+      typed:
+        state.typewriter !== null && !state.typewriter.done
+          ? state.shownText
+          : undefined,
+    }).html;
+  }
+
+  function view(): NarrativeOverlayView {
+    return {
+      speaker: state.speaker,
+      text: state.text,
+      lineHtml: lineHtml(),
+      canAdvance: state.canAdvance,
+      waiting: state.waiting,
+      menuPrompt: state.menuPrompt,
+      menuOptions: state.menuOptions,
+      inputPrompt: state.inputPrompt,
+      nvlMode: state.nvlMode,
+      nvlLines: state.nvlBuffer,
+      hasElements: state.elementList.length > 0,
+    };
+  }
+
+  function tickTypewriter(dt: number): boolean {
+    const tw = state.typewriter;
+    if (tw === null || tw.done) return false;
+    tw.tick(dt);
+    const next = tw.visible;
+    if (next === state.shownText) return false;
+    state.shownText = next;
+    return true;
+  }
+
+  function finishTypewriter(): boolean {
+    const tw = state.typewriter;
+    if (tw === null || tw.done) return false;
+    tw.click();
+    state.shownText = tw.visible;
+    return true;
+  }
+
+  return {
+    state,
+    applyChange,
+    sync,
+    lineHtml,
+    view,
+    resetTypewriter,
+    tickTypewriter,
+    finishTypewriter,
+  };
+}

package/src/overlay/surface.ts

@@ -0,0 +1,125 @@
+/**
+ * 覆盖层表面端口：中立面只描述「每一层要显示什么」，落到哪个渲染体系由宿主决定。
+ *
+ * **解决的问题**：覆盖层的五层（舞台 / 元素 / 转场 / 对话 / 选择 / 通知 / 接管）原先直接由
+ * 展示层建 `HTMLElement` 并写 `style` / `innerHTML`，于是「叙事能力嵌进已有游戏」这条路上，
+ * 任何非 Web 宿主都得自己重写一份渲染接线。
+ *
+ * **为什么不是元素层那种描述树**：元素层每帧整棵重建即可（`RenderSpec` 无状态、可序列化）；
+ * 覆盖层不是——对话层有打字机**逐帧改同一处文本**的高频写，通知层有**生命周期**（到时移除），
+ * 输入形态有**焦点与光标**（整层重建会丢正在输入的字）。因此这里传的是**每层的视图模型**
+ * （纯数据）+ 一次整层提交：模型怎么算归中立核心，怎么落到节点/组件/`setData` 归宿主。
+ *
+ * **契约边界**：本文件不得出现任何平台类型（`HTMLElement` / `document` / `window` …）。
+ * DOM 实现见 `packages/ui/src/dom/overlay-surface.ts`（`createDomOverlaySurface`）。
+ */
+import type { RenderPort } from "../element/spec";
+import type { FrameSource } from "../host/frame-loop";
+
+/** 覆盖层的层位（中立词表；与 DOM 无关，宿主按自己的层级体系落地） */
+export type OverlayLayerId =
+  | "stage"
+  | "element"
+  | "transition"
+  | "dialogue"
+  | "choices"
+  | "takeover"
+  | "notifications";
+
+/**
+ * 对话层的一次整层提交。
+ *
+ * 骨架固定为「说话人 / 正文 / 推进提示」三段，皮肤由 `rootClass` 与三个 HTML 片段表达；
+ * `visible` 为假时**隐藏而非清空**（恢复时不闪）——隐藏与清空是两种语义，故显式入模型。
+ */
+export interface DialogueLayerView {
+  /** 皮肤类名（模板产出；DOM 侧拼在基类之后） */
+  rootClass: string;
+  /** 本层是否可见（假 = 让位给菜单/输入/视频层） */
+  visible: boolean;
+  /** 说话人片段 HTML（空串 = 本句无说话人） */
+  speakerHtml: string;
+  /** 说话人配色（空串 = 用皮肤默认） */
+  speakerColor: string;
+  /** 正文片段 HTML（打字中 = 可见前缀） */
+  bodyHtml: string;
+  /** 正文整句字体族（已过白名单校验；空串 = 不设，回落宿主 CSS/浏览器默认） */
+  bodyFont: string;
+  /** 推进提示片段 HTML（空串 = 本句无提示） */
+  hintHtml: string;
+}
+
+/** 选择层的一个选项（`html` 是呈现片段，`label` 是可访问名，`target` 是回核心的列 id） */
+export interface ChoicesLayerOption {
+  html: string;
+  label: string;
+  target: string;
+}
+
+/** 选择层的输入形态参数（表单提交回核心） */
+export interface ChoicesLayerInput {
+  /** 输入提示（同时作为输入框的可访问名；空串 = 用宿主文案「输入」） */
+  prompt: string;
+  /** 提交按钮显示文本 */
+  submitText: string;
+}
+
+/**
+ * 选择层的一次整层提交（菜单与输入两形态互斥，用哪个由哪个字段非空表达）。
+ *
+ * 层内不存在需要保留的局部状态（原文如此），因此每次重渲都整体重建；
+ * 点击与提交不是模型的一部分——它们是端口上的两条回调（见 `OverlaySurface`）。
+ */
+export interface ChoicesLayerView {
+  /** 皮肤类名（菜单形态的模板产出；输入形态为空串） */
+  rootClass: string;
+  /** 菜单提示片段 HTML（空串 = 无提示） */
+  promptHtml: string;
+  /** 菜单选项（顺序即呈现顺序；输入形态为空数组） */
+  options: readonly ChoicesLayerOption[];
+  /** 输入形态参数（菜单形态为 `null`） */
+  input: ChoicesLayerInput | null;
+}
+
+/** 通知层的一条 toast（停留时长不在这里——它由端口调用的参数给出的毫秒数决定） */
+export interface NotifyLayerItem {
+  /** 语气类名（模板产出） */
+  rootClass: string;
+  /** 正文片段 HTML */
+  bodyHtml: string;
+}
+
+/**
+ * 覆盖层表面端口：宿主实现它，把每层模型落到自己的渲染体系。
+ *
+ * 两个 `RenderPort`（舞台 / 元素）复用元素层的描述树词表；其余层各有自己的整层提交方法。
+ * 时钟与定时器不进中立面：帧能力经 `frame` 注入，通知的到时移除归宿主实现。
+ */
+export interface OverlaySurface {
+  /** 帧源（宿主平台的「下一帧」能力；无帧环境返回一个永不回调的帧源） */
+  readonly frame: FrameSource;
+  /** 舞台层：背景 / 立绘（宿主也可自行往这里提描述树） */
+  readonly stage: RenderPort;
+  /** 元素层：元素树渲染目标 */
+  readonly elements: RenderPort;
+  /** 层级 z 下发（幂等，可反复调用；未显式指定的层走宿主默认） */
+  setLayerZ(layer: OverlayLayerId, z: number): void;
+  /** 提交对话层（整层重建） */
+  setDialogue(view: DialogueLayerView): void;
+  /** 提交选择层；`null` = 整层隐藏（菜单/输入都结束） */
+  setChoices(view: ChoicesLayerView | null): void;
+  /** 上屏一条通知，`durationMs` 毫秒后由宿主移除 */
+  pushNotification(item: NotifyLayerItem, durationMs: number): void;
+  /**
+   * 卸载收尾：清空全部层与在排定时器。
+   *
+   * 注意**接管层与转场遮罩不在这里**：它们是宿主自己的层（外部玩法系统 / 转场动画），
+   * 中立核心从不驱动它们（引擎只把它们的 z 交下来）。Web 宿主用 DOM 实现暴露的 `nodes`
+   * 或 `stage` 端口自行落地；非 Web 宿主用自己的渲染体系，不需要本端口提供方法。
+   */
+  clear(): void;
+  /** 选择出口（装配器在构造时挂上；点是玩家的动作，不是模型的一部分） */
+  onChoose?: (target: string) => void;
+  /** 输入提交出口（装配器在构造时挂上） */
+  onSubmitInput?: (value: string) => void;
+}

package/src/overlay/types.ts

@@ -0,0 +1,124 @@
+/**
+ * 叙事覆盖层的对外契约：表面端口、渲染投影、装配选项与实例方法。
+ *
+ * 这些类型是宿主与覆盖层之间的边界——实现可以按职责拆开，边界形状不动；
+ * 宿主只依赖这里声明的名字，不依赖覆盖层内部的模块划分。
+ *
+ * **渲染落点不在本文件**：覆盖层只产出每层的视图模型，落到哪个渲染体系由宿主实现的
+ * `OverlaySurface` 决定（Web 实现见 `packages/ui/src/dom/overlay-surface.ts`）。
+ * 因此本文件不出现任何平台类型。
+ */
+import type {
+  ElementInstance,
+  LayerZTable,
+  StoryEngine,
+} from "@lingfan-engine/core";
+import type { ChoiceTemplateRegistry } from "../choices/templates";
+import type { ChoicesTexts } from "./choices-view";
+import type { DialogueTemplateRegistry } from "../dialogue/templates";
+import type { ElementRegistry } from "../element/registry";
+import type { NotifyTemplateRegistry } from "../notify/templates";
+import type { OverlaySurface } from "./surface";
+
+/** 渲染投影（只读快照；宿主诊断与自定义渲染可读） */
+export interface NarrativeOverlayView {
+  speaker: string;
+  text: string;
+  /** 当前正文 HTML（打字中 = 可见前缀） */
+  lineHtml: string;
+  canAdvance: boolean;
+  /** 当前等待态（`none` = 无等待） */
+  waiting: string;
+  menuPrompt: string;
+  /** 选项（文本 + 目标列，顺序即呈现顺序） */
+  menuOptions: readonly { text: string; target: string }[];
+  inputPrompt: string;
+  nvlMode: string;
+  nvlLines: readonly string[];
+  /** 元素树是否非空（宿主可据此决定是否显示自己的背景层） */
+  hasElements: boolean;
+}
+
+/**
+ * 装配覆盖层的全部输入：一个覆盖层表面 + 一个已构造的引擎，其余都可省。
+ *
+ * 省掉的每一项都有明确后果（用内建默认或不做）——例如不传 `resolveResource`
+ * 则元素里的图片一律显示替代文本。逐字段说明见下。
+ */
+export interface NarrativeOverlayOptions {
+  /**
+   * 覆盖层表面：宿主把「每一层要显示什么」落到自己渲染体系的出口。
+   * Web 宿主用 `createDomOverlaySurface(container)`（层骨架由它建）。
+   */
+  surface: OverlaySurface;
+  /** 引擎实例（已构造；`start()` 与平台端口归宿主） */
+  engine: StoryEngine;
+  /**
+   * 每帧回调（宿主游戏主循环钩子）：本装配器每帧调用一次，
+   * 宿主据此把覆盖层与自己引擎的位置对齐（如气泡跟随角色）。
+   */
+  onFrame?: (dtSeconds: number) => void;
+  /** 打字速度（字符/秒；缺省 30，与内建默认一致） */
+  textSpeed?: number;
+  /** 渲染投影变化通知（宿主可作状态指示；每帧打字推进也会触发） */
+  onView?: (view: NarrativeOverlayView) => void;
+  /** 对话模板注册表（不传 = 内建） */
+  dialogueTemplates?: DialogueTemplateRegistry;
+  /** 选择模板注册表（不传 = 内建） */
+  choiceTemplates?: ChoiceTemplateRegistry;
+  /** 选择层文案覆盖（输入提交按钮等；不传 = 内建缺省） */
+  choiceTexts?: Partial<ChoicesTexts>;
+  /** 通知模板注册表（不传 = 内建） */
+  notifyTemplates?: NotifyTemplateRegistry;
+  /** 元素渲染器注册表（不传 = 内建全集） */
+  elementRegistry?: ElementRegistry;
+  /**
+   * 层级 z 表（不传 = 内建默认）。
+   * 宿主若从 `project.json shell.layers` 解析过覆盖表，经 `resolveLayerZ` 后注入。
+   */
+  layerZ?: LayerZTable;
+  /** 元素 `cmd` 命令处理器（未注册 fail-closed 上报） */
+  commands?: Map<
+    string,
+    (value: string | undefined, element: ElementInstance) => void
+  >;
+  /** 资源解析（元素 source/src/path → URL） */
+  resolveResource?: (path: string) => string | undefined;
+  /** 错误上报（引擎错误、未注册类型/命令；缺省 = 控制台） */
+  onError?: (message: string) => void;
+}
+
+/**
+ * 装配出的覆盖层实例：一面是宿主给进来的表面（`surface`，宿主可自行往舞台/接管层挂内容），
+ * 一面是交给宿主的动作。
+ *
+ * 引擎的推进权仍在宿主手里——`advance` / `choose` / `submitInput` 是宿主根据
+ * 自己的输入路由决定要不要调的，覆盖层不代宿主决定。
+ */
+export interface NarrativeOverlay {
+  /** 覆盖层表面（宿主可进一步定制，如往 `stage` / 接管层挂自己的内容） */
+  readonly surface: OverlaySurface;
+  /** 当前渲染投影（只读） */
+  view(): NarrativeOverlayView;
+  /** 与引擎状态对齐（读档 / 回溯完成后调用） */
+  sync(): void;
+  /** 帧循环开关（宿主游戏暂停时可关，避免空转） */
+  setRunning(running: boolean): void;
+  /**
+   * 输入是否归叙事层消费（**只判事件目标**：控件/面板内不吃）。
+   * 模式层面的让位（外部玩法系统接管）由宿主按自己的域状态决定——
+   * 那是宿主游戏的路由权，覆盖层不代宿主决定。
+   *
+   * 参数是**事件目标**（DOM 宿主传 `event.target`），故类型为 `unknown`：
+   * 判据在展示层唯一的 `isGameInputTarget` 里，本层不引入平台事件类型。
+   */
+  shouldConsumeInput(target: unknown): boolean;
+  /** 推进（二段式已处理：打字中先瞬间完成） */
+  advance(): void;
+  /** 选择选项（`menu` 等待） */
+  choose(target: string): void;
+  /** 提交输入（`input` 等待） */
+  submitInput(value: string): void;
+  /** 卸载：停帧循环、退订、清空挂载点 */
+  dispose(): void;
+}

package/src/resources/index.ts

@@ -0,0 +1,10 @@
+/**
+ * 资源域出口（UI 侧单一入口）：逻辑资源路径 → 已解析 URL 的缓存。
+ *
+ * 音频 / 视频 / 元素三处渲染路径共用同一份实现，避免各自维护一份「查表 + 在途去重」。
+ */
+export {
+  createResourceUrlCache,
+  type ResourceUrlCache,
+  type ResourceUrlCacheOptions,
+} from "./urlCache";

package/src/resources/urlCache.ts

@@ -0,0 +1,79 @@
+/**
+ * 资源 URL 缓存：逻辑资源路径 → 已解析 URL（UI 侧单一实现）。
+ *
+ * 元素渲染是同步的（`renderElementTree` 直接产 DOM），而资源解析是异步的——
+ * 这个接缝把两者对上：同步查表 → 在途去重 → 命中即返回 URL；
+ * 未命中**只启动一次**异步解析，落地后回调宿主；失败不粘滞（资源补上后仍可再试），
+ * 也不触发回调——不伪造 URL，诊断归端口/宿主。
+ *
+ * 释放策略归**消费方**：本模块只提供「已落地 URL」的枚举与清空，
+ * 何时释放（以及释放几次）由消费方在自己的销毁路径上决定。
+ */
+export interface ResourceUrlCacheOptions {
+  /** 解析落地后的回调（宿主据此重渲染表层）；失败不触发 */
+  onResolved?: () => void;
+}
+
+/**
+ * 缓存实例的两条取用路径：`get` 是同步的（拿不到就先别用），`resolve` 是异步的
+ * （一定会给一个结果，或在失败时抛）。
+ *
+ * `values` / `clear` 是留给消费方做释放的——缓存自己不认识「释放」这个概念，
+ * 因为 URL 怎么建、怎么撤销只有消费方的端口知道。
+ */
+export interface ResourceUrlCache {
+  /** 同步查表：已落地返回 URL；未落地（未请求或在途）返回 `undefined` */
+  get(path: string): string | undefined;
+  /** 取用：命中即返回；未命中只发起一次解析（同路径在途去重）；失败不粘滞 */
+  resolve(path: string): Promise<string>;
+  /** 已落地 URL（消费方据此统一释放） */
+  values(): IterableIterator<string>;
+  /** 清空缓存（可重复调用） */
+  clear(): void;
+}
+
+/**
+ * 造一个缓存：`resolveUrl` 负责真正取源，本模块负责「同一路径只解析一次」。
+ *
+ * 每个实例一张表，多个消费方共用一个实例才能共享解析结果；要隔离就各造各的。
+ * 失败不写进表，因此坏路径会重试，而 `onResolved` 只在真正落地时触发。
+ */
+export function createResourceUrlCache(
+  resolveUrl: (path: string) => Promise<string>,
+  options: ResourceUrlCacheOptions = {},
+): ResourceUrlCache {
+  const urls = new Map<string, string>();
+  /** 在途解析：同一路径的并发取用共用同一次解析（失败即移除，不粘滞） */
+  const inFlight = new Map<string, Promise<string>>();
+
+  return {
+    get(path: string): string | undefined {
+      return urls.get(path);
+    },
+    resolve(path: string): Promise<string> {
+      const cached = urls.get(path);
+      if (cached !== undefined) return Promise.resolve(cached);
+      const pending = inFlight.get(path);
+      if (pending !== undefined) return pending;
+      const promise = resolveUrl(path)
+        .then((url) => {
+          urls.set(path, url);
+          inFlight.delete(path);
+          options.onResolved?.();
+          return url;
+        })
+        .catch((error: unknown) => {
+          inFlight.delete(path); // 失败不粘滞：资源补上后仍可再试
+          throw error;
+        });
+      inFlight.set(path, promise);
+      return promise;
+    },
+    values(): IterableIterator<string> {
+      return urls.values();
+    },
+    clear(): void {
+      urls.clear();
+    },
+  };
+}

package/src/templates/index.ts

@@ -0,0 +1,7 @@
+/** 挂载点模板域出口（通用注册表；各挂载点的具体模板各自成域）。 */
+export {
+  TemplateRegistry,
+  createTemplateRegistry,
+  type TemplateFn,
+  type TemplateViewBase,
+} from "./registry";