@lingfan-engine/create 0.0.0-stage → 0.1.4

package/template/overlays/tauri/README.md

@@ -0,0 +1,59 @@
+# 桌面壳层（Tauri 2）
+
+这一层是**壳**，不是框架层：页面结构沿用骨架那一份，`index.html` 与 `vite.config.ts` 原样保留。
+加进来的只有工程根下的 `src-tauri/`、一份清单补丁，以及本层自己的组合根 `src/main.ts`——
+它覆盖骨架的同名文件，只把存档端口换成 Rust 实现。
+
+## 内容
+
+- `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` 脚本
+
+窗口 1280×720，标题取工程名；`frontendDist` 指向 `../dist`，开发期 `devUrl` 指向
+`http://localhost:1420`（与骨架 `vite.config.ts` 的 `server.port` 一致），所以 `beforeDevCommand`
+直接跑骨架的 `pnpm dev`。
+
+## 最小子集：只做两件事
+
+### 存档换成文件
+
+`save_write` / `save_read` / `save_delete` / `save_list`，一槽一文件落在应用数据目录的 `saves/` 下，
+写临时文件再改名，避免半截 JSON 覆盖好档；槽位名只放行字母数字与 `-` `_`，挡住 `..` 这类逃逸路径。
+
+为什么换：WebView 的 `localStorage` 落在系统给这个应用分配的 WebView 数据目录里，清缓存、换系统账户、
+重装都会带走存档；桌面工程的存档应当是可指路径上的文件。
+
+### 偏好换成文件
+
+`preferences_read` / `preferences_write`，明文落在 `app_data/preferences.json`——偏好只有音量、
+语言这类非敏感项，解密负担留在存档域；字段校验交给前端 `PlayerPreferences.hydrate`，
+新增偏好项不必同步改 Rust。
+
+命令名与参数形状是**跨语言契约**：`packages/adapters/src/save/tauri.ts` 与
+`src/preferences/tauriPreferences.ts` 按这些名字 invoke，改名要两边同时改。
+
+## 工程文件与资源：不换端口，也不造命令
+
+骨架的 `vite.config.ts` 把 `Resources/` 当静态根，打包时这些文件被复制进 `dist/`，
+所以打包后 `/project.json`、`/Stories/**`、`/Audio/x.mp3` 仍按同一套路径取得到。
+桌面壳不需要为此多造一组 Rust 命令，也不需要 `fs` 能力或 `asset` 协议——
+除非工程要读**运行时可变的**外部目录（那时该加的是一对「端口 + 适配器」，不是往本层塞命令）。
+
+## 故意不提供的
+
+资源加密、媒体 HTTP 服务、zip 索引、工程写回、开发期 WS——这些在参考宿主里有实现，
+本层不带。要加密或媒体服务的工程自己加：能力以端口 + 适配器成对出现，
+壳层只负责把端口接到原生侧（插口是骨架的 `src/ports.ts` 与 `bootHost` 的 `ports` 选项）。
+
+## 怎么用
+
+```bash
+pnpm install
+pnpm tauri dev
+```
+
+`pnpm tauri dev` 会先跑骨架的 `vite`，再编译 Rust 侧并开窗。首次编译要下依赖，耗时在 Rust 侧。
+
+打包命令（`pnpm tauri build`）本层不在自动化流程里跑，需要时由人手工执行。

package/template/overlays/tauri/package.patch.json

@@ -0,0 +1,14 @@
+{
+  "scripts": {
+    "tauri": "tauri"
+  },
+  "dependencies": {
+    "@tauri-apps/api": "^2"
+  },
+  "devDependencies": {
+    "@tauri-apps/cli": "^2"
+  },
+  "create": {
+    "pinned": ["@tauri-apps/cli", "@tauri-apps/api"]
+  }
+}

package/template/overlays/tauri/src/main.ts

@@ -0,0 +1,58 @@
+/**
+ * 组合根（桌面壳形态）：与骨架只差一处——把存档端口换成 Rust 实现。
+ *
+ * 为什么换存档：WebView 的 `localStorage` 落在系统给这个应用分配的 WebView 数据目录里，
+ * 清缓存、换系统账户、重装都会带走存档；桌面工程的存档应当是可指路径上的文件。
+ * 换法是把端口交给 `bootHost` 的 `ports.saves`，装配顺序与其余接线一行不改。
+ *
+ * 工程文件与资源**不换**：骨架的 `vite.config.ts` 把 `Resources/` 当静态根，
+ * 打包时这些文件被复制进 `dist/`，所以打包后 `/project.json`、`/Stories/**`、
+ * `/Audio/x.mp3` 仍按同一套路径取得到——桌面壳不需要为此多造一组 Rust 命令。
+ *
+ * 页面结构沿用骨架的 `index.html`（本层不带自己的），故节点解析与骨架同源。
+ */
+import { DEFAULT_TEXT_CPS, DEFAULT_TOAST_MS } from "@lingfan-engine/ui";
+import { createTauriSavePort } from "@lingfan-engine/adapters";
+import { bootHost, must, reportBootFailure, type StageDom } from "./host";
+
+/**
+ * 工程清单与故事文件：**都在应用资源根 `Resources/` 内**。
+ * 打包后它们位于 `dist/` 顶层，路径与开发期一致。
+ * **新增故事文件必须同步此表**（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,
+  ports: {
+    // 存档落到应用数据目录的 saves/ 下，一槽一文件（加密与回档保护在 Rust 侧扩展）
+    saves: createTauriSavePort(),
+  },
+}).catch((error: unknown) => {
+  reportBootFailure(dom, error);
+});

package/template/overlays/tauri/src-tauri/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "__project__"
+version = "0.1.0"
+edition = "2021"
+
+[lib]
+name = "app_lib"
+crate-type = ["staticlib", "cdylib", "rlib"]
+
+[build-dependencies]
+tauri-build = { version = "2", features = [] }
+
+[dependencies]
+tauri = { version = "2", features = [] }
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"

package/template/overlays/tauri/src-tauri/build.rs

@@ -0,0 +1,6 @@
+// Tauri 的构建期钩子：在编译 Rust 侧代码之前生成权限清单与上下文资源。
+// `tauri_build::build()` 会读取 `tauri.conf.json` 与 `capabilities/`，
+// 缺了这一步 `generate_context!()` 在编译期拿不到配置。
+fn main() {
+    tauri_build::build()
+}

package/template/overlays/tauri/src-tauri/capabilities/default.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "../gen/schemas/desktop-schema.json",
+  "identifier": "default",
+  "description": "主窗口的缺省权限集：只用 Tauri 核心能力，不额外开插件权限。",
+  "windows": ["main"],
+  "permissions": ["core:default"]
+}

package/template/overlays/tauri/src-tauri/src/lib.rs

@@ -0,0 +1,26 @@
+//! 库入口：装配 Tauri 应用并注册命令表。
+//!
+//! 拆出 `lib.rs` 是为了让移动端也能复用同一份 `run()`（移动端由外部运行器链接
+//! `app_lib`，没有自己的 `main`）。桌面端 `main.rs` 只做一次转发。
+//!
+//! 命令分两个域注册：存档（`save/`）与偏好（`preferences/`）。新增命令时在对应
+//! 域的模块里实现，再到 `invoke_handler` 里点名——Tauri 不做按模块自动收集。
+
+mod preferences;
+mod save;
+
+/// 启动应用。命令名必须与前端 `packages/adapters/src/save/tauri.ts`、
+/// `src/preferences/tauriPreferences.ts` 里的 `invoke(...)` 逐字一致。
+pub fn run() {
+    tauri::Builder::default()
+        .invoke_handler(tauri::generate_handler![
+            save::save_write,
+            save::save_read,
+            save::save_delete,
+            save::save_list,
+            preferences::preferences_read,
+            preferences::preferences_write,
+        ])
+        .run(tauri::generate_context!())
+        .expect("Tauri 应用启动失败");
+}

package/template/overlays/tauri/src-tauri/src/main.rs

@@ -0,0 +1,7 @@
+// 可执行入口：只做一件事——把控制权交给库里的 `run()`。
+// 发布构建下隐藏 Windows 控制台窗口（`windows_subsystem`），调试构建保留它以便看日志。
+#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
+
+fn main() {
+    app_lib::run()
+}

package/template/overlays/tauri/src-tauri/src/preferences.rs

@@ -0,0 +1,50 @@
+//! 偏好域的 Rust 侧实现：`preferences_read` / `preferences_write` 两条命令。
+//!
+//! 与存档的差别在于**不加密**：偏好只有音量、语言、窗口尺寸这类非敏感项，
+//! 密钥管理留在存档域。文件落在应用数据目录的 `preferences.json`，明文 JSON。
+//!
+//! 字段校验不在这里做：读回来的值原样交给前端，由引擎的 `PlayerPreferences.hydrate`
+//! 兜非法字段并退回缺省值。这样新增偏好项时不需要同步改 Rust。
+
+use std::fs;
+use std::path::PathBuf;
+
+use serde_json::Value;
+use tauri::{AppHandle, Manager};
+
+/// 偏好文件路径。
+fn prefs_path(app: &AppHandle) -> Result<PathBuf, String> {
+    let dir = app
+        .path()
+        .app_data_dir()
+        .map_err(|e| format!("取应用数据目录失败: {e}"))?;
+    fs::create_dir_all(&dir).map_err(|e| format!("建应用数据目录失败: {e}"))?;
+    Ok(dir.join("preferences.json"))
+}
+
+#[tauri::command]
+pub fn preferences_read(app: AppHandle) -> Result<Option<Value>, String> {
+    let path = prefs_path(&app)?;
+    // 第一次启动没有这个文件，返回 None 让前端取缺省值，不当成错误。
+    let text = match fs::read_to_string(&path) {
+        Ok(text) => text,
+        Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(None),
+        Err(e) => return Err(format!("读偏好失败: {e}")),
+    };
+    match serde_json::from_str::<Value>(&text) {
+        Ok(value) => Ok(Some(value)),
+        // 文件被手工改坏时按「没有偏好」处理：偏好不值得为它挡住启动。
+        Err(_) => Ok(None),
+    }
+}
+
+#[tauri::command]
+pub fn preferences_write(app: AppHandle, prefs: Value) -> Result<(), String> {
+    let path = prefs_path(&app)?;
+    let text = serde_json::to_string_pretty(&prefs).map_err(|e| format!("序列化偏好失败: {e}"))?;
+    // 与存档同法：临时文件 + 改名，避免半截 JSON 覆盖掉还能读的旧偏好。
+    let tmp = path.with_extension("json.tmp");
+    fs::write(&tmp, text).map_err(|e| format!("写偏好失败: {e}"))?;
+    fs::rename(&tmp, &path).map_err(|e| format!("替换偏好失败: {e}"))?;
+    Ok(())
+}

package/template/overlays/tauri/src-tauri/src/save.rs

@@ -0,0 +1,178 @@
+//! 存档域的 Rust 侧实现：`save_write` / `save_read` / `save_delete` / `save_list` 四条命令。
+//!
+//! 命令名与参数形状是**跨语言契约**：前端 `packages/adapters/src/save/tauri.ts` 按这些名字
+//! invoke，改名或改参数键就要两边同时改。槽位摘要是 snake_case，前端自己做 camelCase 映射。
+//!
+//! 存档落在应用数据目录的 `saves/` 下，一槽一文件（`<slot>.json`），先写临时文件再改名，
+//! 避免进程在写一半时被杀留下半个存档。
+
+use std::fs;
+use std::path::PathBuf;
+
+use serde::{Deserialize, Serialize};
+use tauri::{AppHandle, Manager};
+
+/// `save_list` 的返回行。字段名保持 snake_case，前端按这个形状映射成引擎的槽位摘要。
+#[derive(Serialize, Deserialize)]
+pub struct SlotSummary {
+    pub slot: String,
+    pub save_count: u32,
+    pub timestamp: u64,
+    pub mode: String,
+}
+
+/// 存档目录：应用数据目录下的 `saves/`，不存在时创建。
+fn saves_dir(app: &AppHandle) -> Result<PathBuf, String> {
+    let dir = app
+        .path()
+        .app_data_dir()
+        .map_err(|e| format!("取应用数据目录失败: {e}"))?
+        .join("saves");
+    fs::create_dir_all(&dir).map_err(|e| format!("建存档目录失败: {e}"))?;
+    Ok(dir)
+}
+
+/// 校验槽位名。槽位名来自调用方，`..` 或路径分隔符会逃出存档目录，
+/// 因此只放行 ASCII 字母数字与 `-` `_`。
+///
+/// 单独拆出来是为了能直接对校验规则做单元测试：`slot_path` 需要 `AppHandle`，
+/// 在测试里造不出来。
+fn validate_slot(slot: &str) -> Result<(), String> {
+    if slot.is_empty()
+        || !slot
+            .chars()
+            .all(|c| c.is_ascii_alphanumeric() || c == '-' || c == '_')
+    {
+        return Err(format!("非法槽位名: {slot}"));
+    }
+    Ok(())
+}
+
+/// 单个槽位的文件路径。
+fn slot_path(app: &AppHandle, slot: &str) -> Result<PathBuf, String> {
+    validate_slot(slot)?;
+    Ok(saves_dir(app)?.join(format!("{slot}.json")))
+}
+
+#[tauri::command]
+pub fn save_write(
+    app: AppHandle,
+    slot: String,
+    payload: String,
+    mode: String,
+) -> Result<(), String> {
+    let target = slot_path(&app, &slot)?;
+    let body = serde_json::json!({
+        "slot": slot,
+        "mode": mode,
+        "timestamp": now_secs(),
+        "payload": payload,
+    });
+    let text = serde_json::to_string(&body).map_err(|e| format!("序列化存档失败: {e}"))?;
+
+    // 先写临时文件再改名：改名在同一文件系统内是原子的，
+    // 中途崩溃只会留下临时文件，不会让槽位文件变成半截 JSON。
+    let tmp = target.with_extension("json.tmp");
+    fs::write(&tmp, text).map_err(|e| format!("写存档失败: {e}"))?;
+    fs::rename(&tmp, &target).map_err(|e| format!("替换存档失败: {e}"))?;
+    Ok(())
+}
+
+#[tauri::command]
+pub fn save_read(app: AppHandle, slot: String) -> Result<String, String> {
+    let target = slot_path(&app, &slot)?;
+    let text = fs::read_to_string(&target).map_err(|e| format!("读存档失败: {e}"))?;
+    let body: serde_json::Value =
+        serde_json::from_str(&text).map_err(|e| format!("存档不是合法 JSON: {e}"))?;
+    // 只把 payload 还给前端：外面那层是本实现的封套，不属于存档内容。
+    body.get("payload")
+        .and_then(|v| v.as_str())
+        .map(|s| s.to_string())
+        .ok_or_else(|| format!("存档 {slot} 缺少 payload 字段"))
+}
+
+#[tauri::command]
+pub fn save_delete(app: AppHandle, slot: String) -> Result<(), String> {
+    let target = slot_path(&app, &slot)?;
+    // 槽位本就不存在时视为成功：删档是幂等操作，重试不该报错。
+    match fs::remove_file(&target) {
+        Ok(()) => Ok(()),
+        Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(()),
+        Err(e) => Err(format!("删档失败: {e}")),
+    }
+}
+
+#[tauri::command]
+pub fn save_list(app: AppHandle) -> Result<Vec<SlotSummary>, String> {
+    let dir = saves_dir(&app)?;
+    let mut out = Vec::new();
+    let entries = fs::read_dir(&dir).map_err(|e| format!("列存档目录失败: {e}"))?;
+    for entry in entries.flatten() {
+        let path = entry.path();
+        // 只认 `.json`：临时文件与别的东西不参与列表。
+        if path.extension().and_then(|e| e.to_str()) != Some("json") {
+            continue;
+        }
+        let Ok(text) = fs::read_to_string(&path) else {
+            continue;
+        };
+        let Ok(body) = serde_json::from_str::<serde_json::Value>(&text) else {
+            continue;
+        };
+        let slot = body
+            .get("slot")
+            .and_then(|v| v.as_str())
+            .map(|s| s.to_string())
+            .unwrap_or_else(|| {
+                path.file_stem()
+                    .and_then(|s| s.to_str())
+                    .unwrap_or_default()
+                    .to_string()
+            });
+        out.push(SlotSummary {
+            slot,
+            save_count: body.get("save_count").and_then(|v| v.as_u64()).unwrap_or(1) as u32,
+            timestamp: body.get("timestamp").and_then(|v| v.as_u64()).unwrap_or(0),
+            mode: body
+                .get("mode")
+                .and_then(|v| v.as_str())
+                .unwrap_or("normal")
+                .to_string(),
+        });
+    }
+    // 新的排前面：前端列表直接取这个顺序当「最近存档」。
+    out.sort_by(|a, b| b.timestamp.cmp(&a.timestamp));
+    Ok(out)
+}
+
+/// 当前时间（秒）。只用于列表排序与展示，不参与任何校验。
+fn now_secs() -> u64 {
+    std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map(|d| d.as_secs())
+        .unwrap_or(0)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::validate_slot;
+
+    #[test]
+    fn accepts_regular_slot_names() {
+        for slot in ["slot1", "Slot_2", "a-b_c", "9"] {
+            assert!(validate_slot(slot).is_ok(), "{slot} 应当被接受");
+        }
+    }
+
+    #[test]
+    fn rejects_empty_slot_name() {
+        assert!(validate_slot("").is_err());
+    }
+
+    #[test]
+    fn rejects_names_escaping_save_dir() {
+        for slot in ["..", "../etc", "a/b", "a\\b", "a.b", "slot 1"] {
+            assert!(validate_slot(slot).is_err(), "{slot} 应当被拒绝");
+        }
+    }
+}

package/template/overlays/tauri/src-tauri/tauri.conf.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://schema.tauri.app/config/2",
+  "productName": "__PROJECT__",
+  "version": "0.1.0",
+  "identifier": "com.example.__project__",
+  "build": {
+    "frontendDist": "../dist",
+    "devUrl": "http://localhost:1420",
+    "beforeDevCommand": "pnpm dev",
+    "beforeBuildCommand": "pnpm build"
+  },
+  "app": {
+    "windows": [
+      {
+        "title": "__PROJECT__",
+        "width": 1280,
+        "height": 720
+      }
+    ],
+    "security": {
+      "csp": null
+    }
+  },
+  "bundle": {
+    "active": true,
+    "targets": "all",
+    "icon": [
+      "icons/32x32.png",
+      "icons/128x128.png",
+      "icons/128x128@2x.png",
+      "icons/icon.icns",
+      "icons/icon.ico"
+    ]
+  }
+}

package/template/overlays/vue/index.html

@@ -0,0 +1,16 @@
+<!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>
+    <!-- Vue 的挂载点：层结构在 src/App.vue 里声明，样式仍在 src/styles/stage.css -->
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/template/overlays/vue/package.patch.json

@@ -0,0 +1,16 @@
+{
+  "dependencies": {
+    "vue": "^3.5.44"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.3",
+    "@vitejs/plugin-vue": "^6.0.10",
+    "vue-tsc": "^3.3.5"
+  },
+  "scripts": {
+    "typecheck": "vue-tsc --noEmit && tsc --noEmit -p tsconfig.node.json"
+  },
+  "create": {
+    "pinned": ["typescript"]
+  }
+}

package/template/overlays/vue/src/App.vue

@@ -0,0 +1,30 @@
+<!--
+  页面结构（Vue 形态）：与骨架的 index.html 逐层对齐——引擎与适配器不认识它，
+  换框架只改这份模板与组合根。所有 id 都是与引擎侧共用的契约，改名必须同步
+  `src/main.ts` 里的句柄表与 `src/styles/stage.css`。
+
+  本组件**不碰引擎**：装配在 `src/main.ts`（唯一组合根），交互监听由骨架的
+  `src/host/` 用原生事件绑定——Vue 在这里只负责把节点渲染出来。
+-->
+<template>
+  <!-- 舞台根：屏幕震动（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>
+</template>

package/template/overlays/vue/src/main.ts

@@ -0,0 +1,68 @@
+/**
+ * 组合根（Vue 形态）：装配适配器 → 加载组装工程 → 建引擎 → 挂载展示层。
+ *
+ * 与骨架的差别只有「谁渲染页面结构」：这里先 `createApp(App).mount("#app")`，
+ * 再读节点句柄——引擎要的 15 个节点由 `App.vue` 渲染出来，挂载前 `must` 只会抛。
+ * 骨架的 `src/host/` 一行未改：它操作的是 `StageDom` 句柄表，不认识 Vue。
+ *
+ * 页面的层结构在 `src/App.vue`，样式在 `src/styles/stage.css`（两者都来自模板骨架，
+ * 本层只替换入口与组合根）。
+ */
+import { createApp } from "vue";
+import { DEFAULT_TEXT_CPS, DEFAULT_TOAST_MS } from "@lingfan-engine/ui";
+import { bootHost, must, reportBootFailure, type StageDom } from "./host";
+import App from "./App.vue";
+
+/**
+ * 工程清单与故事文件：**都在应用资源根 `Resources/` 内**。
+ * 宿主把 `Resources` 作为静态根，故逻辑路径就是 `project.json` / `Stories/**`。
+ * **新增故事文件必须同步此表**（Web 形态按显式清单取文件）。
+ */
+const MANIFEST = "project.json";
+/** 本工程的故事文件表（相对资源根；新增故事必须同步此表） */
+const STORIES = ["Stories/title/title_main.story"];
+
+/** 页面节点句柄表：每个 id 都必须由 `App.vue` 渲染（缺一个 `must` 当场抛） */
+function readDom(): StageDom {
+  return {
+    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"),
+  };
+}
+
+/** 挂载页面结构；失败（含节点缺失）写进页面错误条，不留白屏 */
+function mountApp(): StageDom | undefined {
+  try {
+    createApp(App).mount("#app");
+    return readDom();
+  } catch (error) {
+    console.error(error);
+    return undefined;
+  }
+}
+
+const dom = mountApp();
+if (dom !== undefined) {
+  void bootHost({
+    dom,
+    manifestFile: MANIFEST,
+    stories: STORIES,
+    defaultCps: DEFAULT_TEXT_CPS,
+    toastDurationMs: DEFAULT_TOAST_MS,
+  }).catch((error: unknown) => {
+    reportBootFailure(dom, error);
+  });
+}