@lingfan-engine/create 0.2.0 → 0.3.1

package/template/__PROJECT__/src/host/stage-dom.ts

@@ -17,6 +17,18 @@ export function must<T extends HTMLElement>(selector: string): T {
   return el;
 }
 
+/**
+ * 按选择器取**可选**节点：缺失返回 `null`，不抛。
+ *
+ * 只给「有则增强、无则退化成没有该功能」的节点用——目前三个：历史面板、偏好面板
+ * 与 UI 挂载层的容器。它们和 `must()` 的区别是**契约强度**：页面结构由叠加层重写时
+ * （Vue / React / 小程序各自的 `App`），那份页面可以选择不提供这些槽位，
+ * 此时对应功能不启用，游戏照常跑；而 `must()` 守的节点缺一个就是装配错误，必须当场抛。
+ */
+export function optional<T extends HTMLElement>(selector: string): T | null {
+  return document.querySelector<T>(selector);
+}
+
 /** 常驻节点句柄表：装配期就要用到、且页面里始终存在的那些 */
 export interface StageDom {
   /** 舞台根：屏幕震动施加位移的对象 */
@@ -39,6 +51,30 @@ export interface StageDom {
   notifications: HTMLElement;
   /** 工具条：存档槽与存 / 读按钮 */
   toolbar: HTMLElement;
+  /**
+   * 历史面板槽位（**可选**：`null` = 本页面没给这个槽位）。
+   *
+   * 给了就有「历史」按钮与已走过对话的列表，点一条即回退到那个检查点；
+   * 不给则只是回看/回溯要另想办法，游戏照常跑——与 `prefs` 同属「有则增强」。
+   * 取用点：`optional("#history")`；`layer-z.ts` 写 `history` 层 z 时会判空。
+   */
+  history: HTMLElement | null;
+  /**
+   * 偏好面板槽位（**可选**：`null` = 本页面没给这个槽位）。
+   *
+   * 与上面 15 个 `must()` 节点的区别：那些是引擎渲染的落点，缺一个就是装配错误；
+   * 这个只是「没有面板就没有音量/字速 UI」，游戏照常跑，所以按可选处理。
+   * 取用点：`optional("#prefs")`；`layer-z.ts` 写 `prefs` 层 z 时会判空。
+   */
+  prefs: HTMLElement | null;
+  /**
+   * UI 挂载层容器（**可选**：`null` = 本页面不给 UI 挂载留槽位）。
+   *
+   * 给了就按 `SYS.mounts` 把 `src/ui/` 下的 UI 挂进来（`mount` op 控制显隐），
+   * 不给则 `mount` 只改状态、没有任何组件出现——降级是「少功能」，不是错误。
+   * 与 `prefs` 同属「有则增强」的槽位：取用点 `optional("#mounts")`。
+   */
+  mounts: HTMLElement | null;
   /** 存档槽下拉 */
   slot: HTMLSelectElement;
   /** 存按钮 */

package/template/__PROJECT__/src/host/thumbnails.ts

@@ -0,0 +1,101 @@
+/**
+ * 存档缩略图：合成一张「存档卡」，而不是对舞台做像素级截屏。
+ *
+ * 为什么是合成卡：WebView 没有跨端的截图 API（wry 未暴露 WebView2 的 CapturePreview，
+ * WKWebView 的 takeSnapshot 也未接），宿主能拿到的只有 DOM，不是像素。合成卡把
+ * 「背景 + 说话人 + 正文片段 + 时间戳」画进 canvas，确定性与可配性都更好，
+ * 也不受舞台适配（缩放/裁切）影响。
+ *
+ * 尺寸/质量/是否带文本全部由工程清单的 `shell.saves.thumbnail` 决定（解析在
+ * `resolveSavesConfig`），本模块只吃解析后的配置——宿主不自己读 JSON，避免
+ * 「改工程配置却不生效」这类静默失败。
+ *
+ * 失败即降级：没有 canvas 2d 上下文（老 WebView / 内存紧张）时抛错，由调用方
+ * 存一张**没有缩略图**的档——存档可用性优先于画面装饰。
+ */
+
+/** 合成卡参数：尺寸/质量/是否带文本来自 `shell.saves.thumbnail`，文本字段取当前对话。 */
+export interface SaveThumbnailInput {
+  width: number;
+  height: number;
+  quality: number;
+  showText: boolean;
+  /** 存档标题（缺省用工程名） */
+  title?: string;
+  /** 当前说话人（纯文本） */
+  speaker?: string;
+  /** 当前正文（纯文本，已剥离标签） */
+  text?: string;
+  timestamp: number;
+}
+
+/** 剥离富文本标签（对话渲染产物是受控 HTML；此处仅作缩略图纯文本投影） */
+export function stripHtml(html: string): string {
+  return html.replace(/<[^>]*>/g, "");
+}
+
+/** 合成「存档卡」：背景渐变 + 说话人/正文片段 + 时间戳；无 canvas 上下文抛错。 */
+export function captureSaveThumbnail(input: SaveThumbnailInput): string {
+  const canvas = document.createElement("canvas");
+  canvas.width = input.width;
+  canvas.height = input.height;
+  const context = canvas.getContext("2d");
+  if (context === null) throw new Error("canvas 2d 上下文不可用");
+
+  // 背景：纵向渐变，与舞台同色系（深色底，缩略图里不刺眼）
+  const gradient = context.createLinearGradient(0, 0, 0, input.height);
+  gradient.addColorStop(0, "#1e1e2e");
+  gradient.addColorStop(1, "#12121a");
+  context.fillStyle = gradient;
+  context.fillRect(0, 0, input.width, input.height);
+
+  drawTextOverlay(context, input);
+
+  return canvas.toDataURL("image/jpeg", input.quality);
+}
+
+/** 文字投影：标题 + 说话人 + 正文逐字符折行 + 时间戳 */
+export function drawTextOverlay(
+  context: CanvasRenderingContext2D,
+  input: SaveThumbnailInput,
+): void {
+  if (!input.showText) return;
+  const pad = Math.round(input.width * 0.06);
+
+  context.fillStyle = "#7aa2f7";
+  context.font = `bold ${Math.round(input.height * 0.09)}px sans-serif`;
+  context.fillText(input.title ?? "", pad, Math.round(input.height * 0.22));
+
+  const speakerY = Math.round(input.height * 0.46);
+  if (input.speaker) {
+    context.fillStyle = "#9ece6a";
+    context.font = `${Math.round(input.height * 0.075)}px sans-serif`;
+    context.fillText(input.speaker, pad, speakerY);
+  }
+
+  const line = (input.text ?? "").replace(/\s+/g, " ").trim();
+  const maxWidth = input.width - pad * 2;
+  const charSize = Math.round(input.height * 0.07);
+  context.fillStyle = "#e6e6f0";
+  context.font = `${charSize}px sans-serif`;
+  // 逐字符折行：缩略图场景够用，CJK 也没有断词问题
+  let cursorX = pad;
+  let cursorY = speakerY + (input.speaker ? Math.round(charSize * 1.8) : 0);
+  for (const char of line) {
+    if (cursorX + charSize > maxWidth) {
+      cursorX = pad;
+      cursorY += Math.round(charSize * 1.4);
+      if (cursorY > input.height - pad) break;
+    }
+    context.fillText(char, cursorX, cursorY);
+    cursorX += charSize;
+  }
+
+  context.fillStyle = "#565f89";
+  context.font = `${Math.round(input.height * 0.06)}px sans-serif`;
+  context.fillText(
+    new Date(input.timestamp).toLocaleString(),
+    pad,
+    input.height - Math.round(pad * 0.8),
+  );
+}

package/template/__PROJECT__/src/main.ts

@@ -13,22 +13,31 @@
  *
  * 覆盖范围（本宿主**保证不卡死**：引擎能进入的每个等待态都有 UI 可推进）：
  *   dialogue / menu / input / wait / video / minigame（可见 fail-closed 提示）+
- *   舞台元素层 + 层级表（shell.layers）+ 存档（shell.saves.slots）。
- * 有意未做（属「少功能」而非「卡死」，见 README 边界表）：历史面板与回溯 UI、
- * 玩家偏好面板、I18N 供给、对话框模板注册、存档缩略图合成。
+ *   舞台元素层 + 层级表（shell.layers）+ 存档（shell.saves.slots）+
+ *   玩家偏好面板 + 历史面板与回溯（点一条即回到那个检查点）。
+ * 有意未做（属「少功能」而非「卡死」，见 README 边界表）：I18N 供给、
+ * 对话框模板注册、存档缩略图合成。
  */
 
+import { MANIFEST_FILE } from "@lingfan-engine/core";
 import { DEFAULT_TEXT_CPS, DEFAULT_TOAST_MS } from "@lingfan-engine/ui";
-import { bootHost, must, reportBootFailure, type StageDom } from "./host";
+import {
+  bootHost,
+  must,
+  optional,
+  reportBootFailure,
+  type StageDom,
+} from "./host";
 import { STORIES } from "./stories";
+import { uis } from "./mounts";
 
 /**
  * 工程清单与故事文件：**都在应用资源根 `Resources/` 内**。
- * 宿主把 `Resources` 作为静态根，故逻辑路径就是 `project.json` / `Stories/**`。
+ * 宿主把 `Resources` 作为静态根，故逻辑路径就是清单名 / `Stories/**`。
  * 清单放在资源根内是有意为之——只有资源根内的文件才会进打包产物，dev 与 prod 同机制。
- * 故事表在 `./stories`（唯一声明点，各形态共用）。
+ * 清单名取引擎契约里的 `MANIFEST_FILE`（组装、写回、定位资源根共用同一个声明）；
+ * 故事表在 `./stories`（唯一出口，各形态共用），内容由构建期扫描资源根得出。
  */
-const MANIFEST = "project.json";
 
 /** 页面节点句柄表：每个 id 都必须存在于 index.html（缺一个 `must` 当场抛） */
 const dom: StageDom = {
@@ -47,14 +56,27 @@ const dom: StageDom = {
   load: must<HTMLButtonElement>("#load"),
   transition: must("#transition"),
   error: must("#error"),
+  prefs: optional("#prefs"),
+  // 历史面板槽位（可选）：本层不给就 null，没有「历史」按钮，其余照常
+  history: optional("#history"),
+  // UI 挂载层槽位（可选）：本层不给就 null，`mount` 命令只改状态、没有组件出现
+  mounts: optional("#mounts"),
 };
 
 void bootHost({
   dom,
-  manifestFile: MANIFEST,
+  manifestFile: MANIFEST_FILE,
   stories: STORIES,
   defaultCps: DEFAULT_TEXT_CPS,
   toastDurationMs: DEFAULT_TOAST_MS,
+  // 偏好面板槽位：页面给了就装（`optional` 已消化「这层不给」的情况）
+  prefsContainer: dom.prefs,
+  // 历史面板槽位：给了就有「历史」按钮与回溯（点一条即回到那个检查点）
+  historyContainer: dom.history,
+  // UI 挂载槽位：给了就把 `mount` 命令控制显隐的组件挂进来
+  mountsContainer: dom.mounts,
+  // 「名字 → UI 工厂」表：来自生成物，键就是 `SYS.mounts` 里的名字
+  mountsTable: uis,
 }).catch((error: unknown) => {
   reportBootFailure(dom, error);
 });

package/template/__PROJECT__/src/mounts.ts

@@ -0,0 +1,22 @@
+/**
+ * UI 注册表的宿主侧出口：`src/**` 内引用生成物的唯一位置。
+ *
+ * 表由 `stories:build` 从 `src/ui/<名>/` 扫描产出到 `src/gen/`，键就是 `SYS.mounts`
+ * 里的名字（= 目录名），因此宿主侧不需要再归一、也不需要手写注册表——手写名单在
+ * 「加了 UI 却忘了登记」时只会表现成运行期「这个 UI 不出现」，而磁盘事实不会漏。
+ *
+ * 三形态（原生 / Vue / React）都从这里取，好让生成物的路径只出现一处：
+ * 换生成器输出名时只改本文件。故事源不经过这里——它按 `*.vue` 的具名导入拿句柄。
+ */
+import { createMountStore } from "@lingfan-engine/ui";
+
+export { uis } from "./gen/ui_register.g";
+
+/**
+ * 挂载状态的宿主侧副本（框架无关）。
+ *
+ * 引擎每写一次 `SYS.mounts`，`bootHost` 就把新值放进来；框架形态的渲染组件订阅它
+ * 拿最新值，原生形态不订阅（渲染器自己算差量）。放在这里而不是各形态一份，是因为
+ * 「值从哪来」三形态完全一样，只有「怎么落成 DOM」不同。
+ */
+export const mountStore = createMountStore();

package/template/__PROJECT__/src/stories/index.ts

@@ -0,0 +1,10 @@
+/**
+ * 故事清单的宿主侧出口。
+ *
+ * 清单由构建期扫描 `Resources/Stories/` 得出（`virtual:story-list`），不是手写名单：
+ * 手写名单在「加了文件却忘了登记」时只会表现成运行期的 `unknown-column`，
+ * 而磁盘事实不会漏。TS 创作链的产物与手写 `.story` 落在同一棵树，共用这一条扫描。
+ *
+ * 组合根与各框架/壳入口都从这里取，不在自己的入口里各写一份。
+ */
+export { STORIES } from "virtual:story-list";

package/template/__PROJECT__/src/styles/stage.css

@@ -160,6 +160,120 @@ input {
 button {
   cursor: pointer;
 }
+/* 历史面板槽位：z 由 shell.layers.history 写入（缺省 1500，与偏好面板同级）；
+   槽位本身不吃事件，只有里面的控件吃——这层没给（或面板收起）时点击直接穿透 */
+#history {
+  position: absolute;
+  top: 12px;
+  left: 12px;
+  max-width: 360px;
+  pointer-events: none;
+}
+#history > * {
+  pointer-events: auto;
+}
+.history-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  border: 1px solid #2f3a4d;
+  border-radius: 8px;
+  background: rgba(27, 33, 48, 0.94);
+  padding: 10px 12px;
+  font-size: 13px;
+}
+.history-list {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  /* 历史可能很长：给个上限自己滚，别把整屏顶开 */
+  max-height: 50vh;
+  overflow-y: auto;
+}
+.history-item {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  text-align: left;
+  background: transparent;
+  border: none;
+  border-radius: 4px;
+  padding: 4px 6px;
+}
+.history-item:hover {
+  background: rgba(122, 162, 247, 0.14);
+}
+.history-speaker {
+  color: #9ece6a;
+  font-size: 12px;
+}
+.history-text {
+  color: #c0caf5;
+  line-height: 1.4;
+}
+/* NVL 块里的行：连续 NVL 聚成一块，逐行缩进以示「同屏累积」 */
+.history-nvl {
+  padding-left: 0.8em;
+}
+/* 偏好面板槽位：z 由 shell.layers.prefs 写入（缺省 1500，与历史面板同级）；
+   槽位本身不吃事件，只有里面的控件吃——面板空着（这层没装）时点击直接穿透 */
+#prefs {
+  position: absolute;
+  top: 12px;
+  right: 12px;
+  max-width: 300px;
+  pointer-events: none;
+}
+#prefs > * {
+  pointer-events: auto;
+}
+.prefs-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  border: 1px solid #2f3a4d;
+  border-radius: 8px;
+  background: rgba(27, 33, 48, 0.94);
+  padding: 10px 12px;
+  font-size: 13px;
+}
+.prefs-row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+.prefs-label {
+  flex: 0 0 4em;
+  color: #a9b1d6;
+}
+.prefs-range {
+  flex: 1 1 auto;
+  min-width: 100px;
+  padding: 0;
+  border: none;
+  background: transparent;
+}
+.prefs-checkbox {
+  padding: 0;
+}
+.prefs-value {
+  flex: 0 0 4em;
+  text-align: right;
+  color: #a9b1d6;
+  font-variant-numeric: tabular-nums;
+}
+/* UI 挂载层：`mount` 命令显示/隐藏的组件挂这里（见 src/host/mount/）。
+   隐藏 = 从渲染树移除，所以这里没有 display:none 的分支——容器空着就是没有 UI。
+   槽位本身不吃事件，只有里面的组件吃：UI 覆盖整屏时不该顺带吃掉对话层的点击，
+   而组件要交互时自己声明（与 #prefs 同一口径）。 */
+#mounts {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+}
+#mounts > * {
+  pointer-events: auto;
+}
 /* 全屏转场遮罩（transition）：屏幕级，恒在最上；透明度由帧驱动写入 */
 #transition {
   position: absolute;

package/template/__PROJECT__/src/vite-env.d.ts

@@ -12,3 +12,12 @@ declare module "virtual:story-fonts" {
   /** 构建期扫描 Resources/Fonts 的字体清单（与 stories:build 注册表同源） */
   export const storyFonts: readonly StoryFontEntry[];
 }
+
+/**
+ * 故事清单的宿主侧声明：构建期递归扫描 `Resources/Stories/` 得到的逻辑路径表
+ * （相对资源根，如 `Stories/title/title_main.story`）。
+ */
+declare module "virtual:story-list" {
+  /** 按路径码元序排列的故事文件逻辑路径 */
+  export const STORIES: readonly string[];
+}

package/template/__PROJECT__/tsconfig.node.json

@@ -3,6 +3,7 @@
     "target": "ES2022",
     "module": "ESNext",
     "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
     "types": ["node"],
     "strict": true,
     "noEmit": true,
@@ -10,5 +11,5 @@
     "noUnusedLocals": true,
     "noUnusedParameters": true
   },
-  "include": ["vite.config.ts"]
+  "include": ["vite.config.ts", "vite.plugins.ts"]
 }

package/template/__PROJECT__/vite.config.ts

@@ -1,57 +1,12 @@
-import { existsSync, readdirSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { defineConfig, type Plugin } from "vite";
-
-/** 字体文件扩展名集合（与 stories-build 的字体名注册表同口径） */
-const FONT_EXTENSIONS = [".ttf", ".otf", ".woff", ".woff2"] as const;
-
-/** 字体清单条目：file = 资源文件名，name = 字体名（文件名去扩展名） */
-interface StoryFontEntry {
-  file: string;
-  name: string;
-}
-
-/** Resources/Fonts 扫描：点文件与未知扩展名跳过，文件名字典序稳定 */
-function scanFonts(fontsDir: string): readonly StoryFontEntry[] {
-  if (!existsSync(fontsDir)) return [];
-  return readdirSync(fontsDir)
-    .filter((file) => {
-      const dot = file.lastIndexOf(".");
-      return (
-        dot > 0 &&
-        (FONT_EXTENSIONS as readonly string[]).includes(
-          file.slice(dot).toLowerCase(),
-        )
-      );
-    })
-    .sort()
-    .map((file) => ({ file, name: file.slice(0, file.lastIndexOf(".")) }));
-}
+import { defineConfig } from "vite";
+import { storyFontsVirtual, storyListVirtual } from "./vite.plugins.ts";
 
 /**
- * 字体清单虚拟模块：构建期扫描 Resources/Fonts 产出字体名清单，
- * 宿主据此注入 @font-face 与项目默认字体——字体名注册表与 stories:build 同源，
- * 零新增依赖（脚手架工程保持可独立安装）。
+ * 脚手架工程的 Vite 配置：约定资源根、宿主端口与两个清单虚拟模块。
+ *
+ * 字体清单与故事清单都由构建期扫描资源根得出（实现见 `vite.plugins.ts`）——
+ * 加一个故事文件、放一个字体，不需要回来改任何名单。
  */
-function storyFontsVirtual(): Plugin {
-  const moduleId = "virtual:story-fonts";
-  const fontsDir = fileURLToPath(new URL("./Resources/Fonts", import.meta.url));
-  return {
-    name: "story-fonts",
-    resolveId(id) {
-      if (id === moduleId) return `\0${moduleId}`;
-      return null;
-    },
-    load(id) {
-      if (id === `\0${moduleId}`) {
-        return `export const storyFonts = ${JSON.stringify(scanFonts(fontsDir))};`;
-      }
-      return null;
-    },
-  };
-}
-
-/** 脚手架工程的 Vite 配置：仅约定资源根与宿主端口，其余随宿主需要自行扩展。 */
 export default defineConfig({
   // 项目资源根即静态根 —— 故事里的逻辑路径 `Audio/x.mp3` 解析为 `/Audio/x.mp3`，
   // 开发与打包产物一致，不依赖进程工作目录。资源根之外无隐式查找路径。
@@ -60,5 +15,5 @@ export default defineConfig({
   // 宿主端口与 Tauri 约定一致；换平台壳时只改这里
   server: { port: 1420, strictPort: true },
 
-  plugins: [storyFontsVirtual()],
+  plugins: [storyFontsVirtual(), storyListVirtual()],
 });

package/template/__PROJECT__/vite.plugins.ts

@@ -0,0 +1,49 @@
+/**
+ * 构建期的两个虚拟模块：字体清单与故事清单。
+ *
+ * 两个清单都是**磁盘事实的投影**，不是需要作者维护的声明文件。让作者手抄名单的代价
+ * 不是「多写一行」，而是漏抄时构建期毫无察觉——漏登记的那一列要到运行期才以
+ * `unknown-column` 现形。
+ *
+ * 扫描实现不在这里：它属于 `@lingfan-engine/stories-build`（构建期清单的权威实现，
+ * 与 `stories:build` 的字体名/故事清单同源）。本文件只负责把「资源根在哪」告诉它——
+ * 缺省是工程资源根，改工程布局时改 `vite.config.ts` 的传参，不改扫描逻辑。
+ */
+import {
+  storyFontsVirtual as sharedStoryFontsVirtual,
+  storyListVirtual as sharedStoryListVirtual,
+  type HostPlugin,
+  type ResourceRootOptions,
+} from "@lingfan-engine/stories-build/host-plugins";
+
+/** 字体清单条目：file = 资源文件名，name = 字体名（文件名去扩展名） */
+export interface StoryFontEntry {
+  file: string;
+  name: string;
+}
+
+/**
+ * 字体清单虚拟模块：构建期扫描资源根下的字体目录产出字体名清单，
+ * 宿主据此注入 @font-face 与项目默认字体。
+ *
+ * @param options 资源根覆盖；缺省 = 本文件同级的 `<RESOURCES_DIR>`
+ */
+export function storyFontsVirtual(
+  options: ResourceRootOptions = {},
+): HostPlugin {
+  return sharedStoryFontsVirtual(options, import.meta.url);
+}
+
+/**
+ * 故事清单虚拟模块：构建期扫描资源根下的故事目录得出要装载的故事文件表。
+ *
+ * TS 创作链的产物（`Stories.src/` 编译出的 `.json`）与手写 `.story` 落在同一棵树，
+ * 共用这一条扫描——创作形态不改变清单的来源。
+ *
+ * @param options 资源根覆盖；缺省 = 本文件同级的 `<RESOURCES_DIR>`
+ */
+export function storyListVirtual(
+  options: ResourceRootOptions = {},
+): HostPlugin {
+  return sharedStoryListVirtual(options, import.meta.url);
+}

package/template/overlays/README.md

@@ -10,11 +10,17 @@
 
 ## 现有层
 
-- `ts/` —— 故事源层，只换故事素材、不碰页面：新增 `Stories.src/`（`config.ts` + 两个示例列）、
-  构建产物 `Resources/Stories/title/*.json` 与 `Stories.src/gen/*.gen.d.ts`、覆盖骨架的
-  `src/stories.ts`（清单改指 `.json` 产物）与独立的 `tsconfig.stories.json`。
+- `ts/` —— 故事源层，只换故事素材、不碰页面：新增 `src/Stories.src/`（`config.ts` + 两个示例列）、
+  构建产物 `Resources/Stories/title/*.json` 与 `src/gen/*.gen.d.ts`、独立的 `tsconfig.stories.json`。
+  故事源与类型面生成物都在 `src/` 下，两者都不进最终包：`src/Stories.src/**` 由 `tsconfig.json`
+  排除在类型检查之外，`src/gen/**` 只有 `fun_register.g.ts` 带运行期值。
+  故事里可以写工程 `tsconfig.json` 声明的任意别名（`@/ui/hub/hub.vue`、`@ui/...`），stories-build
+  会读那份 `paths` 自行解析——宿主不必配任何别名就能构建；若还想让 Vite / tsc 也认同一套别名，
+  在 `vite.config.ts` 里用正则 `find: /^@\//`（字符串 `"@"` 是前缀匹配，会把 `@lingfan-engine/*` 一起吞掉）。
   `package.patch.json` 补 `@lingfan-engine/stories-build` / `@lingfan-engine/editor` 与三条脚本，
   并用 `create.remove` 删掉骨架那份手写故事（产物目录由构建全量管理，两套并存会把 `.story` 当陈旧列清掉）。
+  故事清单不归本层管：骨架的 `vite.plugins.ts` 扫 `Resources/Stories/`，产物 `.json` 落在同一棵树里，
+  自动进清单——层不需要也不应该覆盖 `src/stories/index.ts`。
 - `vue/` —— 页面结构换成单文件组件：`index.html` 变成挂载点，新增 `src/App.vue` 与 Vue 版组合根，
   `package.patch.json` 补 `vue` / `@vitejs/plugin-vue` / `vue-tsc`，并把 `typecheck` 换成
   `vue-tsc --noEmit && tsc --noEmit -p tsconfig.node.json`。`src/host/**` 一行不改，

package/template/overlays/miniprogram/package.patch.json

@@ -4,7 +4,7 @@
     "@dcloudio/uni-components": "3.0.0-4080720251210001",
     "@dcloudio/uni-h5": "3.0.0-4080720251210001",
     "@dcloudio/uni-mp-weixin": "3.0.0-4080720251210001",
-    "@lingfan-engine/shell": "^0.1.0",
+    "@lingfan-engine/shell": "^0.3.0",
     "vue": "3.4.21"
   },
   "devDependencies": {

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

@@ -13,6 +13,7 @@ import {
   defaultEngineTexts,
   findMissingGuards,
   PlayerPreferences,
+  resolveAudioConfig,
   resolveSavesConfig,
   slotIds,
   StoryEngine,
@@ -129,7 +130,8 @@ export async function startMiniprogramHost(
 
   // 存档槽数与缩略图参数来自同一份工程清单（`shell.saves` 逐键覆盖）：清单与故事是同一次
   // 装载（端口内 memo），这里再取一次不产生第二个请求。
-  const saves: SavesConfig = resolveSavesConfig(await filesPort.manifest());
+  const manifest = await filesPort.manifest();
+  const saves: SavesConfig = resolveSavesConfig(manifest);
 
   // 内容是包外的（故事走工程接口，改故事不必发版），守卫却在包里：装载完成先对名字，
   // 缺谁一次报全——错误停在起播之前，而不是播到那条命令才弹「未注册的守卫」。
@@ -145,6 +147,8 @@ export async function startMiniprogramHost(
   });
   const ports = createMiniprogramHostPorts({ videoSurface, projectBaseUrl });
   const engine = new StoryEngine(story, {
+    // 工程默认音量（project.json shell.audio.volumes）：音量的第二级
+    audioConfig: resolveAudioConfig(manifest),
     savePort: ports.save,
     texts: withSlotLabels(defaultEngineTexts),
     // 守卫实现由宿主随代码带上：故事 JSON 只写名字（装载期已校验名字齐全）

package/template/overlays/miniprogram/vite.config.ts

@@ -1,65 +1,26 @@
 /**
- * 构建配置（小程序形态）：UniApp 的 Vite 插件，加上骨架那份字体扫描插件。
+ * 构建配置（小程序形态）：UniApp 的 Vite 插件，加上骨架那份清单插件。
  *
  * 这里不能沿用骨架的 `vite ^8`：`@dcloudio/vite-plugin-uni` 的 peer 精确钉住
  * `vite 5.2.8` 与 `@vue/shared 3.4.21`，与仓库根的那一代不兼容。所以本层自带一份
  * vite 与 vue，靠包管理器的隔离安装各用各的——版本写在 `package.patch.json` 里，
  * 并列入 `create.pinned`，生成器才不会把它改写成 `^最新`。
  *
+ * 清单扫描不再在本层另写一份：字体清单与故事清单都取自骨架的 `./vite.plugins`
+ * （实现属 `@lingfan-engine/stories-build`，与 `stories:build` 同源）。层与层之间
+ * 只差插件数组，扫描规则一处维护——小程序形态同样需要故事清单，否则它只能装载
+ * 骨架里手写的那几列。
+ *
  * `publicDir` 仍是无条件的 `Resources`：开发期的 H5 形态与骨架共用同一个资源根。
  * `copyPublicDir: false` 是有意的——小程序包体里不装故事与素材（故事走工程接口
  * `GET <基址>/project` 一次性返回 `{manifest, stories}`，素材走资源端口按 id 取），
  * 构建产物因此只有代码。
  */
-import { existsSync, readdirSync } from "node:fs";
-import { fileURLToPath } from "node:url";
 import uniModule, {
   type VitePluginUniOptions,
 } from "@dcloudio/vite-plugin-uni";
 import { defineConfig, type Plugin } from "vite";
-
-/** 字体扩展名：只有这些后缀会被当作可注册的字体 */
-const FONT_EXTENSIONS = [".ttf", ".otf", ".woff", ".woff2"] as const;
-
-/** 一份字体条目：`file` 是资源根下的相对路径，`name` 是字体族名（去扩展名的文件名） */
-interface StoryFontEntry {
-  readonly file: string;
-  readonly name: string;
-}
-
-/** 扫描字体目录：目录不存在就是空表，不抛错 */
-function scanFonts(fontsDir: string): StoryFontEntry[] {
-  if (!existsSync(fontsDir)) return [];
-  return readdirSync(fontsDir)
-    .filter((entry) =>
-      FONT_EXTENSIONS.some((ext) => entry.toLowerCase().endsWith(ext)),
-    )
-    .sort()
-    .map((entry) => ({
-      file: `Fonts/${entry}`,
-      name: entry.slice(0, entry.lastIndexOf(".")),
-    }));
-}
-
-/**
- * 字体清单虚拟模块：把「资源根里有哪些字体」以数据形态交给运行期注册。
- *
- * 用虚拟模块而不是构建期 import：字体是资源根里的文件，走资源端口寻址；
- * 构建期 import 在加密资源形态下无文件可指。
- */
-function storyFontsVirtual(): Plugin {
-  const moduleId = "virtual:story-fonts";
-  const resolved = `\0${moduleId}`;
-  const fontsDir = fileURLToPath(new URL("./Resources/Fonts", import.meta.url));
-  return {
-    name: "lingfan:story-fonts",
-    resolveId: (id) => (id === moduleId ? resolved : undefined),
-    load: (id) =>
-      id === resolved
-        ? `export const storyFonts = ${JSON.stringify(scanFonts(fontsDir))};`
-        : undefined,
-  };
-}
+import { storyFontsVirtual, storyListVirtual } from "./vite.plugins.ts";
 
 type UniPluginFactory = (options?: VitePluginUniOptions) => Plugin[];
 
@@ -83,5 +44,5 @@ export default defineConfig({
     port: 1420,
     strictPort: true,
   },
-  plugins: [uni(), storyFontsVirtual()],
+  plugins: [uni(), storyFontsVirtual(), storyListVirtual()],
 });