@lingfan-engine/create 0.3.3 → 0.3.5

package/template/README.md

@@ -41,49 +41,75 @@ npm create @lingfan-engine my-story
 pnpm create @lingfan-engine my-story
 ```
 
-生成器会问四件事：工程名、框架、故事源形态、壳。当前框架可选「原生（框架无关）」「Vue 3」「React」，
-故事源形态可选「故事文件（`.story`）」与「TypeScript 源（`Stories.src/`）」，
-壳可选「浏览器」「小程序（UniApp）」与「桌面（Tauri 2）」。全部取缺省值（原生 + TypeScript 源 + 浏览器）可以跳过问答：
+生成器会问三件事：工程名、描述、形态。工程名写在命令行里就跳过这一问；描述可以留空，
+填了会同时写进 `package.json` 的 `description` 与 `Resources/project.json` 的 `description`。
 
-```
-npm create @lingfan-engine my-story -- --yes
-```
+形态是一次多选，按编号回答，空格或逗号分隔：
+
+| 编号 | 形态             | 选中后得到什么                                                   |
+| ---- | ---------------- | ---------------------------------------------------------------- |
+| 1    | Vue 3            | 页面结构换成单文件组件，装配与宿主不变                           |
+| 2    | React            | 页面结构换成 JSX 组件，装配与宿主不变                            |
+| 3    | 桌面（Tauri 2）  | 在同一份工程上再加一个桌面壳：存档落到应用数据目录，页面结构不变 |
+| 4    | 小程序（UniApp） | 页面层换成 UniApp Vue 3 单文件组件，宿主装配走小程序端口         |
 
-生成后按提示 `cd my-story && pnpm install && pnpm dev`。骨架自带编译好的故事产物，开箱即跑；
+Vue 3 与 React 互斥（页面结构只能有一个所有者）；小程序自带 Vue 页面层，与 Vue 3、React、
+桌面壳都互斥；桌面壳与 Vue 3 或 React 组合都可以。
+回车全跳过即骨架原生形态：框架无关 + 浏览器。
+
+生成后按提示进目录、装依赖、跑起来。生成器不指定包管理器——它按启动自己的那个（npm / pnpm / yarn / bun）给出命令，用哪个都行。骨架自带编译好的故事产物，开箱即跑；
 改过 `src/Stories.src/` 之后才需要跑一次 `pnpm stories:build`（或在开发时挂 `pnpm stories:watch`）。
+生成器默认不装依赖，想一步到位加 `--install`。
 
-想不开交互问答、直接指定框架与壳：
+脚本里不想应答问答时，用参数跳过：
 
 ```
-npm create @lingfan-engine my-story -- --framework vue --shell browser
-npm create @lingfan-engine my-story -- --framework react --shell browser
-npm create @lingfan-engine my-story -- --shell miniprogram
-npm create @lingfan-engine my-story -- --framework vue --shell tauri
-npm create @lingfan-engine my-story -- --sources story
+npm create @lingfan-engine my-story --description "试菜单的小工程" --framework vue --shell tauri
+npm create @lingfan-engine my-story --yes
 ```
 
+`--framework` 取 `none` / `vue` / `react`，`--shell` 取 `browser` / `tauri` / `miniprogram`。
+`--sources` 取 `ts` / `story`：`story` 额外附一份手写 `.story` 示例，不改变骨架里 TS 创作链的去留。
+`--template 框架[-壳[-故事源]]` 是等价写法，例如 `--template vue-tauri`；形态选择以问答为准，这个参数留给既有脚本。
+（npm 会先解析自己的同名开关，用 npm 时要在选项前加 `--`，如 `npm create @lingfan-engine my-story -- --yes`。）
+目标目录非空时生成器会问怎么处置（保留现有文件 / 清空 / 取消），`--overwrite` 是「清空」的非交互写法。
+
 **框架层只换页面结构与入口，`src/host/**`（装配、订阅、帧循环、输入映射）一行不改，
 样式表仍是同一份 `src/styles/stage.css`**，所以换框架不影响游玩界面的外观口径，
 也不影响引擎与适配器——它们不认识任何 UI 框架。选 Vue 3 是 `index.html` 换成挂载点、
 加 `src/App.vue` 与 Vue 版组合根；选 React 是同一套做法换成 `src/App.tsx` 与 React 版组合根，
 外加 `tsconfig.json` 的 `jsx: react-jsx`。
 
-壳层与框架层可以叠加（先框架后壳）：`--framework react --shell tauri` 得到 React 页面 + 桌面外壳。
-小程序是例外——它自带 Vue 页面层，不与其他框架层叠加。
+**壳层分两种**：桌面壳只补一层桌面外壳，页面结构与宿主原样保留，所以能叠在 Vue 3 或 React 之上；
+小程序壳换掉整套页面与宿主，自带 Vue 页面层，因此不与其他框架层叠加。
+
+**故事怎么写与形态那一问无关**：三种创作形态落在同一棵 `Resources/Stories/` 树上，构建期一起被扫描，
+可以混装在一个工程里，谁也不排斥谁——
+
+| 创作形态      | 写在哪                         | 改完怎么生效                                        |
+| ------------- | ------------------------------ | --------------------------------------------------- |
+| TS 源         | `src/Stories.src/**/*.ts`      | 跑 `pnpm stories:build`（开发时挂 `stories:watch`） |
+| 手写 `.story` | `Resources/Stories/**/*.story` | 直接改文本，保存即生效                              |
+| 手写 `.json`  | `Resources/Stories/**/*.json`  | 直接改 JSON，保存即生效                             |
+
+**TS 源**那一条链骨架自带：改 `src/Stories.src/**/*.ts`，跑 `pnpm stories:build` 编译成
+`Resources/Stories/**/*.json`；类型检查走独立的 `tsconfig.stories.json`（故事源有 ambient 全局，
+不该和页面 DOM 类型面混在一个工程里）。骨架自带三条脚本（`stories:build` / `stories:watch` /
+`stories-typecheck`）与开箱可跑的产物，`pnpm dev` 不必先构建。
+
+**手写示例**由 `--sources story` 额外交付：`overlays/story/` 只往工程里加一份
+`Resources/Stories/manual/manual_intro.story`（列 id 全在 `manual_` 命名空间，与骨架自带的两列不撞名），
+不删任何骨架文件，TS 创作链原样保留。想改就改那份 `.story`，想回 TS 就往 `src/Stories.src/` 加列，两边互不影响。
 
-**故事源形态层与框架层、壳层正交**，只决定故事从哪来。缺省形态是 **TypeScript 源**，整条链在骨架里：
-改 `src/Stories.src/**/*.ts`，跑 `pnpm stories:build` 编译成 `Resources/Stories/**/*.json`。产物目录由构建
-**全量管理**——源里没有的列构建会当陈旧列删掉，所以别在产物目录里手改；类型检查走独立的
-`tsconfig.stories.json`（故事源有 ambient 全局，不该和页面 DOM 类型面混在一个工程里）。骨架自带三条脚本
-（`stories:build` / `stories:watch` / `stories-typecheck`）与开箱可跑的产物，`pnpm dev` 不必先构建。
+三条注意：
 
-选「故事文件（`.story`）」则是**反向叠加**：`overlays/story/` 用 `create.remove` 摘掉骨架的整条 TS 创作链
-（`src/Stories.src`、`src/gen/*.gen.d.ts`、`tsconfig.stories.json`），换上一份手写的
-`Resources/Stories/title/title_main.story`，改完保存即生效。这条形态的产物目录里可以 `.story` 与 `.json` 混存。
+- 列 `id` 全工程唯一：不同文件里的列只要 id 不撞就能共存，撞了构建会报出冲突的两个来源。
+- 产物目录 `Resources/Stories/**` 里由构建写出的 `.json` 由构建自己维护：它只清理上一轮写过、这一轮不再产出的文件，
+  手写的 `.story` 与 `.json` 它不碰。改 TS 源比改它生成的 `.json` 可靠。
+- `type=ui` 的列不进历史、不进存档、不建检查点——它是界面，不是剧情。
 
-**壳层是换一整套页面与宿主**：小程序形态的页面结构由 `src/components/**` 承接，宿主装配在
+**小程序壳换的是一整套页面与宿主**：小程序形态的页面结构由 `src/components/**` 承接，宿主装配在
 `src/mp/**`（`uni.*` 只在 `src/mp/platform.ts` 出现一处），内容不进包体、走工程接口按基址取。
-因此它是壳而不是框架，与 `--framework` 不叠加：小程序已自带 Vue 页面层，框架取缺省值即可。
 它的 `vite` 与 `vue` 是一组钉住的版本（UniApp 插件对这些版本有硬约束），由
 `package.patch.json` 的 `create.pinned` 保住，不会被改写成「跟最新」。
 
@@ -98,8 +124,8 @@ npm create @lingfan-engine my-story -- --sources story
 模板依赖三个引擎包：`@lingfan-engine/core`（核心）、`@lingfan-engine/adapters`（预设适配器）、`@lingfan-engine/ui`（参考展示层）。
 它们以 **TS 源码出口**（`exports: "./src/index.ts"`）发布——消费方由 Vite/TS 直接编译，**无中间构建步骤**，
 `pnpm install` 直接可用。骨架还声明两个创作期依赖（`@lingfan-engine/stories-build` 与
-`@lingfan-engine/editor`）——缺省故事源形态是 TS，这条链归骨架；选「故事文件」形态时
-`overlays/story/` 会把链上的文件、脚本与依赖条目一并摘掉（见下文叠加层说明）。
+`@lingfan-engine/editor`）——TS 创作链归骨架，任何形态的生成结果都带着它；
+`--sources story` 只是额外多一份手写示例，这两条依赖照旧保留。
 
 ## 工程结构（单资源根）
 
@@ -127,7 +153,7 @@ __PROJECT__/
 ├── src/styles/stage.css  # 页面与层样式（换框架不动这份：叠加层共用同一张表）
 └── Resources/            # 故事工程根（自包含、可整体搬运）
     ├── project.json      #   工程清单：id/name/entry/lang/formatVersion
-    ├── Stories/          #   故事产物（构建全量管理；故事文件形态下可 .story 与 .json 混存）
+    ├── Stories/          #   故事（构建写的 .json 与手写的 .story/.json 可混存）
     ├── Audio/  Images/  Video/
     ├── Lang/{lang}/      #   I18N overlay
     └── Saves/            #   运行期产物（不入 git）
@@ -179,11 +205,12 @@ pwsh -File pack-template.ps1 -SourceDir ./__PROJECT__ -OutputFile ./__PROJECT__.
 
 ## 叠加层与占位符
 
-`template-meta.json` 的 `frameworks` / `sources` / `shells` 声明生成器会问哪些选项，每项的 `id` 对应
+`template-meta.json` 的 `frameworks` / `sources` / `shells` 声明模板有哪些层，每项的 `id` 对应
 `overlays/<id>/` 目录：同路径文件**覆盖**骨架，根目录的 `*.patch.json` **深合并**进 `package.json`，
-其中 `create.remove` 列出本层要删掉的骨架路径（换形态时清残留）。缺省项（`none` / `ts` / `browser`）
-没有目录，表示「这一层什么都不加」，不是错误——缺省故事源 `ts` 正是如此：整条创作链在骨架里，
-没有叠加层可加。`story` 反过来是「摘掉骨架的 TS 链、换上手写故事」，所以它有目录。合并顺序固定为「骨架 → 框架 → 故事源 → 壳」：
+其中 `create.remove` 列出本层要删掉的骨架路径（换形态时清残留）。`frameworks` / `shells` 决定生成器会问哪些选项；
+`sources` 不参与形态问答——TS 源、手写 `.story`、手写 `.json` 在同一棵树上共存，它只表示要不要额外附一份手写示例。
+缺省项（`none` / `ts` / `browser`）没有目录，表示「这一层什么都不加」，不是错误——缺省故事源 `ts` 正是如此：
+整条创作链在骨架里，没有叠加层可加。`story` 有目录，但只为多放一份示例文件，不删骨架的任何东西。合并顺序固定为「骨架 → 框架 → 故事源 → 壳」：
 故事源要晚于框架层才能把各框架入口的故事表指向生成物；壳放最后，因为它对工程形态有最终发言权。
 
 骨架里的占位符有两种大小写形态：`__PROJECT__`（清单 id/name、页面标题、目录名）与

package/template/__PROJECT__/gitignore

@@ -1,5 +1,7 @@
 # 运行期产物不进版本库（存档由 Rust 安全层落盘）
 Resources/Saves/
+# 构建产物账：记录上一轮生成的产物清单，用于只清理自己生成过的陈旧文件
+.lingfan/
 node_modules/
 dist/
 target/

package/template/__PROJECT__/package.json

@@ -17,7 +17,8 @@
     "@lingfan-engine/core": "^0.3.2",
     "@lingfan-engine/shell": "^0.3.2",
     "@lingfan-engine/stories-build": "^0.3.2",
-    "@lingfan-engine/ui": "^0.3.2"
+    "@lingfan-engine/ui": "^0.3.2",
+    "@tauri-apps/api": "^2"
   },
   "devDependencies": {
     "@lingfan-engine/editor": "^0.3.2",

package/template/__PROJECT__/package.patch.json

@@ -0,0 +1,5 @@
+{
+  "create": {
+    "pinned": ["typescript"]
+  }
+}

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

@@ -39,6 +39,7 @@ export {
   type NativeUiTable,
 } from "./mount/index";
 export { wireEngine, type HostWiringOptions } from "./engine-wiring";
+export { createNativePorts, isTauriHosted } from "./native-ports";
 export { startHostFrameLoop, type HostFrameLoopOptions } from "./frame-loop";
 export { wireInput, type HostInputOptions } from "./input-map";
 export {

package/template/__PROJECT__/src/host/native-ports.ts

@@ -0,0 +1,56 @@
+/**
+ * 原生宿主端口：让同一份工程既能跑在浏览器里，也能被桌面壳加载。
+ *
+ * 为什么判定放在这里而不是壳层：`tauri` 叠加层只补 `src-tauri/` 与清单补丁，
+ * 页面结构与组合根永远归属框架层。若壳层自己带一份组合根，`vue`/`react` 形态的
+ * 页面节点就不再与那份组合根同源。所以「是否需要原生端口」由运行时事实判定，
+ * 各形态的组合根都调同一个函数。
+ *
+ * 为什么用运行时判定：`tauri dev` 时页面可能被外部浏览器打开，构建期开关会判错。
+ * `__TAURI_INTERNALS__` 只由真实 WebView 注入，是此刻唯一可靠的事实。
+ *
+ * 为什么模块名写在这里：打包器按字面量说明符静态解析（所以本工程必须声明
+ * `@tauri-apps/api`），而适配器包不出现该模块名，浏览器与小程序形态才能在
+ * 没有它时也装得上。非壳形态直接返回 `undefined`，动态导入一次都不会发生。
+ */
+import {
+  createTauriSavePort,
+  type TauriInvoke,
+} from "@lingfan-engine/adapters";
+import type { BootPortOverrides } from "./boot";
+
+/** 当前页面是否由桌面壳加载（只有真实 WebView 会注入 `__TAURI_INTERNALS__`） */
+export function isTauriHosted(): boolean {
+  return typeof window !== "undefined" && "__TAURI_INTERNALS__" in window;
+}
+
+/**
+ * 惰性 invoke：首次真正调用存档命令时才装载 `@tauri-apps/api/core`。
+ *
+ * 不在启动路径上 await 是刻意的——存档端口是同步构造的，而装载要等模块解析；
+ * 把等待推迟到第一次读写，启动时序与浏览器形态完全一致。装载失败会原样抛给
+ * 调用方，由存档流程的既有错误处理呈现，不会变成静默失败。
+ */
+function createLazyInvoke(): TauriInvoke {
+  let loading: Promise<TauriInvoke> | undefined;
+  return async (command, args) => {
+    loading ??= import("@tauri-apps/api/core").then((module) => {
+      const loaded: TauriInvoke = (name, payload) =>
+        module.invoke(name, payload);
+      return loaded;
+    });
+    const invoke = await loading;
+    return invoke(command, args);
+  };
+}
+
+/**
+ * 按运行时事实给出端口覆盖；非桌面壳形态返回 `undefined`。
+ *
+ * 现在只换存档（`localStorage` 落在 WebView 数据目录，清缓存、换账户、重装都会
+ * 带走存档）。其余端口沿用 `bootHost` 的 Web 缺省实现，随需要再加。
+ */
+export function createNativePorts(): BootPortOverrides | undefined {
+  if (!isTauriHosted()) return undefined;
+  return { saves: createTauriSavePort(createLazyInvoke()) };
+}

package/template/__PROJECT__/src/main.ts

@@ -3,8 +3,8 @@
  *
  * 本宿主**不依赖任何 UI 框架**——这是「引擎框架无关」的活证明：渲染直接操作 DOM，
  * 换成 Vue / React / 其他只改本文件与 index.html，引擎与适配器零改动。
- * 形态：**纯 Web**（vite 静态根 `Resources/`）——Tauri 壳的装配（invoke / 资源加密 /
- * 方向锁定 / 宿主信息 / 热重载）见引擎仓库 `apps/playground` 的组合根。
+ * 页面结构与这里的节点解析始终成对：桌面壳只补 `src-tauri/`，不自带组合根，
+ * 故 `-f` 选什么框架都不影响「`must` 与 index.html 同源」这条前提。
  *
  * 本文件只做三件事，实现都在 `host/` 里：
  *   1. 解析页面节点（`must` 调用点集中在此，与 index.html 的 id 互锁一眼可见）；
@@ -23,6 +23,7 @@ import { MANIFEST_FILE } from "@lingfan-engine/core";
 import { DEFAULT_TEXT_CPS, DEFAULT_TOAST_MS } from "@lingfan-engine/ui";
 import {
   bootHost,
+  createNativePorts,
   must,
   optional,
   reportBootFailure,
@@ -69,6 +70,8 @@ void bootHost({
   stories: STORIES,
   defaultCps: DEFAULT_TEXT_CPS,
   toastDurationMs: DEFAULT_TOAST_MS,
+  // 桌面壳里换成原生存档端口；浏览器里返回 undefined，端口走 Web 缺省实现
+  ports: createNativePorts(),
   // 偏好面板槽位：页面给了就装（`optional` 已消化「这层不给」的情况）
   prefsContainer: dom.prefs,
   // 历史面板槽位：给了就有「历史」按钮与回溯（点一条即回到那个检查点）

package/template/overlays/README.md

@@ -3,6 +3,8 @@
 每个子目录是一层可选的工程内容，目录名就是 `template-meta.json` 里 `frameworks[]` / `sources[]` / `shells[]` 的 `id`。
 生成器按「骨架 → 框架层 → 故事源层 → 壳层」的顺序合并，同路径文件由后一层覆盖前一层。
 故事源层的两个 id 不对称：缺省 `ts` 没有目录（链在骨架里），可选 `story` 有目录（要摘掉那条链）。
+有些层不能共存，这一层与谁相斥写在 `template-meta.json` 的 `excludes` 里；生成器据此推导合法形态，
+不维护白名单。
 
 ## 缺省项没有目录
 
@@ -96,6 +98,10 @@
 1. 在 `template-meta.json` 的 `frameworks`、`sources` 或 `shells` 里加一项 `{ id, label, hint }`。
 2. 建同名目录，放入该层独有的文件与 `package.patch.json`。
 3. 生成器不改：它对目录是缺席即跳过，不需要为新 `id` 写分支。
+4. 这一层与别的层不能共存时，用 `excludes` 声明：写上对方层的 id，可以跨维度（框架排斥壳、
+   壳排斥框架都行）。只写单边就生效，但建议两边都写，读的人一眼能看清这对互斥。
+   尤其当这一层也要写 `src/main.*` 或 `src/App.*` 时——页面结构只能有一个所有者，
+   必须靠 `excludes` 明确谁赢，不能让合并顺序替你做这个决定。
 
 一层只加自己真正需要的东西。能被骨架覆盖的差异（比如只换一个入口文件的 import）优先留在骨架里，
 叠加层越多，同一处逻辑就有越多份副本要跟着改。

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

@@ -15,6 +15,7 @@ import { MANIFEST_FILE } from "@lingfan-engine/core";
 import { DEFAULT_TEXT_CPS, DEFAULT_TOAST_MS } from "@lingfan-engine/ui";
 import {
   bootHost,
+  createNativePorts,
   must,
   optional,
   reportBootFailure,
@@ -92,6 +93,8 @@ if (dom !== undefined) {
     stories: STORIES,
     defaultCps: DEFAULT_TEXT_CPS,
     toastDurationMs: DEFAULT_TOAST_MS,
+    // 桌面壳里换成原生存档端口；浏览器里返回 undefined，端口走 Web 缺省实现
+    ports: createNativePorts(),
     historyContainer: dom.history,
     prefsContainer: dom.prefs,
     // UI 挂载落法由 React 接管：`#mounts` 的子节点归 `UiHost` 渲染，

package/template/overlays/story/Resources/Stories/{title/title_main.story → manual/manual_intro.story}

@@ -1,29 +1,34 @@
-// __PROJECT__ 示例工程（文本形态 = JSON v1 的投影）
+// __PROJECT__ 的手写故事示例（文本形态 = JSON v1 的投影）
 // 资源路径相对项目资源根 Resources/：如 bgm "Audio/main.mp3"
 // 一个文件里可以写多列（label / scene）；拆文件直接放进 Resources/Stories/ 下，构建期扫描自动收录。
+//
+// 这份示例与骨架自带的 `Stories/title/*.json` 并存：TS 源、手写 .story、手写 .json
+// 是同一棵树上的三种文件形态，可以混装。列 id 全在 `manual_` 命名空间里，
+// 因此不会与骨架已有的 `title_main` / `look_around` 撞名（列 id 全工程唯一）。
+// 想从这里接着写，改本文件即可；要切回 TS 源，往 src/Stories.src 里加列即可，两边互不影响。
 
 // 标题界面：`type=ui` 的列不进历史、不进存档、不建检查点——它是界面，不是剧情。
 // 引擎对这类列只管一件事：按 op 渲染（say 出一句、menu 出一组选项），所以下面几条开箱即跑，
 // 视图上就是标题界面本身。想换成自己的视觉有两条路：常驻舞台的组件放 src/ui/ 并用 mount 控显隐；
 // 整屏的标题页/设置页属宿主应用，落 src/pages/ 一类宿主目录、由宿主自己切进切出。
-scene title_main type=ui
-  say "欢迎来到 __PROJECT__。"
-  say "在 Resources/Stories/ 下继续写你的故事；媒体放 Resources/Audio、Resources/Images、Resources/Video。"
+scene manual_intro type=ui
+  say "这一段来自 Resources/Stories/manual/manual_intro.story。"
+  say "文本故事、手写 JSON、TS 源可以同时在 Resources/Stories/ 下混装；列 id 全工程唯一即可。"
   menu "接下来去哪里？"
-    "开始游戏" -> chapter1
-    "看舞台元素" -> stage_demo
+    "看对话与输入" -> manual_talk
+    "看舞台元素" -> manual_stage
 
 // 游戏正文第一列：进入这里才开始有历史与存档。
-scene chapter1
+scene manual_talk
   input "先问一句：你叫什么名字？" store="player.name"
   say "你好，{player.name}！"
   say "这一列是 game 列：从这里开始，每一步都可回溯、可存档。"
   menu "接下来去哪里？"
-    "看舞台元素" -> stage_demo
-    "回标题界面" -> title_main
+    "看舞台元素" -> manual_stage
+    "回这一列开头" -> manual_talk
 
 // scene 列 = 声明式空间层：进入本列时整体装载，切换列时清空
-scene stage_demo
+scene manual_stage
   panel x=5% y=10% width=90% zindex=10
     text "scene 列 = 声明式空间层：这些方块是元素，不是对话"
     text "panel 是容器，子元素用更深缩进写"

package/template/overlays/story/package.patch.json

@@ -1,17 +1 @@
-{
-  "create": {
-    "remove": [
-      "Resources/Stories",
-      "src/Stories.src",
-      "src/gen/font.gen.d.ts",
-      "src/gen/script.gen.d.ts",
-      "src/gen/state.gen.d.ts",
-      "src/gen/stories.gen.d.ts",
-      "tsconfig.stories.json"
-    ],
-    "unset": {
-      "scripts": ["stories:build", "stories:watch", "stories-typecheck"],
-      "devDependencies": ["@lingfan-engine/editor"]
-    }
-  }
-}
+{}

package/template/overlays/tauri/README.md

@@ -1,15 +1,15 @@
 # 桌面壳层（Tauri 2）
 
 这一层是**壳**，不是框架层：页面结构沿用骨架那一份，`index.html` 与 `vite.config.ts` 原样保留。
-加进来的只有工程根下的 `src-tauri/`、一份清单补丁，以及本层自己的组合根 `src/main.ts`——
-它覆盖骨架的同名文件，只把存档端口换成 Rust 实现。
+加进来的只有工程根下的 `src-tauri/` 和一份清单补丁——**不带组合根**：入口与页面结构
+永远归属框架层，否则 `-f vue` / `-f react` 时壳层的节点解析会与框架层渲染的页面错配。
+桥的装配在骨架 `src/host/native-ports.ts`，由各形态的组合根统一调用。
 
 ## 内容
 
 - `src-tauri/Cargo.toml`、`build.rs`、`tauri.conf.json`、`capabilities/default.json`
 - `src-tauri/src/`：`main.rs`（转发到库入口）、`lib.rs`（装配与命令注册）、`save.rs`、`preferences.rs`
-- `src/main.ts`：覆盖骨架的组合根，`ports.saves` 换成 `createTauriSavePort()`
-- `package.patch.json`：补 `@tauri-apps/api`（运行时）与 `@tauri-apps/cli`（命令行），加 `tauri` 脚本
+- `package.patch.json`：补 `@tauri-apps/cli`（命令行）与 `tauri` 脚本
 
 窗口 1280×720，标题取工程名；`frontendDist` 指向 `../dist`，开发期 `devUrl` 指向
 `http://localhost:1420`（与骨架 `vite.config.ts` 的 `server.port` 一致），所以 `beforeDevCommand`
@@ -45,7 +45,8 @@
 
 资源加密、媒体 HTTP 服务、zip 索引、工程写回、开发期 WS——这些在参考宿主里有实现，
 本层不带。要加密或媒体服务的工程自己加：能力以端口 + 适配器成对出现，
-壳层只负责把端口接到原生侧（插口是骨架的 `src/ports.ts` 与 `bootHost` 的 `ports` 选项）。
+壳层只负责把端口接到原生侧（插口是 `bootHost` 的 `ports` 选项，
+现有的原生存档端口见骨架 `src/host/native-ports.ts`）。
 
 ## 怎么用
 

package/template/overlays/tauri/package.patch.json

@@ -2,13 +2,10 @@
   "scripts": {
     "tauri": "tauri"
   },
-  "dependencies": {
-    "@tauri-apps/api": "^2"
-  },
   "devDependencies": {
     "@tauri-apps/cli": "^2"
   },
   "create": {
-    "pinned": ["@tauri-apps/cli", "@tauri-apps/api"]
+    "pinned": ["@tauri-apps/cli"]
   }
 }

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

@@ -13,6 +13,7 @@ import { MANIFEST_FILE } from "@lingfan-engine/core";
 import { DEFAULT_TEXT_CPS, DEFAULT_TOAST_MS } from "@lingfan-engine/ui";
 import {
   bootHost,
+  createNativePorts,
   must,
   optional,
   reportBootFailure,
@@ -76,6 +77,8 @@ if (dom !== undefined) {
     stories: STORIES,
     defaultCps: DEFAULT_TEXT_CPS,
     toastDurationMs: DEFAULT_TOAST_MS,
+    // 桌面壳里换成原生存档端口；浏览器里返回 undefined，端口走 Web 缺省实现
+    ports: createNativePorts(),
     prefsContainer: dom.prefs,
     // 历史面板槽位：给了就有「历史」按钮与回溯
     historyContainer: dom.history,

package/template/template-meta.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.9.0",
+  "version": "1.12.0",
   "minEngineVersion": "0.3.2",
   "placeholder": "__PROJECT__",
   "frameworks": [
@@ -11,12 +11,14 @@
     {
       "id": "vue",
       "label": "Vue 3",
-      "hint": "页面结构换成单文件组件，装配与宿主不变"
+      "hint": "页面结构换成单文件组件，装配与宿主不变",
+      "excludes": ["react", "miniprogram"]
     },
     {
       "id": "react",
       "label": "React",
-      "hint": "页面结构换成 JSX 组件，装配与宿主不变"
+      "hint": "页面结构换成 JSX 组件，装配与宿主不变",
+      "excludes": ["vue", "miniprogram"]
     }
   ],
   "shells": [
@@ -25,15 +27,17 @@
       "label": "浏览器",
       "hint": "只生成 Web 端工程，用 vite 起本地服务"
     },
-    {
-      "id": "miniprogram",
-      "label": "小程序（UniApp）",
-      "hint": "页面层换成 UniApp Vue 3 单文件组件，宿主装配走小程序端口"
-    },
     {
       "id": "tauri",
       "label": "桌面（Tauri 2）",
-      "hint": "给浏览器形态再加一个桌面壳：存档落到应用数据目录，其余不变"
+      "hint": "给同一份工程再加一个桌面壳：存档落到应用数据目录，页面结构不变",
+      "excludes": ["miniprogram"]
+    },
+    {
+      "id": "miniprogram",
+      "label": "小程序（UniApp）",
+      "hint": "页面层换成 UniApp Vue 3 单文件组件，宿主装配走小程序端口",
+      "excludes": ["vue", "react", "tauri"]
     }
   ],
   "sources": [
@@ -44,9 +48,9 @@
     },
     {
       "id": "story",
-      "label": "故事文件（.story）",
-      "hint": "直接写引擎自带的文本故事格式：叠在骨架上，摘掉 TS 创作链，改完保存即生效"
+      "label": "附带手写故事示例",
+      "hint": "多放一份 .story 示例，与 TS 源共存，不摘任何东西"
     }
   ],
-  "_comment": "模板版本唯一来源，独立于引擎版本：仅当 template/v1 内容真正变化时才手动 bump。placeholder 是目录/文件内的工程名占位符，生成时整体替换为工程名（对齐 _LingFanEngineTemplateTitle_ 占位符语义）。minEngineVersion 表示此模板要求的最低引擎版本——生成期会拿它跟 registry 上的实际版本比对，不达标即失败（离线查不到版本时跳过判定）。frameworks / shells / sources 决定生成器会问什么、能叠哪些层，各自首项为缺省值；每一项的 id 对应 template/v1/overlays/<id> 目录（缺省层可以没有目录——缺省故事源 `ts` 就是这样：整条创作链在骨架里，不需要叠加层）。合并顺序为「骨架 → 框架 → 故事源 → 壳」，同路径文件由后一层覆盖前一层。"
+  "_comment": "模板版本唯一来源，独立于引擎版本：仅当 template/v1 内容真正变化时才手动 bump。placeholder 是目录/文件内的工程名占位符，生成时整体替换为工程名（对齐 _LingFanEngineTemplateTitle_ 占位符语义）。minEngineVersion 表示此模板要求的最低引擎版本——生成期会拿它跟 registry 上的实际版本比对，不达标即失败（离线查不到版本时跳过判定）。frameworks / shells 决定生成器会问什么、能叠哪些层，各自首项为缺省值；每一项的 id 对应 template/v1/overlays/<id> 目录（缺省层可以没有目录——缺省的 none 与 browser 就是这样，不需要叠加层）。sources 不参与形态问答：TS 源、手写 .story、手写 .json 是同一棵 Resources/Stories/ 树上的三种文件形态，可以共存于一个工程，所以 story 层的目录只额外附一份手写示例、不摘任何骨架文件；缺省故事源 ts 同样没有目录。合并顺序为「骨架 → 框架 → 故事源 → 壳」，同路径文件由后一层覆盖前一层。excludes 声明该层与哪些层不能共存，元素是层 id、可以跨维度引用，生成器据此推导合法形态；只写单边即可生效，但成对声明能让读的人一眼看清——所以每一对互斥都在两边都写了。页面结构只能有一个所有者：两层都要写 src/main.* 或 src/App.* 时，必须在其中一方 excludes 里声明互斥，不得靠合并顺序决定谁活下来。"
 }

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

@@ -1,101 +0,0 @@
-/**
- * 组合根（桌面壳形态）：与骨架只差两处——先装宿主桥，再把存档端口换成 Rust 实现。
- *
- * 为什么先装桥：`@lingfan-engine/adapters` 是给外部工程消费的源码包，包内不写
- * `@tauri-apps/api` 的模块名（写了会让纯 Web 形态在构建期解析失败，写成变量说明符又会在
- * 产物里残留裸模块名、WebView 执行时抛错）。模块名留在本文件这一层——本工程有这个依赖，
- * 且只在壳里跑到这里；`installTauriBridge` 把两个函数交给适配器，之后各端口工厂的
- * 缺省实现才可用。
- *
- * 为什么换存档：WebView 的 `localStorage` 落在系统给这个应用分配的 WebView 数据目录里，
- * 清缓存、换系统账户、重装都会带走存档；桌面工程的存档应当是可指路径上的文件。
- * 换法是把端口交给 `bootHost` 的 `ports.saves`，装配顺序与其余接线一行不改。
- *
- * 工程文件与资源**不换**：骨架的 `vite.config.ts` 把 `Resources/` 当静态根，
- * 打包时这些文件被复制进 `dist/`，所以打包后 `/project.json`、`/Stories/**`、
- * `/Audio/x.mp3` 仍按同一套路径取得到——桌面壳不需要为此多造一组 Rust 命令。
- *
- * 页面结构沿用骨架的 `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,
-  optional,
-  reportBootFailure,
-  type StageDom,
-} from "./host";
-import { STORIES } from "./stories";
-import { uis } from "./mounts";
-
-/**
- * 工程清单与故事文件：**都在应用资源根 `Resources/` 内**。
- * 打包后它们位于 `dist/` 顶层，路径与开发期一致。
- * 清单名取引擎契约里的 `MANIFEST_FILE`（组装、写回、定位资源根共用同一个声明）；
- * 故事表在 `./stories`（唯一出口，各形态共用），内容由构建期扫描资源根得出。
- */
-
-/** 页面节点句柄表：每个 id 都必须存在于 index.html（缺一个 `must` 当场抛） */
-const dom: StageDom = {
-  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"),
-  // 历史面板槽位（可选）：骨架 index.html 里有，缺了也不影响启动
-  history: optional("#history"),
-  // 偏好面板槽位（可选）：骨架 index.html 里有，缺了也不影响启动
-  prefs: optional("#prefs"),
-  // UI 挂载层槽位（可选）：本层不给就 null，`mount` 命令只改状态、没有组件出现
-  mounts: optional("#mounts"),
-};
-
-/**
- * 装配宿主桥并启动宿主。
- *
- * 静态说明符（不带 `@vite-ignore`）是刻意的：打包器据此把这两个模块打进产物，
- * 运行期不再需要解析裸模块名。
- */
-async function boot(): Promise<void> {
-  const [{ invoke }, { listen }] = await Promise.all([
-    import("@tauri-apps/api/core"),
-    import("@tauri-apps/api/event"),
-  ]);
-  installTauriBridge({ invoke, listen });
-
-  await bootHost({
-    dom,
-    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(),
-    },
-  });
-}
-
-boot().catch((error: unknown) => {
-  reportBootFailure(dom, error);
-});