@lingfan-engine/create 0.3.2 → 0.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lingfan-engine/create",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "type": "module",
   "description": "工程生成器：从模板骨架生成新工程，可选框架与壳",
   "license": "Apache-2.0",

package/src/generate/project.ts

@@ -220,6 +220,7 @@ function renderManifest(
   >;
   const withPatch =
     patch === undefined ? manifest : mergeManifest(manifest, patch);
+  applyUnset(withPatch, patch);
   delete withPatch[CREATE_FIELD];
   const pinned = new Set(pinnedNames(patch));
   for (const field of ["dependencies", "devDependencies"] as const) {
@@ -271,6 +272,38 @@ function mergeManifest(
  */
 const CREATE_FIELD = "create";
 
+/**
+ * 把增量点名的清单键抹掉。
+ *
+ * `mergeManifest` 只合并键、不删键，所以 `scripts` 与 `devDependencies` 这类表
+ * 在叠加层里只能增不能减。可反向叠加层需要的正是减法：故事文件形态摘掉骨架的
+ * TS 创作链之后，配套的三条脚本与创作期依赖也应当一起消失，否则产物里留着
+ * 一个必然失败的命令。
+ *
+ * 形状与 `create.remove` 并列：外层是 `package.json` 的字段名，内层是要去掉的键名。
+ * 缺省项不必写它——缺省形态什么都不叠，本来就没有要减的东西。
+ */
+function applyUnset(
+  manifest: Record<string, unknown>,
+  patch: Readonly<Record<string, unknown>> | undefined,
+): void {
+  if (patch === undefined) return;
+  const section = patch[CREATE_FIELD];
+  if (!isPlainRecord(section)) return;
+  const unset = section.unset;
+  if (!isPlainRecord(unset)) return;
+  for (const [field, keys] of Object.entries(unset)) {
+    if (!Array.isArray(keys)) continue;
+    const table = manifest[field];
+    if (!isPlainRecord(table)) continue;
+    const next: Record<string, unknown> = { ...table };
+    for (const key of keys) {
+      if (typeof key === "string") delete next[key];
+    }
+    manifest[field] = next;
+  }
+}
+
 /**
  * 读叠加层声明的「不要跟最新版」的依赖名。
  *

package/template/README.md

@@ -43,14 +43,14 @@ pnpm create @lingfan-engine my-story
 
 生成器会问四件事：工程名、框架、故事源形态、壳。当前框架可选「原生（框架无关）」「Vue 3」「React」，
 故事源形态可选「故事文件（`.story`）」与「TypeScript 源（`Stories.src/`）」，
-壳可选「浏览器」「小程序（UniApp）」与「桌面（Tauri 2）」。全部取缺省值（原生 + 故事文件 + 浏览器）可以跳过问答：
+壳可选「浏览器」「小程序（UniApp）」与「桌面（Tauri 2）」。全部取缺省值（原生 + TypeScript 源 + 浏览器）可以跳过问答：
 
 ```
 npm create @lingfan-engine my-story -- --yes
 ```
 
-生成后按提示 `cd my-story && pnpm install && pnpm dev`。选了 TypeScript 源形态的，
-`pnpm dev` 之前先跑一次 `pnpm stories:build`（模板已带产物，改过源之后才需要）。
+生成后按提示 `cd my-story && pnpm install && pnpm dev`。骨架自带编译好的故事产物，开箱即跑；
+改过 `src/Stories.src/` 之后才需要跑一次 `pnpm stories:build`（或在开发时挂 `pnpm stories:watch`）。
 
 想不开交互问答、直接指定框架与壳：
 
@@ -59,7 +59,7 @@ 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 ts
+npm create @lingfan-engine my-story -- --sources story
 ```
 
 **框架层只换页面结构与入口，`src/host/**`（装配、订阅、帧循环、输入映射）一行不改，
@@ -71,12 +71,15 @@ npm create @lingfan-engine my-story -- --sources ts
 壳层与框架层可以叠加（先框架后壳）：`--framework react --shell tauri` 得到 React 页面 + 桌面外壳。
 小程序是例外——它自带 Vue 页面层，不与其他框架层叠加。
 
-**故事源形态层与框架层、壳层正交**，只决定故事从哪来：缺省形态直接改 `Resources/Stories/**/*.story`；
-`ts` 形态改 `Stories.src/**/*.ts` 再跑构建，产物是 `Resources/Stories/**/*.json`。后者会删掉骨架那份
-手写故事（层里声明 `create.remove: ["Resources/Stories"]`），再补上开箱可跑的生成物与三条脚本
-（`stories:build` / `stories:watch` / `stories-typecheck`）。产物目录由构建**全量管理**——源里没有的列
-构建会当陈旧列删掉，所以别在产物目录里手改；类型检查走独立的 `tsconfig.stories.json`（故事源有 ambient
-全局，不该和页面 DOM 类型面混在一个工程里）。
+**故事源形态层与框架层、壳层正交**，只决定故事从哪来。缺省形态是 **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` 混存。
 
 **壳层是换一整套页面与宿主**：小程序形态的页面结构由 `src/components/**` 承接，宿主装配在
 `src/mp/**`（`uni.*` 只在 `src/mp/platform.ts` 出现一处），内容不进包体、走工程接口按基址取。
@@ -94,8 +97,9 @@ npm create @lingfan-engine my-story -- --sources ts
 
 模板依赖三个引擎包：`@lingfan-engine/core`（核心）、`@lingfan-engine/adapters`（预设适配器）、`@lingfan-engine/ui`（参考展示层）。
 它们以 **TS 源码出口**（`exports: "./src/index.ts"`）发布——消费方由 Vite/TS 直接编译，**无中间构建步骤**，
-`pnpm install` 直接可用。选了 TypeScript 源形态的工程会多两个创作期依赖
-（`@lingfan-engine/stories-build` 与 `@lingfan-engine/editor`），由 `ts` 层自己声明。
+`pnpm install` 直接可用。骨架还声明两个创作期依赖（`@lingfan-engine/stories-build` 与
+`@lingfan-engine/editor`）——缺省故事源形态是 TS，这条链归骨架；选「故事文件」形态时
+`overlays/story/` 会把链上的文件、脚本与依赖条目一并摘掉（见下文叠加层说明）。
 
 ## 工程结构（单资源根）
 
@@ -106,6 +110,7 @@ __PROJECT__/
 ├── pnpm-workspace.yaml   # 只声明 allowBuilds：pnpm 12 起「未批准的构建脚本」是硬错误
 ├── tsconfig.json         # 浏览器侧：src/ 下的 ts 与 vue
 ├── tsconfig.node.json    # Node 侧：vite.config.ts 与 vite.plugins.ts（要 node:fs 与 @types/node）
+├── tsconfig.stories.json # 故事源独立工程：查 src/Stories.src/ 与 src/gen/ 的类型面（纯 tsc，不带页面 DOM 类型面）
 ├── vite.config.ts        # publicDir: "Resources" ← 资源根即静态根
 ├── vite.plugins.ts       # 构建期扫描：故事清单与字体清单（虚拟模块，层只换插件数组）
 ├── index.html            # RenderTargets 落地：stage/dialogue/choices/notifications/toolbar（+ 可选 #prefs / #mounts）
@@ -113,7 +118,8 @@ __PROJECT__/
 ├── src/stories/          # 故事清单出口（转发 virtual:story-list；清单本身来自磁盘扫描）
 ├── src/mounts.ts         # 挂载表出口 + mountStore（框架形态从这里订阅挂载值）
 ├── src/controls/         # 宿主控制面出口：挂载 UI 拿 pause/navigate/save/load 的地方
-├── src/gen/              # 构建生成物：清单、字体、守卫表、UI 注册表（手改会被覆盖）
+├── src/Stories.src/      # 故事源（TS 创作链）：config.ts 声明章节与入口，一函数 = 一列
+├── src/gen/              # 构建生成物：故事类型面、字体、守卫表、UI 注册表（手改会被覆盖）
 ├── src/ui/               # 可挂载界面（`<名>/<名>.<扩展名>`，可缺省：没有就不生成注册表）
 ├── src/host/             # 宿主：装配、订阅、帧循环、输入映射、挂载层与面板（不认识 UI 框架）
 │   ├── mount/            #   UI 挂载层（原生形态）：差量渲染器 + 工厂表契约
@@ -121,7 +127,7 @@ __PROJECT__/
 ├── src/styles/stage.css  # 页面与层样式（换框架不动这份：叠加层共用同一张表）
 └── Resources/            # 故事工程根（自包含、可整体搬运）
     ├── project.json      #   工程清单：id/name/entry/lang/formatVersion
-    ├── Stories/          #   故事（JSON v1 / .story 混存合法）
+    ├── Stories/          #   故事产物（构建全量管理；故事文件形态下可 .story 与 .json 混存）
     ├── Audio/  Images/  Video/
     ├── Lang/{lang}/      #   I18N overlay
     └── Saves/            #   运行期产物（不入 git）
@@ -175,8 +181,9 @@ pwsh -File pack-template.ps1 -SourceDir ./__PROJECT__ -OutputFile ./__PROJECT__.
 
 `template-meta.json` 的 `frameworks` / `sources` / `shells` 声明生成器会问哪些选项，每项的 `id` 对应
 `overlays/<id>/` 目录：同路径文件**覆盖**骨架，根目录的 `*.patch.json` **深合并**进 `package.json`，
-其中 `create.remove` 列出本层要删掉的骨架路径（换形态时清残留）。缺省项（`none` / `story` / `browser`）
-没有目录，表示「这一层什么都不加」，不是错误。合并顺序固定为「骨架 → 框架 → 故事源 → 壳」：
+其中 `create.remove` 列出本层要删掉的骨架路径（换形态时清残留）。缺省项（`none` / `ts` / `browser`）
+没有目录，表示「这一层什么都不加」，不是错误——缺省故事源 `ts` 正是如此：整条创作链在骨架里，
+没有叠加层可加。`story` 反过来是「摘掉骨架的 TS 链、换上手写故事」，所以它有目录。合并顺序固定为「骨架 → 框架 → 故事源 → 壳」：
 故事源要晚于框架层才能把各框架入口的故事表指向生成物；壳放最后，因为它对工程形态有最终发言权。
 
 骨架里的占位符有两种大小写形态：`__PROJECT__`（清单 id/name、页面标题、目录名）与

package/template/__PROJECT__/package.json

@@ -7,6 +7,9 @@
     "dev": "vite",
     "build": "vite build",
     "preview": "vite preview",
+    "stories:build": "lingfan-stories-build .",
+    "stories:watch": "lingfan-stories-watch .",
+    "stories-typecheck": "tsc --noEmit -p tsconfig.stories.json",
     "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.node.json"
   },
   "dependencies": {
@@ -17,6 +20,7 @@
     "@lingfan-engine/ui": "^0.3.2"
   },
   "devDependencies": {
+    "@lingfan-engine/editor": "^0.3.2",
     "@types/node": "^26.6.3",
     "typescript": "~6.0.3",
     "vite": "^8.0.16"

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/{__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/template-meta.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.8.2",
+  "version": "1.9.0",
   "minEngineVersion": "0.3.2",
   "placeholder": "__PROJECT__",
   "frameworks": [
@@ -40,13 +40,13 @@
     {
       "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/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"]
-  }
-}