@lingfan-engine/ui 0.0.0-stage → 0.1.1

package/src/element/render.ts

@@ -0,0 +1,77 @@
+/**
+ * 元素树渲染（宿主入口）：清空渲染根 → 逐元素经注册表取描述树 → 交给渲染端口物化。
+ *
+ * fail-closed 约束：**未注册类型不渲染、不伪造**，经 `onUnknownType` 上报宿主
+ * （与小游戏注册表同构——小游戏未注册也是上报后保持等待）。
+ *
+ * 幂等：每次调用整体重建（元素数量有限；避免增量 diff 的复杂度，
+ * 帧级高频状态另有其道，见帧驱动文档）。
+ */
+import type { ElementInstance } from "@lingfan-engine/core";
+import type { ElementRegistry } from "./registry";
+import type { RenderPort, RenderSpec } from "./spec";
+
+/**
+ * 一帧元素树的渲染请求：`registry` / `port` / `elements` 必给，
+ * 其余三个回调不传即「没有对应的宿主能力」（表现为元素不可点、表达式不求解、资源显示替代文本）。
+ *
+ * `port` 是宿主注入的渲染端口（Web 侧 `createDomRenderPort`）——渲染器只产出描述树，
+ * 平台差异全部收口在端口实现里。
+ */
+export interface ElementTreeRenderOptions {
+  registry: ElementRegistry;
+  port: RenderPort;
+  elements: readonly ElementInstance[];
+  /** 交互激活（宿主把元素语义翻译成引擎命令，如 nav → navigate / ops → runElementOps） */
+  activate?: (element: ElementInstance) => void;
+  /** `disabled` 表达式求值（返回 null = 求值失败；表达式语法归核心层） */
+  evalDisable?: (expression: string) => boolean | null;
+  /** 资源解析（source/src/path → URL） */
+  resolveResource?: (path: string) => string | undefined;
+  /** 未注册类型上报（fail-closed；宿主负责可见诊断） */
+  onUnknownType?: (type: string) => void;
+}
+
+/**
+ * 把一帧元素列表渲染进 `port`（先清空，再整棵重建）。
+ *
+ * 调用方每帧给全量元素——本函数不记上一帧、不做增量对比。未注册类型跳过并上报，
+ * 不画占位：宁可少一个节点，也不让内容错误看起来像渲染成功。
+ */
+export function renderElementTree(options: ElementTreeRenderOptions): void {
+  const { port, registry, elements } = options;
+  port.clear();
+
+  const renderChildren = (list: readonly ElementInstance[]): RenderSpec[] => {
+    const specs: RenderSpec[] = [];
+    for (const element of list) {
+      const spec = renderOne(element);
+      if (spec !== undefined) specs.push(spec);
+    }
+    return specs;
+  };
+
+  function renderOne(element: ElementInstance): RenderSpec | undefined {
+    const renderer = registry.get(element.type);
+    if (renderer === undefined) {
+      options.onUnknownType?.(element.type);
+      return undefined;
+    }
+    const spec = renderer({
+      element,
+      renderChildren,
+      activate: options.activate,
+      evalDisable: options.evalDisable,
+      resolveResource: options.resolveResource,
+    });
+    // 舞台内叠放序（两级叠放：元素之间在 stage 容器内独立比较）覆盖作者声明，
+    // 帧驱动定位锚挂在根节点上（动画按 id 找节点）
+    return {
+      ...spec,
+      style: { ...spec.style, zIndex: String(element.z) },
+      id: element.id,
+    };
+  }
+
+  for (const spec of renderChildren(elements)) port.mount(spec);
+}

package/src/element/renderers/base.ts

@@ -0,0 +1,56 @@
+/**
+ * 渲染器公共基座：根节点描述与数值属性读取。
+ *
+ * 根节点一次承载三样东西：基类（元素层通用样式）、类型类（按类型定向样式）、
+ * 作者 class（`class` / `style` 属性别名），以及属性映射出的 CSS 声明。
+ */
+import { elementClassName, elementStyle } from "../style";
+import type { ElementRenderContext } from "../registry";
+import type { RenderEvent, RenderKind, RenderSpec } from "../spec";
+
+/** 元素根节点基类名：所有渲染器共用，类型类与作者 class 另加 */
+const BASE_CLASS = "lf-el";
+
+/** 元素根节点描述：基类 + 类型类 + 作者 class（style 别名）+ 属性 → CSS */
+export function createRoot(
+  kind: RenderKind,
+  ctx: ElementRenderContext,
+): RenderSpec {
+  const authorClass = elementClassName(ctx.element.props);
+  return {
+    kind,
+    className: [BASE_CLASS, `lf-${ctx.element.type}`, authorClass]
+      .filter((s) => s !== "")
+      .join(" "),
+    style: elementStyle(ctx.element.props),
+  };
+}
+
+/** 追加/覆盖样式声明，返回新描述（渲染器不改手上的那棵） */
+export function withStyle(
+  spec: RenderSpec,
+  style: Readonly<Record<string, string>>,
+): RenderSpec {
+  return { ...spec, style: { ...spec.style, ...style } };
+}
+
+/** 追加/覆盖原生属性，返回新描述（插入顺序即物化顺序，勿打乱 `crossOrigin` 与 `src`） */
+export function withProps(
+  spec: RenderSpec,
+  props: Readonly<Record<string, string | number | boolean>>,
+): RenderSpec {
+  return { ...spec, props: { ...spec.props, ...props } };
+}
+
+/** 追加事件绑定，返回新描述（已有事件保序在前） */
+export function withEvents(
+  spec: RenderSpec,
+  events: readonly RenderEvent[],
+): RenderSpec {
+  return { ...spec, events: [...(spec.events ?? []), ...events] };
+}
+
+/** 数值属性读取：非有限数值一律回退（`min` / `max` / `value` 等共用） */
+export function numProp(value: unknown, fallback: number): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}

package/src/element/renderers/bindings.ts

@@ -0,0 +1,178 @@
+/**
+ * 交互与视觉态绑定（渲染器共用）。
+ *
+ * 三类视觉态（`disabled_*` / `hover_*` / `selected_*`）与点击行为**正交**：
+ * 禁用元素不挂点击但仍保留可辨识视觉态，否则玩家只看到「点了没反应」。
+ * 点击类判定走纯函数，与宿主选路同源，避免两处判定漂移。
+ *
+ * 视觉态交换以「事件补丁」表达（`RenderEvent.handler` 的返回值）：
+ * 空闲值取自描述树自身，**不从节点读回**——渲染器手上没有节点。
+ */
+import { hasElementInteraction, isElementDisabled } from "../interaction";
+import type { ElementRenderContext } from "../registry";
+import type { RenderEventPatch, RenderSpec } from "../spec";
+import { withEvents, withProps, withStyle } from "./base";
+
+/**
+ * 元素是否被禁用（最高优先级 `disabled`；`enabled=false` 同义）。
+ * 表达式形态的 `disabled` 由宿主求值后经 `ctx.evalDisable` 注入——UI 层不解析表达式语法。
+ */
+export function isDisabled(ctx: ElementRenderContext): boolean {
+  const props = ctx.element.props;
+  return isElementDisabled(props, { evalDisable: ctx.evalDisable });
+}
+
+/** 非空字符串属性（`disabled_color` / `hover_color` / `selected_color` 共用判据） */
+function colorProp(value: unknown): string | undefined {
+  return typeof value === "string" && value !== "" ? value : undefined;
+}
+
+/** 数值或长度串属性（`*_opacity` 共用判据） */
+function opacityProp(value: unknown): string | undefined {
+  if (typeof value === "number") return String(value);
+  return typeof value === "string" && value !== "" ? value : undefined;
+}
+
+/** 换图资源（`*_source`）：解析不出即不做改动（不伪造） */
+function sourceUrl(
+  ctx: ElementRenderContext,
+  value: unknown,
+): string | undefined {
+  const source = colorProp(value);
+  return source === undefined ? undefined : ctx.resolveResource?.(source);
+}
+
+/**
+ * `disabled_*` 视觉：禁用时改前景色 / 透明度 / 换图。
+ * 与点击正交——禁用元素不挂点击，但仍有可辨识的视觉态。
+ */
+function applyDisabled(
+  spec: RenderSpec,
+  ctx: ElementRenderContext,
+): RenderSpec {
+  if (!isDisabled(ctx)) return spec;
+  const props = ctx.element.props;
+  const color = colorProp(props.disabled_color);
+  const opacity = opacityProp(props.disabled_opacity);
+  const url = sourceUrl(ctx, props.disabled_source);
+  let out = spec;
+  const style: Record<string, string> = {};
+  if (color !== undefined) style.color = color;
+  if (opacity !== undefined) style.opacity = opacity;
+  if (Object.keys(style).length > 0) out = withStyle(out, style);
+  // 换图只发生在图像壳上（与既有实现同判据：非图像壳忽略 `disabled_source`）
+  if (url !== undefined && spec.kind === "image") {
+    out = withProps(out, { src: url });
+  }
+  return out;
+}
+
+/**
+ * `hover_*` 视觉：`hover_color` 改前景色、
+ * `hover_opacity` 改透明度、`hover_source` 换图（仅 image）。与点击正交。
+ */
+function applyHover(spec: RenderSpec, ctx: ElementRenderContext): RenderSpec {
+  const props = ctx.element.props;
+  const color = colorProp(props.hover_color);
+  const opacity = opacityProp(props.hover_opacity);
+  const url = sourceUrl(ctx, props.hover_source);
+  if (color === undefined && opacity === undefined && url === undefined) {
+    return spec;
+  }
+
+  const isImage = spec.kind === "image";
+  const idleColor = spec.style?.color;
+  const idleOpacity = spec.style?.opacity;
+  const idleSrc = isImage ? spec.props?.src : undefined;
+
+  const enter: RenderEventPatch = {};
+  const leave: RenderEventPatch = {};
+  if (color !== undefined) {
+    enter.style = { ...enter.style, color };
+    leave.style = { ...leave.style, color: idleColor ?? "" };
+  }
+  if (opacity !== undefined) {
+    enter.style = { ...enter.style, opacity };
+    leave.style = { ...leave.style, opacity: idleOpacity ?? "" };
+  }
+  if (url !== undefined && isImage) {
+    enter.props = { ...enter.props, src: url };
+    leave.props = { ...leave.props, src: idleSrc ?? "" };
+  }
+
+  return withEvents(spec, [
+    { on: "mouseenter", handler: () => enter },
+    { on: "mouseleave", handler: () => leave },
+  ]);
+}
+
+/**
+ * `selected_*` 视觉：点击切换选中态
+ * （`selected_color` 改前景色、`selected_source` 换图）。
+ */
+function applySelected(
+  spec: RenderSpec,
+  ctx: ElementRenderContext,
+): RenderSpec {
+  const props = ctx.element.props;
+  const color = colorProp(props.selected_color);
+  const url = sourceUrl(ctx, props.selected_source);
+  if (color === undefined && url === undefined) return spec;
+
+  const isImage = spec.kind === "image";
+  const idleColor = spec.style?.color;
+  const idleSrc = isImage ? spec.props?.src : undefined;
+  let selected = false;
+  return withEvents(spec, [
+    {
+      on: "click",
+      handler: (): RenderEventPatch => {
+        selected = !selected;
+        const patch: RenderEventPatch = {};
+        if (color !== undefined) {
+          patch.style = { color: selected ? color : (idleColor ?? "") };
+        }
+        if (url !== undefined && isImage) {
+          patch.props = { src: selected ? url : (idleSrc ?? "") };
+        }
+        return patch;
+      },
+    },
+  ]);
+}
+
+/**
+ * 交互绑定，完整优先级：`disabled` > `nav` > `ops` > `cmd` > `hover_*` > `selected_*`。
+ * - 点击：`disabled` 短路（不挂任何交互，但保留禁用视觉态）→ `nav`（核心 `navigate`）→
+ *   `ops`（引擎按序执行数据侧动作）→ `cmd`（宿主命名命令）；
+ *   分支判定在宿主（`activate` 回调内按该优先级选路），本层只负责挂载与短路。
+ * - 视觉：`hover_*` / `selected_*` / `disabled_*` 与点击正交，独立绑定。
+ */
+export function bindInteraction(
+  spec: RenderSpec,
+  ctx: ElementRenderContext,
+): RenderSpec {
+  let out = applyDisabled(spec, ctx); // 禁用视觉态（不挂点击）
+  if (isDisabled(ctx)) return out; // 最高优先级：禁用即不挂任何交互
+  out = applyHover(out, ctx);
+  out = applySelected(out, ctx);
+
+  // 点击类交互判定走纯函数（与宿主分支同源，避免两处判定漂移）
+  if (
+    !hasElementInteraction(ctx.element.props, { evalDisable: ctx.evalDisable })
+  ) {
+    return out;
+  }
+  // 元素层容器 pointer-events:none（不阻塞舞台推进）——可交互元素自行恢复
+  out = withStyle(out, { cursor: "pointer", pointerEvents: "auto" });
+  return withEvents(out, [
+    {
+      on: "click",
+      // 元素点击不应同时触发舞台推进
+      stopPropagation: true,
+      handler: () => {
+        ctx.activate?.(ctx.element);
+      },
+    },
+  ]);
+}

package/src/element/renderers/container.ts

@@ -0,0 +1,141 @@
+/**
+ * 容器族渲染器：`panel` 组（默认 flex 排布）、`grid`、`canvas`、`border`、
+ * `scroll` 组（`scroll` / `scrollviewer` / `viewport`）。
+ *
+ * 子元素一律经 `ctx.renderChildren` 取描述树，再放进自己节点的 `children` 里——
+ * 容器渲染器不接触任何节点对象。
+ */
+import { ELEMENT_CONTAINER_TYPES } from "@lingfan-engine/core";
+import { bindInteraction } from "./bindings";
+import { createRoot } from "./base";
+import type { ElementRenderContext } from "../registry";
+import type { RenderSpec } from "../spec";
+
+/**
+ * 契约判为「容器」（可承载子元素）之外的 6 型。
+ *
+ * 契约的容器判据管的是**结构合法性**：这 6 型确实能装子元素，
+ * 但各自的排布语义由专用分支决定（网格轨道 / 绝对定位 / 边框 / 滚动溢流），
+ * 不走默认 flex 分支。这里显式列出差值，是为了让契约新增容器类型时
+ * 默认排布不会被悄悄改变——若哪天新增的类型本就该 flex 排布，
+ * 从这份差集里去掉它即可，改动点只有一处。
+ */
+const NON_FLEX_CONTAINERS: ReadonlySet<string> = new Set([
+  "grid",
+  "canvas",
+  "border",
+  "scroll",
+  "scrollviewer",
+  "viewport",
+]);
+
+/** 默认走 flex 排布的容器类型（由契约容器集合减去专用分支型派生） */
+const FLEX_CONTAINERS: ReadonlySet<string> = new Set(
+  [...ELEMENT_CONTAINER_TYPES].filter((t) => !NON_FLEX_CONTAINERS.has(t)),
+);
+
+/** 容器盒模型：flex 方向（`direction` 覆盖类型默认）与 `spacing` → gap */
+function applyContainerBox(
+  style: Record<string, string>,
+  ctx: ElementRenderContext,
+): void {
+  const props = ctx.element.props;
+  const type = ctx.element.type;
+  if (!FLEX_CONTAINERS.has(type) && props.direction === undefined) return;
+  style.display = "flex";
+  const horizontal =
+    props.direction === "horizontal" || props.direction === "row";
+  style.flexDirection = horizontal || type === "hbox" ? "row" : "column";
+  const spacing = props.spacing;
+  if (typeof spacing === "number") style.gap = `${spacing}px`;
+  else if (typeof spacing === "string" && spacing !== "") style.gap = spacing;
+}
+
+/** 面板族容器：默认 flex 盒 + 递归渲染子元素 + 交互绑定（`panel`/`frame`/`window`/`vbox` 等共用） */
+export function renderContainer(ctx: ElementRenderContext): RenderSpec {
+  const spec = createRoot("box", ctx);
+  const style: Record<string, string> = { ...spec.style };
+  applyContainerBox(style, ctx);
+  return bindInteraction(
+    { ...spec, style, children: ctx.renderChildren(ctx.element.children) },
+    ctx,
+  );
+}
+
+/**
+ * grid：`columns`/`rows` 支持数字（等分）或 CSS 轨道串；
+ * 子元素附着 `col`/`row`/`colspan`/`rowspan` 按 Grid 语义（**0 基**）
+ * 映射到 CSS Grid（1 基）。
+ */
+export function renderGrid(ctx: ElementRenderContext): RenderSpec {
+  const spec = createRoot("box", ctx);
+  const style: Record<string, string> = { ...spec.style, display: "grid" };
+  const toTrack = (value: unknown): string | undefined => {
+    if (typeof value === "number" && Number.isFinite(value)) {
+      return `repeat(${value}, 1fr)`;
+    }
+    if (typeof value === "string" && value !== "") return value;
+    return undefined;
+  };
+  const columns = toTrack(ctx.element.props.columns);
+  const rows = toTrack(ctx.element.props.rows);
+  if (columns !== undefined) style.gridTemplateColumns = columns;
+  if (rows !== undefined) style.gridTemplateRows = rows;
+
+  const children = ctx.renderChildren(ctx.element.children);
+  // Grid 附着属性：按「子元素序 ↔ 描述树序」对齐（未注册类型不产出描述树，
+  // 与既有的 DOM 子节点索引同语义）
+  ctx.element.children.forEach((child, index) => {
+    const target = children[index];
+    if (target === undefined) return;
+    const { col, row, colspan, rowspan } = child.props;
+    const next: Record<string, string> = { ...target.style };
+    if (typeof col === "number") next.gridColumnStart = String(col + 1);
+    if (typeof row === "number") next.gridRowStart = String(row + 1);
+    if (typeof colspan === "number") next.gridColumnEnd = `span ${colspan}`;
+    if (typeof rowspan === "number") next.gridRowEnd = `span ${rowspan}`;
+    children[index] = { ...target, style: next };
+  });
+  return bindInteraction({ ...spec, style, children }, ctx);
+}
+
+/** canvas：自由定位容器（子元素按自身 x/y 绝对定位） */
+export function renderCanvas(ctx: ElementRenderContext): RenderSpec {
+  const spec = createRoot("box", ctx);
+  const style: Record<string, string> = { ...spec.style };
+  if (style.position === undefined) style.position = "relative";
+  if (style.overflow === undefined) style.overflow = "hidden";
+  return bindInteraction(
+    { ...spec, style, children: ctx.renderChildren(ctx.element.children) },
+    ctx,
+  );
+}
+
+/** border：纯边框/背景容器（外观由 `borderColor`/`borderThickness`/`cornerRadius` 驱动） */
+export function renderBorder(ctx: ElementRenderContext): RenderSpec {
+  const spec = createRoot("box", ctx);
+  const style: Record<string, string> = { ...spec.style };
+  if (style.border === undefined) style.border = "1px solid currentColor";
+  return bindInteraction(
+    { ...spec, style, children: ctx.renderChildren(ctx.element.children) },
+    ctx,
+  );
+}
+
+/**
+ * 滚动容器：`scroll_h`/`scroll_v` 为 false 时关闭对应轴滚动；
+ * `viewport` 语义 = 裁剪视口（不外溢，特化渲染分支）。
+ */
+export function renderScroll(ctx: ElementRenderContext): RenderSpec {
+  const spec = createRoot("box", ctx);
+  const style: Record<string, string> = {
+    ...spec.style,
+    overflow: ctx.element.type === "viewport" ? "hidden" : "auto",
+  };
+  if (ctx.element.props.scroll_h === false) style.overflowX = "hidden";
+  if (ctx.element.props.scroll_v === false) style.overflowY = "hidden";
+  return bindInteraction(
+    { ...spec, style, children: ctx.renderChildren(ctx.element.children) },
+    ctx,
+  );
+}

package/src/element/renderers/controls.ts

@@ -0,0 +1,80 @@
+/**
+ * 控件族渲染器：`button` / `choice` / `slider` / `checkbox` / 进度条三型。
+ * 取值统一经 `numProp` 归一，比例裁剪复用引擎侧的数值判据。
+ */
+import { clamp01 } from "@lingfan-engine/core";
+import { bindInteraction, isDisabled } from "./bindings";
+import { createRoot, numProp, withProps, withStyle } from "./base";
+import type { ElementRenderContext } from "../registry";
+import type { RenderSpec } from "../spec";
+
+/** 按钮：取 `text` 作正文，禁用态落到原生 `disabled`，再挂交互绑定 */
+export function renderButton(ctx: ElementRenderContext): RenderSpec {
+  const spec = createRoot("action", ctx);
+  const text = ctx.element.props.text;
+  const withText = typeof text === "string" ? { ...spec, text } : spec;
+  const props: Record<string, string | boolean> = { type: "button" };
+  if (isDisabled(ctx)) props.disabled = true;
+  return bindInteraction(withProps(withText, props), ctx);
+}
+
+/** 进度条：`value` 在 `[min, max]` 内的比例 → 内层填充（vbar 纵向） */
+export function renderProgress(ctx: ElementRenderContext): RenderSpec {
+  const spec = createRoot("box", ctx);
+  const props = ctx.element.props;
+  const min = numProp(props.min, 0);
+  const max = numProp(props.max, 100);
+  const value = numProp(props.value, min);
+  const ratio = max > min ? clamp01((value - min) / (max - min)) : 0;
+  const vertical = ctx.element.type === "vbar";
+
+  const style: Record<string, string> = { ...spec.style };
+  if (style.overflow === undefined) style.overflow = "hidden";
+
+  const fillStyle: Record<string, string> = {
+    position: "absolute",
+    background: "currentColor",
+  };
+  if (vertical) {
+    fillStyle.left = "0";
+    fillStyle.right = "0";
+    fillStyle.bottom = "0";
+    fillStyle.height = `${ratio * 100}%`;
+  } else {
+    fillStyle.left = "0";
+    fillStyle.top = "0";
+    fillStyle.bottom = "0";
+    fillStyle.width = `${ratio * 100}%`;
+  }
+  const fill: RenderSpec = {
+    kind: "box",
+    className: "lf-progress-fill",
+    style: fillStyle,
+  };
+  return { ...spec, style, children: [fill] };
+}
+
+/** 滑块：`min`/`max`/`value` 归一后写进原生 input；纵向由 `orientation` 决定书写方向 */
+export function renderSlider(ctx: ElementRenderContext): RenderSpec {
+  const spec = createRoot("slider", ctx);
+  const withPropsSpec = withProps(spec, {
+    type: "range",
+    min: String(numProp(ctx.element.props.min, 0)),
+    max: String(numProp(ctx.element.props.max, 100)),
+    value: String(numProp(ctx.element.props.value, 0)),
+  });
+  const out =
+    ctx.element.props.orientation === "vertical"
+      ? withStyle(withPropsSpec, { writingMode: "vertical-lr" })
+      : withPropsSpec;
+  return bindInteraction(out, ctx);
+}
+
+/** 复选框：`checked === true` 才勾上（其余取值一律不勾，不猜真值） */
+export function renderCheckbox(ctx: ElementRenderContext): RenderSpec {
+  const spec = createRoot("checkbox", ctx);
+  const props: Record<string, string | boolean> = { type: "checkbox" };
+  if (ctx.element.props.checked === true) props.checked = true;
+  if (isDisabled(ctx)) props.disabled = true;
+  return bindInteraction(withProps(spec, props), ctx);
+}

package/src/element/renderers/decoration.ts

@@ -0,0 +1,28 @@
+/**
+ * 间隔装饰：`separator`（分隔线）与 `spacer`（自适应留白）。
+ *
+ * 两者都是「无子节点的盒子」，只改一行布局声明：分隔线取当前前景色画一根 1px 线，
+ * 留白取 flex 剩余空间。作者已显式写下的同类声明优先（不覆盖）。
+ */
+import type { ElementRenderContext } from "../registry";
+import type { RenderSpec } from "../spec";
+import { createRoot, withStyle } from "./base";
+
+export function renderSeparator(ctx: ElementRenderContext): RenderSpec {
+  const spec = createRoot("box", ctx);
+  const style: Record<string, string> = { ...spec.style };
+  if (style.background === undefined) style.background = "currentColor";
+  if (ctx.element.props.direction === "vertical") {
+    if (style.width === undefined) style.width = "1px";
+    if (style.height === undefined) style.alignSelf = "stretch";
+  } else if (style.height === undefined) {
+    style.height = "1px";
+  }
+  return { ...spec, style };
+}
+
+export function renderSpacer(ctx: ElementRenderContext): RenderSpec {
+  const spec = createRoot("box", ctx);
+  if (spec.style?.flex !== undefined) return spec;
+  return withStyle(spec, { flex: "1 1 auto" });
+}

package/src/element/renderers/index.ts

@@ -0,0 +1,5 @@
+/**
+ * 元素渲染器的对外出口：只暴露注册入口，渲染器与绑定实现留在目录内部
+ * （渲染器签名与内部拆分方式都不构成对外契约）。
+ */
+export { registerBuiltinElementRenderers } from "./register";

package/src/element/renderers/media.ts

@@ -0,0 +1,71 @@
+/**
+ * 图像族渲染器：`image` / `background` / `portrait` / `video` / `imagebutton`。
+ *
+ * 资源解析统一走 `ctx.resolveResource`：解析失败时**保留原文**（alt / 文本），
+ * 不伪造占位图——静默占位会掩盖内容错误。
+ */
+import { elementSource } from "../style";
+import { bindInteraction, isDisabled } from "./bindings";
+import { createRoot, withProps, withStyle } from "./base";
+import type { ElementRenderContext } from "../registry";
+import type { RenderSpec } from "../spec";
+
+/** 解析资源并写回描述树，失败/能力缺失时保留原文（不伪造占位） */
+export function applySource(
+  spec: RenderSpec,
+  ctx: ElementRenderContext,
+  attr: "src" | "backgroundImage",
+): RenderSpec {
+  const source = elementSource(ctx.element.props);
+  if (source === undefined) return spec;
+  const url = ctx.resolveResource?.(source);
+  if (url === undefined) {
+    if (attr === "src") return withProps(spec, { alt: source });
+    return spec;
+  }
+  if (attr === "src") {
+    // CORS 匿名加载：存档缩略图 canvas 合成需可导出（lfstream 协议已带 ACAO:*；
+    // blob/同源不受影响）。**须在 src 赋值前设置**——插入顺序即物化顺序。
+    return withProps(spec, { crossOrigin: "anonymous", src: url });
+  }
+  return withStyle(spec, { backgroundImage: `url("${url}")` });
+}
+
+/** 图像：图像壳 + 资源（解析不出时把路径落在 `alt` 上，让读者看得见缺了什么） */
+export function renderImage(ctx: ElementRenderContext): RenderSpec {
+  return bindInteraction(
+    applySource(createRoot("image", ctx), ctx, "src"),
+    ctx,
+  );
+}
+
+/** 视频：媒体壳（隐藏控件，播放由视频域驱动），资源接法与图像同一条路 */
+export function renderVideo(ctx: ElementRenderContext): RenderSpec {
+  const spec = withProps(createRoot("media", ctx), { controls: false });
+  return bindInteraction(applySource(spec, ctx, "src"), ctx);
+}
+
+/** imagebutton：按钮壳 + 图（`source` 优先，无则退化为文本） */
+export function renderImageButton(ctx: ElementRenderContext): RenderSpec {
+  const spec = createRoot("action", ctx);
+  const source = elementSource(ctx.element.props);
+  const url = source === undefined ? undefined : ctx.resolveResource?.(source);
+
+  let out: RenderSpec;
+  if (url !== undefined) {
+    const image: RenderSpec = {
+      kind: "image",
+      className: "lf-imagebutton-img",
+      // 缩略图 canvas 合成：CORS 匿名加载（须先于 src）
+      props: { crossOrigin: "anonymous", src: url },
+    };
+    out = { ...spec, children: [image] };
+  } else {
+    const text = ctx.element.props.text;
+    out = { ...spec, text: typeof text === "string" ? text : (source ?? "") };
+  }
+
+  const props: Record<string, string | boolean> = { type: "button" };
+  if (isDisabled(ctx)) props.disabled = true;
+  return bindInteraction(withProps(out, props), ctx);
+}