@lingfan-engine/create 0.2.0 → 0.3.1

package/bin/create.mjs

@@ -8,7 +8,7 @@
  * `src/cli/cli.ts`，也不该被迫装一整套构建链。垫片用本包自带依赖 `tsx` 装载真实 CLI，
  * 呈现与编排逻辑仍然只有一份。
  *
- * 用法：`npm create @lingfan-engine [工程名] [-- --framework vanilla --shell browser]`；
+ * 用法：`npm create @lingfan-engine [工程名] [-- --framework vue --shell browser]`；
  * 不带参数即进入交互问答。
  */
 import { tsImport } from "tsx/esm/api";

package/package.json

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

package/src/cli/cli.ts

@@ -15,6 +15,7 @@ import {
   collectDependencyNames,
 } from "../generate/index.ts";
 import {
+  checkEngineCompatibility,
   readTemplateMeta,
   resolveTemplateRoot,
   resolveVersions,
@@ -218,6 +219,16 @@ async function generate(input: {
   if (resolved.size === 0 && names.length > 0) {
     process.stderr.write(`${texts.warnVersionOffline}\n`);
   }
+  // 版本判定在写盘之前：模板要求的引擎还没发布时，生成出来的工程装不上，
+  // 让它失败在「什么都没写」的时刻，而不是在别人的工程里第一次 pnpm dev 时。
+  const incompatible = checkEngineCompatibility(
+    input.meta.minEngineVersion,
+    resolved,
+  );
+  if (incompatible !== undefined) {
+    process.stderr.write(`${incompatible}\n`);
+    return 1;
+  }
 
   process.stderr.write(`${texts.stageCopy}\n`);
   let result;

package/src/generate/project.ts

@@ -47,7 +47,7 @@ export interface GenerateOptions {
   /** 壳叠加层 id */
   readonly shell: string;
   /**
-   * 故事源形态叠加层 id；缺省 `story`（直接写故事文件）。
+   * 故事源形态叠加层 id；缺省 `ts`（TypeScript 源，编译成故事文件）。
    *
    * 可选是为了不破坏既有调用方——只关心框架与壳的代码不必为一个用不到的参数改签名。
    */
@@ -68,8 +68,15 @@ export interface GenerateResult {
   readonly sources: string;
 }
 
-/** 故事源形态的缺省 id：不叠加任何层，直接用骨架自带的故事文件 */
-export const DEFAULT_SOURCES = "story";
+/**
+ * 故事源形态的缺省 id：TypeScript 源（`src/Stories.src/` → 编译成故事文件）。
+ *
+ * 三种创作形态是**同一个架构的三条入口**，不是三档能力：手写 `.story`、`.json`、
+ * TS 源最终都落到资源根下的故事目录，引擎装载时只认那棵树的扫描结果。TS 只是
+ * 多一层「写起来更强」的创作面（类型补全、复用 TS 能力），编译产物与手写文件同构，
+ * 因此缺省取它不改变任何运行期语义——生成出来的工程开箱即是可扩展的那一种。
+ */
+export const DEFAULT_SOURCES = "ts";
 
 /**
  * 生成一个工程。
@@ -110,12 +117,12 @@ export function generateProject(options: GenerateOptions): GenerateResult {
  * 依次列出要合并的目录：骨架在前，框架层次之，故事源形态层再次，壳层最后。
  *
  * 顺序有实际后果，不是随便排的：
- * - 故事源形态层要晚于框架层——它替换 `src/stories.ts`，而各框架入口都从那里取表，
- *   晚于框架层才能覆盖到「框架层是否也带了自己的 stories.ts」这类情况；
+ * - 故事源形态层要晚于框架层——它替换 `src/stories/index.ts`，而各框架入口都从那里取表，
+ *   晚于框架层才能覆盖到「框架层是否也带了自己的 stories/index.ts」这类情况；
  * - 壳层最后——壳对工程形态有最终发言权（小程序壳会删掉浏览器宿主的 `src/host/`），
  *   让它压过其余各层才不会出现「壳删了、下层又写回来」。
  *
- * 缺席的叠加层直接跳过——缺省项（`none` / `browser` / `story`）本就没有目录，
+ * 缺席的叠加层直接跳过——缺省项（`none` / `browser`）本就没有目录，
  * 这不是错误，只是「这一层什么都不加」。
  */
 export function layerBases(options: GenerateOptions): string[] {

package/src/index.ts

@@ -25,6 +25,8 @@ export {
 } from "./overlay/index.ts";
 export type { MergedLayer, PendingFile } from "./overlay/index.ts";
 export {
+  checkEngineCompatibility,
+  ENGINE_SCOPE,
   applyResolvedVersions,
   fetchLatestVersion,
   overlayDirOf,
@@ -40,8 +42,13 @@ export type {
 } from "./registry/index.ts";
 export {
   caretRange,
+  compareSemver,
+  floorOfRange,
   isValidProjectName,
+  meetsMinimum,
+  parseSemver,
   suggestProjectName,
 } from "./shared/index.ts";
+export type { Semver } from "./shared/index.ts";
 export { defaultCreateTexts } from "./shared/index.ts";
 export type { CreateTexts } from "./shared/index.ts";

package/src/registry/compat.ts

@@ -0,0 +1,49 @@
+/**
+ * 模板与引擎的版本兼容判定。
+ *
+ * 为什么需要：`template-meta.json` 的 `minEngineVersion` 曾是纯声明——没有任何代码读它，
+ * 于是「模板用了新引擎才有的 API、而生成的工程装的是旧引擎」这种组合可以一路生成成功，
+ * 直到使用者 `pnpm dev` 才炸在一条看不懂的报错上。判据放在生成期，是为了让失败发生在
+ * 「还没写盘」的时刻，而不是在别人的工程里。
+ *
+ * 判定只认 registry 上的**实际**版本：模板声明的区间再漂亮，装不到也是空话。查不到版本
+ * （离线）时不做判定——那时模板记录的区间就是将要安装的东西，模板自身的自洽性由
+ * `tests/template/template.test.ts` 的静态判据守。
+ */
+import { compareSemver } from "../shared/index.ts";
+
+/** 引擎包的 scope：本仓发布的包都挂在这里 */
+export const ENGINE_SCOPE = "@lingfan-engine/";
+
+/**
+ * 判定「这次生成会装到的引擎版本」是否满足模板要求。
+ *
+ * 返回问题描述而不是抛错：措辞归调用方（CLI 与库对同一件事可以说得不一样），
+ * 这里只负责说清「谁、要多少、实际是多少」。
+ *
+ * `resolved` 为空表示一个版本都没查到（离线或 registry 不可达）——此时无从判定，
+ * 返回 undefined 放行，离线生成仍然可用。
+ */
+export function checkEngineCompatibility(
+  minEngineVersion: string,
+  resolved: ReadonlyMap<string, string>,
+): string | undefined {
+  if (resolved.size === 0) return undefined;
+  const problems: string[] = [];
+  for (const [name, version] of [...resolved].sort((a, b) =>
+    a[0] < b[0] ? -1 : 1,
+  )) {
+    if (!name.startsWith(ENGINE_SCOPE)) continue;
+    const order = compareSemver(version, minEngineVersion);
+    if (order === undefined) {
+      problems.push(`${name}@${version} 无法与 ${minEngineVersion} 比较`);
+      continue;
+    }
+    if (order < 0) problems.push(`${name}@${version}`);
+  }
+  if (problems.length === 0) return undefined;
+  return (
+    `模板要求引擎不低于 ${minEngineVersion}，但 registry 上的最新版是 ${problems.join("、")}。` +
+    "引擎还没发布这个版本，生成的工程装不上模板需要的 API——先发引擎，或把模板的 minEngineVersion 降到已发布版本。"
+  );
+}

package/src/registry/index.ts

@@ -1,4 +1,5 @@
-/** registry 域唯一出口：模板元数据定位 + npm 版本查询。 */
+/** registry 域唯一出口：模板元数据定位 + npm 版本查询 + 引擎兼容判定。 */
+export { checkEngineCompatibility, ENGINE_SCOPE } from "./compat.ts";
 export {
   overlayDirOf,
   readTemplateMeta,

package/src/shared/index.ts

@@ -1,7 +1,14 @@
-/** shared 域唯一出口：文案表与参数校验。 */
+/** shared 域唯一出口：文案表、参数校验与版本运算。 */
 export { defaultCreateTexts, type CreateTexts } from "./texts.ts";
 export {
   caretRange,
   isValidProjectName,
   suggestProjectName,
 } from "./guards.ts";
+export {
+  compareSemver,
+  floorOfRange,
+  meetsMinimum,
+  parseSemver,
+  type Semver,
+} from "./semver.ts";

package/src/shared/semver.ts

@@ -0,0 +1,115 @@
+/**
+ * 语义化版本运算：解析、比较、取依赖区间的下界。
+ *
+ * 为什么自己写：生成器只用到这三件事，装 `semver` 会带进一整棵依赖树——而这个包
+ * 是随 `npm create` 下载的，为了比两个版本号先拉一棵树不可接受。
+ *
+ * 与 `scripts/release/version.mjs` 的边界：那是**发布工具链**的版本运算（递增、
+ * dist-tag、发布合法性判定），跑在维护者机器与 CI 上；它既不在本包的 `files` 里，
+ * 也不是 TypeScript，发布形态的生成器根本 import 不到。两边共用的是语义化版本规范
+ * 本身，不是同一份代码——改这里时请对照那一处，别让两套解读漂移。
+ */
+
+/** 拆开的版本号；`prerelease` 缺席表示正式版 */
+export interface Semver {
+  readonly major: number;
+  readonly minor: number;
+  readonly patch: number;
+  readonly prerelease?: string;
+}
+
+/**
+ * 解析 `主.次.修订[-预发布]`。
+ *
+ * 不接受 `v` 前缀与构建元数据：前者是标签写法不是版本写法，后者 npm 发布时会裁掉，
+ * 让「模板里写的」与「registry 上的」对不上。非法输入返回 undefined，由调用方决定
+ * 报什么错——本模块不做措辞。
+ */
+export function parseSemver(text: string): Semver | undefined {
+  const matched =
+    /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z.-]+))?$/.exec(
+      text.trim(),
+    );
+  if (matched === null) return undefined;
+  const prerelease = matched[4];
+  return {
+    major: Number(matched[1]),
+    minor: Number(matched[2]),
+    patch: Number(matched[3]),
+    ...(prerelease === undefined ? {} : { prerelease }),
+  };
+}
+
+/**
+ * 比较两个版本：负数表示前者更小，无法解析时返回 undefined。
+ *
+ * 预发布按规范排：有预发布 < 无预发布；两者都有时逐段比，纯数字段按数值、
+ * 其余按码元序，数字段小于字母段（`0.3.0-rc.2 < 0.3.0-rc.10 < 0.3.0`）。
+ */
+export function compareSemver(left: string, right: string): number | undefined {
+  const a = parseSemver(left);
+  const b = parseSemver(right);
+  if (a === undefined || b === undefined) return undefined;
+  for (const key of ["major", "minor", "patch"] as const) {
+    if (a[key] !== b[key]) return a[key] < b[key] ? -1 : 1;
+  }
+  if (a.prerelease === b.prerelease) return 0;
+  if (a.prerelease === undefined) return 1;
+  if (b.prerelease === undefined) return -1;
+  return comparePrerelease(a.prerelease, b.prerelease);
+}
+
+/** 逐段比较预发布标识符 */
+function comparePrerelease(left: string, right: string): number {
+  const a = left.split(".");
+  const b = right.split(".");
+  for (let index = 0; index < Math.max(a.length, b.length); index += 1) {
+    const one = a[index];
+    const other = b[index];
+    if (one === undefined) return -1;
+    if (other === undefined) return 1;
+    if (one === other) continue;
+    const oneIsNumber = /^\d+$/.test(one);
+    const otherIsNumber = /^\d+$/.test(other);
+    if (oneIsNumber && otherIsNumber) {
+      return Number(one) < Number(other) ? -1 : 1;
+    }
+    if (oneIsNumber) return -1;
+    if (otherIsNumber) return 1;
+    return one < other ? -1 : 1;
+  }
+  return 0;
+}
+
+/**
+ * 取依赖区间能接受的**最低**版本；认不出的区间返回 undefined。
+ *
+ * 只服务一个用途：判断「模板声明的引擎区间」是否容得下模板要求的最低引擎版本。
+ * 区间下界是够用的判据——区间上界不影响「装得上最低要求」这件事。
+ *
+ * 认得的写法：裸版本（`0.3.0`）、`^`、`~`、`>=`、`>`、`=`、`*`（无下界）。
+ * 复合区间（`>=0.3.0 <0.5.0`）与 `||` 取第一段的下界——模板里不该出现它们，
+ * 真出现了也不该因为「太复杂」而静默放过。
+ */
+export function floorOfRange(range: string): string | undefined {
+  const trimmed = range.trim();
+  if (trimmed === "" || trimmed === "*" || trimmed === "x") return undefined;
+  const first = trimmed.split("||")[0]?.trim() ?? "";
+  const matched = /^(?:[\^~><=]*)\s*([0-9][0-9A-Za-z.+-]*)/.exec(first);
+  if (matched === null) return undefined;
+  return parseSemver(matched[1]) === undefined ? undefined : matched[1];
+}
+
+/**
+ * `version` 是否满足「不低于 `minimum`」。
+ *
+ * 任一版本号解析不出时返回 undefined：调用方要能把「判不了」与「不达标」分开处理，
+ * 前者是模板写错，后者是版本太旧。
+ */
+export function meetsMinimum(
+  version: string,
+  minimum: string,
+): boolean | undefined {
+  const order = compareSemver(version, minimum);
+  return order === undefined ? undefined : order >= 0;
+}

package/src/shared/texts.ts

@@ -24,7 +24,7 @@ export const defaultCreateTexts = {
     "  -h, --help            显示本说明",
     "",
     "示例：",
-    "  npm create @lingfan-engine my-story -- --framework vanilla --shell browser",
+    "  npm create @lingfan-engine my-story -- --framework vue --shell browser",
     "  npm create @lingfan-engine my-story -- --sources ts",
   ].join("\n"),
   /** 交互问答的提示语 */

package/template/README.md

@@ -9,26 +9,27 @@
 
 ### 覆盖范围 / 有意不做（边界表）
 
-| 能力                                            | 模板                   | 说明                                                                            |
-| ----------------------------------------------- | ---------------------- | ------------------------------------------------------------------------------- |
-| 对话层（打字机 + 内联标记）                     | 是                     | `{p}/{w}` 停顿、样式标记零宽由 `@lingfan-engine/ui` 提供                        |
-| 等待态出口：`menu` / `input` / `wait` / `video` | 是                     | 缺任何一个，含该命令的故事都会**永久停滞**                                      |
-| 等待态：`minigame`                              | 是（可见 fail-closed） | 模板不接注册表 → 显示「未注册」并说明接入方式，**不伪造完成**                   |
-| 舞台元素层（36 类型 + 交互 + 12 个表现 op）     | 是                     | 含 `animate`/`transition`/`shake` 的帧驱动（不驱动会让动画队列只增不减）        |
-| 层级（z 序，`shell.layers`）                    | 是                     | 各层 z 由 `resolveLayerZ` 解析后内联写入                                        |
-| 存档（`shell.saves.slots` 槽位数）              | 是                     | 存/读为命令面；缩略图**不做**（见下行）                                         |
-| 存档缩略图（`shell.saves.thumbnail`）           | 否                     | 合成卡见 `apps/playground`；不传 `screenshot` 即为无缩略图存档                  |
-| 舞台适配（`shell.stage`）                       | 否                     | 模板按固定视口布局；要接就取 `resolveStageConfig` 结果再算 `computeStageLayout` |
-| 游玩界面禁选文本                                | 是                     | `body` 上 `user-select: none`；要提供复制就给部件加 `data-lf-selectable`        |
-| 历史面板与回溯 UI                               | 否                     | 引擎已具备（`historyView`/`rollbackTo`/`back`/`forward`），UI 见 playground     |
-| 玩家偏好（音量/文字速度面板）                   | 否                     | 未接 = 音量为 op 值、打字机取故事级 `text_typewriter`                           |
-| I18N 供给（`Lang/{lang}/` 覆盖）                | 否                     | 未接 `i18nPort` = 原文直出（引擎契约缺省语义）                                  |
-| 对话框模板注册（`say template=`）               | 否                     | 未接 = 内建默认骨架                                                             |
-| 屏幕方向锁定（`shell.orientation`）             | 不适用                 | **纯 Web 形态没有方向 API**；该配置只在 Tauri 壳（playground）生效              |
-| 资源加密 / 热重载 / 宿主信息                    | 不适用                 | 都是 Tauri 壳能力，见 playground 的组合根                                       |
+| 能力                                            | 模板                   | 说明                                                                              |
+| ----------------------------------------------- | ---------------------- | --------------------------------------------------------------------------------- |
+| 对话层（打字机 + 内联标记）                     | 是                     | `{p}/{w}` 停顿、样式标记零宽由 `@lingfan-engine/ui` 提供                          |
+| 等待态出口：`menu` / `input` / `wait` / `video` | 是                     | 缺任何一个，含该命令的故事都会**永久停滞**                                        |
+| 等待态：`minigame`                              | 是（可见 fail-closed） | 模板不接注册表 → 显示「未注册」并说明接入方式，**不伪造完成**                     |
+| 舞台元素层（36 类型 + 交互 + 12 个表现 op）     | 是                     | 含 `animate`/`transition`/`shake` 的帧驱动（不驱动会让动画队列只增不减）          |
+| 层级（z 序，`shell.layers`）                    | 是                     | 各层 z 由 `resolveLayerZ` 解析后内联写入                                          |
+| 存档（`shell.saves.slots` 槽位数）              | 是                     | 存/读为命令面；缩略图见下行                                                       |
+| 存档缩略图（`shell.saves.thumbnail`）           | 是                     | `src/host/thumbnails.ts` 合成卡；尺寸/质量/是否带文本按工程配置，合成失败即无图存 |
+| 舞台适配（`shell.stage`）                       | 否                     | 模板按固定视口布局；要接就取 `resolveStageConfig` 结果再算 `computeStageLayout`   |
+| 游玩界面禁选文本                                | 是                     | `body` 上 `user-select: none`；要提供复制就给部件加 `data-lf-selectable`          |
+| 历史面板与回溯 UI                               | 是                     | `src/host/panels/history.ts`，槽位 `#history` 可选；点一条即回到那个检查点        |
+| 玩家偏好（音量/文字速度面板）                   | 是                     | `src/host/panels/preferences.ts`，槽位 `#prefs` 可选；未接线 = 音量为 op 值       |
+| 界面列（`type=ui`）的渲染                       | 是                     | 按 op 渲染即开箱可跑；常驻界面可加 `src/ui/` 挂载（挂载层已接，生成物为空表）     |
+| I18N 供给（`Lang/{lang}/` 覆盖）                | 否                     | 未接 `i18nPort` = 原文直出（引擎契约缺省语义）                                    |
+| 对话框模板注册（`say template=`）               | 否                     | 未接 = 内建默认骨架                                                               |
+| 屏幕方向锁定（`shell.orientation`）             | 不适用                 | **纯 Web 形态没有方向 API**；该配置只在 Tauri 壳（playground）生效                |
+| 资源加密 / 热重载 / 宿主信息                    | 不适用                 | 都是 Tauri 壳能力，见 playground 的组合根                                         |
 
 > 「否」行均指**模板宿主未接**，不代表引擎没有该能力——引擎能力面以 `apps/playground` 为准
-> （历史面板 / 玩家偏好 / I18N / 对话框模板在引擎侧均已具备，仅模板未接线）。
+> （I18N / 对话框模板在引擎侧均已具备，仅模板未接线）。
 
 > 想升级为全功能实现，看引擎仓库的 `apps/playground`（它同时是模板的第一个实例）：
 > 把 `src/main.ts` 换成 Vue/React/原生任意一种都行——**引擎与适配器零改动**。
@@ -104,11 +105,19 @@ __PROJECT__/
 ├── package.json
 ├── pnpm-workspace.yaml   # 只声明 allowBuilds：pnpm 12 起「未批准的构建脚本」是硬错误
 ├── tsconfig.json         # 浏览器侧：src/ 下的 ts 与 vue
-├── tsconfig.node.json    # Node 侧：只覆盖 vite.config.ts（它要 node:fs 与 @types/node）
+├── tsconfig.node.json    # Node 侧：vite.config.ts 与 vite.plugins.ts（要 node:fs 与 @types/node）
 ├── vite.config.ts        # publicDir: "Resources" ← 资源根即静态根
-├── index.html            # RenderTargets 落地：stage/dialogue/choices/notifications/toolbar
+├── vite.plugins.ts       # 构建期扫描：故事清单与字体清单（虚拟模块，层只换插件数组）
+├── index.html            # RenderTargets 落地：stage/dialogue/choices/notifications/toolbar（+ 可选 #prefs / #mounts）
 ├── src/main.ts           # 组合根：装配适配器 → 组装工程 → 建引擎 → 订阅渲染 + 帧驱动
-├── src/stories.ts        # 故事文件表（Web 形态按显式清单取文件，全工程唯一声明点）
+├── src/stories/          # 故事清单出口（转发 virtual:story-list；清单本身来自磁盘扫描）
+├── src/mounts.ts         # 挂载表出口 + mountStore（框架形态从这里订阅挂载值）
+├── src/controls/         # 宿主控制面出口：挂载 UI 拿 pause/navigate/save/load 的地方
+├── src/gen/              # 构建生成物：清单、字体、守卫表、UI 注册表（手改会被覆盖）
+├── src/ui/               # 可挂载界面（`<名>/<名>.<扩展名>`，可缺省：没有就不生成注册表）
+├── src/host/             # 宿主：装配、订阅、帧循环、输入映射、挂载层与面板（不认识 UI 框架）
+│   ├── mount/            #   UI 挂载层（原生形态）：差量渲染器 + 工厂表契约
+│   └── panels/           #   玩家偏好面板（音量、静音、文字速度）
 ├── src/styles/stage.css  # 页面与层样式（换框架不动这份：叠加层共用同一张表）
 └── Resources/            # 故事工程根（自包含、可整体搬运）
     ├── project.json      #   工程清单：id/name/entry/lang/formatVersion
@@ -123,6 +132,35 @@ __PROJECT__/
 
 故事里的资源路径**相对 `Resources/`**：`bgm "Audio/main.mp3"`、`video "Video/op.mp4"`。
 
+## 界面列：按 op 渲染，或换一套视觉
+
+`type=ui` 的列不进历史、不进存档、不建检查点——它是界面，不是剧情。引擎对这类列的认知只有这一条
+（判据看列的类型是不是 `game`），它不知道「页面」是什么，也不管界面长什么样。
+
+所以开箱就是按 op 渲染：`say` 出一句、`menu` 出一组选项，和剧情列走同一条渲染路径。
+
+想换一套视觉，有两条互相独立的路：
+
+- **对局内界面**——常驻在舞台上、跟着故事显隐的那类（状态栏、好感度条、地图角标）。组件放
+  `src/ui/<名>/<名>.<扩展名>`，故事源一行 `import` 拿到句柄，再用 `mount(名字, true/false)` 控显隐。
+  宿主不用改：挂载层已接好，组件表由构建期扫描产出，宿主只经 `src/mounts.ts` 取。详见文档站的
+  [挂载 UI 组件](https://mofeng-02.github.io/LingFan.Engine/guides/ui-mount/)。
+- **普通页面**——登录、大厅、存档选择、设置这类整屏界面。它们属宿主应用层，与引擎同级，引擎完全不参与：
+  落 `src/pages/` 或任何你觉得合适的宿主目录，切进切出由宿主自己用 `v-if` / 路由决定。判据只有一条——
+  引擎当前停在哪一列（`createStateReader(engine).currentColumnId()`，空串 = 还没开始跑）。详见文档站的
+  [普通页面与对局内界面](https://mofeng-02.github.io/LingFan.Engine/guides/pages/)。
+
+宿主给 `ui` 列画界面时守两条：
+
+- **读走 `StateReader`，写走命令面**（`navigate` / `choose` / `input` / `save` / `load`）。界面不碰状态键，
+  也不自己造存档格式——绕过去就等于绕过了保留键守卫与快照一致性。
+- **切走即真销毁**。换界面是完整替换：Vue 调 `app.unmount()`、React 调 `root.unmount()`、
+  原生清空容器并解绑监听器。**卸载逻辑归宿主写，引擎不管也不检测。**
+
+`#prefs` 与 `#mounts` 都是**可选槽位**：不给就是这一层不接，故事照常跑、`mount` 命令只改状态不出现组件，
+都不报错。`#prefs` 接偏好面板（`src/host/panels/preferences.ts`），`#mounts` 接 UI 挂载层
+（`src/host/mount/`）。
+
 ## 打包分发
 
 ```

package/template/__PROJECT__/Resources/Stories/title/title_main.story

@@ -2,14 +2,25 @@
 // 资源路径相对项目资源根 Resources/：如 bgm "Audio/main.mp3"
 // 一个文件里可以写多列（label / scene）；拆文件时把新文件加进 src/main.ts 的 STORIES 列表。
 
-label title_main:
+// 标题界面：`type=ui` 的列不进历史、不进存档、不建检查点——它是界面，不是剧情。
+// 引擎对这类列只管一件事：按 op 渲染（say 出一句、menu 出一组选项），所以下面几条开箱即跑，
+// 视图上就是标题界面本身。想换成自己的视觉有两条路：常驻舞台的组件放 src/ui/ 并用 mount 控显隐；
+// 整屏的标题页/设置页属宿主应用，落 src/pages/ 一类宿主目录、由宿主自己切进切出。
+scene title_main type=ui
   say "欢迎来到 __PROJECT__。"
-  say "在 Resources/Stories/ 下继续写你的故事；媒体放 Resources/{Audio,Images,Video}。"
+  say "在 Resources/Stories/ 下继续写你的故事；媒体放 Resources/Audio、Resources/Images、Resources/Video。"
+  menu "接下来去哪里？"
+    "开始游戏" -> chapter1
+    "看舞台元素" -> stage_demo
+
+// 游戏正文第一列：进入这里才开始有历史与存档。
+scene chapter1
   input "先问一句：你叫什么名字？" store="player.name"
   say "你好，{player.name}！"
+  say "这一列是 game 列：从这里开始，每一步都可回溯、可存档。"
   menu "接下来去哪里？"
     "看舞台元素" -> stage_demo
-    "看重来一次" -> title_main
+    "回标题界面" -> title_main
 
 // scene 列 = 声明式空间层：进入本列时整体装载，切换列时清空
 scene stage_demo
@@ -21,4 +32,4 @@ scene stage_demo
   window hide
   say "（对话框已隐藏——点击继续）"
   window show
-  say "对话框回来了。层级、存档槽位等工程配置见 README 的边界表。"
+  say "对话框回来了。层级、存档槽位等工程配置见 README 的边界表。"

package/template/__PROJECT__/index.html

@@ -26,6 +26,13 @@
         <button id="save">存</button>
         <button id="load">读</button>
       </div>
+      <!-- 历史面板槽位：可选节点（缺了游戏照跑，只是回看已走过的对话要另想办法） -->
+      <div id="history"></div>
+      <!-- 偏好面板槽位：可选节点（缺了游戏照跑，只是没有音量/字速面板） -->
+      <div id="prefs"></div>
+      <!-- UI 挂载层：`mount` 命令显示/隐藏的组件挂在这里（可选节点，缺了只是没有 UI）。
+           位置在对话与工具条之后、转场遮罩之前：UI 盖住对话层，但盖不住转场与错误条。 -->
+      <div id="mounts"></div>
       <div id="transition"></div>
       <div id="error"></div>
     </div>

package/template/__PROJECT__/package.json

@@ -10,9 +10,11 @@
     "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.node.json"
   },
   "dependencies": {
-    "@lingfan-engine/adapters": "^0.1.0",
-    "@lingfan-engine/core": "^0.1.0",
-    "@lingfan-engine/ui": "^0.1.0"
+    "@lingfan-engine/adapters": "^0.3.0",
+    "@lingfan-engine/core": "^0.3.0",
+    "@lingfan-engine/shell": "^0.3.0",
+    "@lingfan-engine/stories-build": "^0.3.0",
+    "@lingfan-engine/ui": "^0.3.0"
   },
   "devDependencies": {
     "@types/node": "^26.6.3",

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

@@ -0,0 +1,7 @@
+/**
+ * 宿主控制面的宿主侧出口。
+ *
+ * 组合根在 `onControls` 回调里把句柄喂进 `controlsStore`，框架形态的挂载组件只从这里取，
+ * 不在自己的入口里各写一份订阅。
+ */
+export { controlsStore } from "./store";

package/template/__PROJECT__/src/controls/store.ts

@@ -0,0 +1,32 @@
+/**
+ * 宿主控制面的宿主侧副本（框架无关）。
+ *
+ * `bootHost` 造出控制面后经 `onControls` 交给组合根，组合根放进这里；框架形态的挂载
+ * 组件订阅它拿最新句柄。与 `mountStore` 同处一层但装的东西不同：那边是故事给的值
+ * （JSON 安全、随存档），这边是宿主给的操作句柄（含函数、不进快照）。
+ *
+ * 复用同一个单元格实现而不是另写一份订阅逻辑：形状一样（一个当前值 + 订阅），
+ * 差别只在取出来时的类型，用一层薄转写把 `unknown` 收回来即可。
+ */
+import { createMountStore } from "@lingfan-engine/ui";
+import type { HostControls } from "@lingfan-engine/core";
+
+const cell = createMountStore();
+
+/** 控制面单元格：`snapshot` 取当下、`subscribe` 追随变化、`set` 在组合根里喂 */
+export const controlsStore = {
+  /** 当下的控制面；宿主尚未交付时为 `null` */
+  snapshot(): HostControls | null {
+    return (cell.snapshot() ?? null) as HostControls | null;
+  },
+  /** 订阅变化（订阅时回放当下值由调用方自己先取一次 `snapshot`） */
+  subscribe(listener: (controls: HostControls | null) => void): () => void {
+    return cell.subscribe((raw) => {
+      listener((raw ?? null) as HostControls | null);
+    });
+  },
+  /** 交付控制面（组合根在 `onControls` 回调里调一次） */
+  set(controls: HostControls): void {
+    cell.set(controls);
+  },
+};

package/template/__PROJECT__/src/gen/ui_register.g.ts

@@ -0,0 +1,5 @@
+/* GENERATED by stories:build (ui-register) — 手改会在下次构建被覆盖 */
+
+/** 宿主用：「名字 → 组件」表。键就是 `SYS.mounts` 里的名字，不需要再归一。 */
+export const uis: Record<string, unknown> = {
+};