@lingfan-engine/create 0.2.0 → 0.3.1

package/template/overlays/react/src/App.tsx

@@ -6,6 +6,8 @@
  * 本组件**不碰引擎**：装配在 `src/main.tsx`（唯一组合根），交互监听由骨架的
  * `src/host/` 用原生事件绑定——React 在这里只负责把节点渲染出来。
  */
+import { UiHost } from "./UiHost.tsx";
+
 export function App() {
   return (
     // 舞台根：屏幕震动（shake）施于此；各层 z 由 main.tsx 按 shell.layers 写入
@@ -25,6 +27,16 @@ export function App() {
         <button id="save">存</button>
         <button id="load">读</button>
       </div>
+      {/* 历史面板槽位：可选节点（本层不给也能跑，只是没有回看与回溯） */}
+      <div id="history"></div>
+      {/* 偏好面板槽位：可选节点（本层不给也能跑，只是没有音量/字速面板） */}
+      <div id="prefs"></div>
+      {/* UI 挂载层：`mount` 命令显示/隐藏的组件挂在这里（可选节点，缺了只是没有 UI）。
+           位置在对话与工具条之后、转场遮罩之前：UI 盖住对话层，但盖不住转场与错误条。
+           内容由 `UiHost` 渲染——父子关系归 React，组合根不再往这个容器里写节点。 */}
+      <div id="mounts">
+        <UiHost />
+      </div>
       <div id="transition"></div>
       <div id="error"></div>
     </div>

package/template/overlays/react/src/UiHost.tsx

@@ -0,0 +1,62 @@
+/**
+ * UI 挂载层（React 形态）：把 `SYS.mounts` 里可见的 UI 铺成子组件。
+ *
+ * 与 Vue 形态逐条对等，只是取值的接缝换了：
+ * 1. **值从哪来**：`mountStore` 由组合根喂（`bootHost` 的 `onMounts`），这里用
+ *    `useSyncExternalStore` 订阅——React 的并发渲染要求外部值的读取是「快照式」的，
+ *    自己 `useState` + `useEffect` 会在首帧读到旧值。
+ * 2. **表从哪来**：`uis` 来自生成物（`src/gen/ui_register.g.ts`），键就是目录名，
+ *    不做 `import.meta.glob`——那会把 `src/ui/` 下的文件全部静态拉进包。
+ * 3. **隐藏 = 不渲染**：列表就是可见集合，不可见的组件不在渲染树上，它的副作用与
+ *    定时器随卸载一起清（不是 `display:none`）。
+ *
+ * 组件由 React 自己创建，所以挂载点的父子关系归 React——组合根不该再往这个容器里写节点。
+ */
+import { createElement, useEffect, useMemo, useSyncExternalStore } from "react";
+import { missingMounts, selectMounts } from "@lingfan-engine/ui";
+import { controlsStore } from "./controls";
+import { mountStore, uis } from "./mounts";
+
+/** 生成物里没有的名字只报一次：按帧重渲染会把它刷成噪音，反而看不见真问题 */
+const reported = new Set<string>();
+
+export function UiHost() {
+  const raw = useSyncExternalStore(
+    mountStore.subscribe,
+    mountStore.snapshot,
+    mountStore.snapshot,
+  );
+  /**
+   * 操作句柄：来自组合根而不是故事值。
+   *
+   * 它与 `props` 分属两条通道——`props` 是故事命令写下的值（随存档、必须 JSON 安全），
+   * 句柄含函数、不进快照，所以单独订阅一格再作为 prop 发给每个挂载组件。
+   */
+  const controls = useSyncExternalStore(
+    controlsStore.subscribe,
+    controlsStore.snapshot,
+    controlsStore.snapshot,
+  );
+  const items = useMemo(() => selectMounts(raw, uis), [raw]);
+
+  useEffect(() => {
+    for (const name of missingMounts(raw, uis)) {
+      if (reported.has(name)) continue;
+      reported.add(name);
+      console.error(
+        `[ui] 生成物 uis 里没有 ${name}，这条挂载被跳过——构建期本应拦住越界的 UI 名`,
+      );
+    }
+  }, [raw]);
+
+  return createElement(
+    null,
+    ...items.map((item) =>
+      createElement(item.component as never, {
+        key: item.name,
+        ...item.props,
+        controls,
+      }),
+    ),
+  );
+}

package/template/overlays/react/src/main.tsx

@@ -10,17 +10,26 @@
  */
 import { createElement, StrictMode } from "react";
 import { createRoot } from "react-dom/client";
+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 { controlsStore } from "./controls";
+import { mountStore } from "./mounts";
 import { App } from "./App.tsx";
 
 /**
  * 工程清单与故事文件：**都在应用资源根 `Resources/` 内**。
- * 宿主把 `Resources` 作为静态根，故逻辑路径就是 `project.json` / `Stories/**`。
- * 故事表在 `./stories`（唯一声明点，各形态共用）。
+ * 宿主把 `Resources` 作为静态根，故逻辑路径就是清单名 / `Stories/**`。
+ * 清单名取引擎契约里的 `MANIFEST_FILE`（组装、写回、定位资源根共用同一个声明）；
+ * 故事表在 `./stories`（唯一出口，各形态共用），内容由构建期扫描资源根得出。
  */
-const MANIFEST = "project.json";
 
 /** 页面节点句柄表：每个 id 都必须由 `App.tsx` 渲染（缺一个 `must` 当场抛） */
 function readDom(): StageDom {
@@ -40,6 +49,12 @@ function readDom(): StageDom {
     load: must<HTMLButtonElement>("#load"),
     transition: must("#transition"),
     error: must("#error"),
+    // 历史面板槽位（可选）：本层 App 没给就 null，回看与回溯不装、游戏照跑
+    history: optional("#history"),
+    // 偏好面板槽位（可选）：本层 App 没给就 null，面板不装、游戏照跑
+    prefs: optional("#prefs"),
+    // UI 挂载层槽位（可选）：本层不给就 null，`mount` 命令只改状态、没有组件出现
+    mounts: optional("#mounts"),
   };
 }
 
@@ -63,10 +78,17 @@ const dom = mountApp();
 if (dom !== undefined) {
   void bootHost({
     dom,
-    manifestFile: MANIFEST,
+    manifestFile: MANIFEST_FILE,
     stories: STORIES,
     defaultCps: DEFAULT_TEXT_CPS,
     toastDurationMs: DEFAULT_TOAST_MS,
+    historyContainer: dom.history,
+    prefsContainer: dom.prefs,
+    // UI 挂载落法由 React 接管：`#mounts` 的子节点归 `UiHost` 渲染，
+    // 宿主再往里写节点就会与 React 的渲染树打架（所以不传 mountsContainer）
+    onMounts: (raw) => mountStore.set(raw),
+    // 操作句柄另走一条路：值进 mountStore（随存档），句柄进 controlsStore（不进快照）
+    onControls: (controls) => controlsStore.set(controls),
   }).catch((error: unknown) => {
     reportBootFailure(dom, error);
   });

package/template/overlays/react/src/vite-env.d.ts

@@ -12,3 +12,15 @@ declare module "virtual:story-fonts" {
   /** 构建期扫描 Resources/Fonts 的字体清单（与 stories:build 注册表同源） */
   export const storyFonts: readonly StoryFontEntry[];
 }
+
+/**
+ * 故事清单的宿主侧声明：构建期递归扫描 `Resources/Stories/` 得到的逻辑路径表
+ * （相对资源根，如 `Stories/title/title_main.story`）。
+ *
+ * 本层带自己的 `vite-env.d.ts` 是为了追加 JSX 相关的类型，但它**整体覆盖**骨架的同名文件，
+ * 所以骨架里已声明的虚拟模块必须原样在此再声明一次，否则生成工程必然 `TS2307`。
+ */
+declare module "virtual:story-list" {
+  /** 按路径码元序排列的故事文件逻辑路径 */
+  export const STORIES: readonly string[];
+}

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

@@ -3,56 +3,13 @@
  *
  * 资源根仍是无条件镜像 `Resources`——纯 Web 工程就是「浏览器游戏模式」的交付正例，
  * 不引入壳侧的开关判定（那属于 Tauri 壳的交付形态，见引擎仓库 `apps/playground`）。
+ *
+ * 字体清单与故事清单的扫描实现在骨架的 `vite.plugins.ts`，本层只多挂一个框架插件：
+ * 清单规则一处维护，换框架不该换掉「清单来自磁盘」这件事。
  */
-import { existsSync, readdirSync } from "node:fs";
-import { fileURLToPath } from "node:url";
 import react from "@vitejs/plugin-react";
-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(".")) }));
-}
-
-/** 字体清单虚拟模块：构建期扫描 Resources/Fonts，与 stories:build 的注册表同源 */
-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;
-    },
-  };
-}
+import { defineConfig } from "vite";
+import { storyFontsVirtual, storyListVirtual } from "./vite.plugins.ts";
 
 /** 脚手架工程的 Vite 配置（React 形态） */
 export default defineConfig({
@@ -63,5 +20,5 @@ export default defineConfig({
   // 宿主端口与 Tauri 约定一致；换平台壳时只改这里
   server: { port: 1420, strictPort: true },
 
-  plugins: [react(), storyFontsVirtual()],
+  plugins: [react(), storyFontsVirtual(), storyListVirtual()],
 });

package/template/overlays/tauri/src/main.ts

@@ -17,20 +17,28 @@
  *
  * 页面结构沿用骨架的 `index.html`（本层不带自己的），故节点解析与骨架同源。
  */
+import { MANIFEST_FILE } from "@lingfan-engine/core";
 import { DEFAULT_TEXT_CPS, DEFAULT_TOAST_MS } from "@lingfan-engine/ui";
 import {
   createTauriSavePort,
   installTauriBridge,
 } from "@lingfan-engine/adapters";
-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/` 内**。
  * 打包后它们位于 `dist/` 顶层，路径与开发期一致。
- * 故事表在 `./stories`（唯一声明点，各形态共用）。
+ * 清单名取引擎契约里的 `MANIFEST_FILE`（组装、写回、定位资源根共用同一个声明）；
+ * 故事表在 `./stories`（唯一出口，各形态共用），内容由构建期扫描资源根得出。
  */
-const MANIFEST = "project.json";
 
 /** 页面节点句柄表：每个 id 都必须存在于 index.html（缺一个 `must` 当场抛） */
 const dom: StageDom = {
@@ -49,6 +57,12 @@ const dom: StageDom = {
   load: must<HTMLButtonElement>("#load"),
   transition: must("#transition"),
   error: must("#error"),
+  // 历史面板槽位（可选）：骨架 index.html 里有，缺了也不影响启动
+  history: optional("#history"),
+  // 偏好面板槽位（可选）：骨架 index.html 里有，缺了也不影响启动
+  prefs: optional("#prefs"),
+  // UI 挂载层槽位（可选）：本层不给就 null，`mount` 命令只改状态、没有组件出现
+  mounts: optional("#mounts"),
 };
 
 /**
@@ -66,10 +80,15 @@ async function boot(): Promise<void> {
 
   await bootHost({
     dom,
-    manifestFile: MANIFEST,
+    manifestFile: MANIFEST_FILE,
     stories: STORIES,
     defaultCps: DEFAULT_TEXT_CPS,
     toastDurationMs: DEFAULT_TOAST_MS,
+    historyContainer: dom.history,
+    prefsContainer: dom.prefs,
+    // UI 挂载槽位：壳层用骨架的原生渲染器（本层不引框架，`#mounts` 的子节点由宿主写）
+    mountsContainer: dom.mounts,
+    mountsTable: uis,
     ports: {
       // 存档落到应用数据目录的 saves/ 下，一槽一文件（加密与回档保护在 Rust 侧扩展）
       saves: createTauriSavePort(),

package/template/overlays/ts/package.patch.json

@@ -1,7 +1,6 @@
 {
   "devDependencies": {
-    "@lingfan-engine/editor": "^0.1.0",
-    "@lingfan-engine/stories-build": "^0.1.0"
+    "@lingfan-engine/editor": "^0.3.0"
   },
   "scripts": {
     "stories:build": "lingfan-stories-build .",

package/template/overlays/ts/{Stories.src → src/Stories.src}/title/title_main.ts

@@ -11,6 +11,12 @@
  */
 import { script } from "@lingfan-engine/editor";
 
+/**
+ * 本列是界面列（`ui`）：界面列不参与历史与存档，其余与 `game` 列一样在舞台上渲染。
+ * 缺省不写即 `game`——「是不是界面列」是数据，不是约定。
+ */
+export const columnType = "ui";
+
 const { menu, option, say } = script;
 
 export default function title_main(): void {

package/template/overlays/ts/tsconfig.stories.json

@@ -21,5 +21,5 @@
     "noUnusedParameters": true,
     "noFallthroughCasesInSwitch": true
   },
-  "include": ["Stories.src/**/*.ts"]
+  "include": ["src/Stories.src/**/*.ts"]
 }

package/template/overlays/vue/src/App.vue

@@ -6,6 +6,9 @@
   本组件**不碰引擎**：装配在 `src/main.ts`（唯一组合根），交互监听由骨架的
   `src/host/` 用原生事件绑定——Vue 在这里只负责把节点渲染出来。
 -->
+<script setup lang="ts">
+import UiHost from "./UiHost.vue";
+</script>
 <template>
   <!-- 舞台根：屏幕震动（shake）施于此；各层 z 由 main.ts 按 shell.layers 写入 -->
   <div id="stage-root">
@@ -24,6 +27,16 @@
       <button id="save">存</button>
       <button id="load">读</button>
     </div>
+    <!-- 历史面板槽位：可选节点（本层不给也能跑，只是没有回看与回溯） -->
+    <div id="history"></div>
+    <!-- 偏好面板槽位：可选节点（本层不给也能跑，只是没有音量/字速面板） -->
+    <div id="prefs"></div>
+    <!-- UI 挂载层：`mount` 命令显示/隐藏的组件挂在这里（可选节点，缺了只是没有 UI）。
+         位置在对话与工具条之后、转场遮罩之前：UI 盖住对话层，但盖不住转场与错误条。
+         内容由 `UiHost` 渲染——父子关系归 Vue，组合根不再往这个容器里写节点。 -->
+    <div id="mounts">
+      <UiHost />
+    </div>
     <div id="transition"></div>
     <div id="error"></div>
   </div>

package/template/overlays/vue/src/UiHost.vue

@@ -0,0 +1,65 @@
+<script setup lang="ts">
+/**
+ * UI 挂载层（Vue 形态）：把 `SYS.mounts` 里可见的 UI 铺成子组件。
+ *
+ * 三条边界：
+ * 1. **值从哪来**：`mountStore` 由组合根喂（`bootHost` 的 `onMounts`），这里只订阅。
+ *    自己再订阅一次引擎的话，退订就有两份实现，漏一份会在拆掉页面后继续写渲染树。
+ * 2. **表从哪来**：`uis` 来自生成物（`src/gen/ui_register.g.ts`），键就是目录名，
+ *    不做 `import.meta.glob`——那会把 `src/ui/` 下的文件全部静态拉进包。
+ * 3. **隐藏 = 不渲染**：`v-for` 的集合就是可见集合，不可见的组件不在渲染树上，
+ *    它的响应式与定时器随卸载一起停（不是 `display:none`）。
+ *
+ * 组件由 Vue 自己创建，所以挂载点的父子关系归 Vue——组合根不该再往这个容器里写节点。
+ */
+import { computed, onUnmounted, ref, watch } from "vue";
+import { missingMounts, selectMounts } from "@lingfan-engine/ui";
+import type { HostControls } from "@lingfan-engine/core";
+import { controlsStore } from "./controls";
+import { mountStore, uis } from "./mounts";
+
+/** 当前 `SYS.mounts` 原始值：订阅前先读一次快照（订阅不回放历史） */
+const raw = ref<unknown>(mountStore.snapshot());
+const stop = mountStore.subscribe((next) => {
+  raw.value = next;
+});
+onUnmounted(stop);
+
+/**
+ * 操作句柄：来自组合根而不是故事值。
+ *
+ * 它与 `props` 分属两条通道——`props` 是故事命令写下的值（随存档、必须 JSON 安全），
+ * 句柄含函数、不进快照，所以单独订阅一格再作为 prop 发给每个挂载组件。
+ */
+const controls = ref<HostControls | null>(controlsStore.snapshot());
+const stopControls = controlsStore.subscribe((next) => {
+  controls.value = next;
+});
+onUnmounted(stopControls);
+
+/** 这一帧该渲染的 UI：取不到组件的名字被跳过并单独上报 */
+const items = computed(() => selectMounts(raw.value, uis));
+const missing = computed(() => missingMounts(raw.value, uis));
+
+// 生成物里没有的名字只报一次：按帧重渲染会把它刷成噪音，反而看不见真问题
+const reported = new Set<string>();
+watch(missing, (names) => {
+  for (const name of names) {
+    if (reported.has(name)) continue;
+    reported.add(name);
+    console.error(
+      `[ui] 生成物 uis 里没有 ${name}，这条挂载被跳过——构建期本应拦住越界的 UI 名`,
+    );
+  }
+});
+</script>
+
+<template>
+  <component
+    :is="item.component"
+    v-for="item in items"
+    :key="item.name"
+    v-bind="item.props"
+    :controls="controls"
+  />
+</template>

package/template/overlays/vue/src/main.ts

@@ -9,17 +9,26 @@
  * 本层只替换入口与组合根）。
  */
 import { createApp } from "vue";
+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 { controlsStore } from "./controls";
+import { mountStore } from "./mounts";
 import App from "./App.vue";
 
 /**
  * 工程清单与故事文件：**都在应用资源根 `Resources/` 内**。
- * 宿主把 `Resources` 作为静态根，故逻辑路径就是 `project.json` / `Stories/**`。
- * 故事表在 `./stories`（唯一声明点，各形态共用）。
+ * 宿主把 `Resources` 作为静态根，故逻辑路径就是清单名 / `Stories/**`。
+ * 清单名取引擎契约里的 `MANIFEST_FILE`（组装、写回、定位资源根共用同一个声明）；
+ * 故事表在 `./stories`（唯一出口，各形态共用），内容由构建期扫描资源根得出。
  */
-const MANIFEST = "project.json";
 
 /** 页面节点句柄表：每个 id 都必须由 `App.vue` 渲染（缺一个 `must` 当场抛） */
 function readDom(): StageDom {
@@ -39,6 +48,12 @@ function readDom(): StageDom {
     load: must<HTMLButtonElement>("#load"),
     transition: must("#transition"),
     error: must("#error"),
+    // 偏好面板槽位（可选）：本层 App 没给就 null，面板不装、游戏照跑
+    prefs: optional("#prefs"),
+    // 历史面板槽位（可选）：本层 App 没给就 null，没有「历史」按钮
+    history: optional("#history"),
+    // UI 挂载层槽位（可选）：本层不给就 null，`mount` 命令只改状态、没有组件出现
+    mounts: optional("#mounts"),
   };
 }
 
@@ -57,10 +72,18 @@ const dom = mountApp();
 if (dom !== undefined) {
   void bootHost({
     dom,
-    manifestFile: MANIFEST,
+    manifestFile: MANIFEST_FILE,
     stories: STORIES,
     defaultCps: DEFAULT_TEXT_CPS,
     toastDurationMs: DEFAULT_TOAST_MS,
+    prefsContainer: dom.prefs,
+    // 历史面板槽位：给了就有「历史」按钮与回溯
+    historyContainer: dom.history,
+    // UI 挂载落法由 Vue 接管：`#mounts` 的子节点归 `UiHost` 渲染，
+    // 宿主再往里写节点就会与 Vue 的渲染树打架（所以不传 mountsContainer）
+    onMounts: (raw) => mountStore.set(raw),
+    // 操作句柄另走一条路：值进 mountStore（随存档），句柄进 controlsStore（不进快照）
+    onControls: (controls) => controlsStore.set(controls),
   }).catch((error: unknown) => {
     reportBootFailure(dom, error);
   });

package/template/overlays/vue/src/vite-env.d.ts

@@ -13,6 +13,18 @@ declare module "virtual:story-fonts" {
   export const storyFonts: readonly StoryFontEntry[];
 }
 
+/**
+ * 故事清单的宿主侧声明：构建期递归扫描 `Resources/Stories/` 得到的逻辑路径表
+ * （相对资源根，如 `Stories/title/title_main.story`）。
+ *
+ * 本层带自己的 `vite-env.d.ts` 是为了追加 `.vue` 模块声明，但它**整体覆盖**骨架的同名文件，
+ * 所以骨架里已声明的虚拟模块必须原样在此再声明一次，否则生成工程必然 `TS2307`。
+ */
+declare module "virtual:story-list" {
+  /** 按路径码元序排列的故事文件逻辑路径 */
+  export const STORIES: readonly string[];
+}
+
 /** 单文件组件的模块声明：`vue-tsc` 之外的工具读到 `.vue` 时不至于整片报错 */
 declare module "*.vue" {
   import type { DefineComponent } from "vue";

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

@@ -3,56 +3,13 @@
  *
  * 资源根仍是无条件镜像 `Resources`——纯 Web 工程就是「浏览器游戏模式」的交付正例，
  * 不引入壳侧的开关判定（那属于 Tauri 壳的交付形态，见引擎仓库 `apps/playground`）。
+ *
+ * 字体清单与故事清单的扫描实现在骨架的 `vite.plugins.ts`，本层只多挂一个框架插件：
+ * 清单规则一处维护，换框架不该换掉「清单来自磁盘」这件事。
  */
-import { existsSync, readdirSync } from "node:fs";
-import { fileURLToPath } from "node:url";
 import vue from "@vitejs/plugin-vue";
-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(".")) }));
-}
-
-/** 字体清单虚拟模块：构建期扫描 Resources/Fonts，与 stories:build 的注册表同源 */
-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;
-    },
-  };
-}
+import { defineConfig } from "vite";
+import { storyFontsVirtual, storyListVirtual } from "./vite.plugins.ts";
 
 /** 脚手架工程的 Vite 配置（Vue 形态） */
 export default defineConfig({
@@ -63,5 +20,5 @@ export default defineConfig({
   // 宿主端口与 Tauri 约定一致；换平台壳时只改这里
   server: { port: 1420, strictPort: true },
 
-  plugins: [vue(), storyFontsVirtual()],
+  plugins: [vue(), storyFontsVirtual(), storyListVirtual()],
 });

package/template/template-meta.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.7.0",
-  "minEngineVersion": "0.1.0",
+  "version": "1.8.1",
+  "minEngineVersion": "0.3.0",
   "placeholder": "__PROJECT__",
   "frameworks": [
     {
@@ -37,16 +37,16 @@
     }
   ],
   "sources": [
-    {
-      "id": "story",
-      "label": "故事文件（.story）",
-      "hint": "直接写引擎自带的文本故事格式，改完保存即生效"
-    },
     {
       "id": "ts",
       "label": "TypeScript 源（Stories.src）",
       "hint": "用 TS 写故事列：有类型补全与重构，构建时编译成故事文件"
+    },
+    {
+      "id": "story",
+      "label": "故事文件（.story）",
+      "hint": "直接写引擎自带的文本故事格式，改完保存即生效"
     }
   ],
-  "_comment": "模板版本唯一来源，独立于引擎版本：仅当 template/v1 内容真正变化时才手动 bump。placeholder 是目录/文件内的工程名占位符，生成时整体替换为工程名（对齐 _LingFanEngineTemplateTitle_ 占位符语义）。minEngineVersion 表示此模板要求的最低引擎版本。frameworks / shells / sources 决定生成器会问什么、能叠哪些层，各自首项为缺省值；每一项的 id 对应 template/v1/overlays/<id> 目录（缺省层可以没有目录）。合并顺序为「骨架 → 框架 → 故事源 → 壳」，同路径文件由后一层覆盖前一层。"
+  "_comment": "模板版本唯一来源，独立于引擎版本：仅当 template/v1 内容真正变化时才手动 bump。placeholder 是目录/文件内的工程名占位符，生成时整体替换为工程名（对齐 _LingFanEngineTemplateTitle_ 占位符语义）。minEngineVersion 表示此模板要求的最低引擎版本——生成期会拿它跟 registry 上的实际版本比对，不达标即失败（离线查不到版本时跳过判定）。frameworks / shells / sources 决定生成器会问什么、能叠哪些层，各自首项为缺省值；每一项的 id 对应 template/v1/overlays/<id> 目录（缺省层可以没有目录）。合并顺序为「骨架 → 框架 → 故事源 → 壳」，同路径文件由后一层覆盖前一层。"
 }

package/template/__PROJECT__/src/stories.ts

@@ -1,11 +0,0 @@
-/**
- * 本工程的故事文件表（相对资源根 `Resources/`）——**全工程唯一声明点**。
- *
- * Web 形态按显式清单取文件（不做目录扫描：扫描会让「多一个文件」变成静默行为，
- * 而打包产物里到底带了哪些故事必须一眼可见），因此新增故事文件要改这里。
- * 各框架/壳的组合根都从这里取，不在自己的入口里各写一份。
- *
- * 走 TS 创作链的工程会整体替换本文件（构建产物是 `.json`，清单随之指向它），
- * 入口与宿主一行不用改。
- */
-export const STORIES: readonly string[] = ["Stories/title/title_main.story"];

package/template/overlays/ts/src/stories.ts

@@ -1,10 +0,0 @@
-/**
- * 本工程的故事文件表（相对资源根 `Resources/`）——**全工程唯一声明点**。
- *
- * 本工程走 TS 创作链：这里列的是 `Stories.src/` 编译出来的产物，
- * 不要直接改 `Resources/Stories/**` 下的文件——它们是生成物，下次构建会被覆盖，
- * 源里没有的旧列还会被清理掉。改故事请改 `Stories.src/`，然后 `pnpm stories:build`。
- *
- * 新增一列后记得回来把产物路径加进本表（Web 形态按显式清单取文件，不扫目录）。
- */
-export const STORIES: readonly string[] = ["Stories/title/title_main.json"];