@lingfan-engine/create 0.2.0 → 0.3.1

package/template/__PROJECT__/src/host/mount/renderer.ts

@@ -0,0 +1,128 @@
+/**
+ * 原生形态的挂载渲染器：把 `SYS.mounts` 落到真实 DOM 上。
+ *
+ * 框架形态靠各自的响应式系统重渲染，原生形态没有那层——它必须自己算差量：
+ * 谁新出现就造节点挂上，谁消失了就拆掉，谁只是换了入参就**整份重挂**（不是改属性）。
+ * 差量与投影都不在这里（`@lingfan-engine/ui` 的 mount 域），本文件只做三件 DOM 事：
+ * 追加、移除、调拆除钩子。
+ *
+ * 隐藏 = 从渲染树移除，不是 `display: none`：容器里那一项真的不在了，
+ * 组件自己的定时器、订阅、媒体元素随拆除钩子一起停掉。
+ *
+ * 挂载失败一律 fail-closed 上报、不渲染那一条：一个 UI 写错不该黑掉整屏，
+ * 也不该静默消失——作者要能看见「哪个名字没挂上」。
+ */
+import {
+  mountProps,
+  planMounts,
+  visibleMounts,
+  type MountPlan,
+} from "@lingfan-engine/ui";
+import type { HostControls } from "@lingfan-engine/core";
+import { resolveNativeFactory, type NativeUiInstance } from "./table";
+
+/** 渲染器输入：容器、生成物表、控制面、诊断出口 */
+export interface NativeMountRendererOptions {
+  /** 挂载容器：子节点就是当前可见的 UI（按挂载次序排列） */
+  container: HTMLElement;
+  /** 「名字 → 工厂」表（生成物 `uis`） */
+  table: Readonly<Record<string, unknown>>;
+  /**
+   * 交给每个 UI 的操作句柄（暂停、换栏、存读档）。
+   *
+   * 与 `props` 分属两条通道：`props` 是故事值（存档随行、必须 JSON 安全），
+   * 这里这个含函数、运行期注入、不进快照，所以从选项走而不是塞进 props。
+   */
+  controls: HostControls;
+  /** 诊断出口：挂不上、拆除失败都从这里出去，不吞 */
+  reportError(message: string): void;
+}
+
+/** 渲染器：喂状态、拆干净 */
+export interface NativeMountRenderer {
+  /** 推进到新状态（首帧传 `undefined` 也可） */
+  sync(raw: unknown): void;
+  /** 拆掉全部已挂 UI 并退订钩子；之后 `sync` 不再有效 */
+  dispose(): void;
+}
+
+/**
+ * 造一个原生挂载渲染器。
+ *
+ * 已挂的节点**不重排**：顺序由首次挂载决定。重排会让组件内部状态、滚动位置与焦点
+ * 在每次状态变化时抖一下——那份收益（与框架形态顺序完全一致）不值这个代价。
+ */
+export function createNativeMountRenderer(
+  options: NativeMountRendererOptions,
+): NativeMountRenderer {
+  const mounted = new Map<string, NativeUiInstance>();
+  /** 已上报过的「挂不上」名字：同一条诊断不每帧刷屏，名字消失后再出现会重新报 */
+  const reported = new Set<string>();
+  let previous: unknown = undefined;
+  let disposed = false;
+
+  function unmountOne(name: string): void {
+    const instance = mounted.get(name);
+    if (instance === undefined) return;
+    mounted.delete(name);
+    try {
+      instance.dispose?.();
+    } catch (error) {
+      options.reportError(`UI ${name} 拆除失败：${String(error)}`);
+    }
+    if (instance.element.parentNode === options.container) {
+      options.container.removeChild(instance.element);
+    }
+  }
+
+  function mountOne(name: string, raw: unknown): void {
+    const factory = resolveNativeFactory(options.table, name);
+    if (factory === undefined) {
+      if (!reported.has(name)) {
+        reported.add(name);
+        options.reportError(
+          `找不到 UI 的工厂：${name}（生成物 uis 里没有这个名字，或它不是函数——原生形态的 UI 必须导出工厂）`,
+        );
+      }
+      return;
+    }
+    let instance: NativeUiInstance;
+    try {
+      instance = factory(mountProps(raw, name) ?? {}, options.controls);
+    } catch (error) {
+      options.reportError(`UI ${name} 挂载失败：${String(error)}`);
+      return;
+    }
+    reported.delete(name);
+    mounted.set(name, instance);
+    options.container.appendChild(instance.element);
+  }
+
+  function apply(plan: MountPlan, raw: unknown): void {
+    // 先卸再挂：同时存在新旧两份时，焦点、滚动位置与无障碍树都会出现两个答案
+    for (const name of plan.unmount) unmountOne(name);
+    for (const name of plan.update) unmountOne(name);
+    for (const name of plan.update) mountOne(name, raw);
+    for (const name of plan.mount) mountOne(name, raw);
+    // 已上报过的名字若已不可见，忘掉它：下次再挂同名的失败要能重新出声
+    const visible = new Set(visibleMounts(raw));
+    for (const name of [...reported]) {
+      if (!visible.has(name)) reported.delete(name);
+    }
+  }
+
+  return {
+    sync(raw: unknown): void {
+      if (disposed) return;
+      const plan = planMounts(previous, raw);
+      previous = raw;
+      apply(plan, raw);
+    },
+    dispose(): void {
+      if (disposed) return;
+      disposed = true;
+      for (const name of [...mounted.keys()]) unmountOne(name);
+      reported.clear();
+    },
+  };
+}

package/template/__PROJECT__/src/host/mount/table.ts

@@ -0,0 +1,52 @@
+/**
+ * 原生形态的「名字 → UI 工厂」表。
+ *
+ * 框架形态里 UI 就是组件对象，原生形态没有组件这个概念——UI 是一个**函数**：
+ * 拿入参、造出一棵 DOM 子树、返回节点与拆除钩子。表由生成物 `src/gen/ui_register.g.ts`
+ * 提供（名字即 `src/ui/<名>/` 目录名），本文件只负责**取表项并验形**。
+ *
+ * 为什么不在渲染器里直接 `table[name]`：生成物是 `Record<string, unknown>`，值可能因为
+ * 作者把 `.vue` 写进原生工程而变成组件对象。那种情况必须 fail-closed 并说清原因，
+ * 而不是让渲染器在 `factory is not a function` 上崩掉整屏。
+ */
+import type { HostControls } from "@lingfan-engine/core";
+
+/** 一份已挂载的原生 UI：一个根节点 + 可选拆除钩子 */
+export interface NativeUiInstance {
+  /** 挂进容器的根节点；渲染器只 append / remove 它，不看它内部 */
+  readonly element: HTMLElement;
+  /** 拆除：退订、清定时器、释放资源；渲染器在卸载与整份重挂时调用一次 */
+  dispose?(): void;
+}
+
+/**
+ * 原生形态的 UI：入参进，节点出。
+ *
+ * 两个参数是两条不同的通道：`props` 是故事命令给出的值（JSON 安全、随快照存档），
+ * `controls` 是宿主给的操作句柄（含函数，不存档）。UI 要显示什么读前者，
+ * 要操作引擎（暂停、换栏、存读档）用后者。
+ */
+export type NativeUiFactory = (
+  props: Readonly<Record<string, unknown>>,
+  controls: HostControls,
+) => NativeUiInstance;
+
+/** 「名字 → 工厂」表（生成物 `uis` 的原生形态投影） */
+export type NativeUiTable = Readonly<Record<string, NativeUiFactory>>;
+
+/**
+ * 取某个名字的工厂；取不到或形态不对时返回 `undefined`（由调用方决定怎么报）。
+ *
+ * 形态判据是「函数」而不是「对象」：原生形态的 UI 是工厂，Vue / React 的组件对象
+ * 也是函数或带 `setup` 的对象——两者在 `typeof` 上都可能像函数，所以这里不猜，
+ * 只认调用结果：真调不通时由渲染器捕获并报一条带名字的诊断。
+ */
+export function resolveNativeFactory(
+  table: Readonly<Record<string, unknown>>,
+  name: string,
+): NativeUiFactory | undefined {
+  const candidate = table[name];
+  return typeof candidate === "function"
+    ? (candidate as NativeUiFactory)
+    : undefined;
+}

package/template/__PROJECT__/src/host/panels/history.ts

@@ -0,0 +1,193 @@
+/**
+ * 历史面板（纯 DOM）：已走过的对话按「呈现块」列出，点一块就回退到那个检查点。
+ *
+ * 两件事分开，与偏好面板同一口径：
+ * - **数据整形**归 `@lingfan-engine/shell` 的 `filterHistoryEntries` / `buildHistoryBlocks`
+ *   （连续 NVL 聚成一块，回溯粒度仍是逐检查点）。本模块不自己聚合——那套规则若在
+ *   宿主里另写一份，「面板显示的行」与「回溯落点」迟早对不上。
+ * - **本模块只管**：把块列表画进容器、把点击翻译成 `engine.rollbackTo(index)`。
+ *
+ * 回溯本身是引擎命令面（`rollbackTo` / `back` / `forward`），宿主不重放、不改状态。
+ * 回溯完成后的媒体对齐不在引擎里（它只回状态、不下发端口动作），所以本模块留了一个
+ * `onRollback` 出口给组合根接媒体同步——这是宿主的职责，不是面板的。
+ *
+ * 面板自带开关按钮：容器是可选的（叠加层可以不给 `#history`），若把开关放在工具条里，
+ * 那道槽位就变强制了。放在容器内则「有容器才有历史 UI」，与 `#prefs` 同口径。
+ */
+
+import {
+  buildHistoryBlocks,
+  filterHistoryEntries,
+  type HistoryBlock,
+  type HistoryEntry,
+} from "@lingfan-engine/shell";
+
+/** 历史面板需要的引擎能力（只读历史 + 坐标回溯，不含推进） */
+export interface HistoryEngine {
+  /** 逐检查点的历史条目 */
+  historyView(): readonly HistoryEntry[];
+  /** 回溯到第 index 个检查点 */
+  rollbackTo(target: number): void;
+}
+
+/** 面板当前应显示的视图值（纯数据，测试断言这一层） */
+export interface HistoryPanelView {
+  /** 面板是否展开 */
+  open: boolean;
+  /** 呈现块（连续 NVL 已聚合） */
+  blocks: HistoryBlock[];
+}
+
+/** 历史面板的输入 */
+export interface HistoryPanelOptions {
+  /** 引擎（读历史、执行回溯） */
+  engine: HistoryEngine;
+  /** 面板容器（由调用方给，本模块不自己 append 到 body） */
+  container: HTMLElement;
+  /**
+   * 回溯完成后的宿主侧收尾（可选）：媒体位置需显式对齐——引擎 `rollback.done`
+   * 只带坐标，播放器不会自己跳回去。与 `wireEngine` 的 `syncMedia` 是同一件事。
+   */
+  onRollback?(): void;
+}
+
+/** 历史面板出口 */
+export interface HistoryPanel {
+  /** 面板当前应显示的视图值；每次现读引擎历史 */
+  view(): HistoryPanelView;
+  /** 展开并重画（重复调用幂等） */
+  open(): void;
+  /** 收起 */
+  close(): void;
+  /** 展开 ↔ 收起 */
+  toggle(): void;
+  /** 回退到某个检查点：回溯 + 收起 + 宿主收尾 */
+  rollbackTo(index: number): void;
+  /** 挂载控件与监听（重复调用幂等，不叠控件） */
+  mount(): void;
+  /** 卸载：清空容器并断开引用；之后可再次 `mount()` */
+  destroy(): void;
+}
+
+/**
+ * 创建历史面板。构造只持有引擎与容器，不碰 DOM——`mount()` 才建控件，
+ * 因此未挂载的面板可以安全地只调 `view()`（视图计算与 DOM 解耦）。
+ */
+export function createHistoryPanel(options: HistoryPanelOptions): HistoryPanel {
+  const { engine, container } = options;
+
+  /** 非 null = 已挂载；同时充当容器根节点句柄 */
+  let root: HTMLElement | null = null;
+  let list: HTMLElement | null = null;
+  let toggleButton: HTMLButtonElement | null = null;
+  let openState = false;
+
+  function view(): HistoryPanelView {
+    const blocks = buildHistoryBlocks(
+      filterHistoryEntries(engine.historyView()),
+    );
+    return { open: openState, blocks };
+  }
+
+  /** 一次块渲染：一级按钮 = 一个块，点它即回溯到块尾检查点 */
+  function renderBlocks(): void {
+    if (list === null) return;
+    list.textContent = ""; // 整体重建：块数不多，重建比逐块 diff 简单且不会残留
+    const { blocks } = view();
+    for (const block of blocks) {
+      const item = document.createElement("button");
+      item.type = "button";
+      item.className = "history-item";
+      // 回溯目标是**块尾**检查点，标在节点上便于宿主排查与测试取证
+      item.dataset.index = String(block.index);
+      if (block.speaker !== "") {
+        const speaker = document.createElement("span");
+        speaker.className = "history-speaker";
+        speaker.textContent = block.speaker;
+        item.appendChild(speaker);
+      }
+      for (const line of block.lines) {
+        const text = document.createElement("span");
+        text.className = block.nvl
+          ? "history-text history-nvl"
+          : "history-text";
+        text.textContent = line;
+        item.appendChild(text);
+      }
+      item.addEventListener("click", () => {
+        rollbackTo(block.index);
+      });
+      list.appendChild(item);
+    }
+  }
+
+  /** 展开态落到 DOM：列表显隐 + 按钮文案 */
+  function applyOpen(): void {
+    if (list !== null) list.style.display = openState ? "" : "none";
+    if (toggleButton !== null)
+      toggleButton.textContent = openState ? "关闭历史" : "历史";
+  }
+
+  function open(): void {
+    openState = true;
+    renderBlocks();
+    applyOpen();
+  }
+
+  function close(): void {
+    openState = false;
+    applyOpen();
+  }
+
+  function toggle(): void {
+    if (openState) close();
+    else open();
+  }
+
+  function rollbackTo(index: number): void {
+    // 引擎 fail-closed：越界、重放中都会自己报错，这里只管把面板收起来
+    engine.rollbackTo(index);
+    // 回溯改了状态，但面板若还开着，接下来点哪一块都基于旧列表——收起最省事
+    close();
+    options.onRollback?.();
+  }
+
+  function mount(): void {
+    if (root !== null) return; // 已挂载：幂等，重复调用不重复建控件
+    container.dataset.uiZone = "";
+    const section = document.createElement("section");
+    section.className = "history-panel";
+    section.dataset.uiZone = "";
+
+    const button = document.createElement("button");
+    button.type = "button";
+    button.className = "history-toggle";
+    button.textContent = "历史";
+    button.addEventListener("click", () => {
+      toggle();
+    });
+    section.appendChild(button);
+
+    const blockList = document.createElement("div");
+    blockList.className = "history-list";
+    blockList.style.display = "none";
+    section.appendChild(blockList);
+
+    container.appendChild(section);
+    root = section;
+    list = blockList;
+    toggleButton = button;
+    openState = false;
+    applyOpen();
+  }
+
+  function destroy(): void {
+    container.textContent = "";
+    root = null;
+    list = null;
+    toggleButton = null;
+    openState = false;
+  }
+
+  return { view, open, close, toggle, rollbackTo, mount, destroy };
+}

package/template/__PROJECT__/src/host/panels/preferences.ts

@@ -0,0 +1,216 @@
+/**
+ * 偏好面板（纯 DOM）：四通道音量 + 静音 + 文字速度。
+ *
+ * 读写一律经 `PlayerPreferences`——钳制、非法值忽略都在偏好层，本模块只做两件事：
+ * 把偏好快照画到控件上，把控件事件翻译成偏好写入。所以换掉这套原生 DOM 不影响偏好语义。
+ *
+ * 用法：调用方给一个容器（通常来自 `index.html`），`mount()` 建控件并订阅偏好变化，
+ * `destroy()` 清空容器并退订。原生 DOM 没有框架卸载钩子，解绑必须自己成对做，
+ * 否则面板关掉后每次改偏好还会去写已卸下的节点。
+ *
+ * 注意：面板必须落在 `data-ui-zone` 里——输入作用域靠这个属性把面板内的滚轮/按键
+ * 判成「控件输入」，否则滚动音量滑杆会连带触发故事回溯。容器由调用方提供，
+ * 不能假定它已标记，故 `mount()` 给容器与面板根节点都补上。
+ */
+
+import type { AudioChannel, PlayerPreferences } from "@lingfan-engine/core";
+
+/** 音量通道与显示名；顺序即面板行序 */
+export const PREF_CHANNELS: ReadonlyArray<{
+  channel: AudioChannel;
+  label: string;
+}> = [
+  { channel: "bgm", label: "BGM" },
+  { channel: "se", label: "音效" },
+  { channel: "ambient", label: "环境" },
+  { channel: "voice", label: "语音" },
+];
+
+/** 文字速度滑杆的上下限（字/秒；下限 1 与偏好层的下限一致） */
+const TEXT_SPEED_MIN = 1;
+const TEXT_SPEED_MAX = 80;
+
+/** 面板当前应显示的视图值（纯数据，测试断言这一层） */
+export interface PreferencesPanelView {
+  volumes: Record<AudioChannel, number>;
+  muted: boolean;
+  textSpeed: number;
+  /** 固定四通道的展示序 */
+  channels: readonly AudioChannel[];
+}
+
+/** 偏好面板的输入 */
+export interface PreferencesPanelOptions {
+  /** 偏好端口（读写与订阅都走它） */
+  preferences: PlayerPreferences;
+  /** 面板根节点（由调用方给，本模块不自己 append 到 body） */
+  container: HTMLElement;
+}
+
+/** 偏好面板出口 */
+export interface PreferencesPanel {
+  /** 面板当前应显示的视图值；每次现读偏好快照 */
+  view(): PreferencesPanelView;
+  /** 挂载控件与监听（重复调用幂等，不叠控件） */
+  mount(): void;
+  /** 卸载：退订并清空容器；之后可再次 `mount()` */
+  destroy(): void;
+}
+
+/** 单行音量控件的引用：同步视图时按通道回填 */
+interface VolumeRow {
+  channel: AudioChannel;
+  input: HTMLInputElement;
+  readout: HTMLElement;
+}
+
+/**
+ * 读滑杆数值：空串按无效处理。
+ * `Number("")` 是 0，直接写会把通道误调到静音；返回 NaN 时偏好层忽略该次写入。
+ */
+function sliderValue(input: HTMLInputElement): number {
+  const raw = input.value;
+  return raw === "" ? Number.NaN : Number(raw);
+}
+
+/**
+ * 创建偏好面板。构造只持有端口，不碰 DOM——`mount()` 才建控件，
+ * 因此未挂载的面板可以安全地只调 `view()`（视图计算与 DOM 解耦）。
+ */
+export function createPreferencesPanel(
+  options: PreferencesPanelOptions,
+): PreferencesPanel {
+  const preferences = options.preferences;
+  const container = options.container;
+
+  /** 非 null = 已挂载；同时充当退订句柄（挂载判定与退订成对，避免重复订阅） */
+  let off: (() => void) | null = null;
+  let volumeRows: VolumeRow[] = [];
+  let mutedInput: HTMLInputElement | null = null;
+  let textSpeedInput: HTMLInputElement | null = null;
+  let textSpeedReadout: HTMLElement | null = null;
+
+  function view(): PreferencesPanelView {
+    const snapshot = preferences.snapshot();
+    return {
+      volumes: snapshot.volumes,
+      muted: snapshot.muted,
+      textSpeed: snapshot.textSpeed,
+      channels: PREF_CHANNELS.map((entry) => entry.channel),
+    };
+  }
+
+  /** 把当前偏好画到控件上（挂载时与每次偏好变化时调用） */
+  function sync(): void {
+    const snapshot = preferences.snapshot();
+    for (const row of volumeRows) {
+      const volume = snapshot.volumes[row.channel];
+      row.input.value = String(volume);
+      // 静音时滑杆禁用：此时通道偏好仍保留，只是合成末端归零，拖它看不出效果
+      row.input.disabled = snapshot.muted;
+      row.readout.textContent = `${Math.round(volume * 100)}%`;
+    }
+    if (mutedInput !== null) mutedInput.checked = snapshot.muted;
+    if (textSpeedInput !== null) {
+      textSpeedInput.value = String(snapshot.textSpeed);
+    }
+    if (textSpeedReadout !== null) {
+      textSpeedReadout.textContent = `${Math.round(snapshot.textSpeed)} 字/秒`;
+    }
+  }
+
+  /** 一行 = 标签 + 控件 +（可选）数值读数 */
+  function row(
+    labelText: string,
+    control: HTMLElement,
+    readout?: HTMLElement,
+  ): HTMLElement {
+    const wrapper = document.createElement("label");
+    wrapper.className = "prefs-row";
+    const label = document.createElement("span");
+    label.className = "prefs-label";
+    label.textContent = labelText;
+    wrapper.appendChild(label);
+    wrapper.appendChild(control);
+    if (readout !== undefined) wrapper.appendChild(readout);
+    return wrapper;
+  }
+
+  function buildVolumeRows(root: HTMLElement): void {
+    for (const entry of PREF_CHANNELS) {
+      const input = document.createElement("input");
+      input.type = "range";
+      input.className = "prefs-range";
+      // 通道标在节点上：样式与后续宿主接线都按通道取控件，不靠子节点下标
+      input.dataset.channel = entry.channel;
+      input.min = "0";
+      input.max = "1";
+      input.step = "0.05";
+      input.addEventListener("input", () => {
+        preferences.setVolume(entry.channel, sliderValue(input));
+      });
+      const readout = document.createElement("span");
+      readout.className = "prefs-value";
+      root.appendChild(row(entry.label, input, readout));
+      volumeRows.push({ channel: entry.channel, input, readout });
+    }
+  }
+
+  function buildMutedRow(root: HTMLElement): void {
+    const input = document.createElement("input");
+    input.type = "checkbox";
+    input.className = "prefs-checkbox";
+    input.dataset.setting = "muted";
+    input.addEventListener("change", () => {
+      preferences.setMuted(input.checked);
+    });
+    root.appendChild(row("静音", input));
+    mutedInput = input;
+  }
+
+  function buildTextSpeedRow(root: HTMLElement): void {
+    const input = document.createElement("input");
+    input.type = "range";
+    input.className = "prefs-range";
+    input.dataset.setting = "text-speed";
+    input.min = String(TEXT_SPEED_MIN);
+    input.max = String(TEXT_SPEED_MAX);
+    input.step = "1";
+    input.addEventListener("input", () => {
+      preferences.setTextSpeed(sliderValue(input));
+    });
+    const readout = document.createElement("span");
+    readout.className = "prefs-value";
+    root.appendChild(row("文字速度", input, readout));
+    textSpeedInput = input;
+    textSpeedReadout = readout;
+  }
+
+  function mount(): void {
+    if (off !== null) return; // 已挂载：幂等，重复调用不重复建控件
+    container.dataset.uiZone = "";
+    const root = document.createElement("section");
+    root.className = "prefs-panel";
+    root.dataset.uiZone = "";
+    buildVolumeRows(root);
+    buildMutedRow(root);
+    buildTextSpeedRow(root);
+    container.appendChild(root);
+    sync(); // 先按当前偏好铺初值，再订阅——避免挂载瞬间被一次多余通知重画
+    off = preferences.onChange(sync);
+  }
+
+  function destroy(): void {
+    if (off !== null) {
+      off();
+      off = null;
+    }
+    container.textContent = "";
+    volumeRows = [];
+    mutedInput = null;
+    textSpeedInput = null;
+    textSpeedReadout = null;
+  }
+
+  return { view, mount, destroy };
+}

package/template/__PROJECT__/src/host/save-slots.ts

@@ -1,20 +1,26 @@
 /**
- * 存档接线：槽位下拉与存 / 读两个按钮。
+ * 存档接线：槽位下拉、存 / 读两个按钮，以及存档缩略图。
  *
  * 槽位有几个、叫什么，由引擎按工程配置判定（`project.json` 的 `shell.saves.slots`），
  * 宿主只负责把 id 放进 `<option>`。槽位口径若搬进宿主，「改工程配置却不生效」就会变成
- * 难查的静默失败。
+ * 难查的静默失败。缩略图的尺寸/质量/是否带文本同理，全部来自 `shell.saves.thumbnail`。
  *
  * 存 / 读都走引擎既有命令面：宿主不自己拼存档数据；写档失败的可见诊断由引擎出站事件
  * 统一给出（见 `engine-wiring.ts`）。
+ *
+ * 缩略图是**可选增强**：合成失败（老 WebView 没有 canvas 2d 上下文）就存一张没有图的档，
+ * 而不是让这次存档整体失败——存档能用优先于卡片好看。
  */
 
 import {
+  SYS,
+  resolveProjectName,
   resolveSavesConfig,
   slotIds,
   type StoryEngine,
 } from "@lingfan-engine/core";
 import type { StageDom } from "./stage-dom";
+import { captureSaveThumbnail, stripHtml } from "./thumbnails";
 
 /** 按工程清单里的存档壳配置填充槽位下拉（调用方保证只填一次） */
 export function fillSaveSlots(dom: StageDom, manifest: unknown): void {
@@ -27,10 +33,52 @@ export function fillSaveSlots(dom: StageDom, manifest: unknown): void {
   }
 }
 
+/** 从引擎状态取一个字符串（缺键 / 非字符串都当空串，避免把 undefined 画进卡片） */
+function readText(engine: StoryEngine, key: string): string {
+  const value = engine.get(key);
+  return typeof value === "string" ? value : "";
+}
+
+/**
+ * 合成当前存档的缩略图（data URL）；失败返回 undefined 让存档照常落盘。
+ *
+ * 取的是**当前对话帧**：此刻玩家点的「存」，看到的就是这一句，卡片理应也是这一句。
+ * 标题用工程展示名——存档列表里认出「这是哪个工程」比认出「这是第几槽」更有用。
+ */
+function captureThumbnail(
+  engine: StoryEngine,
+  manifest: unknown,
+): string | undefined {
+  const { thumbnail } = resolveSavesConfig(manifest);
+  try {
+    return captureSaveThumbnail({
+      width: thumbnail.width,
+      height: thumbnail.height,
+      quality: thumbnail.quality,
+      showText: thumbnail.showText,
+      title: resolveProjectName(manifest),
+      speaker: readText(engine, SYS.currentDialogSpeaker),
+      text: stripHtml(readText(engine, SYS.currentDialogText)),
+      timestamp: Date.now(),
+    });
+  } catch {
+    // 没有 canvas 2d 上下文：降级为无图存档，不阻断存盘
+    return undefined;
+  }
+}
+
 /** 接线存 / 读按钮：槽位取下拉当前选中值 */
-export function wireSaveSlots(dom: StageDom, engine: StoryEngine): void {
+export function wireSaveSlots(
+  dom: StageDom,
+  engine: StoryEngine,
+  manifest: unknown,
+): void {
   dom.save.addEventListener("click", () => {
-    engine.save(dom.slot.value);
+    const screenshot = captureThumbnail(engine, manifest);
+    engine.save(
+      dom.slot.value,
+      screenshot === undefined ? undefined : { screenshot },
+    );
   });
   dom.load.addEventListener("click", () => {
     engine.load(dom.slot.value);