@lingfan-engine/ui 0.0.0-stage → 0.1.0

package/src/commands/registry.ts

@@ -0,0 +1,54 @@
+/**
+ * 宿主命名命令注册表 —— 通用命令扩展处理器的注册制。
+ *
+ * 用途：元素的 `cmd` 属性是**宿主业务命令**（打开设置面板、回标题、外部跳转…），
+ * 引擎核心不感知这些命令（输入语义归核心层——`nav` 走核心 `navigate`，
+ * `cmd` 走宿主注册表；未注册即 fail-closed，不静默忽略作者意图）。
+ *
+ * 与 minigame / 元素渲染器注册表同一口径：**无默认回退**。
+ */
+import type { ElementInstance } from "@lingfan-engine/core";
+
+/**
+ * 命令处理器。
+ * `value` 为**点击时**已求值的参数（宿主先用 `engine.interpolate` 插值，
+ * 取值语义 = 点击那一刻的变量值）。
+ */
+export type NamedCommandHandler = (
+  value: string | undefined,
+  source: ElementInstance,
+) => void;
+
+/**
+ * 宿主命令表：`register` 与 `get` 是配对的两端，`get` 未命中即 `undefined`
+ * （这里不兜底——命令没注册就是没注册，由调用方决定怎么上报）。
+ * 表本身不持有状态，命令处理器持有的状态与它无关。
+ */
+export interface CommandRegistry {
+  /** 注册/覆盖（同名再注册 = 替换，宿主扩展与开发热替换语义） */
+  register(name: string, handler: NamedCommandHandler): void;
+  /** 解析处理器；未注册 = undefined（fail-closed，宿主必须显式上报） */
+  get(name: string): NamedCommandHandler | undefined;
+  has(name: string): boolean;
+  /** 已注册命令名（诊断 / 帮助面板用） */
+  names(): string[];
+}
+
+/** 造一张空的宿主命令表；命令由宿主在装配期注册，本函数不预置任何命令 */
+export function createCommandRegistry(): CommandRegistry {
+  const handlers = new Map<string, NamedCommandHandler>();
+  return {
+    register(name: string, handler: NamedCommandHandler): void {
+      handlers.set(name, handler);
+    },
+    get(name: string): NamedCommandHandler | undefined {
+      return handlers.get(name);
+    },
+    has(name: string): boolean {
+      return handlers.has(name);
+    },
+    names(): string[] {
+      return [...handlers.keys()];
+    },
+  };
+}

package/src/dialogue/index.ts

@@ -0,0 +1,24 @@
+/**
+ * 对话渲染域出口：内联标记 + 打字机二段式 +
+ * **统一文字渲染接缝**（textView——打字机/NVL/历史/模板共用的唯一管线）。
+ */
+export {
+  configureStoryFonts,
+  renderInlineMarkup,
+  sanitizeFont,
+  type StoryFontGate,
+} from "./inline";
+export { Typewriter, tokenizeStream } from "./typewriter";
+export {
+  renderDialogueLine,
+  type DialogueLineInput,
+  type DialogueLineView,
+} from "./textView";
+export {
+  builtinBubbleTemplate,
+  createDialogueTemplateRegistry,
+  type DialogueTemplateFn,
+  type DialogueTemplateInput,
+  type DialogueTemplateRegistry,
+  type DialogueTemplateView,
+} from "./templates";

package/src/dialogue/inline.ts

@@ -0,0 +1,136 @@
+/**
+ * UI 职责：内联富文本标记解析渲染（核心层只透传，本模块负责上屏）。
+ * 标记集（单一真相源）：
+ * - 样式：{b}{/b} {i}{/i} {u}{/u} {color=#xxx}{/color} {font=名}{/font} {size=N}{/size}
+ * - 控制符：{p}/{w} 段内停顿、{fast}——打字机阶段接管，当前渲染为空
+ * - 裸 {color}{font}{size} 按闭合处理
+ * - 未知 {…}（含用户字面量）按原文渲染；HTML 全量转义防注入
+ * - {font=名} 受字体名注册表约束（configureStoryFonts 宿主装配）：未注册名回退默认字体
+ *   并回调诊断；未接入时保持字符集白名单的纯展示行为
+ */
+
+/** HTML 特殊字符全量转义（`&` `<` `>` `"` `'`），防注入 */
+function escapeHtml(s: string): string {
+  return s
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+}
+
+/** color 值白名单：#hex 或 CSS 颜色名词汇（防 style 注入） */
+function sanitizeColor(v: string): string | null {
+  return /^#[0-9a-fA-F]{3,8}$/.test(v) || /^[a-zA-Z]+$/.test(v) ? v : null;
+}
+
+/** size 值：纯数字 → px */
+function sanitizeSize(v: string): string | null {
+  return /^\d+(\.\d+)?$/.test(v) ? `${v}px` : null;
+}
+
+/** font 值：字母数字/空格/中文/逗号（防引号逃逸与分号注入）；导出供宿主整句字体落 DOM 前同口径过筛 */
+export function sanitizeFont(v: string): string | null {
+  return /^[\w\u4e00-\u9fa5 ,]+$/.test(v) ? v : null;
+}
+
+/** 闭合标记集（`/b` `/i` `/u` `/color` `/font` `/size`）；裸 `{color}` 这类也按闭合处理 */
+const CLOSERS = new Set([
+  "/b",
+  "/i",
+  "/u",
+  "/color",
+  "/font",
+  "/size",
+  "color",
+  "font",
+  "size",
+]);
+
+/** 字体名注册表接入点：宿主装配（合法名集合来自 Resources/Fonts）；undefined = 未接入 */
+let fontGate: StoryFontGate | undefined;
+
+export interface StoryFontGate {
+  /** 合法字体名集合（文件名去扩展名；构建期检查用同一集合） */
+  readonly names: ReadonlySet<string>;
+  /** 未注册名回调（宿主接诊断输出；名字已按字符集白名单过筛，此处只报未注册） */
+  readonly onUnregistered?: (name: string) => void;
+}
+
+/**
+ * 装配/清除字体名注册表。未接入时 `{font=…}` 保持字符集白名单的旧行为（纯展示不校验）；
+ * 接入后未注册名不上字体 span，文本照常渲染（回退默认字体），并回调 onUnregistered。
+ */
+export function configureStoryFonts(gate: StoryFontGate | undefined): void {
+  fontGate = gate;
+}
+
+/** 渲染内联标记为安全 HTML（配 v-html 使用；所有文本内容均转义） */
+export function renderInlineMarkup(text: string): string {
+  let html = "";
+  const stack: string[] = []; // 未闭合标记对应的闭合串
+  let i = 0;
+  while (i < text.length) {
+    const ch = text[i]!;
+    if (ch !== "{") {
+      html += escapeHtml(ch);
+      i += 1;
+      continue;
+    }
+    const end = text.indexOf("}", i);
+    if (end < 0) {
+      html += escapeHtml(text.slice(i));
+      break;
+    }
+    const content = text.slice(i + 1, end).trim();
+    i = end + 1;
+    if (content === "") continue;
+
+    if (CLOSERS.has(content)) {
+      const close = stack.pop();
+      if (close !== undefined) html += close;
+      continue;
+    }
+    if (content === "p" || content === "w" || content === "fast") continue; // 打字机阶段接管
+
+    if (content.startsWith("color=")) {
+      const color = sanitizeColor(content.slice(6).trim());
+      if (color !== null) {
+        stack.push("</span>");
+        html += `<span style="color:${color}">`;
+      }
+      continue;
+    }
+    if (content.startsWith("size=")) {
+      const size = sanitizeSize(content.slice(5).trim());
+      if (size !== null) {
+        stack.push("</span>");
+        html += `<span style="font-size:${size}">`;
+      }
+      continue;
+    }
+    if (content.startsWith("font=")) {
+      const font = sanitizeFont(content.slice(5).trim());
+      if (font !== null) {
+        // 注册表已接入时未注册名回退：不上字体 span，文本照常渲染（动态拼接名
+        // 无法静态检查，运行期档是它的唯一守门——编译期 fail-closed 只覆盖静态引用）
+        if (fontGate !== undefined && !fontGate.names.has(font)) {
+          fontGate.onUnregistered?.(font);
+          continue;
+        }
+        stack.push("</span>");
+        html += `<span style="font-family:'${font}'">`;
+      }
+      continue;
+    }
+    if (content === "b" || content === "i" || content === "u") {
+      stack.push(`</${content}>`);
+      html += `<${content}>`;
+      continue;
+    }
+    // 未知 {…}：变量插值已在核心层完成，这里按字面保留
+    html += escapeHtml(`{${content}}`);
+  }
+  while (stack.length > 0) html += stack.pop()!; // 未闭合标记容错补齐
+  return html;
+}

package/src/dialogue/templates.ts

@@ -0,0 +1,70 @@
+/**
+ * 对话框模板（挂载点模板的一例：语义骨架三挂点 + rootClass 皮肤）。
+ *
+ * 模板 = 对话框「语义骨架各挂点」的注册渲染函数（纯 TS 可测；作者纯 TS 创作与
+ * 未来编辑器可视化创作产出同构描述，装配到同一注册表）。
+ * 模板名由核心层解析三级优先级后写入 `__dialog_template`（say template >
+ * character screen > 全局默认），本表按名解析、未知名/null 回退默认。
+ * 性能硬约束：打字帧每帧重算——speaker/hint 输入不变时输出
+ * 为纯字符串派生（宿主 Vue diff 后不 patch）；NVL 累积层按增量渲染约定保持宿主
+ * 固定骨架，不走模板全量重渲。统一渲染接缝（renderDialogueLine）即行渲染原语。
+ *
+ * 注册语义（注册 / 解析 / 默认回退）由通用 [`TemplateRegistry`] 承载——
+ * 本模块只定义对话挂载点的输入输出形状与内置模板。
+ */
+import {
+  TemplateRegistry,
+  createTemplateRegistry,
+} from "../templates/registry";
+import { renderDialogueLine } from "./textView";
+
+/** 模板输入：对话渲染状态投影（宿主从引擎状态/渲染态映射） */
+export interface DialogueTemplateInput {
+  /** 插值后说话人（空 = 无说话人行） */
+  speaker: string;
+  /** 角色色（空 = 默认；内置模板经宿主 style 应用，自定义模板可自定消费） */
+  speakerColor: string;
+  /** 统一接缝产物：renderDialogueLine({ text, typed }).html（含打字前缀） */
+  lineHtml: string;
+  /** 对话等待推进指示（▼） */
+  canAdvance: boolean;
+}
+
+/** 模板输出：语义骨架各挂点内容（宿主骨架固定：speaker 行 / 正文 / 推进指示器） */
+export interface DialogueTemplateView {
+  /** 对话框根皮肤类（宿主布局类叠加） */
+  rootClass: string;
+  /** 说话人行 HTML（空串 = 隐藏该行）；经统一接缝转义 */
+  speakerHtml: string;
+  /** 正文 HTML（打字帧每帧变化） */
+  bodyHtml: string;
+  /** 推进指示器 HTML（空串 = 隐藏） */
+  hintHtml: string;
+}
+
+/** 对话层模板：吃投影出的对话状态，吐骨架三挂点内容。纯函数——打字帧每帧调用，不得有副作用 */
+export type DialogueTemplateFn = (
+  input: DialogueTemplateInput,
+) => DialogueTemplateView;
+
+/** 对话挂载点的模板注册表（通用注册表的具体化） */
+export type DialogueTemplateRegistry = TemplateRegistry<
+  DialogueTemplateInput,
+  DialogueTemplateView
+>;
+
+/** 造一张空的对话层模板注册表；宿主在装配期向它 `register` 模板（本函数不装内建默认） */
+export function createDialogueTemplateRegistry(): DialogueTemplateRegistry {
+  return createTemplateRegistry<DialogueTemplateInput, DialogueTemplateView>();
+}
+
+/** 内置 bubble 模板：参考视觉（speaker 行 + 统一接缝正文 + ▼ 推进） */
+export const builtinBubbleTemplate: DialogueTemplateFn = (input) => ({
+  rootClass: "tpl-bubble",
+  speakerHtml:
+    input.speaker === ""
+      ? ""
+      : renderDialogueLine({ text: input.speaker }).html,
+  bodyHtml: input.lineHtml,
+  hintHtml: input.canAdvance ? "▼" : "",
+});

package/src/dialogue/textView.ts

@@ -0,0 +1,35 @@
+/**
+ * 统一文字渲染接缝（同一管线多容器）：打字机前缀 / 整句 / NVL 行 / 历史条目 /
+ * 未来模板——全部经此一条管线（转义 + 内联标记 → HTML）。
+ * 容器（对话框 / NVL 累积层 / 历史面板 / 模板）只决定「放在哪、长什么样」，
+ * 不各自实现渲染——这是对话渲染的复用结论。
+ * 性能硬约束：**逐帧变化的只有打字前缀**；
+ * 静态行（NVL 已打完的行 / 历史条目）的 HTML 必须由调用方 memo（computed），
+ * 避免 O(全文) 每帧重建。
+ */
+import { renderInlineMarkup } from "./inline";
+
+/**
+ * 一行对话的渲染请求。`typed` 与 `text` 二选一即可——给了 `typed` 就按它渲染，
+ * 这是「打字中每帧变、打完不变」两种调用形态共用同一入口的方式。
+ */
+export interface DialogueLineInput {
+  /** 原始标记文本（`{b}{color=#…}` 等，核心层透传） */
+  text: string;
+  /** 打字机可见前缀（打字中传入；完成态/静态省略） */
+  typed?: string;
+}
+
+/**
+ * 渲染产物：转义后的富文本 HTML。内容已安全，容器可直接 `innerHTML` 上屏；
+ * 输出刻意只有这一个字段——渲染接缝不掺布局决策。
+ */
+export interface DialogueLineView {
+  /** 富文本 HTML（已全量转义；容器用 v-html / innerHTML 上屏） */
+  html: string;
+}
+
+/** 统一渲染：typed 优先（打字中），否则整段 text。模板系统的替换点也在这里。 */
+export function renderDialogueLine(line: DialogueLineInput): DialogueLineView {
+  return { html: renderInlineMarkup(line.typed ?? line.text) };
+}

package/src/dialogue/typewriter.ts

@@ -0,0 +1,181 @@
+/**
+ * 打字机二段式（可测纯逻辑，UI 层 rAF 驱动 tick）。
+ * - 打字流 = 原文剥离 {p}/{w}/{fast}；**样式标记零宽**：不消耗打字时长、不计入可见字符，
+ *   且可见前缀**永不以半截标记结尾**——否则渲染层会把 `{color=#` 之类的残缺标记原样上屏
+ *   （回归保护：打字中裸标记不得上屏）
+ * - tick(dt) 按 cps 推进已显示的可见字符数；遇停顿点停下等点击
+ * - click()：停在 {p}/{w} → 越过停顿继续打字（passed-pause）；未完成 → 瞬间完成（completed）；
+ *   已完成 → no-op（UI 转 advance）
+ */
+
+/** 打字流快照：流文本、停顿点坐标与可见字符总数 */
+export interface TypingStream {
+  /** 打字流：原文去 {p}/{w}/{fast}；样式标记整段保留（零宽，渲染层据此着色） */
+  stream: string;
+  /** 停顿点（可见字符坐标：流内标记零宽不计） */
+  pausePoints: number[];
+  /** 可见字符总数（流内标记不计） */
+  visibleTotal: number;
+}
+
+/** 标记分词：{p}/{w} 记停顿点、{fast} 删除、其余 {…} 标记保留在流内（零宽） */
+export function tokenizeStream(text: string): TypingStream {
+  let stream = "";
+  let visibleTotal = 0;
+  const pausePoints: number[] = [];
+  let i = 0;
+  while (i < text.length) {
+    const ch = text[i]!;
+    if (ch !== "{") {
+      stream += ch;
+      visibleTotal += 1;
+      i += 1;
+      continue;
+    }
+    const end = text.indexOf("}", i);
+    if (end < 0) {
+      stream += text.slice(i); // 未闭合容错：尾部残缺标记按字面保留
+      break;
+    }
+    const content = text.slice(i + 1, end);
+    if (content === "p" || content === "w") {
+      pausePoints.push(visibleTotal); // 停顿发生在标记前的可见字符处
+      i = end + 1;
+      continue;
+    }
+    if (content === "fast") {
+      i = end + 1;
+      continue;
+    }
+    stream += text.slice(i, end + 1); // 样式标记零宽随流
+    i = end + 1;
+  }
+  return { stream, pausePoints, visibleTotal };
+}
+
+/**
+ * 一句话的打字进度机：按 cps 推进可见字符，遇停顿点停下等点击。
+ *
+ * 进度用「已显示的可见字符数」表示，不用流下标——样式标记零宽，不参与计时与停顿坐标。
+ * 用法：宿主每帧调 `tick(dt)`，用户点击调 `click()`，用 `visible` 取当前该上屏的文本前缀。
+ * 本类只管进度，不碰 DOM，也不自己计时。
+ */
+export class Typewriter {
+  /**
+   * 打字进度：已显示的可见字符数，流内样式标记不算。
+   * `tick` 每帧按预算累加、`click` 瞬间置满，因此它只增不减，上界是 `visibleTotal`。
+   * `visible` 用它决定前缀取到哪里，`done` / `pausedAtMark` 也由它推导；达到上界即打完。
+   */
+  private shown = 0; // 已显示的可见字符数（流内标记不计）
+  /**
+   * 下一个未消费的停顿点在 `pausePoints` 中的下标。只有「正停在 {p}/{w} 上点击」
+   * （`click` 返回 passed-pause）会把它 +1，其余路径都不动它，所以它也只增不减。
+   * `currentPause()` 靠它取出当前停顿坐标；`pausePoints` 升序，于是「`shown` 是否已够到
+   * 该坐标」就是「是否停在停顿点上」的判定（`pausedAtMark`）。
+   */
+  private nextPause = 0; // 下一个未消费的停顿点（在 pausePoints 中的下标）
+  /** 停顿点的可见字符坐标（升序，构造时由分词结果一次算定；只读） */
+  private readonly pausePoints: number[];
+  /** 打字流：原文去 {p}/{w}/{fast}，样式标记整段保留（见 `tokenizeStream`） */
+  private readonly stream: string;
+  /** 可见字符总数；`shown` 达到它即打完 */
+  private readonly visibleTotal: number;
+
+  /**
+   * @param text 原始富文本（含 {p}/{w}/{fast} 与样式标记），构造时就地分词
+   * @param cps 每秒推进的可见字符数；`setSpeed` 可在播放中调整
+   */
+  constructor(
+    text: string,
+    private cps: number,
+  ) {
+    const tokenized = tokenizeStream(text);
+    this.stream = tokenized.stream;
+    this.pausePoints = tokenized.pausePoints;
+    this.visibleTotal = tokenized.visibleTotal;
+  }
+
+  /** SetTextSpeed：玩家偏好即时调整当前句打字速度（非法值忽略，下限 1） */
+  setSpeed(cps: number): void {
+    if (typeof cps === "number" && Number.isFinite(cps)) {
+      this.cps = Math.max(1, cps);
+    }
+  }
+
+  /** 下一个未消费停顿点的可见坐标（无则 null） */
+  private currentPause(): number | null {
+    return this.nextPause < this.pausePoints.length
+      ? this.pausePoints[this.nextPause]!
+      : null;
+  }
+
+  /**
+   * 推进一帧：按 `cps × dtSeconds` 增加已显示字符数，但**不越过下一个停顿点**。
+   *
+   * 停在停顿点后本方法变为空转，直到 `click()` 消费掉该停顿点。已打完或正停在
+   * 停顿点时直接返回；`cps` 使本帧预算不足 1 个字符时也返回（等下一帧累积）。
+   */
+  tick(dtSeconds: number): void {
+    if (this.done || this.pausedAtMark) return;
+    const budget = Math.ceil(this.cps * dtSeconds);
+    if (budget <= 0) return; // cps=0 → 永不推进（点击兜底完成）
+    const pause = this.currentPause();
+    const limit = pause === null ? this.visibleTotal : pause;
+    this.shown = Math.min(this.shown + budget, limit);
+  }
+
+  /** 点击（二段式）：停在 {p}/{w} → 越过停顿继续打字；未完成 → 瞬间完成；已完成 → no-op（UI 转 advance） */
+  click(): "passed-pause" | "completed" | "no-op" {
+    if (this.done) return "no-op";
+    if (this.pausedAtMark) {
+      this.nextPause += 1;
+      return "passed-pause";
+    }
+    this.shown = this.visibleTotal;
+    return "completed";
+  }
+
+  /** 是否已打完（可见字符全部显示；停在停顿点上时**不算**打完） */
+  get done(): boolean {
+    return this.shown >= this.visibleTotal;
+  }
+
+  /**
+   * 可见前缀：可见坐标 → 流前缀。途经的完整标记整段吞入（渲染层据此着色），
+   * 停在刚显示的可见字符处——因此前缀**永不以半截标记结尾**；打完时返回整条流（含收尾标记）。
+   */
+  get visible(): string {
+    if (this.shown >= this.visibleTotal) return this.stream;
+    let out = "";
+    let visibleCount = 0;
+    let i = 0;
+    while (i < this.stream.length && visibleCount < this.shown) {
+      const ch = this.stream[i]!;
+      if (ch !== "{") {
+        out += ch;
+        visibleCount += 1;
+        i += 1;
+        continue;
+      }
+      const end = this.stream.indexOf("}", i);
+      if (end < 0) {
+        out += this.stream.slice(i); // 理论不达：分词已做未闭合容错
+        break;
+      }
+      out += this.stream.slice(i, end + 1); // 标记零宽：整段吞入
+      i = end + 1;
+    }
+    return out;
+  }
+
+  /** 是否停在 {p}/{w} 段内停顿点（点击将越过停顿而非瞬间完成） */
+  get pausedAtMark(): boolean {
+    const pause = this.currentPause();
+    return pause !== null && this.shown >= pause;
+  }
+
+  /** 本条文本的可见字符总数（`shown` 的上界；进度条与「打完了吗」的分母） */
+  get total(): number {
+    return this.visibleTotal;
+  }
+}

package/src/dom/index.ts

@@ -0,0 +1,7 @@
+/** DOM 物化域出口：`RenderSpec` → Web 节点（ui 内唯一允许碰 DOM 的目录，见本目录文件头规则）。 */
+export { createDomRenderPort, materialize } from "./materialize";
+export {
+  createDomOverlaySurface,
+  type DomOverlaySurface,
+  type NarrativeMounts,
+} from "./overlay-surface";

package/src/dom/materialize.ts

@@ -0,0 +1,88 @@
+/**
+ * 本目录是 `packages/ui` 内**唯一**允许出现 DOM 类型与 DOM 全局的目录。
+ *
+ * 与 `packages/ui/src/host/index.ts` 同一口气的规则：其余目录一律只产出 `RenderSpec`；
+ * 需要碰 DOM 的地方经 `RenderPort` 收口到这里，别的平台（小程序）在同一位置换成自己的物化器。
+ */
+import type {
+  RenderEvent,
+  RenderEventPatch,
+  RenderKind,
+  RenderPort,
+  RenderPropValue,
+  RenderSpec,
+} from "../element/spec";
+
+/** 中立词表 → Web 标签（`text` 落在 `div` 上：文本族的落地形态一直是 `div`） */
+const KIND_TAG: Readonly<Record<RenderKind, string>> = {
+  box: "div",
+  text: "div",
+  image: "img",
+  media: "video",
+  input: "input",
+  slider: "input",
+  checkbox: "input",
+  action: "button",
+};
+
+/** 写属性：顺序即 `props` 的插入顺序（`crossOrigin` 须先于 `src`，见图像族渲染器） */
+function applyProps(
+  node: HTMLElement,
+  props: Readonly<Record<string, RenderPropValue>>,
+): void {
+  const target = node as unknown as Record<string, RenderPropValue>;
+  for (const [key, value] of Object.entries(props)) {
+    target[key] = value;
+  }
+}
+
+function applyPatch(node: HTMLElement, patch: RenderEventPatch): void {
+  if (patch.style !== undefined) Object.assign(node.style, patch.style);
+  if (patch.props !== undefined) applyProps(node, patch.props);
+}
+
+function bindEvents(
+  node: HTMLElement,
+  events: readonly RenderEvent[] | undefined,
+): void {
+  for (const event of events ?? []) {
+    node.addEventListener(event.on, (domEvent) => {
+      if (event.stopPropagation === true) domEvent.stopPropagation();
+      const patch = event.handler?.();
+      if (patch !== undefined) applyPatch(node, patch);
+    });
+  }
+}
+
+/** 把一棵描述树物化成 DOM 节点（含整棵子树与事件） */
+export function materialize(spec: RenderSpec): HTMLElement {
+  const node = document.createElement(KIND_TAG[spec.kind]);
+  if (spec.className !== undefined) node.className = spec.className;
+  if (spec.style !== undefined) Object.assign(node.style, spec.style);
+  if (spec.text !== undefined) node.textContent = spec.text;
+  if (spec.html !== undefined) node.innerHTML = spec.html;
+  if (spec.props !== undefined) applyProps(node, spec.props);
+  // 帧驱动定位锚（动画按 id 找节点；无 dataset 的环境自动跳过）
+  if (spec.id !== undefined && node.dataset !== undefined) {
+    node.dataset.lfId = spec.id;
+  }
+  for (const child of spec.children ?? []) node.appendChild(materialize(child));
+  bindEvents(node, spec.events);
+  return node;
+}
+
+/**
+ * 把一个元素当作渲染根，造出 Web 版渲染端口。
+ *
+ * 每次调用产出独立的端口对象（无状态包装），因此同一元素重复取端口不会串扰。
+ */
+export function createDomRenderPort(element: HTMLElement): RenderPort {
+  return {
+    clear(): void {
+      element.innerHTML = "";
+    },
+    mount(spec: RenderSpec): void {
+      element.appendChild(materialize(spec));
+    },
+  };
+}