@lingfan-engine/create 0.0.0-stage → 0.1.4

package/src/registry/template-meta.ts

@@ -0,0 +1,107 @@
+/**
+ * 模板目录定位与元数据读取。
+ *
+ * 为什么需要「两处找」：模板内容在仓库里是 `template/v1`（与版本号一起在 git 里演进），
+ * 但发布到 npm 的包里不可能把仓库根目录带上——`prepack` 时会把它复制进
+ * `packages/create/template`。所以运行期先在包内找，找不到再退回仓库布局，
+ * 让「仓内直接跑」与「装到别的工程里跑」走同一份代码。
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** 本包根目录（`packages/create`）：`src/registry/` 上溯两级 */
+const PACKAGE_ROOT = resolve(
+  dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "..",
+);
+
+/** 模板元数据：模板版本、占位符、可选的框架与壳 */
+export interface TemplateMeta {
+  /** 模板自身版本，独立于引擎版本 */
+  readonly version: string;
+  /** 此模板要求的最低引擎版本 */
+  readonly minEngineVersion: string;
+  /** 生成时整体替换的占位符 */
+  readonly placeholder: string;
+  /** 可选框架，首项为缺省值 */
+  readonly frameworks: readonly TemplateOption[];
+  /** 可选壳，首项为缺省值 */
+  readonly shells: readonly TemplateOption[];
+}
+
+/** 一个可选项（框架或壳）：`id` 对应叠加层目录名 */
+export interface TemplateOption {
+  /** 叠加层目录名，也是命令行取值 */
+  readonly id: string;
+  /** 人读名称，交互问答里显示 */
+  readonly label: string;
+  /** 一句话说明，交互问答里作为提示 */
+  readonly hint: string;
+}
+
+/**
+ * 解析模板根目录。
+ *
+ * 顺序：包内 `template/`（发布形态）→ 仓库 `template/v1`（开发形态）。
+ * 两者都不存在时返回 undefined，由调用方转成可读错误——这里不抛异常，
+ * 因为「模板缺席」是部署问题而非参数问题，报错措辞在 CLI 层统一。
+ */
+export function resolveTemplateRoot(): string | undefined {
+  const bundled = join(PACKAGE_ROOT, "template");
+  if (existsSync(join(bundled, "template-meta.json"))) return bundled;
+  const inRepo = resolve(PACKAGE_ROOT, "..", "..", "template", "v1");
+  if (existsSync(join(inRepo, "template-meta.json"))) return inRepo;
+  return undefined;
+}
+
+/**
+ * 读取模板元数据。
+ *
+ * `frameworks` / `shells` 缺失时补成只剩缺省项的单元素表，而不是报错——旧模板
+ * （只有骨架、没有框架分层）仍然可以被生成器消费，向后兼容由此保证。
+ */
+export function readTemplateMeta(root: string): TemplateMeta {
+  const raw = JSON.parse(
+    readFileSync(join(root, "template-meta.json"), "utf8"),
+  ) as Partial<TemplateMeta> & { version: string; placeholder: string };
+  return {
+    version: raw.version,
+    minEngineVersion: raw.minEngineVersion ?? "0.0.0",
+    placeholder: raw.placeholder,
+    frameworks: raw.frameworks ?? [SKELETON_ONLY],
+    shells: raw.shells ?? [BROWSER_ONLY],
+  };
+}
+
+/** 旧模板无框架分层时的缺省项：叠加层目录不存在 = 只用骨架 */
+const SKELETON_ONLY: TemplateOption = {
+  id: "none",
+  label: "骨架（框架无关）",
+  hint: "不叠加任何框架层",
+};
+
+/** 旧模板无壳分层时的缺省项 */
+const BROWSER_ONLY: TemplateOption = {
+  id: "browser",
+  label: "浏览器",
+  hint: "只生成 Web 端工程",
+};
+
+/** 叠加层目录名 */
+export const OVERLAY_DIR = "overlays";
+
+/**
+ * 取某个选项对应的叠加层目录；不存在时返回 undefined。
+ *
+ * 「不存在」不一定是错误：缺省项（`none`/`browser`）本就没有叠加层，
+ * 判定交给调用方——它知道自己在要的是「必须存在的层」还是「可以缺席的缺省层」。
+ */
+export function overlayDirOf(
+  templateRoot: string,
+  optionId: string,
+): string | undefined {
+  const dir = join(templateRoot, OVERLAY_DIR, optionId);
+  return existsSync(dir) ? dir : undefined;
+}

package/src/registry/versions.ts

@@ -0,0 +1,109 @@
+/**
+ * npm registry 版本查询。
+ *
+ * 存在的理由：模板里记录的引擎版本是模板发布时的快照，装到新工程里可能已经落后。
+ * 生成时查一次当前最新版，把具体版本号钉进工程清单，让新工程一上来就是新的，
+ * 同时又不写 `latest` 标签——标签每次安装解析结果不同，构建会不可重现。
+ *
+ * 网络不可用时**不失败**：退回模板记录的版本并给出提示。生成一个工程不需要联网，
+ * 拉不到最新版不该让整件事失败。
+ */
+import { caretRange } from "../shared/index.ts";
+
+/** 一个包的解析结果：`version` 是 registry 上的最新稳定版 */
+export interface ResolvedVersion {
+  readonly name: string;
+  readonly version: string;
+}
+
+/** 查询超时：生成是交互式操作，宁可退回旧版本也不要让人干等 */
+const TIMEOUT_MS = 8000;
+
+/** 失败重试一次：并发查几个包时偶发单个连接被对端重置，重试即可，不必让使用者看见 */
+const ATTEMPTS = 2;
+
+/** 并发上限：一次甩出十几个连接会让 registry 直接限流，分批查反而快 */
+const CONCURRENCY = 3;
+
+/** registry 地址：允许经环境变量覆盖（企业内网镜像、离线代理） */
+function registryBase(): string {
+  const configured = process.env.LINGFAN_CREATE_REGISTRY;
+  return (
+    configured !== undefined && configured !== ""
+      ? configured
+      : "https://registry.npmjs.org"
+  ).replace(/\/+$/, "");
+}
+
+/**
+ * 查询单个包的 `dist-tags.latest`。
+ *
+ * 只取标签页而不是完整文档（`/<pkg>/latest` 更小），并显式请求 `dist-tags`：
+ * 完整文档在 `react` 这类包上是几 MB，生成器没必要为拿一个版本号付这个代价。
+ *
+ * 失败重试一次：并发查询时偶发连接被对端重置，重试的代价远小于「某个包的版本
+ * 悄悄留在模板旧值」——那种结果看不出来，却让产物自相矛盾。
+ */
+export async function fetchLatestVersion(
+  name: string,
+): Promise<string | undefined> {
+  for (let attempt = 0; attempt < ATTEMPTS; attempt += 1) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+    try {
+      const response = await fetch(`${registryBase()}/${name}/latest`, {
+        signal: controller.signal,
+        headers: { accept: "application/json" },
+      });
+      if (!response.ok) continue;
+      const body = (await response.json()) as { version?: unknown };
+      if (typeof body.version === "string") return body.version;
+    } catch {
+      // 断网、超时、DNS 失败、JSON 损坏都走这里：还有一次机会，然后按「拿不到」处理
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  return undefined;
+}
+
+/**
+ * 批量查询：分批并发，任一失败不影响其它。
+ *
+ * 返回表只含查到的项——调用方拿模板记录的版本兜底，因此「缺席」比「空串」更好判。
+ */
+export async function resolveVersions(
+  names: readonly string[],
+): Promise<Map<string, string>> {
+  const out = new Map<string, string>();
+  for (let start = 0; start < names.length; start += CONCURRENCY) {
+    const batch = names.slice(start, start + CONCURRENCY);
+    const settled = await Promise.all(
+      batch.map(
+        async (name) => [name, await fetchLatestVersion(name)] as const,
+      ),
+    );
+    for (const [name, version] of settled) {
+      if (version !== undefined) out.set(name, version);
+    }
+  }
+  return out;
+}
+
+/**
+ * 把查到的版本合进工程清单的依赖表。
+ *
+ * 规则：清单里有、也查到了 → 换成 `^最新`；查不到 → 保留模板记录的原值不动。
+ * 只改清单里已有的键，不新增依赖——依赖集合由模板决定，生成器不是包管理器。
+ */
+export function applyResolvedVersions(
+  dependencies: Readonly<Record<string, string>>,
+  resolved: ReadonlyMap<string, string>,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [name, range] of Object.entries(dependencies)) {
+    const latest = resolved.get(name);
+    out[name] = latest === undefined ? range : caretRange(latest);
+  }
+  return out;
+}

package/src/shared/guards.ts

@@ -0,0 +1,85 @@
+/**
+ * 参数校验与小工具。
+ *
+ * 为什么单独成文件：CLI 与生成编排都要判「工程名是否可用」，两处各写一份必然漂移
+ * （一处放过 Windows 保留名，另一处不放），故只留这一处判定。
+ */
+
+/**
+ * npm 包名与目录名共同接受的形态：小写字母/数字/连字符/下划线。
+ *
+ * 首字符限字母或数字：npm 明确禁止包名以 `.` 或 `_` 开头，而工程名同时要当包名用，
+ * 放过下划线开头会让新工程在「日后想发布」时才发现不合规。
+ */
+const NAME_PATTERN = /^[a-z0-9][a-z0-9_-]*$/;
+
+/** Windows 上不可用作目录名的保留字（大小写不敏感） */
+const RESERVED_NAMES = new Set([
+  "con",
+  "prn",
+  "aux",
+  "nul",
+  "com1",
+  "com2",
+  "com3",
+  "com4",
+  "com5",
+  "com6",
+  "com7",
+  "com8",
+  "com9",
+  "lpt1",
+  "lpt2",
+  "lpt3",
+  "lpt4",
+  "lpt5",
+  "lpt6",
+  "lpt7",
+  "lpt8",
+  "lpt9",
+]);
+
+/**
+ * 工程名是否合法。
+ *
+ * 只接受小写形态：工程名同时进 `package.json` 的 `name`、`Resources/project.json`
+ * 的 `id` 与目录名，三处共用一份字符串。大写会让 `name` 违反 npm 规范（npm 拒绝
+ * 大写包名，日后想发布就卡住），故一开始就不放行，而不是事后改。
+ */
+export function isValidProjectName(name: string): boolean {
+  if (name.length === 0 || name.length > 64) return false;
+  if (!NAME_PATTERN.test(name)) return false;
+  return !RESERVED_NAMES.has(name);
+}
+
+/**
+ * 把任意人类输入收敛成合法工程名：小写、非法字符折叠成连字符、去首尾连字符。
+ *
+ * 用途是「给个建议值」——交互问答里预填，命令行参数仍然走严格校验，
+ * 免得用户以为自己指定的名字被悄悄改过。
+ */
+export function suggestProjectName(input: string): string {
+  const collapsed = input
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return collapsed.length > 0 ? collapsed : "lingfan-story";
+}
+
+/**
+ * 把用户输入的版本号归一成 `^x.y.z`。
+ *
+ * 为什么不直接写 `latest` 标签：标签每次安装都解析到当时的最高版本，同一份
+ * `package.json` 在不同日子装出不同依赖，构建不可重现。生成时查一次、把具体
+ * 版本号钉进清单，之后由使用者显式升级。
+ *
+ * 已经带范围符号（`^`、`~`、`>`、`<`、`=`、`*`）的输入原样返回——参数来自
+ * registry 的 `latest` 字段时是裸版本号，但也会被直接传入，多包一层 `^~x` 会让
+ * 清单解析失败。
+ */
+export function caretRange(version: string): string {
+  return RANGE_PREFIXES.test(version) ? version : `^${version}`;
+}
+
+/** 版本范围符号；命中即视为调用方已指定范围 */
+const RANGE_PREFIXES = /^[\^~><=*]/;

package/src/shared/index.ts

@@ -0,0 +1,7 @@
+/** shared 域唯一出口：文案表与参数校验。 */
+export { defaultCreateTexts, type CreateTexts } from "./texts.ts";
+export {
+  caretRange,
+  isValidProjectName,
+  suggestProjectName,
+} from "./guards.ts";

package/src/shared/texts.ts

@@ -0,0 +1,55 @@
+/**
+ * 生成器集中文案。
+ *
+ * 为什么集中：CLI 呈现是唯一对使用者说话的地方，措辞散在多个文件里就会各自漂移
+ * （一半说「工程」一半说「项目」）。集中一处后，改口径只需改这里。
+ *
+ * 用法：除 CLI 层外不要直接拼中文字符串；文案一律走这里，便于日后整体替换语言。
+ */
+export const defaultCreateTexts = {
+  /** CLI 标题行，`<name>` 由调用方替换 */
+  banner: "灵泛叙事引擎 · 工程生成器",
+  help: [
+    "用法：",
+    "  npm create @lingfan-engine [工程名] [选项]",
+    "  pnpm create @lingfan-engine [工程名] [选项]",
+    "",
+    "选项：",
+    "  -f, --framework <id>  框架（缺省取模板声明的默认值）",
+    "  -s, --shell <id>      壳（缺省取模板声明的默认值）",
+    "  -d, --dir <路径>      生成到哪个目录下（缺省 = 当前目录）",
+    "      --no-install      生成后不自动安装依赖",
+    "  -y, --yes             全部取缺省值，不进入交互问答",
+    "  -h, --help            显示本说明",
+    "",
+    "示例：",
+    "  npm create @lingfan-engine my-story -- --framework vanilla --shell browser",
+  ].join("\n"),
+  /** 交互问答的提示语 */
+  promptProjectName: "工程名",
+  promptFramework: "框架",
+  promptShell: "壳",
+  promptInstall: "生成后立即安装依赖？",
+  /** 参数校验失败 */
+  nameRequired: "工程名不能为空",
+  nameInvalid:
+    "工程名只能包含小写字母、数字、连字符与下划线，且不能以点或连字符开头",
+  dirMissing: "目标目录不存在",
+  frameworkUnknown: "未知框架",
+  shellUnknown: "未知壳",
+  overlayMissing: "模板缺少该选项对应的叠加层",
+  targetExists: "目标目录已存在且非空",
+  templateMissing: "找不到模板目录：本包未随附模板内容，或开发态仓库结构不完整",
+  /** 生成过程 */
+  stageResolve: "解析模板与版本…",
+  stageCopy: "写入工程文件…",
+  stageInstall: "安装依赖…",
+  doneTitle: "工程已生成",
+  nextSteps: ["cd <name>", "pnpm install", "pnpm dev"].join("\n"),
+  /** 非致命提示 */
+  warnVersionOffline:
+    "无法查询 npm registry 上的最新版本，已沿用模板记录的版本",
+  warnInstallFailed: "依赖安装失败，请在工程目录内手动执行 pnpm install",
+} as const;
+
+export type CreateTexts = typeof defaultCreateTexts;

package/template/README.md

@@ -0,0 +1,138 @@
+# 灵泛工程脚手架 v1
+
+**引擎服务 = 核心（框架无关）+ 脚手架（工程骨架）**。本目录是脚手架本体：
+新工程由它生成，因此「选什么展示框架」只影响本模板内的宿主代码，**不影响引擎底层**。
+
+模板自带的宿主**不依赖任何 UI 框架**（直接操作 DOM）——这既是「框架无关」的活证明，也让模板保持精简。
+但**精简的底线是「不卡死」**：引擎能进入的每一个等待态，模板都必须给出可推进的出口，
+并且 `project.json` 的 `shell.*` 配置必须被真正消费（否则作者改了配置却毫无效果）。
+
+### 覆盖范围 / 有意不做（边界表）
+
+| 能力                                            | 模板                   | 说明                                                                            |
+| ----------------------------------------------- | ---------------------- | ------------------------------------------------------------------------------- |
+| 对话层（打字机 + 内联标记）                     | 是                     | `{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 的组合根                                       |
+
+> 「否」行均指**模板宿主未接**，不代表引擎没有该能力——引擎能力面以 `apps/playground` 为准
+> （历史面板 / 玩家偏好 / I18N / 对话框模板在引擎侧均已具备，仅模板未接线）。
+
+> 想升级为全功能实现，看引擎仓库的 `apps/playground`（它同时是模板的第一个实例）：
+> 把 `src/main.ts` 换成 Vue/React/原生任意一种都行——**引擎与适配器零改动**。
+
+## 生成一个新工程
+
+```
+npm create @lingfan-engine my-story
+pnpm create @lingfan-engine my-story
+```
+
+生成器会问两件事：工程名、框架与壳。当前框架可选「原生（框架无关）」「Vue 3」「React」，
+壳可选「浏览器」「小程序（UniApp）」与「桌面（Tauri 2）」。全部取缺省值（原生 + 浏览器）可以跳过问答：
+
+```
+npm create @lingfan-engine my-story -- --yes
+```
+
+生成后按提示 `cd my-story && pnpm install && pnpm dev`。
+
+想不开交互问答、直接指定框架与壳：
+
+```
+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
+```
+
+**框架层只换页面结构与入口，`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 页面层，不与其他框架层叠加。
+
+**壳层是换一整套页面与宿主**：小程序形态的页面结构由 `src/components/**` 承接，宿主装配在
+`src/mp/**`（`uni.*` 只在 `src/mp/platform.ts` 出现一处），内容不进包体、走工程接口按基址取。
+因此它是壳而不是框架，与 `--framework` 不叠加：小程序已自带 Vue 页面层，框架取缺省值即可。
+它的 `vite` 与 `vue` 是一组钉住的版本（UniApp 插件对这些版本有硬约束），由
+`package.patch.json` 的 `create.pinned` 保住，不会被改写成「跟最新」。
+
+工程名只允许小写字母、数字、`-` 与 `_`，且不能以下划线或点开头——它同时进 `package.json` 的 `name`、
+`project.json` 的 `id` 与目录名，大写与点开头在 npm 侧非法。
+
+引擎包版本由生成器在**生成时**查一次 registry，把当时的最新版本写成 `^x.y.z` 记进产物。
+不写 `latest` 标签是因为它每次安装都解析到当时最高版，同一份工程在两台机器上会装出不同版本。
+
+## 依赖接入（引擎包）
+
+模板依赖三个引擎包：`@lingfan-engine/core`（核心）、`@lingfan-engine/adapters`（预设适配器）、`@lingfan-engine/ui`（参考展示层）。
+它们以 **TS 源码出口**（`exports: "./src/index.ts"`）发布——消费方由 Vite/TS 直接编译，**无中间构建步骤**，
+`pnpm install` 直接可用。
+
+## 工程结构（单资源根）
+
+```
+__PROJECT__/
+├── project.json          # 工程清单：id/name/entry/lang/formatVersion
+├── package.json
+├── pnpm-workspace.yaml   # 只声明 allowBuilds：pnpm 12 起「未批准的构建脚本」是硬错误
+├── tsconfig.json         # 浏览器侧：src/ 下的 ts 与 vue
+├── tsconfig.node.json    # Node 侧：只覆盖 vite.config.ts（它要 node:fs 与 @types/node）
+├── vite.config.ts        # publicDir: "Resources" ← 资源根即静态根
+├── index.html            # RenderTargets 落地：stage/dialogue/choices/notifications/toolbar
+├── src/main.ts           # 组合根：装配适配器 → 组装工程 → 建引擎 → 订阅渲染 + 帧驱动
+├── src/styles/stage.css  # 页面与层样式（换框架不动这份：叠加层共用同一张表）
+└── Resources/            # 故事工程根（自包含、可整体搬运）
+    ├── project.json      #   工程清单：id/name/entry/lang/formatVersion
+    ├── Stories/          #   故事（JSON v1 / .story 混存合法）
+    ├── Audio/  Images/  Video/
+    ├── Lang/{lang}/      #   I18N overlay
+    └── Saves/            #   运行期产物（不入 git）
+```
+
+**清单在资源根内**（不是项目根）：只有 `Resources/` 内的文件才会进打包产物，dev 与 prod 因此走同一机制——
+清单若留在项目根，dev 下 Vite 顺带服务根目录能取到，打包产物里却会 404。
+
+故事里的资源路径**相对 `Resources/`**：`bgm "Audio/main.mp3"`、`video "Video/op.mp4"`。
+
+## 打包分发
+
+```
+pwsh -File pack-template.ps1 -SourceDir ./__PROJECT__ -OutputFile ./__PROJECT__.zip
+```
+
+排除 `node_modules/`、`dist/`、`.git/`、`Resources/Saves/`（运行期产物不进模板）。
+
+打包脚本是给「不走生成器、只想把骨架拿走」的场景准备的。正常路径是 `npm create @lingfan-engine`。
+
+## 叠加层与占位符
+
+`template-meta.json` 的 `frameworks` / `shells` 声明生成器会问哪些选项，每项的 `id` 对应
+`overlays/<id>/` 目录：同路径文件**覆盖**骨架，根目录的 `*.patch.json` **深合并**进 `package.json`。
+缺省项（`none` / `browser`）没有目录，表示「这一层什么都不加」，不是错误。
+
+骨架里的占位符有两种大小写形态：`__PROJECT__`（清单 id/name、页面标题、目录名）与
+`__project__`（`package.json` 的 name，npm 要求小写）。生成时两者都替换成工程名。
+
+`.gitignore` 在模板里存成不带点的 `gitignore`：npm 把包装进 `node_modules` 时会把包内的
+`.gitignore` 改名成 `.npmignore`，模板若按原名存，生成的工程就会既缺忽略规则又多个无用文件。
+
+## 版本
+
+`template-meta.json` 是模板版本的唯一来源（独立于引擎版本）：仅当模板内容真正变化时才 bump。

package/template/__PROJECT__/Resources/Fonts/README.md

@@ -0,0 +1,10 @@
+# Fonts/——字体名注册表
+
+把字体文件放进本目录即完成注册：**字体名 = 文件名去扩展名**（`楷体.ttf` → 字体名 `楷体`）。
+
+- 参与注册的扩展名：`.ttf` / `.otf` / `.woff` / `.woff2`（其余文件忽略）。
+- 引用：故事层只写字体名字符串——`{font=楷体}` 行内标签或 `say` 行参 `font: "楷体"`。
+- 守门分两档：构建期对静态引用 fail-closed（未注册名 stories:build 直接报错）；
+  运行期对动态拼接名回退默认字体并输出诊断（`configureStoryFonts` 宿主装配）。
+- 宿主自动为本目录的字体注入 `@font-face`（Vite 构建期扫描），无需手写样式。
+- 建议文件名只用字母数字、中文与连字符，避免空格等需转义字符。

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

@@ -0,0 +1,24 @@
+// __PROJECT__ 示例工程（文本形态 = JSON v1 的投影）
+// 资源路径相对项目资源根 Resources/：如 bgm "Audio/main.mp3"
+// 一个文件里可以写多列（label / scene）；拆文件时把新文件加进 src/main.ts 的 STORIES 列表。
+
+label title_main:
+  say "欢迎来到 __PROJECT__。"
+  say "在 Resources/Stories/ 下继续写你的故事；媒体放 Resources/{Audio,Images,Video}。"
+  input "先问一句：你叫什么名字？" store="player.name"
+  say "你好，{player.name}！"
+  menu "接下来去哪里？"
+    "看舞台元素" -> stage_demo
+    "看重来一次" -> title_main
+
+// scene 列 = 声明式空间层：进入本列时整体装载，切换列时清空
+scene stage_demo
+  panel x=5% y=10% width=90% zindex=10
+    text "scene 列 = 声明式空间层：这些方块是元素，不是对话"
+    text "panel 是容器，子元素用更深缩进写"
+  say "进入 scene 列：元素已整体装载（回顾/读档会自动随行）。"
+  say "下一条会隐藏对话框，再下一条让它回来。"
+  window hide
+  say "（对话框已隐藏——点击继续）"
+  window show
+  say "对话框回来了。层级、存档槽位等工程配置见 README 的边界表。"

package/template/__PROJECT__/Resources/project.json

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

package/template/__PROJECT__/gitignore

@@ -0,0 +1,8 @@
+# 运行期产物不进版本库（存档由 Rust 安全层落盘）
+Resources/Saves/
+node_modules/
+dist/
+target/
+src-tauri/target/
+src-tauri/gen/
+*.local

package/template/__PROJECT__/index.html

@@ -0,0 +1,34 @@
+<!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>
+    <!-- 舞台根：屏幕震动（shake）施于此；各层 z 由 main.ts 按 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>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/template/__PROJECT__/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "__project__",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "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"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.3",
+    "typescript": "~6.0.3",
+    "vite": "^8.0.16"
+  }
+}

package/template/__PROJECT__/pnpm-workspace.yaml

@@ -0,0 +1,8 @@
+# pnpm 12 起，「未批准的构建脚本」是硬错误（ERR_PNPM_IGNORED_BUILDS），
+# 会让 `pnpm install` 整个失败、并连锁跳过其后的构建步骤。
+# 这里的批准面只放 esbuild（vite 与 UniApp 工具链的既定安装步骤）；
+# 带安装脚本但不需要执行的包显式写 false ——「知道了、故意不跑」与「未批准」是两回事，
+# 不写 false 每次安装都会以同一个错误收场。core-js 的 postinstall 只打印赞助信息。
+allowBuilds:
+  core-js: false
+  esbuild: true