@lingfan-engine/ui 0.0.0-stage → 0.1.0

package/src/dom/overlay-surface.ts

@@ -0,0 +1,278 @@
+/**
+ * 覆盖层端口的 DOM 实现：把每层视图模型落成真实的 `HTMLElement` 树。
+ *
+ * **本目录是 `packages/ui` 内唯一允许出现 DOM 类型与 DOM 全局的地方**（见 `dom/index.ts`
+ * 的文件头规则）。层骨架、类名、标签形状（`<p>` / `<span>` / `<form>`）、`pointer-events`
+ * 策略与输入焦点全都归这里——中立核心只给模型。
+ *
+ * 事件策略（嵌入场景的关键）：**层自身恒不吃事件**（`pointer-events: none`），层里的
+ * 实际控件再逐个恢复点击（`clickable`）。于是层内空白区透传给宿主游戏——对话框铺满
+ * 视口时，玩家仍能点击对话框之外的地方。
+ *
+ * 接管层（`lf-takeover`）与转场遮罩（`lf-transition`）是**宿主自己的层**：中立核心从不
+ * 驱动它们，这里只按 `LayerZTable` 建出来并交给 `nodes`，宿主往里面挂自己的内容。
+ */
+import { DEFAULT_LAYER_Z, resolveInstanceZ } from "@lingfan-engine/core";
+import type { LayerZTable } from "@lingfan-engine/core";
+import type { FrameSource } from "../host/frame-loop";
+import type {
+  ChoicesLayerView,
+  DialogueLayerView,
+  NotifyLayerItem,
+  OverlayLayerId,
+  OverlaySurface,
+} from "../overlay/surface";
+import { createDomRenderPort } from "./materialize";
+
+/** 覆盖层挂载点（Web 侧宿主落地形态；中立契约见 `OverlaySurface`） */
+export interface NarrativeMounts {
+  /** 覆盖层根 */
+  root: HTMLElement;
+  /** 舞台层：背景 / 立绘 */
+  stage: HTMLElement;
+  /** 元素层：舞台之上的空间层（元素树渲染目标） */
+  elementLayer: HTMLElement;
+  /** 对话层（含打字机） */
+  dialogue: HTMLElement;
+  /** 选择层（菜单 / 输入） */
+  choices: HTMLElement;
+  /** 通知层（toast） */
+  overlay: HTMLElement;
+  /** 外部系统接管层（小游戏 / 玩法系统） */
+  takeover: HTMLElement;
+  /** 全屏转场遮罩 */
+  transition: HTMLElement;
+}
+
+/** DOM 实现：中立端口 + Web 宿主可直取的层节点 */
+export interface DomOverlaySurface extends OverlaySurface {
+  /** 层节点表（宿主可进一步定制，如往 takeover 里挂自己的 iframe/canvas） */
+  readonly nodes: NarrativeMounts;
+}
+
+/** 建一个铺满父容器的层（层自身不吃事件） */
+function layer(parent: HTMLElement, className: string, z: number): HTMLElement {
+  const node = parent.ownerDocument.createElement("div");
+  node.className = className;
+  node.style.position = "absolute";
+  node.style.inset = "0";
+  node.style.zIndex = String(z);
+  node.style.pointerEvents = "none";
+  parent.appendChild(node);
+  return node;
+}
+
+/** 让指定控件恢复点击（层自身透明，故必须逐控件开启） */
+function clickable<T extends HTMLElement>(node: T): T {
+  node.style.pointerEvents = "auto";
+  return node;
+}
+
+/**
+ * 造一个以窗口 `requestAnimationFrame` 为底的帧源。
+ *
+ * 无 rAF 的环境（测试 / 降级）下 `request` 返回 0 且**永不回调**：帧循环因此静默不启，
+ * 功能仍可用（整句直出、按钮照常工作），只是打字机不走帧。
+ *
+ * 首次 `request` 用建端口时读到的窗口，其后每次重读——沿用原覆盖层「启动读一次、
+ * 之后每帧重读」的语义（宿主换文档时仍取当帧的窗口）。
+ */
+function createWindowFrameSource(container: HTMLElement): FrameSource {
+  const first = container.ownerDocument.defaultView;
+  let started = false;
+  return {
+    request(callback: (now: number) => void): number {
+      const view = started ? container.ownerDocument.defaultView : first;
+      started = true;
+      if (view === null || view === undefined) return 0;
+      return view.requestAnimationFrame(callback);
+    },
+    cancel(handle: number): void {
+      if (handle === 0) return;
+      container.ownerDocument.defaultView?.cancelAnimationFrame(handle);
+    },
+  };
+}
+
+/**
+ * 装配一个 DOM 覆盖层表面：按 `LayerZTable` 在父容器内建出各层，并交出端口。
+ *
+ * 创建顺序即 DOM 叠放顺序（后建的默认盖在先建的之上），z 值显式写在层样式里，因此
+ * 这里不依赖创建顺序表达层级。`takeover` 与 `choices` 初始不占位（外部系统挂载、
+ * 或进入选择等待时才显示）。`container` 只用于建层与取窗口，随后不再被引用。
+ */
+export function createDomOverlaySurface(
+  container: HTMLElement,
+  layerZ: Partial<LayerZTable> = {},
+): DomOverlaySurface {
+  // 入参是「工程覆盖」而非完整表：与内建默认合并后再逐层解析（与旧 mounts.ts 同口径）。
+  const table: LayerZTable = { ...DEFAULT_LAYER_Z, ...layerZ };
+  const root = layer(container, "lf-overlay", 0);
+  const stage = layer(
+    root,
+    "lf-stage",
+    resolveInstanceZ("stage", undefined, table),
+  );
+  const elementLayer = layer(stage, "lf-element-layer", 0);
+  const transition = layer(
+    root,
+    "lf-transition",
+    resolveInstanceZ("video", undefined, table),
+  );
+  const dialogue = layer(
+    root,
+    "lf-dialogue",
+    resolveInstanceZ("dialogue", undefined, table),
+  );
+  const choices = layer(
+    root,
+    "lf-choices",
+    resolveInstanceZ("choices", undefined, table),
+  );
+  const takeover = layer(
+    root,
+    "lf-takeover",
+    resolveInstanceZ("minigame", undefined, table),
+  );
+  const overlay = layer(
+    root,
+    "lf-notifications",
+    resolveInstanceZ("notifications", undefined, table),
+  );
+  // 接管层空闲时不占位（外部系统挂载时才显示）
+  takeover.style.display = "none";
+  choices.style.display = "none";
+
+  const nodes: NarrativeMounts = {
+    root,
+    stage,
+    elementLayer,
+    dialogue,
+    choices,
+    overlay,
+    takeover,
+    transition,
+  };
+  const timers = new Set<ReturnType<typeof setTimeout>>();
+
+  /** 层位 → 节点（z 下发与「哪一层」的唯一映射处） */
+  const byLayer: Record<OverlayLayerId, HTMLElement> = {
+    stage,
+    element: elementLayer,
+    transition,
+    dialogue,
+    choices,
+    takeover,
+    notifications: overlay,
+  };
+
+  const doc = (): Document => container.ownerDocument;
+
+  const surface: DomOverlaySurface = {
+    frame: createWindowFrameSource(container),
+    stage: createDomRenderPort(stage),
+    elements: createDomRenderPort(elementLayer),
+    nodes,
+
+    setLayerZ(layerId: OverlayLayerId, z: number): void {
+      byLayer[layerId].style.zIndex = String(z);
+    },
+
+    setDialogue(view: DialogueLayerView): void {
+      dialogue.className = `lf-dialogue ${view.rootClass}`;
+      dialogue.innerHTML = "";
+      if (view.speakerHtml !== "") {
+        const speaker = doc().createElement("p");
+        speaker.className = "lf-speaker";
+        speaker.innerHTML = view.speakerHtml;
+        if (view.speakerColor !== "") speaker.style.color = view.speakerColor;
+        dialogue.appendChild(speaker);
+      }
+      const body = doc().createElement("p");
+      body.className = "lf-text";
+      body.innerHTML = view.bodyHtml;
+      if (view.bodyFont !== "") body.style.fontFamily = `'${view.bodyFont}'`;
+      dialogue.appendChild(body);
+      if (view.hintHtml !== "") {
+        const hint = doc().createElement("span");
+        hint.className = "lf-hint";
+        hint.innerHTML = view.hintHtml;
+        dialogue.appendChild(hint);
+      }
+      // 隐藏而非清空：恢复时不会闪一下
+      dialogue.style.display = view.visible ? "" : "none";
+    },
+
+    setChoices(view: ChoicesLayerView | null): void {
+      choices.style.display = view === null ? "none" : "";
+      choices.innerHTML = "";
+      if (view === null) return;
+
+      if (view.input !== null) {
+        const prompt = view.input.prompt;
+        choices.className = "lf-choices";
+        const label = doc().createElement("p");
+        label.className = "lf-prompt";
+        label.textContent = prompt;
+        const form = doc().createElement("form");
+        form.className = "lf-input-row";
+        const field = clickable(doc().createElement("input"));
+        field.type = "text";
+        field.setAttribute("aria-label", prompt === "" ? "输入" : prompt);
+        const submit = clickable(doc().createElement("button"));
+        submit.type = "submit";
+        submit.textContent = view.input.submitText;
+        form.addEventListener("submit", (event) => {
+          event.preventDefault();
+          // 出口由装配器挂上；未挂时不消费（不是本层的错，故不报错）
+          surface.onSubmitInput?.(field.value.trim());
+        });
+        form.append(field, submit);
+        choices.append(label, form);
+        return;
+      }
+
+      choices.className = `lf-choices ${view.rootClass}`;
+      if (view.promptHtml !== "") {
+        const prompt = doc().createElement("p");
+        prompt.className = "lf-prompt";
+        prompt.innerHTML = view.promptHtml;
+        choices.appendChild(prompt);
+      }
+      const row = doc().createElement("div");
+      row.className = "lf-choice-row";
+      for (const option of view.options) {
+        const button = clickable(doc().createElement("button"));
+        button.type = "button";
+        button.innerHTML = option.html;
+        // innerHTML 内容不进无障碍名计算（等价于 v-html）：显式给可访问名
+        button.setAttribute("aria-label", option.label);
+        // 点击交核心 choose（目标是列 id，不是显示文本）
+        button.addEventListener("click", () =>
+          surface.onChoose?.(option.target),
+        );
+        row.appendChild(button);
+      }
+      choices.appendChild(row);
+    },
+
+    pushNotification(item: NotifyLayerItem, durationMs: number): void {
+      const node = doc().createElement("div");
+      node.className = item.rootClass;
+      node.innerHTML = item.bodyHtml;
+      overlay.appendChild(node);
+      const timer = setTimeout(() => {
+        timers.delete(timer);
+        node.remove();
+      }, durationMs);
+      timers.add(timer);
+    },
+
+    clear(): void {
+      for (const timer of timers) clearTimeout(timer);
+      timers.clear();
+      root.remove();
+    },
+  };
+  return surface;
+}

package/src/element/animation.ts

@@ -0,0 +1,141 @@
+/**
+ * 帧驱动表现的纯逻辑（可测）：缓动映射、动画插值、震动偏移。
+ *
+ * 分工：核心层写「描述」，本模块提供**每帧计算**，宿主（App.vue / 其他）把结果写到 DOM。
+ * 不碰引擎、不碰 DOM —— 便于单测覆盖（帧驱动）。
+ */
+import type { AnimationSpec } from "@lingfan-engine/core";
+
+/**
+ * 缓动名 → 归一化函数（`t ∈ [0,1] → [0,1]`）。
+ * 默认 `EaseOutQuad`；未知名字**回退 EaseOutQuad**（不静默变成线性）。
+ *
+ * 缓动全集 **16 个**（Linear + Quad×3 + Cubic×3 + Back×3 +
+ * Elastic×3 + Bounce×3）——只列一部分的话，作者写 `EaseOutBounce` 会被静默回退成默认缓动。
+ * **回退语义**（解析失败 → `EaseOutQuad`）故不改为抛错（避免对既有故事
+ * 制造新错误）；「未知缓动名」的编辑期提示列为可选后续。
+ */
+const EASINGS: Record<string, (t: number) => number> = {
+  // 命名**首字母大写**（`Linear`），因此这里大小写不敏感查找
+  Linear: (t) => t,
+  EaseInQuad: (t) => t * t,
+  EaseOutQuad: (t) => t * (2 - t),
+  EaseInOutQuad: (t) => (t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t),
+  EaseInCubic: (t) => t * t * t,
+  EaseOutCubic: (t) => 1 - (1 - t) ** 3,
+  EaseInOutCubic: (t) => (t < 0.5 ? 4 * t * t * t : 1 - (-2 * t + 2) ** 3 / 2),
+  // —— Back / Elastic / Bounce族（补齐缓动全集，逐条给定公式）——
+  // 命名与公式：Linear + Quad×3 + Cubic×3 + Back×3 + Elastic×3 + Bounce×3
+  EaseInBack: (t) => t * t * (2.70158 * t - 1.70158),
+  EaseOutBack: (t) => (t - 1) * (t - 1) * (2.70158 * (t - 1) + 1.70158) + 1,
+  EaseInOutBack: (t) =>
+    t < 0.5
+      ? 0.5 * (t * 2) * (t * 2) * (2.70158 * (t * 2) - 1.70158)
+      : 0.5 *
+        ((t * 2 - 2) * (t * 2 - 2) * (2.70158 * (t * 2 - 2) + 1.70158) + 2),
+  EaseInElastic: (t) =>
+    t === 0 || t === 1
+      ? t
+      : -Math.pow(2, 10 * t - 10) * Math.sin((t * 10 - 10.75) * 2.094395102),
+  EaseOutElastic: (t) =>
+    t === 0 || t === 1
+      ? t
+      : Math.pow(2, -10 * t) * Math.sin((t * 10 - 0.75) * 2.094395102) + 1,
+  EaseInOutElastic: (t) =>
+    t === 0 || t === 1
+      ? t
+      : t < 0.5
+        ? -(
+            Math.pow(2, 20 * t - 10) * Math.sin((20 * t - 11.125) * 1.396263402)
+          ) / 2
+        : (Math.pow(2, -20 * t + 10) *
+            Math.sin((20 * t - 11.125) * 1.396263402)) /
+            2 +
+          1,
+  EaseOutBounce: (t) => easeOutBounce(t),
+  EaseInBounce: (t) => 1 - easeOutBounce(1 - t),
+  EaseInOutBounce: (t) =>
+    t < 0.5
+      ? (1 - easeOutBounce(1 - 2 * t)) / 2
+      : (1 + easeOutBounce(2 * t - 1)) / 2,
+};
+
+/** Bounce 基函数（分段式） */
+function easeOutBounce(t: number): number {
+  const n1 = 7.5625;
+  const d1 = 2.75;
+  if (t < 1 / d1) return n1 * t * t;
+  if (t < 2 / d1) {
+    const t2 = t - 1.5 / d1;
+    return n1 * t2 * t2 + 0.75;
+  }
+  if (t < 2.5 / d1) {
+    const t3 = t - 2.25 / d1;
+    return n1 * t3 * t3 + 0.9375;
+  }
+  const t4 = t - 2.625 / d1;
+  return n1 * t4 * t4 + 0.984375;
+}
+
+/** 默认缓动名（缓动查表的兜底） */
+const DEFAULT_EASING = "EaseOutQuad";
+
+/**
+ * 大小写不敏感查找表：登记表用 `Linear`（首字母大写），
+ * 而既有语料/测试可能写 `linear` —— 两者都解析到同一函数（**更宽松 = 不破坏既有故事**）。
+ */
+const EASING_LOOKUP: ReadonlyMap<string, (t: number) => number> = new Map(
+  Object.entries(EASINGS).map(([name, fn]) => [name.toLowerCase(), fn]),
+);
+
+/**
+ * 按名取缓动函数（大小写不敏感）。名字不认识时不报错——回退到默认缓动，
+ * 让动画照常跑完；名字写错属于作者侧问题，不该把一帧动画变成一次崩溃。
+ */
+export function easingFn(name: string): (t: number) => number {
+  return EASING_LOOKUP.get(name.toLowerCase()) ?? EASINGS[DEFAULT_EASING]!;
+}
+
+/** 已知缓动名（编辑器表单/诊断可枚举；不含回退项）——恒为全集 16 个 */
+export function easingNames(): string[] {
+  return Object.keys(EASINGS);
+}
+
+/**
+ * 单条动画在 `elapsed`（秒）时刻的插值。
+ * `done=true` 表示已到终值（宿主据此把该 seq 交回 `engine.animationFinished`）。
+ */
+export function interpolateAnimation(
+  spec: AnimationSpec,
+  elapsed: number,
+): { value: number; done: boolean } {
+  if (spec.duration <= 0) return { value: spec.to, done: true };
+  const t = Math.min(1, Math.max(0, elapsed / spec.duration));
+  const value = spec.from + (spec.to - spec.from) * easingFn(spec.easing)(t);
+  return { value, done: t >= 1 };
+}
+
+/**
+ * 屏幕震动偏移（宿主每帧计算并应用）。
+ * 用**衰减正弦**近似：幅度随进度线性衰减到 0，x/y 取不同相位避免直线往复。
+ * `phase` 为宿主传入的帧时间（秒）或随机源，保证同一输入可复现（测试友好）。
+ */
+export function shakeOffset(
+  intensity: number,
+  progress: number,
+  phase: number,
+): { x: number; y: number } {
+  const decay = Math.max(0, 1 - progress);
+  const amplitude = intensity * decay;
+  // `|| 0` 归一化 -0（Math.round 可产出 -0，会让相等断言与 style 序列化不一致）
+  return {
+    x: Math.round(Math.sin(phase * 47) * amplitude) || 0,
+    y: Math.round(Math.cos(phase * 61) * amplitude) || 0,
+  };
+}
+
+/** 转场遮罩不透明度（`fade` 系）：0 → 1 → 0 的三段式（中点为全遮） */
+export function transitionOpacity(progress: number): number {
+  const t = Math.min(1, Math.max(0, progress));
+  return t <= 0.5 ? t * 2 : (1 - t) * 2;
+}

package/src/element/index.ts

@@ -0,0 +1,38 @@
+/** 元素渲染域出口（UI 侧单一入口）。 */
+export {
+  createElementRegistry,
+  type ElementRegistry,
+  type ElementRenderer,
+  type ElementRenderContext,
+} from "./registry";
+export {
+  createElementResourceResolver,
+  type ElementResourceResolver,
+  type ElementResourceResolverOptions,
+} from "./resource";
+export { elementClassName, elementSource, elementStyle } from "./style";
+export { registerBuiltinElementRenderers } from "./renderers";
+export { renderElementTree, type ElementTreeRenderOptions } from "./render";
+export {
+  type RenderEvent,
+  type RenderEventPatch,
+  type RenderKind,
+  type RenderPort,
+  type RenderPropValue,
+  type RenderSpec,
+} from "./spec";
+export {
+  hasElementInteraction,
+  isElementDisabled,
+  resolveElementAction,
+  type ElementAction,
+  type ElementActionOptions,
+  type ElementActionSource,
+} from "./interaction";
+export {
+  easingFn,
+  easingNames,
+  interpolateAnimation,
+  shakeOffset,
+  transitionOpacity,
+} from "./animation";

package/src/element/interaction.ts

@@ -0,0 +1,123 @@
+/**
+ * 点击动作解析（输入语义归核心层，UI 只做翻译）。
+ *
+ * **`disabled` > `nav` > `ops` > `cmd`** —— 前四级决定**点击行为**：
+ * - `disabled` 短路（可写布尔，也可写表达式原文如 `{player.gold < 10}`，点击时刻求值）
+ * - `nav` 优先于 `ops`/`cmd`（跳列是最直接的编排语义）
+ * - `ops` = **数据侧动作序列**（点一下按序执行一串 op，复用引擎既有 op 分发表）
+ * - `cmd` = 宿主命名命令（宿主自有业务：打开面板、外部跳转…）
+ *
+ * `hover_*` / `selected_*` / `disabled_*` 是与点击**正交**的视觉态（由渲染器绑定）。
+ *
+ * 纯函数：宿主据此选路（`nav` → 核心 `navigate`；`ops` → 引擎 `runElementOps`；
+ * `cmd` → 宿主命名命令注册表）。
+ */
+import type { ElementInstance } from "@lingfan-engine/core";
+
+/**
+ * 点击动作的解析结果：调用方据 `kind` 选路，不自行读属性。
+ *
+ * `none` / `disabled` 都不产生动作，区别在语义——前者是「元素没声明交互」，
+ * 后者是「声明了但当下被禁用」。调用方只看 `hasElementInteraction` 时两者等价，
+ * 但要区分「未声明」与「被禁用」（例如做提示文案）时用得上。
+ */
+export type ElementAction =
+  | { kind: "none" }
+  /** 禁用：不产生任何动作（调用方应短路，不挂点击） */
+  | { kind: "disabled" }
+  | { kind: "nav"; target: string }
+  /** 数据侧动作序列：原样交给引擎（表达式在点击时刻由引擎求值） */
+  | { kind: "ops"; ops: readonly Record<string, unknown>[] }
+  /** `value` 为原文（可能含 `{expr}`）——宿主按点击时刻插值后再交处理器 */
+  | { kind: "cmd"; name: string; value?: string };
+
+/**
+ * 动作解析的可选注入点：宿主提供「表达式怎么求值」。
+ * 不传 = 不求解——字符串形态的 `disabled` 一律按「未禁用」处理（见 `isElementDisabled`）。
+ */
+export interface ElementActionOptions {
+  /**
+   * `disabled` 表达式求值（返回 null = 求值失败）。
+   * 由宿主注入（引擎侧 `interpolate`+解析）；缺省 = 不求解，字符串形态按「未禁用」处理。
+   */
+  evalDisable?: (expression: string) => boolean | null;
+}
+
+/**
+ * 禁用判定（`enabled === false` 与 `disabled` 同义，任一命中即禁用）。
+ *
+ * 表达式求值失败（null）= **不禁用**：宁可点得动、由 `ops` 执行期 fail-closed 报错，
+ * 也不因求值问题让玩家彻底无法交互（禁用态误判是「锁死」，比报错更难恢复）。
+ */
+export function isElementDisabled(
+  props: Record<string, unknown>,
+  options: ElementActionOptions = {},
+): boolean {
+  if (props.enabled === false) return true;
+  const value = props.disabled;
+  if (typeof value === "boolean") return value;
+  if (typeof value === "string" && value !== "") {
+    if (options.evalDisable === undefined) return false;
+    return options.evalDisable(value) === true;
+  }
+  return false;
+}
+
+/**
+ * `ops` 负载形态校验：非空数组，每项为对象且 `op` 为非空字符串。
+ * 畸形 = 无声明的形态 ⇒ 返回 null（调用方按「未声明 ops」继续，由引擎解析期 fail-closed 报错）。
+ */
+function readOps(value: unknown): readonly Record<string, unknown>[] | null {
+  if (!Array.isArray(value) || value.length === 0) return null;
+  for (const item of value) {
+    if (typeof item !== "object" || item === null || Array.isArray(item)) {
+      return null;
+    }
+    const op = (item as { op?: unknown }).op;
+    if (typeof op !== "string" || op === "") return null;
+  }
+  return value as readonly Record<string, unknown>[];
+}
+
+/**
+ * 按优先级解析出该元素在点击时应产生的动作。
+ *
+ * 优先级 `disabled` > `nav` > `ops` > `cmd`，全不命中 = `{ kind: "none" }`。
+ * 只读属性、不写状态：同一组属性任何时候调都得到同一个结果（表达式求值那步除外，
+ * 它按调用时刻求值）。交给调用方选路的，是这个判别联合——不是原始属性。
+ */
+export function resolveElementAction(
+  props: Record<string, unknown>,
+  options: ElementActionOptions = {},
+): ElementAction {
+  // 最高优先级：禁用 → 不产生任何动作
+  if (isElementDisabled(props, options)) return { kind: "disabled" };
+
+  const nav = props.nav;
+  if (typeof nav === "string" && nav !== "")
+    return { kind: "nav", target: nav };
+
+  const ops = readOps(props.ops);
+  if (ops !== null) return { kind: "ops", ops };
+
+  const cmd = props.cmd;
+  if (typeof cmd === "string" && cmd !== "") {
+    const value = props.value;
+    return typeof value === "string"
+      ? { kind: "cmd", name: cmd, value }
+      : { kind: "cmd", name: cmd };
+  }
+  return { kind: "none" };
+}
+
+/** 元素是否拥有交互（点击类）——渲染器据此决定是否挂点击与手型光标 */
+export function hasElementInteraction(
+  props: Record<string, unknown>,
+  options: ElementActionOptions = {},
+): boolean {
+  const action = resolveElementAction(props, options);
+  return action.kind !== "none" && action.kind !== "disabled";
+}
+
+/** 供宿主把动作翻译成引擎/注册表调用（`source` 回传给命令处理器） */
+export type ElementActionSource = ElementInstance;

package/src/element/registry.ts

@@ -0,0 +1,69 @@
+/**
+ * 元素渲染器注册表（UI 层职责）：核心层只声明元素 `type` 与属性，
+ * 宿主经注册表解析渲染器后把结果交给渲染端口物化。
+ *
+ * 与 minigame 注册表同一口径：**未知类型无默认回退** = fail-closed
+ * ——静默占位会掩盖内容错误（渲染"看得见"，但语义是错的）。
+ *
+ * 框架与平台无关：渲染器只产出 `RenderSpec`，不碰 DOM，也不依赖任何 UI 框架
+ * （核心只写状态，UI 只渲染；渲染器是宿主可替换的产物）。
+ */
+import type { ElementInstance } from "@lingfan-engine/core";
+import type { RenderSpec } from "./spec";
+
+/** 元素渲染上下文：渲染器只消费宿主提供的能力，不直接接触引擎 */
+export interface ElementRenderContext {
+  /** 元素实例（id/type/name/props/z/children） */
+  element: ElementInstance;
+  /**
+   * 递归渲染子元素，返回子树的描述树（容器渲染器把结果放进自己的 `children`）。
+   * 未注册的类型不产出节点（fail-closed），因此返回的项数与传入的子元素数可能不等。
+   */
+  renderChildren: (children: readonly ElementInstance[]) => RenderSpec[];
+  /** 交互激活（判定通过后由渲染器调用；具体 nav/ops/cmd 语义归宿主） */
+  activate?: (element: ElementInstance) => void;
+  /**
+   * `disabled` 表达式求值（返回 null = 求值失败）。
+   * 表达式语法归核心层：UI 只做形态判定，求值经此回调交给宿主/引擎。
+   */
+  evalDisable?: (expression: string) => boolean | null;
+  /** 资源解析（source/src/path → 可加载 URL）；缺省或失败返回 undefined（不静默伪造） */
+  resolveResource?: (path: string) => string | undefined;
+}
+
+/** 渲染器：产出元素的描述树（根节点承载类名/样式，子元素在 `children` 里） */
+export type ElementRenderer = (ctx: ElementRenderContext) => RenderSpec;
+
+/**
+ * 元素类型 → 渲染器的查表。`get` 未命中即 `undefined`，本表不做兜底
+ * （画一个空占位会让内容错误看起来「渲染成功」）。
+ * 表本身不持有渲染状态；渲染器是无状态函数，同一个可跨元素层复用。
+ */
+export interface ElementRegistry {
+  /** 注册/覆盖（同类型再注册 = 替换，宿主扩展与开发热替换语义） */
+  register(type: string, renderer: ElementRenderer): void;
+  /** 解析渲染器；未注册 = undefined（fail-closed，宿主必须显式上报） */
+  get(type: string): ElementRenderer | undefined;
+  has(type: string): boolean;
+  /** 已注册类型（诊断/清单用） */
+  types(): string[];
+}
+
+/** 造一张空的元素渲染器表——内建 36 类型由元素域的注册入口另行登记 */
+export function createElementRegistry(): ElementRegistry {
+  const renderers = new Map<string, ElementRenderer>();
+  return {
+    register(type: string, renderer: ElementRenderer): void {
+      renderers.set(type, renderer);
+    },
+    get(type: string): ElementRenderer | undefined {
+      return renderers.get(type);
+    },
+    has(type: string): boolean {
+      return renderers.has(type);
+    },
+    types(): string[] {
+      return [...renderers.keys()];
+    },
+  };
+}