@lingfan-engine/create 0.0.0-stage → 0.1.5

package/template/overlays/miniprogram/src/mp/ports.ts

@@ -0,0 +1,84 @@
+/**
+ * 平台端口装配：把小程序能力接到引擎与展示层的端口上。
+ *
+ * 四件事：同步存储（存档与玩家偏好共用同一份面）、资源地址（内容在服务端：故事里的裸 id
+ * 由资源端口拼成 `<工程基址>/<id>`）、媒体端口（音频实例由平台造，视频呈现面由组合根注入——
+ * 它要写页面数据，属宿主形态而非平台能力）、以及存档键前缀（与参考宿主的前缀区分开，
+ * 同一台设备上不会串档）。
+ */
+import {
+  createMiniprogramAudioPort,
+  createMiniprogramPreferencesPort,
+  createMiniprogramSavePort,
+  createMiniprogramVideoPort,
+  type MiniprogramStorageLike,
+  type MiniprogramVideoSurfaceLike,
+} from "@lingfan-engine/adapters";
+import type {
+  AudioPort,
+  PreferencesPort,
+  ResourcePort,
+  SavePort,
+  VideoPort,
+} from "@lingfan-engine/core";
+import { createAudioContext, uniApi } from "./platform.ts";
+import { createRemoteResourcePort } from "./project-source.ts";
+
+/** 本工程的存档键前缀（含高水位键，两者必须同前缀才互不干扰） */
+const SAVE_KEY_PREFIX = "lingfan-miniprogram:";
+/** 高水位键：低于已记录档数的读档会被拒绝，防误覆盖 */
+const SAVE_HIGH_WATER_KEY = "lingfan-miniprogram:highwater";
+
+/** 宿主给引擎与装配器用的端口 */
+export interface MiniprogramHostPorts {
+  save: SavePort;
+  preferences: PreferencesPort;
+  resources: ResourcePort;
+  /** 音频端口：四条通道共用一套实例管理（实例由平台造） */
+  audio: AudioPort;
+  /** 视频端口：状态推给呈现面，播放中的控制走组件控制柄 */
+  video: VideoPort;
+}
+
+/** 端口装配参数：视频呈现面由组合根造（它要写页面数据） */
+export interface MiniprogramPortsOptions {
+  /** 视频呈现面（宿主形态相关，不属于平台能力） */
+  videoSurface: MiniprogramVideoSurfaceLike;
+  /** 工程基址（故事与资源都从它取）；缺省读运行期配置 */
+  projectBaseUrl?: string;
+}
+
+/** 装配平台端口 */
+export function createMiniprogramHostPorts(
+  options: MiniprogramPortsOptions,
+): MiniprogramHostPorts {
+  const storage = createStorageFace();
+  return {
+    save: createMiniprogramSavePort(storage, {
+      keyPrefix: SAVE_KEY_PREFIX,
+      highWaterKey: SAVE_HIGH_WATER_KEY,
+    }),
+    preferences: createMiniprogramPreferencesPort(storage),
+    resources: createRemoteResourcePort(options.projectBaseUrl),
+    audio: createMiniprogramAudioPort(createAudioContext),
+    video: createMiniprogramVideoPort(options.videoSurface),
+  };
+}
+
+/** 把 `uni` 的同步存储包成适配器认识的存储面（取不到的键归一为空串） */
+function createStorageFace(): MiniprogramStorageLike {
+  const api = uniApi();
+  return {
+    set: (key, value) => {
+      api.setStorageSync(key, value);
+    },
+    get: (key) => {
+      const value = api.getStorageSync(key);
+      return typeof value === "string" ? value : "";
+    },
+    remove: (key) => {
+      api.removeStorageSync(key);
+    },
+    keys: () => api.getStorageInfoSync().keys,
+  };
+}

package/template/overlays/miniprogram/src/mp/project-source.ts

@@ -0,0 +1,77 @@
+/**
+ * 工程来源（远端）：清单与故事从工程接口取，媒体资源按同一个基址拼地址。
+ *
+ * 小程序包体只装代码——故事与素材都是内容，走 HTTP 从服务端取，改内容不必重新提审发版。
+ * 基址只有一处（`DEFAULT_PROJECT_BASE_URL`，可用环境变量 `VITE_PROJECT_BASE_URL` 覆盖）：
+ * - 工程接口 = 基址 + `project`：一次返回 `{ manifest, stories }`（故事原文，解析归引擎）；
+ * - 资源地址 = 基址 + 资源 id：`Audio/x.mp3` → `<基址>/Audio/x.mp3`（静态托管形态）。
+ *
+ * 本文件不碰平台全局：取件面由组合根注入（小程序用 `uni.request` 包的那个），
+ * 所以 Node 下能直接单测。
+ */
+import {
+  createHttpProjectFilesPort,
+  createStaticResourcePort,
+  type HttpFetch,
+} from "@lingfan-engine/adapters";
+import type { ProjectFilesPort, ResourcePort } from "@lingfan-engine/core";
+
+/** 缺省基址：与本地开发服务（`scripts/serve-project.mjs`）的端口一致 */
+export const DEFAULT_PROJECT_BASE_URL = "http://127.0.0.1:5273/";
+
+/** 工程接口路径（相对基址） */
+export const PROJECT_ENDPOINT_PATH = "project";
+
+/**
+ * 规范化基址：必须是 http(s) 绝对地址、以 `/` 结尾（资源 id 直接拼上来）。
+ * 形状不对就抛——配错了要在启动时暴露，不能拼出一串坏地址到播放阶段。
+ */
+export function normalizeProjectBaseUrl(baseUrl: string): string {
+  const trimmed = baseUrl.trim();
+  if (!/^https?:\/\//i.test(trimmed)) {
+    throw new Error(`工程基址必须是 http(s) 绝对地址：${baseUrl}`);
+  }
+  return trimmed.endsWith("/") ? trimmed : `${trimmed}/`;
+}
+
+/** 读运行期基址：环境变量优先，缺省指本地开发服务 */
+export function resolveProjectBaseUrl(): string {
+  const env = import.meta.env as
+    { VITE_PROJECT_BASE_URL?: unknown } | undefined;
+  const fromEnv = env?.VITE_PROJECT_BASE_URL;
+  const value = typeof fromEnv === "string" ? fromEnv.trim() : "";
+  return normalizeProjectBaseUrl(
+    value === "" ? DEFAULT_PROJECT_BASE_URL : value,
+  );
+}
+
+/** 工程接口地址 */
+export function projectEndpointUrl(
+  baseUrl: string = resolveProjectBaseUrl(),
+): string {
+  return `${normalizeProjectBaseUrl(baseUrl)}${PROJECT_ENDPOINT_PATH}`;
+}
+
+/**
+ * 造远端工程供给端口：清单与故事都从工程接口取。
+ * @param options 取件面（必给，平台能力由组合根注入）与基址（缺省读运行期配置）
+ */
+export function createRemoteProjectFilesPort(options: {
+  fetch: HttpFetch;
+  baseUrl?: string;
+}): ProjectFilesPort {
+  return createHttpProjectFilesPort({
+    url: projectEndpointUrl(options.baseUrl),
+    fetch: options.fetch,
+  });
+}
+
+/**
+ * 造远端资源端口：故事里的裸资源 id 拼到基址下（`Audio/x.mp3` → `<基址>/Audio/x.mp3`）。
+ * 路径规范化沿用资源域的同一份规则（空段与 `..` 逃逸在信任边界上拒绝）。
+ */
+export function createRemoteResourcePort(
+  baseUrl: string = resolveProjectBaseUrl(),
+): ResourcePort {
+  return createStaticResourcePort(normalizeProjectBaseUrl(baseUrl));
+}

package/template/overlays/miniprogram/src/mp/slots.ts

@@ -0,0 +1,64 @@
+/**
+ * 存档入口的宿主侧装配：槽位视图与存读点选。
+ *
+ * 槽位数、「空槽能不能点」这些判据都在壳层与引擎（`@lingfan-engine/shell` / `@lingfan-engine/core`），
+ * 本文件只做两件事：按工程清单的槽数拉一次逐槽视图，把面板上的点选翻成存/读命令。
+ * 规则不在这里另写一份——槽位 id 生成与桌面宿主同源，改规则只改那一处。
+ *
+ * 本文件不碰平台全局与框架：面板由页面渲染，这里只产出数据与回执，Node 下可直测。
+ */
+import { slotIds, type SavePort } from "@lingfan-engine/core";
+import {
+  canChooseSlot,
+  loadSlotViews,
+  type SlotPanelMode,
+  type SlotView,
+} from "@lingfan-engine/shell";
+
+export type { SlotPanelMode, SlotView };
+/** 空槽判据随出口一起给页面用：槽位能不能点全仓只有壳层这一份规则 */
+export { canChooseSlot };
+
+/** 槽位视图的取数参数 */
+export interface HostSlotViewsOptions {
+  /** 存档端口（清单与逐槽读取） */
+  savePort: SavePort;
+  /** 槽位数量（工程清单 `shell.saves.slots`，内建默认见引擎） */
+  slots: number;
+}
+
+/** 拉取面板要的逐槽视图：打开面板时调一次 */
+export function loadHostSlotViews(
+  options: HostSlotViewsOptions,
+): Promise<SlotView[]> {
+  // 槽位 id 由引擎的唯一规则生成：`slot_1..slot_N`（与 Rust 侧存储命名兼容）
+  return loadSlotViews({
+    savePort: options.savePort,
+    slotIds: slotIds(options.slots),
+  });
+}
+
+/** 存读点选参数：命令回调由宿主句柄注入（引擎归组合根） */
+export interface ChooseHostSlotOptions {
+  /** 面板当前模式（未打开时为 null） */
+  mode: SlotPanelMode | null;
+  /** 被点选的槽位 */
+  view: SlotView;
+  /** 写入存档（`engine.save`） */
+  save(slot: string): boolean;
+  /** 读取存档（`engine.load`） */
+  load(slot: string): boolean;
+}
+
+/**
+ * 按当前模式执行点选。
+ *
+ * 回执 = 命令是否被接受（读档真正落地晚于返回：媒体对齐挂在引擎的 `load.done` 事件上）。
+ * 空槽在读档模式下直接不执行——引擎读不到档也是 fail-closed，但让玩家先点一次再收一条
+ * 提示没有意义；判据与桌面面板同一份（`canChooseSlot`）。
+ */
+export function chooseHostSlot(options: ChooseHostSlotOptions): boolean {
+  if (!canChooseSlot(options.view, options.mode)) return false;
+  if (options.mode === "save") return options.save(options.view.id);
+  return options.load(options.view.id);
+}

package/template/overlays/miniprogram/src/mp/surface.ts

@@ -0,0 +1,239 @@
+/**
+ * 小程序覆盖层表面：把中立层的「每层显示什么」翻成页面数据。
+ *
+ * 中立核心只提交视图模型（对话/选择/通知）与两棵描述树（舞台/元素），落到节点这一端
+ * 归宿主；小程序没有 DOM，所以这一端的产物是**数据补丁**——一次 setData 就是一次整层
+ * 重建。通知的生命周期（到点移除）也在这里：中立面只给停留时长。
+ *
+ * NVL 累积层不在中立表面契约里：它读同一条渲染投影（`onView` 给的
+ * `nvlMode`/`nvlLines`/`lineHtml`），在这里翻成「已打完行 + 打字中一行」的 HTML。
+ * 可见性仍归对话层（NVL 只是对话容器的另一种内容形态，与桌面面板同口径）。
+ *
+ * 层级 z 与 DOM 侧的差别：WXML 没有 z-index 概念，层序由节点顺序决定。这里仍把 z 收下
+ * 并下发，由页面按 z 排层（DOM 宿主用 z-index 落地，语义不变）。
+ */
+import type {
+  ChoicesLayerView,
+  DialogueLayerView,
+  NarrativeOverlayView,
+  NotifyLayerItem,
+  OverlayLayerId,
+  OverlaySurface,
+} from "@lingfan-engine/ui";
+import { isNvlActive, renderDialogueLine } from "@lingfan-engine/ui";
+import { toMiniTree, type MiniNode } from "./view.ts";
+import type { MiniprogramFrameSource } from "@lingfan-engine/adapters";
+
+/** 对话层的小程序形态（字段与 WXML 绑定一致） */
+export interface MiniprogramDialogueData {
+  visible: boolean;
+  rootClass: string;
+  speakerHtml: string;
+  speakerColor: string;
+  bodyHtml: string;
+  bodyFont: string;
+  hintHtml: string;
+}
+
+/**
+ * NVL 累积层的页面数据：已打完的行（HTML）+ 正在打字的最新一行（HTML）。
+ *
+ * NVL 不是独立一层——它住在对话层容器里（桌面面板同一口径：容器换宽高，内容换成累积行），
+ * 因此这里只给内容，可见性与容器形态由对话层决定。`null` = 不在 NVL（走普通三段式）。
+ */
+export interface MiniprogramNvlData {
+  pastLines: string[];
+  typingHtml: string;
+}
+
+/** 选项的小程序形态：多一个稳定键供 wx:key 用 */
+export interface MiniprogramChoiceOptionData {
+  key: string;
+  html: string;
+  label: string;
+  target: string;
+}
+
+/** 选择层的小程序形态（菜单与输入两形态互斥：`options` 与 `input` 只有一个非空） */
+export interface MiniprogramChoicesData {
+  rootClass: string;
+  promptHtml: string;
+  options: MiniprogramChoiceOptionData[];
+  input: { prompt: string; submitText: string } | null;
+}
+
+/** 一条通知的小程序形态 */
+export interface MiniprogramNoticeData {
+  key: string;
+  rootClass: string;
+  bodyHtml: string;
+}
+
+/** 页面持有的覆盖层数据（首次渲染前各层为空） */
+export interface MiniprogramSurfaceData {
+  stage: MiniNode[];
+  elements: MiniNode[];
+  dialogue: MiniprogramDialogueData | null;
+  nvl: MiniprogramNvlData | null;
+  choices: MiniprogramChoicesData | null;
+  notices: MiniprogramNoticeData[];
+  layers: Record<string, number>;
+}
+
+/** 一次整层提交：字段缺省即不动 */
+export type MiniprogramSurfacePatch = Partial<MiniprogramSurfaceData>;
+
+/** 表面装配参数 */
+export interface MiniprogramSurfaceDeps {
+  /** 帧源（覆盖层打字机与帧驱动表现都靠它） */
+  frame: MiniprogramFrameSource;
+  /** 数据发布口：页面把补丁送进 setData */
+  publish(patch: MiniprogramSurfacePatch): void;
+}
+
+/**
+ * 小程序覆盖层表面 = 中立面 + 一条 NVL 通道。
+ *
+ * NVL 不在 `OverlaySurface` 契约里——桌面宿主的做法是读渲染投影
+ * （`NarrativeOverlayView` 的 `nvlMode`/`nvlLines`/`lineHtml`）自己渲染累积层。
+ * 这里沿用同一条投影，只把「行文本 → HTML」这一步收进表面：页面拿到的就是
+ * 可直接绑定的字符串，不用再懂内联标记。
+ */
+export type MiniprogramOverlaySurface = OverlaySurface & {
+  /** 按渲染投影刷新 NVL 累积层（`null` = 不在 NVL，走普通三段式） */
+  setNvl(view: NarrativeOverlayView): void;
+};
+
+/** 造小程序覆盖层表面 */
+export function createMiniprogramOverlaySurface(
+  deps: MiniprogramSurfaceDeps,
+): MiniprogramOverlaySurface {
+  /** 通知键的自增序号 */
+  let noticeSeq = 0;
+  /** 在排的通知移除定时器 */
+  const timers = new Set<ReturnType<typeof setTimeout>>();
+  /** 当前在屏通知（顺序即呈现顺序） */
+  let notices: MiniprogramNoticeData[] = [];
+  /** 各层 z（由中立核心下发；页面按它排层） */
+  const layers: Record<string, number> = {};
+  let dialogue: MiniprogramDialogueData | null = null;
+  let choices: MiniprogramChoicesData | null = null;
+  let nvl: MiniprogramNvlData | null = null;
+  /**
+   * NVL 已打完行的 HTML 缓存：打字帧每帧都会来一次投影通知，而累积行不变——
+   * 按数组引用命中（投影器复用它自己的缓冲数组，打字帧下引用稳定）。
+   */
+  let nvlPastCache: {
+    lines: readonly string[];
+    html: string[];
+  } | null = null;
+
+  function publishStage(tree: MiniNode[]): void {
+    deps.publish({ stage: tree });
+  }
+
+  function publishElements(tree: MiniNode[]): void {
+    deps.publish({ elements: tree });
+  }
+
+  return {
+    frame: deps.frame,
+    stage: {
+      clear: () => publishStage([]),
+      mount: (spec) => publishStage(toMiniTree(spec)),
+    },
+    elements: {
+      clear: () => publishElements([]),
+      mount: (spec) => publishElements(toMiniTree(spec)),
+    },
+    setLayerZ(layer: OverlayLayerId, z: number): void {
+      layers[layer] = z;
+      deps.publish({ layers: { ...layers } });
+    },
+    setDialogue(view: DialogueLayerView): void {
+      dialogue = {
+        visible: view.visible,
+        rootClass: view.rootClass,
+        speakerHtml: view.speakerHtml,
+        speakerColor: view.speakerColor,
+        bodyHtml: view.bodyHtml,
+        bodyFont: view.bodyFont,
+        hintHtml: view.hintHtml,
+      };
+      deps.publish({ dialogue });
+    },
+    setChoices(view: ChoicesLayerView | null): void {
+      choices = view === null ? null : toChoicesData(view);
+      deps.publish({ choices });
+    },
+    setNvl(view: NarrativeOverlayView): void {
+      if (!isNvlActive(view.nvlMode, view.nvlLines)) {
+        if (nvl === null) return;
+        nvl = null;
+        deps.publish({ nvl });
+        return;
+      }
+      // 累积行只在缓冲变化时重算；打字帧只更新最新一行的可见前缀
+      if (nvlPastCache === null || nvlPastCache.lines !== view.nvlLines) {
+        nvlPastCache = {
+          lines: view.nvlLines,
+          html: view.nvlLines
+            .slice(0, -1)
+            .map((line) => renderDialogueLine({ text: line }).html),
+        };
+      }
+      nvl = {
+        pastLines: nvlPastCache.html,
+        typingHtml: view.lineHtml,
+      };
+      deps.publish({ nvl });
+    },
+    pushNotification(item: NotifyLayerItem, durationMs: number): void {
+      const key = `notice-${noticeSeq}`;
+      noticeSeq += 1;
+      notices = [
+        ...notices,
+        { key, rootClass: item.rootClass, bodyHtml: item.bodyHtml },
+      ];
+      deps.publish({ notices });
+      const timer = setTimeout(() => {
+        timers.delete(timer);
+        notices = notices.filter((notice) => notice.key !== key);
+        deps.publish({ notices });
+      }, durationMs);
+      timers.add(timer);
+    },
+    clear(): void {
+      for (const timer of timers) clearTimeout(timer);
+      timers.clear();
+      notices = [];
+      dialogue = null;
+      choices = null;
+      nvl = null;
+      nvlPastCache = null;
+      deps.publish({
+        stage: [],
+        elements: [],
+        dialogue: null,
+        nvl: null,
+        choices: null,
+        notices: [],
+      });
+    },
+  };
+}
+
+/** 选择层视图 → 页面数据（选项补稳定键） */
+function toChoicesData(view: ChoicesLayerView): MiniprogramChoicesData {
+  return {
+    rootClass: view.rootClass,
+    promptHtml: view.promptHtml,
+    options: view.options.map((option, index) => ({
+      key: `option-${index}`,
+      html: option.html,
+      label: option.label,
+      target: option.target,
+    })),
+    input: view.input === null ? null : { ...view.input },
+  };
+}

package/template/overlays/miniprogram/src/mp/video-surface.ts

@@ -0,0 +1,104 @@
+/**
+ * 视频呈现面（小程序）：把视频端口的命令落成页面数据，播放中的控制走组件控制柄。
+ *
+ * 小程序的 `video` 是声明式组件——换片与显示靠页面数据（`src` / 是否可见），
+ * 播放中的暂停、续播、定位靠 `uni.createVideoContext(id)` 的控制柄；自然播完由页面
+ * 把组件的 `bindended` 转进本面的 `notifyEnded`，端口据此解除引擎的 video 等待。
+ *
+ * 控制柄按需取：组件还没渲染时取柄会抛错，此时动作直接丢弃（下一次动作再取），
+ * 不让一次时序问题炸掉整个宿主。
+ */
+
+import type { MiniprogramVideoSurfaceLike } from "@lingfan-engine/adapters";
+import { createVideoContext, type UniVideoContext } from "./platform.ts";
+
+/** 页面数据里的视频状态（页面据此渲染 `video` 组件） */
+export interface MiniprogramVideoData {
+  /** 资源地址（空串 = 无片可播） */
+  url: string;
+  /** 是否可见：不可见时组件不占位，也不盖住舞台 */
+  visible: boolean;
+  /** 0..1 */
+  volume: number;
+  loop: boolean;
+}
+
+/** 视频组件的 id：页面模板与呈现面必须一致 */
+export const VIDEO_COMPONENT_ID = "stage-video";
+
+/** 呈现面装配参数 */
+export interface MiniprogramVideoSurfaceDeps {
+  /** 把视频状态落到页面数据 */
+  publish(video: MiniprogramVideoData): void;
+}
+
+/** 呈现面：端口契约 + 页面侧的播完回传口 */
+export interface MiniprogramVideoSurface extends MiniprogramVideoSurfaceLike {
+  /** 播放自然结束（页面 `bindended` 转发） */
+  notifyEnded(): void;
+}
+
+/** 免于无人观看的视频状态（隐藏时页面数据归零） */
+const HIDDEN: MiniprogramVideoData = {
+  url: "",
+  visible: false,
+  volume: 0,
+  loop: false,
+};
+
+/** 造一个视频呈现面 */
+export function createMiniprogramVideoSurface(
+  deps: MiniprogramVideoSurfaceDeps,
+): MiniprogramVideoSurface {
+  /** 播完处理器（每次 play 换一次，由端口注册） */
+  let ended: (() => void) | null = null;
+  /** 当前是否有片在屏（控制柄只在可见时有意义） */
+  let visible = false;
+  /** 控制柄（懒取；取失败不缓存，下次再试） */
+  let context: UniVideoContext | null = null;
+
+  /** 取控制柄：组件未渲染时返回 null（动作丢弃） */
+  function readContext(): UniVideoContext | null {
+    if (context !== null) return context;
+    try {
+      context = createVideoContext(VIDEO_COMPONENT_ID);
+    } catch {
+      return null;
+    }
+    return context;
+  }
+
+  return {
+    show(request): void {
+      visible = true;
+      deps.publish({
+        url: request.url,
+        visible: true,
+        volume: request.volume,
+        loop: request.loop,
+      });
+    },
+    hide(): void {
+      visible = false;
+      deps.publish({ ...HIDDEN });
+    },
+    pause(): void {
+      if (!visible) return;
+      readContext()?.pause();
+    },
+    resume(): void {
+      if (!visible) return;
+      readContext()?.play();
+    },
+    seek(seconds): void {
+      if (!visible) return;
+      readContext()?.seek(Math.max(0, seconds));
+    },
+    onEnded(callback): void {
+      ended = callback;
+    },
+    notifyEnded(): void {
+      ended?.();
+    },
+  };
+}

package/template/overlays/miniprogram/src/mp/view.ts

@@ -0,0 +1,91 @@
+/**
+ * 渲染树翻译：把 `@lingfan-engine/ui` 的元素描述翻成小程序能绑定的数据树。
+ *
+ * 小程序没有 DOM，WXML 只能绑数据，所以渲染端口在这里不是「造节点」而是「算数据」：
+ * 本文件把描述树算成 `MiniNode[]`，由页面把它送进 setData，再由 WXML 的递归模板
+ * 铺开。样式串也在这里拼好（camelCase 键 → CSS 声明），免得模板里再算一遍。
+ */
+import type { StageLayout } from "@lingfan-engine/shell";
+import type { RenderSpec } from "@lingfan-engine/ui";
+
+/** 一个待渲染节点：字段与 WXML 模板一一对应 */
+export interface MiniNode {
+  /** 同层内稳定键，供模板的 wx:key 用 */
+  key: string;
+  /** 元素种类（box / text / image / media / input / slider / checkbox / action） */
+  kind: string;
+  /** 语义类名（具体观感挂在工程样式表的类上） */
+  className: string;
+  /** 已拼好的行内 CSS 声明串 */
+  style: string;
+  /** 纯文本内容 */
+  text?: string;
+  /** 富文本内容（含标记的片段，交给 rich-text 渲染） */
+  html?: string;
+  /** 媒体地址（图与视频用） */
+  src?: string;
+  /** 子节点 */
+  children?: MiniNode[];
+}
+
+/** 把一棵描述树翻成节点树；`path` 是给子节点编键用的前缀 */
+export function toMiniNode(spec: RenderSpec, path: string): MiniNode {
+  const node: MiniNode = {
+    key: spec.id ?? path,
+    kind: spec.kind,
+    className: spec.className ?? "",
+    style: styleText(spec.style),
+  };
+  if (spec.text !== undefined) node.text = spec.text;
+  if (spec.html !== undefined) node.html = spec.html;
+  const src = spec.props?.["src"];
+  if (typeof src === "string") node.src = src;
+  const children = spec.children ?? [];
+  if (children.length > 0) {
+    node.children = children.map((child, index) =>
+      toMiniNode(child, `${path}-${index}`),
+    );
+  }
+  return node;
+}
+
+/** 把一棵描述树翻成一层节点（无描述 = 空层） */
+export function toMiniTree(spec: RenderSpec | null): MiniNode[] {
+  return spec === null ? [] : [toMiniNode(spec, "0")];
+}
+
+/**
+ * 把舞台布局算成内层容器的行内样式：先按基准尺寸定死舞台，再整体平移与缩放。
+ *
+ * 变换原点取左上角（见工程样式表），因此平移量与缩放量的口径与布局计算一致：
+ * 先缩放再平移，偏移就是缩放后内容与视口的左上角距离。
+ */
+export function stageStyle(layout: StageLayout): string {
+  const translate = `translate(${round(layout.offsetX)}px,${round(layout.offsetY)}px)`;
+  const scale = `scale(${round(layout.scaleX)},${round(layout.scaleY)})`;
+  return [
+    `width:${layout.width}px`,
+    `height:${layout.height}px`,
+    `transform:${translate} ${scale}`,
+  ].join(";");
+}
+
+/** 小数截到三位：避免布局浮点数把样式串撑得过长 */
+function round(value: number): number {
+  return Math.round(value * 1000) / 1000;
+}
+
+/** 拼行内样式：camelCase 键转 CSS 声明的连字符形态，值原样（数值已在元素样式层折算） */
+function styleText(
+  style: Readonly<Record<string, string>> | undefined,
+): string {
+  if (style === undefined) return "";
+  return Object.entries(style)
+    .map(([property, value]) => `${toCssProperty(property)}:${value}`)
+    .join(";");
+}
+
+/** `maxWidth` → `max-width`（已是连字符形态的原样保留） */
+function toCssProperty(property: string): string {
+  return property.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+}