@lingfan-engine/create 0.3.2 → 0.3.4

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/ts → __PROJECT__}/tsconfig.stories.json

@@ -21,5 +21,8 @@
     "noUnusedParameters": true,
     "noFallthroughCasesInSwitch": true
   },
-  "include": ["src/Stories.src/**/*.ts"]
+  /* 两份都要进本工程：故事源 + 生成物类型面（state / script / font / stories 四份
+     gen 声明）。它们是 ambient 全局，不进程序就等于不存在——章节里裸写
+     script.bgm / state.player 会报未定义。 */
+  "include": ["src/Stories.src/**/*.ts", "src/gen/**/*.ts"]
 }

package/template/overlays/README.md

@@ -2,25 +2,24 @@
 
 每个子目录是一层可选的工程内容，目录名就是 `template-meta.json` 里 `frameworks[]` / `sources[]` / `shells[]` 的 `id`。
 生成器按「骨架 → 框架层 → 故事源层 → 壳层」的顺序合并，同路径文件由后一层覆盖前一层。
+故事源层的两个 id 不对称：缺省 `ts` 没有目录（链在骨架里），可选 `story` 有目录（要摘掉那条链）。
 
 ## 缺省项没有目录
 
-`none`（框架无关）、`story`（故事文件）与 `browser`（浏览器）表示「这一层什么都不加」，所以这里看不到它们。
-缺目录不是错误，只是没有内容可叠。
+`none`（框架无关）、`ts`（TypeScript 源）与 `browser`（浏览器）表示「这一层什么都不加」，所以这里看不到它们。
+缺目录不是错误，只是没有内容可叠：缺省故事源形态的整条创作链（`src/Stories.src/`、`src/gen/*.gen.d.ts`、
+`tsconfig.stories.json`、三条 `stories:*` 脚本）都在骨架里，生成时不需要再叠任何东西。
 
 ## 现有层
 
-- `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`。
+- `story/` —— 故事源层，与缺省形态反向：只换故事素材、不碰页面。骨架缺省是 TS 创作链，这一层用
+  `create.remove` 把它整条摘掉（`src/Stories.src`、`src/gen/{font,script,state,stories}.gen.d.ts`、
+  `tsconfig.stories.json`），换上一份手写的 `Resources/Stories/title/title_main.story`，改完保存即生效。
+  `create.remove` 只认精确路径与目录子树，没有通配符，所以四份 `.gen.d.ts` 要逐个点名。
+  骨架那三条 `stories:*` 脚本与 `@lingfan-engine/editor` 依赖由 `create.unset` 一并摘掉
+  （`mergeManifest` 对依赖表是「新增或覆盖」，删键要靠 `unset` 显式点名）。
+  故事清单不归本层管：骨架的 `vite.plugins.ts` 扫 `Resources/Stories/`，`.story` 与 `.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/**` 一行不改，
@@ -69,11 +68,26 @@
   数组与标量整体取代——数组拼接会得到既非骨架也非叠加层的第三种值。
 - `create.remove`（写在同一份 `package.patch.json` 里）：字符串数组，点在它之前各层里的路径
   （文件或目录，目录写不带尾斜杠也行），本层写入前先删掉它们。用来清掉换形态后不再需要的骨架文件。
+- `create.unset`（写在同一份 `package.patch.json` 里）：对象，外层是 `package.json` 的字段名
+  （`scripts`、`devDependencies` 等），内层是要去掉的键名数组。`create.remove` 只能删文件，
+  清单里的键要靠它——比如反向叠加层摘掉 TS 创作链之后，配套的 `stories:*` 命令与创作期依赖
+  也应当一起消失，否则产物里留着一个指向已删除目录、必然失败的命令。
 
 ```json
 { "create": { "remove": ["src/host", "src/styles"] } }
 ```
 
+```json
+{
+  "create": {
+    "unset": {
+      "scripts": ["stories:build"],
+      "devDependencies": ["@lingfan-engine/editor"]
+    }
+  }
+}
+```
+
 新增依赖只写进 `package.patch.json`，不要复制整份 `package.json`：整份复制会让骨架后来加的字段
 在这一层永久丢失。生成器会在合并之后统一查一次 registry，把依赖写成当下最新的 `^x.y.z`。
 

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/{__PROJECT__ → overlays/story}/Resources/Stories/title/title_main.story

@@ -1,6 +1,6 @@
 // __PROJECT__ 示例工程（文本形态 = JSON v1 的投影）
 // 资源路径相对项目资源根 Resources/：如 bgm "Audio/main.mp3"
-// 一个文件里可以写多列（label / scene）；拆文件时把新文件加进 src/main.ts 的 STORIES 列表。
+// 一个文件里可以写多列（label / scene）；拆文件直接放进 Resources/Stories/ 下，构建期扫描自动收录。
 
 // 标题界面：`type=ui` 的列不进历史、不进存档、不建检查点——它是界面，不是剧情。
 // 引擎对这类列只管一件事：按 op 渲染（say 出一句、menu 出一组选项），所以下面几条开箱即跑，

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

@@ -0,0 +1,17 @@
+{
+  "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.8.2",
+  "version": "1.10.0",
   "minEngineVersion": "0.3.2",
   "placeholder": "__PROJECT__",
   "frameworks": [
@@ -33,20 +33,20 @@
     {
       "id": "tauri",
       "label": "桌面（Tauri 2）",
-      "hint": "给浏览器形态再加一个桌面壳：存档落到应用数据目录，其余不变"
+      "hint": "给同一份工程再加一个桌面壳：存档落到应用数据目录，页面结构不变"
     }
   ],
   "sources": [
     {
       "id": "ts",
       "label": "TypeScript 源（Stories.src）",
-      "hint": "用 TS 写故事列：有类型补全与重构，构建时编译成故事文件"
+      "hint": "骨架自带：用 TS 写故事列，有类型补全与重构，构建时编译成故事文件"
     },
     {
       "id": "story",
       "label": "故事文件（.story）",
-      "hint": "直接写引擎自带的文本故事格式，改完保存即生效"
+      "hint": "直接写引擎自带的文本故事格式：叠在骨架上，摘掉 TS 创作链，改完保存即生效"
     }
   ],
-  "_comment": "模板版本唯一来源，独立于引擎版本：仅当 template/v1 内容真正变化时才手动 bump。placeholder 是目录/文件内的工程名占位符，生成时整体替换为工程名（对齐 _LingFanEngineTemplateTitle_ 占位符语义）。minEngineVersion 表示此模板要求的最低引擎版本——生成期会拿它跟 registry 上的实际版本比对，不达标即失败（离线查不到版本时跳过判定）。frameworks / shells / sources 决定生成器会问什么、能叠哪些层，各自首项为缺省值；每一项的 id 对应 template/v1/overlays/<id> 目录（缺省层可以没有目录）。合并顺序为「骨架 → 框架 → 故事源 → 壳」，同路径文件由后一层覆盖前一层。"
+  "_comment": "模板版本唯一来源，独立于引擎版本：仅当 template/v1 内容真正变化时才手动 bump。placeholder 是目录/文件内的工程名占位符，生成时整体替换为工程名（对齐 _LingFanEngineTemplateTitle_ 占位符语义）。minEngineVersion 表示此模板要求的最低引擎版本——生成期会拿它跟 registry 上的实际版本比对，不达标即失败（离线查不到版本时跳过判定）。frameworks / shells / sources 决定生成器会问什么、能叠哪些层，各自首项为缺省值；每一项的 id 对应 template/v1/overlays/<id> 目录（缺省层可以没有目录——缺省故事源 `ts` 就是这样：整条创作链在骨架里，不需要叠加层）。合并顺序为「骨架 → 框架 → 故事源 → 壳」，同路径文件由后一层覆盖前一层。"
 }

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);
-});

package/template/overlays/ts/Resources/project.json

@@ -1,8 +0,0 @@
-{
-  "formatVersion": 1,
-  "id": "title_main",
-  "name": "__PROJECT__",
-  "entry": "title_main",
-  "lang": "zh-CN",
-  "tsSource": true
-}

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

@@ -1,13 +0,0 @@
-{
-  "devDependencies": {
-    "@lingfan-engine/editor": "^0.3.2"
-  },
-  "scripts": {
-    "stories:build": "lingfan-stories-build .",
-    "stories:watch": "lingfan-stories-watch .",
-    "stories-typecheck": "tsc --noEmit -p tsconfig.stories.json"
-  },
-  "create": {
-    "remove": ["Resources/Stories"]
-  }
-}