@lingfan-engine/ui 0.0.0-stage → 0.1.1

package/src/element/renderers/register.ts

@@ -0,0 +1,77 @@
+/**
+ * 内建元素渲染器注册 —— **36 类型全覆盖**（唯一登记处）。
+ *
+ * 登记表是「类型名 → 渲染器」的完整映射，多个类型共用同一渲染器时并列书写，
+ * 便于一眼核对覆盖面；分组注释与渲染器文件的分族保持一致。
+ */
+import type { ElementRegistry, ElementRenderer } from "../registry";
+import { renderImage, renderImageButton, renderVideo } from "./media";
+import {
+  renderButton,
+  renderCheckbox,
+  renderProgress,
+  renderSlider,
+} from "./controls";
+import {
+  renderBorder,
+  renderCanvas,
+  renderContainer,
+  renderGrid,
+  renderScroll,
+} from "./container";
+import { renderSeparator, renderSpacer } from "./decoration";
+import { renderText } from "./text";
+
+/** 内建渲染器注册（宿主可在其后覆盖任意类型；未注册类型由宿主 fail-closed 上报） */
+export function registerBuiltinElementRenderers(
+  registry: ElementRegistry,
+): void {
+  const reg: Record<string, ElementRenderer> = {
+    // 文本族
+    text: renderText,
+    dialog: renderText,
+    narrator: renderText,
+    speaker: renderText,
+    // 交互族
+    button: renderButton,
+    choice: renderButton,
+    imagebutton: renderImageButton,
+    // 图像族
+    image: renderImage,
+    background: renderImage,
+    portrait: renderImage,
+    video: renderVideo,
+    // 容器族
+    panel: renderContainer,
+    frame: renderContainer,
+    window: renderContainer,
+    dialogbox: renderContainer,
+    choicebox: renderContainer,
+    infobox: renderContainer,
+    overlay: renderContainer,
+    popup: renderContainer,
+    vbox: renderContainer,
+    hbox: renderContainer,
+    grid: renderGrid,
+    stack: renderContainer,
+    stackpanel: renderContainer,
+    canvas: renderCanvas,
+    border: renderBorder,
+    // 滚动族
+    scroll: renderScroll,
+    scrollviewer: renderScroll,
+    viewport: renderScroll,
+    // 进度族
+    bar: renderProgress,
+    vbar: renderProgress,
+    progressbar: renderProgress,
+    slider: renderSlider,
+    checkbox: renderCheckbox,
+    // 间隔族
+    separator: renderSeparator,
+    spacer: renderSpacer,
+  };
+  for (const [type, renderer] of Object.entries(reg)) {
+    registry.register(type, renderer);
+  }
+}

package/src/element/renderers/text.ts

@@ -0,0 +1,20 @@
+/**
+ * 文本族渲染（text / dialog / narrator / speaker）。
+ *
+ * 四种类型共用同一渲染器：差异由属性（font/size/color/halign…）与 CSS 类名表达，
+ * 结构上都是「一个承载纯文本的块元素」。文本内容**不做转义/净化**——
+ * 文本族的富文本渲染由对话域负责；元素文本是纯文本，交给宿主原样落地。
+ */
+import type { ElementRenderContext } from "../registry";
+import type { RenderSpec } from "../spec";
+import { bindInteraction } from "./bindings";
+import { createRoot } from "./base";
+
+export function renderText(ctx: ElementRenderContext): RenderSpec {
+  const spec = createRoot("text", ctx);
+  const text = ctx.element.props.text;
+  return bindInteraction(
+    typeof text === "string" ? { ...spec, text } : spec,
+    ctx,
+  );
+}

package/src/element/resource.ts

@@ -0,0 +1,55 @@
+/**
+ * 元素资源解析缓存：`ResourcePort.resolve` 的**同步查表皮**（三宿主共用单一事实源）。
+ *
+ * 元素渲染是同步的（`renderElementTree` 直接产 DOM），而资源解析是异步的——
+ * 这个接缝把两者对上：同步查表 → 在途去重 → 命中即返回 URL；
+ * 未命中**只启动一次**异步解析，落地后回调宿主重渲染（整体重建语义，与 renderElementTree 一致）；
+ * 失败保持替代文本（不伪造 URL，诊断归端口/宿主）。
+ *
+ * 缓存机制本身在资源域（`../resources`）只有一份；此处只把它对到元素渲染的同步契约上。
+ */
+import { createResourceUrlCache } from "../resources";
+
+/**
+ * 装配输入：一个异步解析函数 + 一个「落地了」的回调。
+ * 缓存不关心 URL 怎么来的——换掉 `resolve` 就换了取源方式（本地 / 远端 / 测试替身）。
+ */
+export interface ElementResourceResolverOptions {
+  /** 资源解析（通常即 `resourcePort.resolve`） */
+  resolve: (path: string) => Promise<string>;
+  /** 解析落地后的回调（宿主据此重渲染元素层） */
+  onResolved: () => void;
+}
+
+/**
+ * 元素渲染侧看到的解析器：**同步**的一问一答。
+ * 只暴露这一个方法——在途去重、缓存、失败重试的细节都封在工厂里，
+ * 调用点（`renderElementTree`）不需要知道资源是异步拿到的。
+ */
+export interface ElementResourceResolver {
+  /** 供 `renderElementTree` 的 `resolveResource` 使用；未就绪返回 `undefined`（显示替代文本） */
+  resolveForElement: (path: string) => string | undefined;
+}
+
+/**
+ * 把异步资源端口接到元素渲染的同步契约上。
+ *
+ * 未命中时启动一次解析并立即返回 `undefined`（这一帧显示替代文本），
+ * 落地后经 `onResolved` 让宿主重渲染；解析失败不缓存失败态，下次问还会再试。
+ */
+export function createElementResourceResolver(
+  options: ElementResourceResolverOptions,
+): ElementResourceResolver {
+  const cache = createResourceUrlCache(options.resolve, {
+    onResolved: options.onResolved,
+  });
+  return {
+    resolveForElement(path: string): string | undefined {
+      const cached = cache.get(path);
+      if (cached !== undefined) return cached;
+      // 失败不粘滞：资源补上后仍可再试（错误归端口/宿主诊断，此处不重渲染）
+      void cache.resolve(path).catch(() => undefined);
+      return undefined;
+    },
+  };
+}

package/src/element/spec.ts

@@ -0,0 +1,77 @@
+/**
+ * 渲染描述树（平台中立）：渲染器不建节点，只产出这棵树；由宿主注入的渲染端口
+ * 物化成自己的节点模型（Web 侧实现见 `packages/ui/src/dom`）。
+ *
+ * 中立判据：本文件不出现 DOM 类型、DOM 全局与 DOM 标签名——节点种类用 `RenderKind`
+ * 词表。`slider` / `checkbox` 不与 `input` 合并成「`input` + type 字段」：
+ * `range` / `checkbox` 是 DOM 的 type 词表，留在描述树里等于把 DOM 词汇漏进中立面。
+ */
+
+/** 节点种类：物化器负责映射到自己平台的标签/组件 */
+export type RenderKind =
+  | "box"
+  | "text"
+  | "image"
+  | "media"
+  | "input"
+  | "slider"
+  | "checkbox"
+  | "action";
+
+/** 写入节点的原生属性值（属性名沿用各民族平台的通用拼写：`src` / `alt` / `disabled` …） */
+export type RenderPropValue = string | number | boolean;
+
+/**
+ * 事件触发时对目标节点应用的改动。
+ *
+ * 视觉态交换（hover 进入/离开、点击切换选中）都走这条通道：
+ * 渲染器不需要拿到节点，就能表达「触发时改哪些样式/属性」。
+ */
+export interface RenderEventPatch {
+  style?: Readonly<Record<string, string>>;
+  props?: Readonly<Record<string, RenderPropValue>>;
+}
+
+/** 事件绑定；`handler` 的返回值即触发时要应用的补丁（无返回值 = 不改节点） */
+export interface RenderEvent {
+  on: "click" | "mouseenter" | "mouseleave";
+  handler?: () => RenderEventPatch | void;
+  /** 阻止冒泡（元素点击不应同时触发舞台推进） */
+  stopPropagation?: boolean;
+}
+
+/**
+ * 一棵节点的描述。字段与物化顺序一致：类名 → 样式 → 文本/富文本 → 属性 → 定位锚 →
+ * 子节点 → 事件。
+ *
+ * `html` 沿用「调用方负责转义」的既有约定（见对话文本视图），本树不做二次净化。
+ */
+export interface RenderSpec {
+  kind: RenderKind;
+  /** 类名（物化器原样写入；元素渲染器在此放基类 + 类型类 + 作者 class） */
+  className?: string;
+  /** CSS 声明（camelCase 键，与元素的属性 → CSS 映射同源） */
+  style?: Readonly<Record<string, string>>;
+  /** 纯文本内容 */
+  text?: string;
+  /** 富文本内容（调用方负责转义） */
+  html?: string;
+  props?: Readonly<Record<string, RenderPropValue>>;
+  children?: readonly RenderSpec[];
+  events?: readonly RenderEvent[];
+  /** 定位锚（动画按元素 id 找节点；无锚点概念的宿主可忽略） */
+  id?: string;
+}
+
+/**
+ * 渲染端口（宿主注入）：一对动作——清空渲染根、物化一棵描述树挂上去。
+ *
+ * 「整体重建」是元素渲染的既有语义（每帧全量给元素，不做增量对比），
+ * 因此端口只需这两条原语即可覆盖现状；增量更新由宿主内部决定。
+ */
+export interface RenderPort {
+  /** 清空渲染根下的全部节点 */
+  clear(): void;
+  /** 物化一棵描述树并挂到渲染根下 */
+  mount(spec: RenderSpec): void;
+}

package/src/element/style.ts

@@ -0,0 +1,150 @@
+/**
+ * 元素属性 → CSS 映射（纯函数，可测）。
+ * 只做「属性名/值 → 样式声明」的机械映射：属性合法性在解析期已 fail-closed，
+ * 此处不重复校验；**未覆盖的属性一律不出现在结果中**。
+ *
+ * 「未覆盖」分两类：
+ * ① **由渲染器消费**而非 CSS 的属性（`text` / `source` / `orientation` / `checked` / `nav` / `cmd` / Grid 轨道…）——正常分工；
+ * ② **已声明但当前无 CSS 语义的属性**（`valign` / `xalign` / `yalign` / `xoffset` / `yoffset` / `xanchor` / `yanchor`）——
+ *    对本映射写了不生效；清单单一事实源 = `@lingfan-engine/editor` 的 `UNIMPLEMENTED_ELEMENT_ATTRS`
+ *    （编辑器不再下发这些控件，并对已存在的写出 warning；三面对齐互锁测试守住差集）。
+ *    例外：`order` 不是死属性——引擎装载期在用（z 兜底：packages/core/src/data/element.ts:157、
+ *    runtime/internal/frame-stack.ts:62 消费），只是不经本 CSS 映射，故不在本清单。
+ *
+ * 定位语义：`x`/`y` 支持百分比（若换算为像素 Margin 就锁死了尺寸，
+ * DOM 侧直接交给 CSS，`left: 50%` 天然按父容器尺寸解析）。
+ */
+
+/** 数值 → css 长度（px）；字符串原样（支持 `50%` / `2em` / `center` 等） */
+function len(value: unknown): string | undefined {
+  if (typeof value === "number" && Number.isFinite(value)) return `${value}px`;
+  if (typeof value === "string" && value !== "") return value;
+  return undefined;
+}
+
+/** 数值原样（opacity / zIndex / scale 等纯数字） */
+function num(value: unknown): string | undefined {
+  return typeof value === "number" && Number.isFinite(value)
+    ? String(value)
+    : undefined;
+}
+
+/** 布尔 → 显隐（`visible=false` 等价 `display:none`） */
+function bool(value: unknown): boolean | undefined {
+  return typeof value === "boolean" ? value : undefined;
+}
+
+/** 首个子属性值（多键别名：source/src/path、color/fontColor/textColor） */
+function pick(props: Record<string, unknown>, ...keys: string[]): unknown {
+  for (const key of keys) {
+    const value = props[key];
+    if (value !== undefined) return value;
+  }
+  return undefined;
+}
+
+/**
+ * 属性 → CSS 声明表。返回对象可直接 `Object.assign(el.style, table)`。
+ * 未实现/不适用的属性不出现在结果中。
+ */
+export function elementStyle(
+  props: Record<string, unknown>,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  const set = (key: string, value: string | undefined): void => {
+    if (value !== undefined) out[key] = value;
+  };
+
+  // —— 定位（x/y/right/bottom 任一存在即绝对定位；百分比值原样交给 CSS）——
+  const x = len(props.x);
+  const y = len(props.y);
+  const right = len(props.right);
+  const bottom = len(props.bottom);
+  if (
+    x !== undefined ||
+    y !== undefined ||
+    right !== undefined ||
+    bottom !== undefined
+  ) {
+    set("position", "absolute");
+    if (x !== undefined) set("left", x);
+    if (y !== undefined) set("top", y);
+    if (right !== undefined) set("right", right);
+    if (bottom !== undefined) set("bottom", bottom);
+  }
+  // align 是 halign 的安全网：显式 textAlign/halign 优先
+  set(
+    "textAlign",
+    len(props.textAlign) ?? len(props.halign) ?? len(props.align),
+  );
+
+  // —— 尺寸 ——
+  set("width", len(props.width));
+  set("height", len(props.height));
+  set("minWidth", len(props.minWidth));
+  set("minHeight", len(props.minHeight));
+  set("maxWidth", len(props.maxWidth));
+  set("maxHeight", len(props.maxHeight));
+
+  // —— 盒模型 ——
+  set("margin", len(props.margin));
+  set("padding", len(props.padding));
+
+  // —— 外观 ——
+  set("opacity", num(props.opacity));
+  set("zIndex", num(props.zindex));
+  set("cursor", len(props.cursor));
+  const visible = bool(props.visible);
+  if (visible === false) set("display", "none");
+  if (bool(props.clipToBounds) === true) set("overflow", "hidden");
+
+  // —— 变换 ——
+  const transforms: string[] = [];
+  const rotation = num(props.rotation);
+  if (rotation !== undefined) transforms.push(`rotate(${rotation}deg)`);
+  const scale = num(props.scale);
+  if (scale !== undefined) transforms.push(`scale(${scale})`);
+  else {
+    const scaleX = num(props.scaleX);
+    const scaleY = num(props.scaleY);
+    if (scaleX !== undefined || scaleY !== undefined) {
+      transforms.push(`scale(${scaleX ?? "1"}, ${scaleY ?? "1"})`);
+    }
+  }
+  if (transforms.length > 0) set("transform", transforms.join(" "));
+
+  // —— 边框 ——
+  set("borderRadius", len(props.cornerRadius));
+  const borderThickness = len(props.borderThickness);
+  const borderColor = len(props.borderColor) ?? len(props.borderBrush);
+  if (borderThickness !== undefined || borderColor !== undefined) {
+    set(
+      "border",
+      `${borderThickness ?? "1px"} solid ${borderColor ?? "currentColor"}`,
+    );
+  }
+
+  // —— 文本 ——
+  // size = 文本类 fontSize 别名
+  set("fontSize", len(props.fontSize) ?? len(props.size));
+  set("fontFamily", len(props.font));
+  const color = pick(props, "color", "fontColor", "textColor");
+  set("color", typeof color === "string" ? color : undefined);
+
+  return out;
+}
+
+/** 内容/样式类属性（不进 CSS，由渲染器消费） */
+export function elementClassName(props: Record<string, unknown>): string {
+  // `style` 是 `class` 的别名
+  const raw = pick(props, "class", "style");
+  return typeof raw === "string" ? raw : "";
+}
+
+/** 图片类元素的资源路径（source 优先，src/path 兜底） */
+export function elementSource(
+  props: Record<string, unknown>,
+): string | undefined {
+  const raw = pick(props, "source", "src", "path");
+  return typeof raw === "string" && raw !== "" ? raw : undefined;
+}

package/src/host/duration.ts

@@ -0,0 +1,25 @@
+/**
+ * 宿主表现的行业默认节律（具名导出，**不承担「统一默认值」职责**）。
+ *
+ * 两个参考宿主的实际取值并不相同：Vue 参考宿主用 1500/2500/3000 ms 与各自的偏好速度，
+ * 原生 DOM 模板宿主用 2600 ms 与 30 cps。所以这里只给「同一件事的默认叫什么名字」，
+ * 由各自宿主把自己原本的字面量作为参数传进来——同源的是**声明**，不是取值。
+ */
+
+/** 文字推进的默认速度（可见字符/秒）：故事未声明 `text_typewriter` 速度时的兜底 */
+export const DEFAULT_TEXT_CPS = 30;
+
+/** 提示条默认驻留时长（毫秒） */
+export const DEFAULT_TOAST_MS = 2600;
+
+/** 通知默认驻留时长（毫秒）：`notify` 未自带 duration 时的兜底，最长一档 */
+export const DEFAULT_NOTIFY_MS = 3000;
+
+/** 操作反馈轻提示默认驻留时长（毫秒）：存/读按钮等即时反馈 */
+export const DEFAULT_ACTION_TOAST_MS = 1500;
+
+/** 读档完成提示默认驻留时长（毫秒）：文案含状态说明，比即时反馈多留一档 */
+export const DEFAULT_LOAD_TOAST_MS = 2500;
+
+/** 回溯轻提示默认驻留时长（毫秒）：与即时反馈同档 */
+export const DEFAULT_ROLLBACK_NOTICE_MS = 1500;

package/src/host/effects.ts

@@ -0,0 +1,174 @@
+/**
+ * 帧驱动表现：把引擎里的**动画描述**逐帧插值成 DOM 写入。
+ *
+ * 引擎只写描述（离散、进快照），逐帧的插值与 DOM 写入发生在宿主侧——本模块就是那一步的
+ * 唯一实现。插值数学一律取自展示域既有纯函数（`interpolateAnimation` / `transitionOpacity` /
+ * `shakeOffset`），此处不新增第二份算式。
+ *
+ * 三段共用一个 `dt`，顺序固定：元素动画 → 全屏转场 → 屏幕震动。
+ *
+ * 本模块**不认识引擎实例**：它用到的那几件事（当前动画队列、转场与震动描述、三个播毕交回）
+ * 全部以 `EffectSource` 端口注入。于是每处引擎调用都变成宿主那侧的一行接线，而时机判定、
+ * 累计量与收尾顺序只留在这一处。
+ *
+ * DOM 写入同样经注入：
+ * - `onAnimatedProperty(target, property, value)` 按元素 id 把数值属性写进该节点
+ *   （节点解析与写入都在宿主侧，本模块既不持有也不查询节点）；
+ * - `onTransitionFrame(opacity)` / `onTransitionDone()` 与 `onShakeFrame(x, y)` / `onShakeDone()`
+ *   成对出现：宿主在 `*Frame` 里写遮罩与位移，在 `*Done` 里收尾（隐藏遮罩、位移归位）。
+ *
+ * 元素动画**必须交回引擎**（`source.animationFinished`）：否则动画队列只增不减（长会话泄漏），
+ * 且元素永远到不了终值。
+ *
+ * 「节点在不在」由宿主在 `on*` 里自行兜底（如遮罩元素缺失时直接丢弃该帧）：本模块不做
+ * 存在性判断，否则同一份时机判定会被各宿主的 DOM 结构差异撕成多份。
+ *
+ * 逐帧读 `animations()` 而非构造期取一次：动画由故事命令在任意时刻建立。
+ */
+
+import {
+  interpolateAnimation,
+  shakeOffset,
+  transitionOpacity,
+} from "../element";
+import type { AnimationSpec } from "@lingfan-engine/core";
+
+/**
+ * 元素动画的可写样式声明：只有故事语言里出现的那五个数值属性。
+ * 用对象而不是直接写 `node.style`，是为了让「属性 → CSS」这层映射留在本模块，
+ * 而把唯一的写动作留在宿主（`Object.assign(node.style, …)`）。
+ */
+export interface AnimatedStyle {
+  left?: string;
+  top?: string;
+  opacity?: string;
+  transform?: string;
+}
+
+/**
+ * 数值属性 → CSS 声明。
+ *
+ * `x`/`y` 走 `left`/`top`（相对定位位移），`rotation`/`scale` 都落在 `transform` 上——
+ * 同一时刻只有一个 transform 生效，这是元素样式既有的口径（作者若要叠加请自己写 `style`）。
+ * 未识别的属性返回 null：宿主据此跳过写入，而不是写一个空声明把已有样式抹掉。
+ */
+export function resolveAnimatedStyle(
+  property: string,
+  value: number,
+): AnimatedStyle | null {
+  if (property === "x") return { left: `${value}px` };
+  if (property === "y") return { top: `${value}px` };
+  if (property === "opacity") return { opacity: String(value) };
+  if (property === "rotation") return { transform: `rotate(${value}deg)` };
+  if (property === "scale") return { transform: `scale(${value})` };
+  return null;
+}
+
+/** 引擎侧事实与交回动作：三个播毕交回是动画队列得以继续推进的唯一出口 */
+export interface EffectSource {
+  /** 当前待播的元素动画队列 */
+  animations(): readonly AnimationSpec[];
+  /** 全屏转场的启动键（未在转场时为 undefined） */
+  transition(): { duration: number } | undefined;
+  /** 屏幕震动的启动键（未在震动时为 undefined） */
+  shake(): { intensity: number; duration: number } | undefined;
+  /** 元素动画播毕：交回引擎，元素才会落到终值 */
+  animationFinished(seq: number): void;
+  /** 全屏转场播毕：交回引擎，转场命令才会继续 */
+  transitionFinished(): void;
+  /** 屏幕震动播毕：交回引擎，震动命令才会继续 */
+  shakeFinished(): void;
+}
+
+/**
+ * 宿主触点（注入端口）：本模块只做插值与时机判定，节点解析与 DOM 读写全由宿主实现。
+ * 本模块只交出 `target`（元素 id）——不持有节点、不查节点、不读样式、不写样式。
+ */
+export interface AnimationHost {
+  /**
+   * 数值属性 → CSS 写入：宿主按 `target` 自行解析动画节点（元素渲染器写在
+   * `data-lf-id` 上的定位锚），映射口径用 `resolveAnimatedStyle`；节点不存在时宿主忽略该帧。
+   */
+  onAnimatedProperty(target: string, property: string, value: number): void;
+}
+
+/** 全屏转场与屏幕震动的宿主触点（每帧回调先于播毕回调） */
+export interface EffectSurfaceHost {
+  /** 转场遮罩的一帧：写入不透明度（显示时机由宿主决定） */
+  onTransitionFrame(opacity: number): void;
+  /** 转场播毕：宿主收尾（隐藏遮罩） */
+  onTransitionDone(): void;
+  /** 屏幕震动的一帧：对舞台根施加偏移 */
+  onShakeFrame(x: number, y: number): void;
+  /** 震动播毕：宿主归位 */
+  onShakeDone(): void;
+}
+
+/** 逐帧驱动函数的输入：三段各自的事实来源与 DOM 触点 */
+export interface VisualEffectsOptions {
+  /** 引擎侧事实与播毕交回 */
+  source: EffectSource;
+  animation: AnimationHost;
+  surface: EffectSurfaceHost;
+}
+
+/**
+ * 创建一个逐帧驱动函数：宿主每帧调用一次，传入距上一帧的秒数。
+ *
+ * 累计量（各动画已播秒数、转场已播秒数、震动时钟）都在闭包里，每实例一份——
+ * 放在模块级会让同一页面的两个舞台互相串扰。
+ */
+export function createVisualEffects(
+  options: VisualEffectsOptions,
+): (dt: number) => void {
+  const { source, animation, surface } = options;
+  /** seq → 已播秒数 */
+  const animatedElapsed = new Map<number, number>();
+  let transitionElapsed = 0;
+  let shakeClock = 0;
+
+  return (dt: number): void => {
+    // ① 元素动画：累计 elapsed → 插值写 DOM → 播毕交回引擎（终值写回元素属性）
+    const animations = source.animations();
+    if (animations.length > 0) {
+      for (const spec of animations) {
+        const elapsed = (animatedElapsed.get(spec.seq) ?? 0) + dt;
+        animatedElapsed.set(spec.seq, elapsed);
+        const { value, done } = interpolateAnimation(spec, elapsed);
+        animation.onAnimatedProperty(spec.target, spec.property, value);
+        if (done) {
+          animatedElapsed.delete(spec.seq);
+          source.animationFinished(spec.seq);
+        }
+      }
+    }
+
+    // ② 全屏转场：读启动键按进度改遮罩，播毕清除
+    const transition = source.transition();
+    if (transition != null) {
+      transitionElapsed += dt;
+      const progress =
+        transition.duration > 0 ? transitionElapsed / transition.duration : 1;
+      surface.onTransitionFrame(transitionOpacity(progress));
+      if (progress >= 1) {
+        transitionElapsed = 0;
+        surface.onTransitionDone();
+        source.transitionFinished();
+      }
+    }
+
+    // ③ 屏幕震动：对舞台根施加衰减偏移，播毕归位
+    const shake = source.shake();
+    if (shake != null) {
+      shakeClock += dt;
+      const progress = shake.duration > 0 ? shakeClock / shake.duration : 1;
+      const { x, y } = shakeOffset(shake.intensity, progress, shakeClock);
+      surface.onShakeFrame(x, y);
+      if (progress >= 1) {
+        shakeClock = 0;
+        surface.onShakeDone();
+        source.shakeFinished();
+      }
+    }
+  };
+}

package/src/host/frame-loop.ts

@@ -0,0 +1,84 @@
+/**
+ * 帧循环：把「每帧要推进的事情」编排成一次连续续帧的循环。
+ *
+ * 推进什么由注入的 `onTick` 决定，本模块只管排帧、算 `dt` 与三种收尾：
+ * - `start()` 幂等；`stop()` 不可逆（卸载收尾）；`setRunning()` 是运行中的暂停/恢复，
+ *   恢复时重置时间基准，暂停的时长不会被算进下一帧的 `dt`。
+ * - 帧源（`requestAnimationFrame` 或宿主的等价物）由外部注入——本模块不认平台 API，
+ *   也不自己计时：`dt` 由帧源给的时间戳算出。
+ * - 首帧没有上一帧可比，`dt` 记 0：否则开场会凭空多推进一段时间。
+ */
+
+/** 帧源：宿主把平台的「下一帧」能力包成这两个方法 */
+export interface FrameSource {
+  /** 申请下一帧；回调收到帧源自己的时间原点（毫秒） */
+  request(callback: (now: number) => void): number;
+  /** 取消已申请的帧（句柄来自 `request` 的返回值） */
+  cancel(handle: number): void;
+}
+
+/** 帧循环的输入：帧源 + 每帧要推进的一件事 */
+export interface FrameLoopOptions {
+  frame: FrameSource;
+  /** 推进一帧；`dtSeconds` 是距上一帧的秒数（首帧为 0） */
+  onTick(dtSeconds: number): void;
+}
+
+/**
+ * 帧循环句柄：`start()` 后续帧自动申请，直到 `stop()`（不可逆）或 `setRunning(false)`。
+ *
+ * 句柄只暴露这三个开关，推进顺序由装配方的 `onTick` 固定，循环本身不猜任何业务。
+ */
+export interface FrameLoop {
+  /** 启动循环：已在运行或已卸载时为空操作 */
+  start(): void;
+  /** 不可逆地停帧并取消已排定的帧（卸载时调用） */
+  stop(): void;
+  /** 运行中的暂停/恢复；恢复时会重置时间基准 */
+  setRunning(running: boolean): void;
+}
+
+/**
+ * 创建帧循环：帧源与每帧动作全部由外部注入，故本模块可被任何渲染宿主复用
+ * （覆盖层与各宿主的 `startHostFrameLoop` 都建在它之上）。
+ */
+export function createFrameLoop(options: FrameLoopOptions): FrameLoop {
+  let handle = 0;
+  let last = 0;
+  let running = false;
+  let disposed = false;
+
+  const frame = (now: number): void => {
+    if (!running) return;
+    const dt = last > 0 ? (now - last) / 1000 : 0;
+    last = now;
+
+    options.onTick(dt);
+
+    // `stop()` 可能发生在帧内（如加载失败）：那时不再续帧
+    if (running) handle = options.frame.request(frame);
+  };
+
+  return {
+    start(): void {
+      if (running || disposed) return;
+      running = true;
+      handle = options.frame.request(frame);
+    },
+    stop(): void {
+      if (disposed) return;
+      disposed = true;
+      running = false;
+      if (handle !== 0) options.frame.cancel(handle);
+      handle = 0;
+      last = 0;
+    },
+    setRunning(next: boolean): void {
+      if (disposed || next === running) return;
+      running = next;
+      // 暂停的时长不算进下一帧：恢复时丢掉上一次的基准
+      last = 0;
+      if (running) handle = options.frame.request(frame);
+    },
+  };
+}