@lingfan-engine/create 0.0.0-stage → 0.1.5

package/template/__PROJECT__/src/host/frame-loop.ts

@@ -0,0 +1,42 @@
+/**
+ * 帧循环接线：把 `requestAnimationFrame` 接到展示层的帧循环上。
+ *
+ * 帧源是本宿主唯一认识平台 API 的地方——展示层的帧循环只认「申请下一帧 / 取消」两个方法，
+ * 换平台（小游戏运行时、测试用的假帧源）只改这里。
+ *
+ * 每帧顺序固定：打字机推进 → 上交可见文本 → 媒体位置回写 → 帧驱动表现。
+ * 先上屏再写表现，否则同一帧里的动画会看到上一帧的文本。
+ */
+
+import { createFrameLoop, type FrameLoop } from "@lingfan-engine/ui";
+import type { DialogueView } from "./dialogue-view";
+
+/** 帧循环的输入：对话视图（打字机与上屏都经它）与两项每帧回调 */
+export interface HostFrameLoopOptions {
+  /** 对话视图：打字机实例与可见文本上屏都经它 */
+  dialogue: DialogueView;
+  /** 媒体位置帧级回写（音频端口自带的做法） */
+  onMediaTick(): void;
+  /** 帧驱动表现；传入距上一帧的秒数 */
+  onFrame(dt: number): void;
+}
+
+/** 启动帧循环并返回句柄（本宿主不主动停帧，句柄留给需要停的场合） */
+export function startHostFrameLoop(options: HostFrameLoopOptions): FrameLoop {
+  const loop = createFrameLoop({
+    frame: {
+      request: (callback) => requestAnimationFrame(callback),
+      cancel: (handle) => cancelAnimationFrame(handle),
+    },
+    // 每帧顺序固定：打字机推进 → 上交可见文本 → 媒体位置回写 → 帧驱动表现
+    onTick: (dt) => {
+      const typewriter = options.dialogue.readTypewriter();
+      typewriter?.tick(dt);
+      options.dialogue.onText(typewriter?.visible ?? "");
+      options.onMediaTick();
+      options.onFrame(dt);
+    },
+  });
+  loop.start();
+  return loop;
+}

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

@@ -0,0 +1,27 @@
+/**
+ * 模板宿主出口：组合根与外部只从这里取本宿主的零件，不深入具体文件。
+ *
+ * 转发的都是本宿主的装配入口与契约类型；具体实现留在各自叶子里，
+ * 换一处实现不影响调用方的 import 路径。
+ */
+
+export {
+  must,
+  createErrorReporter,
+  reportBootFailure,
+  type StageDom,
+} from "./stage-dom";
+export { createHostLayerZ, type HostLayerZOptions } from "./layer-z";
+export { fillSaveSlots, wireSaveSlots } from "./save-slots";
+export { createToast, type ToastOptions } from "./toast";
+export {
+  createDialogueView,
+  type DialogueEngine,
+  type DialogueView,
+  type DialogueViewOptions,
+} from "./dialogue-view";
+export { createHostEffects, type HostEffectsOptions } from "./effects";
+export { wireEngine, type HostWiringOptions } from "./engine-wiring";
+export { startHostFrameLoop, type HostFrameLoopOptions } from "./frame-loop";
+export { wireInput, type HostInputOptions } from "./input-map";
+export { bootHost, type BootPortOverrides, type HostBootOptions } from "./boot";

package/template/__PROJECT__/src/host/input-map.ts

@@ -0,0 +1,51 @@
+/**
+ * 输入映射：点击与键盘（空格 / 回车）都汇到同一个 `advance`。
+ *
+ * 语义归核心层——`advance` 自己处理可跳过性、非等待态与 fail-closed，这里只做映射，
+ * 不判断「现在能不能推进」。
+ *
+ * 两处刻意的不推进：交互层（选项 / 工具条 / 通知）内的点击不推进故事（元素可交互节点
+ * 在渲染器内自行 `stopPropagation`，这里再兜一层），输入框内的空格 / 回车不吞键
+ * （那是玩家在打字）。
+ */
+
+import type { StoryEngine } from "@lingfan-engine/core";
+import type { StageDom } from "./stage-dom";
+import type { DialogueView } from "./dialogue-view";
+
+/** 输入映射的输入：节点句柄表、引擎推进面与对话视图 */
+export interface HostInputOptions {
+  /** 常驻节点句柄表 */
+  dom: StageDom;
+  /** 引擎：推进命令面的落地 */
+  engine: StoryEngine;
+  /** 对话视图：打字机未打完时先让打字机瞬间完成 */
+  dialogue: DialogueView;
+}
+
+/** 接线点击与键盘 */
+export function wireInput(options: HostInputOptions): void {
+  const { dom, engine, dialogue } = options;
+
+  /** 二段式推进：打字未完 → 瞬间完成 / 越过停顿；否则推进故事 */
+  function advance(): void {
+    const typewriter = dialogue.readTypewriter();
+    if (typewriter !== null && !typewriter.done) {
+      typewriter.click();
+      return;
+    }
+    engine.advance();
+  }
+
+  dom.root.addEventListener("click", advance);
+  for (const el of [dom.choices, dom.toolbar, dom.notifications]) {
+    el.addEventListener("click", (event) => event.stopPropagation());
+  }
+  document.addEventListener("keydown", (event) => {
+    if (event.key === " " || event.key === "Enter") {
+      if (event.target instanceof HTMLInputElement) return; // 输入框内不吞键
+      event.preventDefault();
+      advance();
+    }
+  });
+}

package/template/__PROJECT__/src/host/layer-z.ts

@@ -0,0 +1,50 @@
+/**
+ * 层级装配：把展示层的层级视图接到本宿主的 DOM 节点与视频端口上。
+ *
+ * 展示层管的是「某层最终该是多少」（实例覆盖 > 工程默认 > 内建），本文件管的是
+ * 「这个值写到哪个节点上」——这层映射是本宿主独有的，不放进共享面。
+ *
+ * 视频层的 z 不在 DOM 上而在端口内部，且只在视频层自己变化时才下发（见 `LayerView`），
+ * 所以这里用 getter 取端口：装配期先落一次 DOM 层，那时端口还没建。
+ */
+
+import { createLayerView, type LayerView } from "@lingfan-engine/ui";
+import type { LayerId, LayerZTable, VideoPort } from "@lingfan-engine/core";
+import type { StageDom } from "./stage-dom";
+
+/**
+ * 层级视图的输入：节点句柄表、工程层默认表与视频端口取值器。
+ * 端口用取值器而非实例：装配期要先落一次 DOM 层，那时端口还没建好。
+ */
+export interface HostLayerZOptions {
+  /** 常驻节点句柄表 */
+  dom: StageDom;
+  /** 工程层默认（`project.json` 的 `shell.layers`） */
+  layerZ: LayerZTable;
+  /** 取当前视频端口（尚未建好时返回 null） */
+  readVideoPort(): VideoPort | null;
+}
+
+/** 某个 DOM 层落到哪个（或哪些）节点上 */
+function writeLayerZ(dom: StageDom, layer: LayerId, z: number): void {
+  const value = String(z);
+  if (layer === "stage") dom.stage.style.zIndex = value;
+  // 对话层的 z 同时管对话框与 NVL 层：两者互斥显示，但要处在同一层级上
+  else if (layer === "dialogue") {
+    dom.dialogue.style.zIndex = value;
+    dom.nvl.style.zIndex = value;
+  } else if (layer === "choices") dom.choices.style.zIndex = value;
+  else if (layer === "notifications") dom.notifications.style.zIndex = value;
+  else if (layer === "toolbar") dom.toolbar.style.zIndex = value;
+}
+
+/** 造本宿主的层级视图：DOM 层写节点，视频层的 z 下发到端口内部 */
+export function createHostLayerZ(options: HostLayerZOptions): LayerView {
+  return createLayerView({
+    layerZ: options.layerZ,
+    applyLayerZ: (layer, z) => writeLayerZ(options.dom, layer, z),
+    onVideoZ: (z) => {
+      options.readVideoPort()?.setZIndex?.(z);
+    },
+  });
+}

package/template/__PROJECT__/src/host/save-slots.ts

@@ -0,0 +1,38 @@
+/**
+ * 存档接线：槽位下拉与存 / 读两个按钮。
+ *
+ * 槽位有几个、叫什么，由引擎按工程配置裁定（`project.json` 的 `shell.saves.slots`），
+ * 宿主只负责把 id 放进 `<option>`。槽位口径若搬进宿主，「改工程配置却不生效」就会变成
+ * 难查的静默失败。
+ *
+ * 存 / 读都走引擎既有命令面：宿主不自己拼存档数据；写档失败的可见诊断由引擎出站事件
+ * 统一给出（见 `engine-wiring.ts`）。
+ */
+
+import {
+  resolveSavesConfig,
+  slotIds,
+  type StoryEngine,
+} from "@lingfan-engine/core";
+import type { StageDom } from "./stage-dom";
+
+/** 按工程清单里的存档壳配置填充槽位下拉（调用方保证只填一次） */
+export function fillSaveSlots(dom: StageDom, manifest: unknown): void {
+  const saves = resolveSavesConfig(manifest);
+  for (const id of slotIds(saves.slots)) {
+    const option = document.createElement("option");
+    option.value = id;
+    option.textContent = id;
+    dom.slot.append(option);
+  }
+}
+
+/** 接线存 / 读按钮：槽位取下拉当前选中值 */
+export function wireSaveSlots(dom: StageDom, engine: StoryEngine): void {
+  dom.save.addEventListener("click", () => {
+    engine.save(dom.slot.value);
+  });
+  dom.load.addEventListener("click", () => {
+    engine.load(dom.slot.value);
+  });
+}

package/template/__PROJECT__/src/host/stage-dom.ts

@@ -0,0 +1,74 @@
+/**
+ * 宿主节点契约：`index.html` 里那些固定 id 在宿主侧长什么样，以及出错往哪儿写。
+ *
+ * id 是宿主与页面的互锁（脚手架测试逐条核对每个 `must()` 的 id 都真的写在 `index.html` 里）。
+ * 缺节点必须在**模块求值期立刻抛错**，而不是等某次渲染静默失败——一行
+ * 「宿主缺少节点：#text」比在页面里找一个不动的 div 好查得多。所以 `must()` 的调用点
+ * 集中在组合根（`main.ts`）：那里一眼能看全宿主依赖了页面的哪些节点。
+ *
+ * 句柄只解析一次（不是每次渲染都查一遍）：页面结构是静态的，节点不会在运行期出现或消失。
+ * 各视图拿到的都是已确认存在的节点，因此不必自己查、也不必兜空。
+ */
+
+/** 按选择器取节点；缺失即抛（错误文案带上选择器，便于直接对照 `index.html`） */
+export function must<T extends HTMLElement>(selector: string): T {
+  const el = document.querySelector<T>(selector);
+  if (el === null) throw new Error(`宿主缺少节点：${selector}`);
+  return el;
+}
+
+/** 常驻节点句柄表：装配期就要用到、且页面里始终存在的那些 */
+export interface StageDom {
+  /** 舞台根：屏幕震动施加位移的对象 */
+  root: HTMLElement;
+  /** 舞台：元素层容器，也是元素动画节点的查找范围 */
+  stage: HTMLElement;
+  /** 对话层：说话人 / 正文 / 提示三件套的容器 */
+  dialogue: HTMLElement;
+  /** 说话人一行 */
+  speaker: HTMLElement;
+  /** 正文一行 */
+  text: HTMLElement;
+  /** 等待态提示符（对话等待时显示 ▼） */
+  hint: HTMLElement;
+  /** NVL 累积层 */
+  nvl: HTMLElement;
+  /** 等待态层：选项 / 输入 / 提示都渲染进这里 */
+  choices: HTMLElement;
+  /** 通知层：提示条追加到这里 */
+  notifications: HTMLElement;
+  /** 工具条：存档槽与存 / 读按钮 */
+  toolbar: HTMLElement;
+  /** 存档槽下拉 */
+  slot: HTMLSelectElement;
+  /** 存按钮 */
+  save: HTMLButtonElement;
+  /** 读按钮 */
+  load: HTMLButtonElement;
+  /** 全屏转场遮罩 */
+  transition: HTMLElement;
+  /** 引擎错误横幅 */
+  error: HTMLElement;
+}
+
+/**
+ * 造一个诊断出口：写进页面上的错误条**并**打控制台。
+ * 两条都要——页面上的那条给玩家看（黑屏时至少知道发生了什么），控制台那条给排查用。
+ * 引擎自己报的错误不走这里（它的控制台行带 `[engine]` 前缀，见 `engine-wiring.ts`）。
+ */
+export function createErrorReporter(dom: StageDom): (message: string) => void {
+  return (message: string): void => {
+    dom.error.textContent = message;
+    console.error(`[host] ${message}`);
+  };
+}
+
+/**
+ * 启动失败的可见出口：正文与错误条各写一行「启动失败：…」，原始错误进控制台。
+ * 装配中途失败时舞台是空的，这行字是玩家唯一能看到的线索。
+ */
+export function reportBootFailure(dom: StageDom, error: unknown): void {
+  dom.text.textContent = `启动失败：${String(error)}`;
+  dom.error.textContent = `启动失败：${String(error)}`;
+  console.error(error);
+}

package/template/__PROJECT__/src/host/theme-fonts.ts

@@ -0,0 +1,60 @@
+/**
+ * 项目默认字体（主题面，RenPy `gui.rpy` 的宿主对应物）：整条字体分辨链最宽的一档，
+ * 所有未显式声明字体的对话都落到它。取值必须是 Resources/Fonts 里的字体名；
+ * undefined = 未声明（对话排版走浏览器回退，逐句声明的字体照常生效）。
+ *
+ * 同时负责注入 @font-face（构建期清单来自 `virtual:story-fonts`，与 stories:build
+ * 的字体名注册表同源）——boot 早期一次性调用，纯展示装配，无运行时状态。
+ */
+import { storyFonts } from "virtual:story-fonts";
+
+/** 项目默认字体（Resources/Fonts 里的字体名；undefined = 未声明） */
+const PROJECT_DEFAULT_FONT: string | undefined = undefined;
+
+/** 根 CSS 变量名：对话排版消费它；运行期 setProperty 同名覆盖即显式切换 */
+const FONT_CSS_VAR = "--lf-story-font";
+
+/** 扩展名 → @font-face format()（与字体名注册表扩展名集合一致） */
+const FORMAT_BY_EXT: Record<string, string> = {
+  ".ttf": "truetype",
+  ".otf": "opentype",
+  ".woff": "woff",
+  ".woff2": "woff2",
+};
+
+/**
+ * 应用项目默认字体：先校验注册表，再把字体名写进根 CSS 变量。
+ * 开发态未注册 = 抛错（作者当面改）；生产态 = 告警回退浏览器默认（不拦启动）。
+ */
+function applyDefaultFont(): void {
+  if (PROJECT_DEFAULT_FONT === undefined) return;
+  const registered = storyFonts.some(
+    (entry) => entry.name === PROJECT_DEFAULT_FONT,
+  );
+  if (!registered) {
+    const message = `[fonts] 项目默认字体 "${PROJECT_DEFAULT_FONT}" 未在 Resources/Fonts 注册——请补字体文件或改 PROJECT_DEFAULT_FONT`;
+    if (import.meta.env.DEV) throw new Error(message);
+    console.warn(`${message}，已回退浏览器默认字体`);
+    return;
+  }
+  document.documentElement.style.setProperty(
+    FONT_CSS_VAR,
+    `'${PROJECT_DEFAULT_FONT}'`,
+  );
+}
+
+/** 注入 @font-face 并应用主题面（boot 一次性调用；空清单 = 不注入） */
+export function installStoryFonts(): void {
+  if (storyFonts.length > 0) {
+    const style = document.createElement("style");
+    style.textContent = storyFonts
+      .map(({ file, name }) => {
+        const ext = file.slice(file.lastIndexOf(".")).toLowerCase();
+        const format = FORMAT_BY_EXT[ext] ?? "truetype";
+        return `@font-face { font-family: '${name}'; src: url('/Fonts/${file}') format('${format}'); }`;
+      })
+      .join("\n");
+    document.head.appendChild(style);
+  }
+  applyDefaultFont();
+}

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

@@ -0,0 +1,29 @@
+/**
+ * 提示条：往通知层追加一条 toast，到点自己消失。
+ *
+ * 驻留时长是**可配置参数**，由调用方具名传入（不传则取展示层的默认名，其值即本宿主的
+ * 现状取值）；写死在模块里会让「换一个宿主」变成改共享代码。
+ */
+
+import { DEFAULT_TOAST_MS } from "@lingfan-engine/ui";
+import type { StageDom } from "./stage-dom";
+
+/** 提示函数的输入：通知层句柄与驻留毫秒数（缺省 = 展示层默认时长） */
+export interface ToastOptions {
+  /** 常驻节点句柄表 */
+  dom: StageDom;
+  /** 驻留毫秒数；缺省 = 展示层给出的默认时长 */
+  durationMs?: number;
+}
+
+/** 创建提示函数：多次调用互不影响，各条各自计时 */
+export function createToast(options: ToastOptions): (text: string) => void {
+  const durationMs = options.durationMs ?? DEFAULT_TOAST_MS;
+  return (text: string): void => {
+    const toast = document.createElement("div");
+    toast.className = "toast";
+    toast.textContent = text;
+    options.dom.notifications.append(toast);
+    window.setTimeout(() => toast.remove(), durationMs);
+  };
+}

package/template/__PROJECT__/src/main.ts

@@ -0,0 +1,61 @@
+/**
+ * 组合根（唯一全知位置：装配适配器 → 加载组装工程 → 建引擎 → 挂载展示层）。
+ *
+ * 本宿主**不依赖任何 UI 框架**——这是「引擎框架无关」的活证明：渲染直接操作 DOM，
+ * 换成 Vue / React / 其他只改本文件与 index.html，引擎与适配器零改动。
+ * 形态：**纯 Web**（vite 静态根 `Resources/`）——Tauri 壳的装配（invoke / 资源加密 /
+ * 方向锁定 / 宿主信息 / 热重载）见引擎仓库 `apps/playground` 的组合根。
+ *
+ * 本文件只做三件事，实现都在 `host/` 里：
+ *   1. 解析页面节点（`must` 调用点集中在此，与 index.html 的 id 互锁一眼可见）；
+ *   2. 声明本工程的清单与故事表（可配置项的取值来源）；
+ *   3. 调用 `bootHost` 装配并启动，失败写进页面。
+ *
+ * 覆盖范围（本宿主**保证不卡死**：引擎能进入的每个等待态都有 UI 可推进）：
+ *   dialogue / menu / input / wait / video / minigame（可见 fail-closed 提示）+
+ *   舞台元素层 + 层级表（shell.layers）+ 存档（shell.saves.slots）。
+ * 有意未做（属「少功能」而非「卡死」，见 README 边界表）：历史面板与回溯 UI、
+ * 玩家偏好面板、I18N 供给、对话框模板注册、存档缩略图合成。
+ */
+
+import { DEFAULT_TEXT_CPS, DEFAULT_TOAST_MS } from "@lingfan-engine/ui";
+import { bootHost, must, reportBootFailure, type StageDom } from "./host";
+
+/**
+ * 工程清单与故事文件：**都在应用资源根 `Resources/` 内**。
+ * 宿主把 `Resources` 作为静态根，故逻辑路径就是 `project.json` / `Stories/**`。
+ * 清单放在资源根内是有意为之——只有资源根内的文件才会进打包产物，dev 与 prod 同机制。
+ * **新增故事文件必须同步此表**（Web 形态按显式清单取文件）。
+ */
+const MANIFEST = "project.json";
+/** 本工程的故事文件表（相对资源根；新增故事必须同步此表） */
+const STORIES = ["Stories/title/title_main.story"];
+
+/** 页面节点句柄表：每个 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"),
+};
+
+void bootHost({
+  dom,
+  manifestFile: MANIFEST,
+  stories: STORIES,
+  defaultCps: DEFAULT_TEXT_CPS,
+  toastDurationMs: DEFAULT_TOAST_MS,
+}).catch((error: unknown) => {
+  reportBootFailure(dom, error);
+});

package/template/__PROJECT__/src/styles/stage.css

@@ -0,0 +1,183 @@
+/* RenderTargets 的落地：stage / dialogue / choices / notifications / toolbar。
+   **层级（z 序）不在这里写死**——由 src/main.ts 按「内建默认 × 工程覆盖
+   （project.json shell.layers）」解析后内联写入。 */
+:root {
+  color-scheme: dark;
+}
+body {
+  margin: 0;
+  background: #10131a;
+  color: #e6e6e6;
+  font-family: system-ui, "Microsoft YaHei", sans-serif;
+  /* 文本框选：台词、按钮、面板标签只作展示，拖动或连点不该留下选中段。
+     要提供复制能力时，给那个部件加 data-lf-selectable 放行，不在宿主外面破例。 */
+  user-select: none;
+  -webkit-user-select: none;
+}
+/* 放行名单：输入框要能选词改写；带 data-lf-selectable 的部件由给出复制操作的宿主自行标记 */
+input,
+textarea,
+[data-lf-selectable] {
+  user-select: text;
+  -webkit-user-select: text;
+}
+/* 舞台根：铺满视口；屏幕震动（shake）施加在它上面 */
+#stage-root {
+  position: fixed;
+  inset: 0;
+  overflow: hidden;
+}
+/* 舞台元素层：容器不阻塞点击（可交互元素自身恢复 pointer-events） */
+#stage {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+}
+/* 对话层 */
+#dialogue {
+  position: absolute;
+  right: 24px;
+  bottom: 24px;
+  left: 24px;
+  box-sizing: border-box;
+  border: 1px solid #2a3140;
+  border-radius: 10px;
+  background: rgba(20, 24, 33, 0.92);
+  padding: 16px 20px;
+  min-height: 96px;
+}
+#speaker {
+  color: #7aa2f7;
+  font-weight: 600;
+  margin-bottom: 8px;
+}
+#text {
+  line-height: 1.7;
+  white-space: pre-wrap;
+  /* 项目默认字体档：theme-fonts setProperty(--lf-story-font) 装配；未声明时
+     变量无效，属性落到继承值（等价不设），逐句声明的字体以内联样式覆盖 */
+  font-family: var(--lf-story-font);
+}
+#hint {
+  text-align: right;
+  color: #6b7280;
+  font-size: 12px;
+}
+/* NVL 累积层：与对话层同域，铺成阅读区 */
+#nvl {
+  position: absolute;
+  inset: 24px;
+  overflow: auto;
+  border: 1px solid #2a3140;
+  border-radius: 10px;
+  background: rgba(20, 24, 33, 0.94);
+  padding: 16px 20px;
+  line-height: 1.7;
+}
+/* 等待态层（各自渲染进 #choices） */
+#choices {
+  position: absolute;
+  top: 50%;
+  left: 24px;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  align-items: flex-start;
+  max-width: min(520px, calc(100% - 48px));
+  transform: translateY(-50%);
+}
+#choices:empty {
+  display: none;
+}
+.prompt {
+  margin: 0 0 4px;
+  color: #9aa5ce;
+}
+.choice {
+  padding: 8px 16px;
+}
+.input-row {
+  display: flex;
+  gap: 8px;
+}
+.input-row input {
+  min-width: 200px;
+}
+.note {
+  color: #6b7280;
+  font-size: 13px;
+}
+.banner {
+  border: 1px solid #e0af6888;
+  border-radius: 6px;
+  background: rgba(42, 36, 21, 0.9);
+  color: #e0af68;
+  padding: 8px 12px;
+}
+/* 通知 toast 层 */
+#notifications {
+  position: absolute;
+  top: 16px;
+  right: 16px;
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  align-items: flex-end;
+}
+.toast {
+  border: 1px solid #7aa2f755;
+  border-radius: 6px;
+  background: rgba(36, 40, 59, 0.94);
+  padding: 6px 12px;
+  font-size: 13px;
+}
+/* 工具条（存/读）：槽位数来自 project.json shell.saves.slots */
+#toolbar {
+  position: absolute;
+  top: 12px;
+  left: 12px;
+  display: flex;
+  gap: 8px;
+  align-items: center;
+  font-size: 13px;
+}
+button,
+select,
+input {
+  font: inherit;
+  color: #e6e6e6;
+  background: #1b2130;
+  border: 1px solid #2f3a4d;
+  border-radius: 6px;
+  padding: 4px 10px;
+}
+button {
+  cursor: pointer;
+}
+/* 全屏转场遮罩（transition）：屏幕级，恒在最上；透明度由帧驱动写入 */
+#transition {
+  position: absolute;
+  inset: 0;
+  display: none;
+  background: #000;
+  opacity: 0;
+  pointer-events: none;
+  z-index: 5000;
+}
+/* 引擎错误横幅（fail-closed 可见，不静默） */
+#error {
+  position: absolute;
+  top: 12px;
+  right: 12px;
+  left: 12px;
+  display: none;
+  border: 1px solid #f7768e88;
+  border-radius: 6px;
+  background: rgba(60, 20, 28, 0.94);
+  color: #f7768e;
+  padding: 8px 12px;
+  font-size: 13px;
+}
+#error:not(:empty) {
+  display: block;
+}

package/template/__PROJECT__/src/vite-env.d.ts

@@ -0,0 +1,14 @@
+/// <reference types="vite/client" />
+
+/**
+ * 字体清单的宿主侧声明（脚手架工程自带，与 vite.config 的虚拟模块对应）。
+ */
+declare module "virtual:story-fonts" {
+  /** 字体清单条目：file = 资源文件名，name = 字体名（文件名去扩展名） */
+  export interface StoryFontEntry {
+    file: string;
+    name: string;
+  }
+  /** 构建期扫描 Resources/Fonts 的字体清单（与 stories:build 注册表同源） */
+  export const storyFonts: readonly StoryFontEntry[];
+}

package/template/__PROJECT__/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "moduleResolution": "bundler",
+    "types": ["vite/client"],
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src/**/*.ts"]
+}

package/template/__PROJECT__/tsconfig.node.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "types": ["node"],
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true
+  },
+  "include": ["vite.config.ts"]
+}