@lingfan-engine/create 0.0.0-stage → 0.1.4

package/template/overlays/miniprogram/src/pages/index/index.vue

@@ -0,0 +1,299 @@
+<script setup lang="ts">
+/**
+ * 页面装配：把宿主演出的数据挂到界面上，再把玩家的动作转回叙事。
+ *
+ * 这一层刻意很薄：装载、布局、渲染数据都归 `mp/`，页面只做三件事——取画布、把补丁写进
+ * 页面状态、把点击与输入交给覆盖层。别在页面里写叙事逻辑。
+ *
+ * 层次口径与桌面宿主一致：舞台层是唯一带基准尺寸与变换的容器（画布等比缩放），对话、
+ * 选择、通知各层住在窗口坐标系里，尺寸只跟窗口走。各层的模板与样式归各自的组件，
+ * 页面只负责编排——这样单文件留在可读尺度内，改一层的形态不必翻整页。
+ *
+ * 差别只在单位——桌面用 px + clamp 跟窗口，小程序页面按平台惯例用 rpx（宽度基准 750），
+ * 比例同源、绝对尺寸按 750 宽度折算。
+ */
+import { onReady, onUnload } from "@dcloudio/uni-app";
+import { ref } from "vue";
+import ChoiceLayer from "../../components/ChoiceLayer.vue";
+import DialogueLayer from "../../components/DialogueLayer.vue";
+import NoticeLayer from "../../components/NoticeLayer.vue";
+import SaveLoadBar from "../../components/SaveLoadBar.vue";
+import StageView from "../../components/StageView.vue";
+import {
+  chooseHostSlot,
+  loadHostSlotViews,
+  queryCanvasNode,
+  startMiniprogramHost,
+  watchWindowResize,
+  type MiniprogramHostHandle,
+  type MiniprogramHostPatch,
+  type MiniprogramNvlData,
+  type MiniprogramSurfaceData,
+  type MiniprogramVideoData,
+  type SlotPanelMode,
+  type SlotView,
+} from "../../mp/index.ts";
+
+/** 帧时钟画布的节点选择器 */
+const CANVAS_SELECTOR = "#stage-canvas";
+
+const stage = ref<MiniprogramSurfaceData["stage"]>([]);
+const elements = ref<MiniprogramSurfaceData["elements"]>([]);
+const dialogue = ref<MiniprogramSurfaceData["dialogue"]>(null);
+const nvl = ref<MiniprogramNvlData | null>(null);
+const choices = ref<MiniprogramSurfaceData["choices"]>(null);
+const notices = ref<MiniprogramSurfaceData["notices"]>([]);
+const layers = ref<MiniprogramSurfaceData["layers"]>({});
+const stageBox = ref("");
+const video = ref<MiniprogramVideoData | null>(null);
+const error = ref("");
+const inputValue = ref("");
+/** 存读面板模式与逐槽视图：null = 收起（只留入口条） */
+const slotMode = ref<SlotPanelMode | null>(null);
+const slotViews = ref<SlotView[]>([]);
+
+let host: MiniprogramHostHandle | null = null;
+let stopResizeWatch: (() => void) | null = null;
+
+/** 把一次补丁写进页面状态：字段缺省即不动（`null` 是「清空」而不是「不动」） */
+function applyPatch(patch: MiniprogramHostPatch): void {
+  if (patch.stage !== undefined) stage.value = patch.stage;
+  if (patch.elements !== undefined) elements.value = patch.elements;
+  if (patch.dialogue !== undefined) dialogue.value = patch.dialogue;
+  if (patch.nvl !== undefined) nvl.value = patch.nvl;
+  if (patch.choices !== undefined) choices.value = patch.choices;
+  if (patch.notices !== undefined) notices.value = patch.notices;
+  if (patch.layers !== undefined) layers.value = patch.layers;
+  if (patch.stageBox !== undefined) stageBox.value = patch.stageBox;
+  if (patch.video !== undefined) video.value = patch.video;
+  if (patch.error !== undefined) error.value = patch.error;
+}
+
+/** 层序：核心下发的 z 表转成行内 z-index（小程序渲染层就是 WebView，z-index 可用） */
+function layerZ(layer: string): number {
+  return layers.value[layer] ?? 0;
+}
+
+/** 启动宿主：取画布（拿不到就退回定时器帧源），接上数据发布口与尺寸变化监听 */
+async function boot(): Promise<void> {
+  try {
+    const canvas = await queryCanvasNode(CANVAS_SELECTOR);
+    const started = await startMiniprogramHost({ canvas, publish: applyPatch });
+    host = started;
+    stopResizeWatch = watchWindowResize(() => {
+      started.resize();
+    });
+  } catch (cause: unknown) {
+    error.value = String(cause);
+  }
+}
+
+onReady(() => {
+  void boot();
+});
+
+onUnload(() => {
+  stopResizeWatch?.();
+  stopResizeWatch = null;
+  host?.dispose();
+  host = null;
+});
+
+/** 点击舞台或对话层 = 推进（打字中则先补完本句，归覆盖层判据） */
+function onAdvance(): void {
+  host?.overlay.advance();
+}
+
+/** 选择菜单：选项带回核心的列 id */
+function onChoose(target: string): void {
+  if (target !== "") host?.overlay.choose(target);
+}
+
+/** 输入框：值先落在页面状态里，提交时一次性交回核心 */
+function onInput(value: string): void {
+  inputValue.value = value;
+}
+
+/** 提交输入：清空输入框再交回，免得下一句沿用上一句的字 */
+function onSubmitInput(): void {
+  const value = inputValue.value;
+  inputValue.value = "";
+  host?.overlay.submitInput(value);
+}
+
+/** 视频自然播完：交回宿主，由它解除引擎的 video 等待 */
+function onVideoEnded(): void {
+  host?.videoEnded();
+}
+
+/** 打开存读面板：槽位视图从宿主取（槽数来自工程清单），取不到就把原因摆到横幅上 */
+async function openSlots(mode: SlotPanelMode): Promise<void> {
+  const current = host;
+  if (current === null) return;
+  slotMode.value = mode;
+  try {
+    slotViews.value = await loadHostSlotViews({
+      savePort: current.ports.save,
+      slots: current.saves.slots,
+    });
+  } catch (cause: unknown) {
+    error.value = String(cause);
+  }
+}
+
+/** 点槽位：面板先收起（存读结果由引擎发通知，宿主不弹第二层） */
+function onChooseSlot(view: SlotView): void {
+  const current = host;
+  const mode = slotMode.value;
+  slotMode.value = null;
+  if (current === null || mode === null) return;
+  chooseHostSlot({
+    mode,
+    view,
+    save: (slot) => current.saveGame(slot),
+    load: (slot) => current.loadGame(slot),
+  });
+}
+
+/** 收起面板：不动任何叙事状态，玩家可以继续点舞台推进 */
+function closeSlots(): void {
+  slotMode.value = null;
+}
+
+defineOptions({ name: "PageIndex" });
+</script>
+
+<template>
+  <view class="page">
+    <!-- 舞台层：视口 → 舞台盒（按宿主算好的缩放与平移变换）→ 元素层，见 StageView -->
+    <view class="viewport" @tap="onAdvance">
+      <!-- 帧时钟：本宿主的帧源取自这块画布（2d 节点带 requestAnimationFrame） -->
+      <canvas class="frame-clock" type="2d" id="stage-canvas"></canvas>
+      <StageView :stage="stage" :elements="elements" :stage-box="stageBox" />
+    </view>
+
+    <!-- 视频层：声明式组件——起播与换片靠这里的数据，控制动作由宿主的 videoContext 驱动 -->
+    <video
+      v-if="video && video.visible"
+      id="stage-video"
+      class="video"
+      :src="video.url"
+      :autoplay="true"
+      :loop="video.loop"
+      :volume="video.volume"
+      :controls="false"
+      :show-center-play-btn="false"
+      :enable-progress-gesture="false"
+      :style="{ zIndex: layerZ('video') }"
+      @ended="onVideoEnded"
+    />
+
+    <!-- 对话层：普通形态与 NVL 形态，见 DialogueLayer -->
+    <DialogueLayer
+      v-if="dialogue && dialogue.visible"
+      :dialogue="dialogue"
+      :nvl="nvl"
+      :z-index="layerZ('dialogue')"
+      @advance="onAdvance"
+    />
+
+    <!-- 选择层：菜单与输入两形态互斥，见 ChoiceLayer -->
+    <ChoiceLayer
+      v-if="choices"
+      :choices="choices"
+      :input-value="inputValue"
+      :z-index="layerZ('choices')"
+      @choose="onChoose"
+      @input="onInput"
+      @submit="onSubmitInput"
+    />
+
+    <!-- 通知层：贴右上角，不吃点击，见 NoticeLayer -->
+    <NoticeLayer :notices="notices" :z-index="layerZ('notifications')" />
+
+    <!-- 失败横幅：只显示信息，不参与交互 -->
+    <view v-if="error" class="error">{{ error }}</view>
+
+    <!--
+      宿主界面层：存读入口与槽位面板。层序跟通知层同档（都属操作面），
+      容器本身不吃点击，只有入口条与面板本体接手势——舞台推进照常。
+    -->
+    <view class="ui-chrome" :style="{ zIndex: layerZ('notifications') }">
+      <SaveLoadBar
+        :mode="slotMode"
+        :views="slotViews"
+        @open="openSlots"
+        @choose="onChooseSlot"
+        @close="closeSlots"
+      />
+    </view>
+  </view>
+</template>
+
+<style>
+/* 页面壳：小程序的页面根节点默认不撑满，显式给块级尺寸 */
+.page {
+  display: block;
+}
+
+/* 视口：舞台与各层的公共坐标系，铺满窗口且裁掉溢出（舞台按基准尺寸缩放，会超出） */
+.viewport {
+  position: fixed;
+  left: 0;
+  top: 0;
+  width: 100%;
+  height: 100%;
+  overflow: hidden;
+  background: #0a0a10;
+}
+
+/* 帧时钟画布：只用来拿 requestAnimationFrame，不可见也不吃点击 */
+.frame-clock {
+  position: absolute;
+  left: 0;
+  top: 0;
+  width: 100%;
+  height: 100%;
+  pointer-events: none;
+}
+
+/* 视频层：铺满窗口，层序由宿主下发的 z 决定（要压在舞台之上、对话之下） */
+.video {
+  position: fixed;
+  left: 0;
+  top: 0;
+  width: 100%;
+  height: 100%;
+  background: #000;
+}
+
+/* 宿主界面层：容器不吃点击，只有其中的入口与面板接手势（舞台推进不被挡住） */
+.ui-chrome {
+  position: absolute;
+  left: 0;
+  top: 0;
+  width: 100%;
+  pointer-events: none;
+}
+
+/* 失败横幅：压在一切之上，只读 */
+.error {
+  position: fixed;
+  left: 0;
+  right: 0;
+  top: 0;
+  padding: 16rpx 24rpx;
+  background: #8a2233;
+  color: #ffffff;
+  font-size: 24rpx;
+  pointer-events: none;
+  z-index: 9999;
+}
+
+@media (orientation: landscape) {
+  .error {
+    padding: 8px 12px;
+    font-size: 12px;
+  }
+}
+</style>

package/template/overlays/miniprogram/src/pages.json

@@ -0,0 +1,18 @@
+{
+  "pages": [
+    {
+      "path": "pages/index/index",
+      "style": {
+        "navigationStyle": "custom",
+        "backgroundColor": "#0a0a10",
+        "disableScroll": true,
+        "pageOrientation": "auto"
+      }
+    }
+  ],
+  "globalStyle": {
+    "navigationStyle": "custom",
+    "backgroundColor": "#0a0a10",
+    "backgroundTextStyle": "dark"
+  }
+}

package/template/overlays/miniprogram/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "moduleResolution": "bundler",
+    "types": ["vite/client", "@dcloudio/types"],
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src/**/*.ts", "src/**/*.vue", "vite.config.ts"],
+  "exclude": ["src/host/**", "src/styles/**"]
+}

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

@@ -0,0 +1,87 @@
+/**
+ * 构建配置（小程序形态）：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`，生成器才不会把它改写成 `^最新`。
+ *
+ * `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,
+  };
+}
+
+type UniPluginFactory = (options?: VitePluginUniOptions) => Plugin[];
+
+/**
+ * 插件包是 CommonJS 构建：ESM 默认导入在不同加载路径下可能拿到命名空间对象
+ * （`{ runDev, runBuild, default }`）而不是那个工厂，所以两种形态都认。
+ */
+const uni: UniPluginFactory =
+  (uniModule as unknown as { default?: UniPluginFactory }).default ??
+  (uniModule as unknown as UniPluginFactory);
+
+export default defineConfig({
+  // 资源根：与骨架同名同位，H5 形态直接从磁盘取，小程序形态不随包体分发
+  publicDir: "Resources",
+  build: {
+    // 包体不装故事与素材：它们由工程接口与资源端口在运行期取
+    copyPublicDir: false,
+  },
+  server: {
+    // 与骨架同一个端口：两种形态的本地约定一致，切换形态不必改文档与脚本
+    port: 1420,
+    strictPort: true,
+  },
+  plugins: [uni(), storyFontsVirtual()],
+});

package/template/overlays/react/index.html

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>__PROJECT__</title>
+    <!-- 页面外观与层样式：与「页面结构」分开，框架叠加层可复用同一份样式表 -->
+    <link rel="stylesheet" href="/src/styles/stage.css" />
+  </head>
+
+  <body>
+    <!-- React 的挂载点：层结构在 src/App.tsx 里声明，样式仍在 src/styles/stage.css -->
+    <div id="app"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/template/overlays/react/package.patch.json

@@ -0,0 +1,18 @@
+{
+  "dependencies": {
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.3",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vitejs/plugin-react": "^6.1.2"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.node.json"
+  },
+  "create": {
+    "pinned": ["typescript"]
+  }
+}

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

@@ -0,0 +1,32 @@
+/**
+ * 页面结构（React 形态）：与骨架的 index.html 逐层对齐——引擎与适配器不认识它，
+ * 换框架只改这份模板与组合根。所有 id 都是与引擎侧共用的契约，改名必须同步
+ * `src/main.tsx` 里的句柄表与 `src/styles/stage.css`。
+ *
+ * 本组件**不碰引擎**：装配在 `src/main.tsx`（唯一组合根），交互监听由骨架的
+ * `src/host/` 用原生事件绑定——React 在这里只负责把节点渲染出来。
+ */
+export function App() {
+  return (
+    // 舞台根：屏幕震动（shake）施于此；各层 z 由 main.tsx 按 shell.layers 写入
+    <div id="stage-root">
+      <div id="stage"></div>
+      <div id="nvl"></div>
+      <div id="dialogue">
+        <div id="speaker"></div>
+        <div id="text">加载中……</div>
+        <div id="hint"></div>
+      </div>
+      <div id="choices"></div>
+      <div id="notifications"></div>
+      <div id="toolbar">
+        <span>存档</span>
+        <select id="slot"></select>
+        <button id="save">存</button>
+        <button id="load">读</button>
+      </div>
+      <div id="transition"></div>
+      <div id="error"></div>
+    </div>
+  );
+}

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

@@ -0,0 +1,74 @@
+/**
+ * 组合根（React 形态）：装配适配器 → 加载组装工程 → 建引擎 → 挂载展示层。
+ *
+ * 与骨架的差别只有「谁渲染页面结构」：这里先把 `App` 挂到 `#app`，再读节点句柄——
+ * 引擎要的 15 个节点由 `App.tsx` 渲染出来，挂载前 `must` 只会抛。骨架的 `src/host/`
+ * 一行未改：它操作的是 `StageDom` 句柄表，不认识 React。
+ *
+ * 页面的层结构在 `src/App.tsx`，样式在 `src/styles/stage.css`（两者都来自模板骨架，
+ * 本层只替换入口与组合根）。
+ */
+import { createElement, StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { DEFAULT_TEXT_CPS, DEFAULT_TOAST_MS } from "@lingfan-engine/ui";
+import { bootHost, must, reportBootFailure, type StageDom } from "./host";
+import { App } from "./App.tsx";
+
+/**
+ * 工程清单与故事文件：**都在应用资源根 `Resources/` 内**。
+ * 宿主把 `Resources` 作为静态根，故逻辑路径就是 `project.json` / `Stories/**`。
+ * **新增故事文件必须同步此表**（Web 形态按显式清单取文件）。
+ */
+const MANIFEST = "project.json";
+/** 本工程的故事文件表（相对资源根；新增故事必须同步此表） */
+const STORIES = ["Stories/title/title_main.story"];
+
+/** 页面节点句柄表：每个 id 都必须由 `App.tsx` 渲染（缺一个 `must` 当场抛） */
+function readDom(): StageDom {
+  return {
+    root: must("#stage-root"),
+    stage: must("#stage"),
+    dialogue: must("#dialogue"),
+    speaker: must("#speaker"),
+    text: must("#text"),
+    hint: must("#hint"),
+    nvl: must("#nvl"),
+    choices: must("#choices"),
+    notifications: must("#notifications"),
+    toolbar: must("#toolbar"),
+    slot: must<HTMLSelectElement>("#slot"),
+    save: must<HTMLButtonElement>("#save"),
+    load: must<HTMLButtonElement>("#load"),
+    transition: must("#transition"),
+    error: must("#error"),
+  };
+}
+
+/** 挂载页面结构；失败（含节点缺失）写进页面错误条，不留白屏 */
+function mountApp(): StageDom | undefined {
+  try {
+    const container = document.querySelector("#app");
+    if (container === null) throw new Error("宿主缺少节点：#app");
+    // StrictMode 只影响开发期的重复渲染提示，不改变侧建行为：引擎在下面单独启动
+    createRoot(container).render(
+      createElement(StrictMode, null, createElement(App)),
+    );
+    return readDom();
+  } catch (error) {
+    console.error(error);
+    return undefined;
+  }
+}
+
+const dom = mountApp();
+if (dom !== undefined) {
+  void bootHost({
+    dom,
+    manifestFile: MANIFEST,
+    stories: STORIES,
+    defaultCps: DEFAULT_TEXT_CPS,
+    toastDurationMs: DEFAULT_TOAST_MS,
+  }).catch((error: unknown) => {
+    reportBootFailure(dom, error);
+  });
+}

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

@@ -0,0 +1,14 @@
+/// <reference types="vite/client" />
+
+/**
+ * 字体清单的宿主侧声明（脚手架工程自带，与 vite.config 的虚拟模块对应）。
+ */
+declare module "virtual:story-fonts" {
+  /** 字体清单条目：file = 资源文件名，name = 字体名（文件名去扩展名） */
+  export interface StoryFontEntry {
+    file: string;
+    name: string;
+  }
+  /** 构建期扫描 Resources/Fonts 的字体清单（与 stories:build 注册表同源） */
+  export const storyFonts: readonly StoryFontEntry[];
+}

package/template/overlays/react/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "moduleResolution": "bundler",
+    "types": ["vite/client"],
+    "jsx": "react-jsx",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src/**/*.ts", "src/**/*.tsx"]
+}

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

@@ -0,0 +1,67 @@
+/**
+ * Vite 配置（React 形态）：在骨架配置上多一个 React 插件，其余逐项保留。
+ *
+ * 资源根仍是无条件镜像 `Resources`——纯 Web 工程就是「浏览器游戏模式」的交付正例，
+ * 不引入壳侧的开关判定（那属于 Tauri 壳的交付形态，见引擎仓库 `apps/playground`）。
+ */
+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;
+    },
+  };
+}
+
+/** 脚手架工程的 Vite 配置（React 形态） */
+export default defineConfig({
+  // 项目资源根即静态根：故事里的逻辑路径 `Audio/x.mp3` 解析为 `/Audio/x.mp3`，
+  // 开发与打包产物一致，不依赖进程工作目录。资源根之外无隐式查找路径。
+  publicDir: "Resources",
+
+  // 宿主端口与 Tauri 约定一致；换平台壳时只改这里
+  server: { port: 1420, strictPort: true },
+
+  plugins: [react(), storyFontsVirtual()],
+});