@lingfan-engine/create 0.0.0-stage → 0.1.5

package/template/__PROJECT__/vite.config.ts

@@ -0,0 +1,64 @@
+import { existsSync, readdirSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { defineConfig, type Plugin } from "vite";
+
+/** 字体文件扩展名集合（与 stories-build 的字体名注册表同口径） */
+const FONT_EXTENSIONS = [".ttf", ".otf", ".woff", ".woff2"] as const;
+
+/** 字体清单条目：file = 资源文件名，name = 字体名（文件名去扩展名） */
+interface StoryFontEntry {
+  file: string;
+  name: string;
+}
+
+/** Resources/Fonts 扫描：点文件与未知扩展名跳过，文件名字典序稳定 */
+function scanFonts(fontsDir: string): readonly StoryFontEntry[] {
+  if (!existsSync(fontsDir)) return [];
+  return readdirSync(fontsDir)
+    .filter((file) => {
+      const dot = file.lastIndexOf(".");
+      return (
+        dot > 0 &&
+        (FONT_EXTENSIONS as readonly string[]).includes(
+          file.slice(dot).toLowerCase(),
+        )
+      );
+    })
+    .sort()
+    .map((file) => ({ file, name: file.slice(0, file.lastIndexOf(".")) }));
+}
+
+/**
+ * 字体清单虚拟模块：构建期扫描 Resources/Fonts 产出字体名清单，
+ * 宿主据此注入 @font-face 与项目默认字体——字体名注册表与 stories:build 同源，
+ * 零新增依赖（脚手架工程保持可独立安装）。
+ */
+function storyFontsVirtual(): Plugin {
+  const moduleId = "virtual:story-fonts";
+  const fontsDir = fileURLToPath(new URL("./Resources/Fonts", import.meta.url));
+  return {
+    name: "story-fonts",
+    resolveId(id) {
+      if (id === moduleId) return `\0${moduleId}`;
+      return null;
+    },
+    load(id) {
+      if (id === `\0${moduleId}`) {
+        return `export const storyFonts = ${JSON.stringify(scanFonts(fontsDir))};`;
+      }
+      return null;
+    },
+  };
+}
+
+/** 脚手架工程的 Vite 配置：仅约定资源根与宿主端口，其余随宿主需要自行扩展。 */
+export default defineConfig({
+  // 项目资源根即静态根 —— 故事里的逻辑路径 `Audio/x.mp3` 解析为 `/Audio/x.mp3`，
+  // 开发与打包产物一致，不依赖进程工作目录。资源根之外无隐式查找路径。
+  publicDir: "Resources",
+
+  // 宿主端口与 Tauri 约定一致；换平台壳时只改这里
+  server: { port: 1420, strictPort: true },
+
+  plugins: [storyFontsVirtual()],
+});

package/template/overlays/README.md

@@ -0,0 +1,70 @@
+# 叠加层
+
+每个子目录是一层可选的工程内容，目录名就是 `template-meta.json` 里 `frameworks[]` / `shells[]` 的 `id`。
+生成器按「骨架 → 框架层 → 壳层」的顺序合并，同路径文件由后一层覆盖前一层。
+
+## 缺省项没有目录
+
+`none`（框架无关）与 `browser`（浏览器）表示「这一层什么都不加」，所以这里看不到它们。
+缺目录不是错误，只是没有内容可叠。
+
+## 现有层
+
+- `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/**` 一行不改，
+  样式仍用骨架的 `src/styles/stage.css`。
+- `react/` —— 页面结构换成 JSX 组件：`index.html` 变成挂载点（`#app`），新增 `src/App.tsx`
+  （渲染骨架 `must()` 要的全部节点）、React 版组合根 `src/main.tsx`（先 `createRoot` 挂载再读节点句柄，
+  然后 `bootHost`）与 `src/vite-env.d.ts`，`vite.config.ts` 在骨架配置上多一个 `@vitejs/plugin-react`
+  （`publicDir`、`server.port` 与字体虚拟模块逐项保留），`tsconfig.json` 打开 `jsx: react-jsx`。
+  `package.patch.json` 补 `react` / `react-dom` 与 `@types/react` / `@types/react-dom` /
+  `@vitejs/plugin-react` / `@types/node`，并把 `typecheck` 换成
+  `tsc --noEmit && tsc --noEmit -p tsconfig.node.json`。`src/host/**` 一行不改，
+  样式仍用骨架的 `src/styles/stage.css`。
+- `miniprogram/` —— 壳层，换掉整套页面与宿主：页面结构由 `src/components/**` 承接（`stage-canvas`、
+  `stage-video` 两个 id 落在组件模板里），宿主装配在 `src/mp/**`（`uni.*` 只在
+  `src/mp/platform.ts` 出现一处），`src/main.ts` 按 UniApp 约定返回 `createSSRApp`，
+  另有 `src/pages.json`、`src/manifest.json` 与开发期内容服务 `scripts/serve-project.mjs`。
+  `vite.config.ts` 保留 `publicDir: "Resources"` 供 H5 形态取资源，同时用
+  `build.copyPublicDir: false` 让小程序包体只有代码；`vite` 与 `vue` 钉在 UniApp 插件要求的
+  那一代（`create.pinned` 保住），`tsconfig.json` 排除 `src/host/**`——那是浏览器形态的宿主，
+  本形态不用它。
+- `tauri/` —— 壳层，只加桌面外壳、不碰页面：新增 `src-tauri/`（`Cargo.toml`、`build.rs`、
+  `tauri.conf.json`、`capabilities/default.json`、`src/{main,lib,save,preferences}.rs`）与
+  一份覆盖骨架的组合根 `src/main.ts`（`ports.saves` 换成 `createTauriSavePort()`，其余端口不换）。
+  `package.patch.json` 补 `@tauri-apps/api` / `@tauri-apps/cli` 与 `tauri` 脚本，
+  `@tauri-apps/*` 用 `create.pinned` 钉住。`index.html`、`vite.config.ts` 与 `src/host/**`
+  全部沿用骨架：`Resources/` 是 `publicDir`，打包时复制进 `dist/`，所以工程文件与资源仍按
+  同一套路径取，不需要额外命令。
+
+## 钉住版本
+
+`package.patch.json` 可以带一个生成期字段 `create.pinned`：数组里点名的依赖不参与
+「查 registry 写最新版」，版本区间保持骨架记录的原值，写盘前这个字段本身会被抹掉。
+
+```json
+{ "create": { "pinned": ["typescript"] } }
+```
+
+存在的理由：模板希望依赖尽量新，但上游并非都兼容——`vue-tsc` 在 `typescript` 7 上会因
+`./lib/tsc` 不再导出而直接崩，这类约束只有层作者知道。只有确实需要时才钉，钉住的包不会再跟到
+最新版。
+
+## 一层里能放什么
+
+- 任意工程文件：路径相对工程根，与骨架同名即覆盖。
+- `package.patch.json`（只在层根）：深合并进产物 `package.json`。依赖表按字段合并，
+  数组与标量整体取代——数组拼接会得到既非骨架也非叠加层的第三种值。
+
+新增依赖只写进 `package.patch.json`，不要复制整份 `package.json`：整份复制会让骨架后来加的字段
+在这一层永久丢失。生成器会在合并之后统一查一次 registry，把依赖写成当下最新的 `^x.y.z`。
+
+## 新增一层
+
+1. 在 `template-meta.json` 的 `frameworks` 或 `shells` 里加一项 `{ id, label, hint }`。
+2. 建同名目录，放入该层独有的文件与 `package.patch.json`。
+3. 生成器不改：它对目录是缺席即跳过，不需要为新 `id` 写分支。
+
+一层只加自己真正需要的东西。能被骨架覆盖的差异（比如只换一个入口文件的 import）优先留在骨架里，
+叠加层越多，同一处逻辑就有越多份副本要跟着改。

package/template/overlays/miniprogram/README.md

@@ -0,0 +1,104 @@
+# **PROJECT**
+
+灵泛叙事引擎工程的小程序形态：页面层是 UniApp（Vue 3）单文件组件，宿主装配在 `src/mp/**`，
+内容（故事与素材）不进包体，走 HTTP 从工程接口取。
+
+## 目录
+
+| 路径                                  | 作用                                                                 |
+| ------------------------------------- | -------------------------------------------------------------------- |
+| `src/pages/index/index.vue`           | 页面装配：取画布、把宿主补丁写进页面状态、把手势转回覆盖层           |
+| `src/components/**`                   | 舞台、对话、选择、通知四层，加存读条与递归节点树                     |
+| `src/mp/**`                           | 小程序宿主：`uni` 能力封装、端口、渲染数据、覆盖层、视频、帧源、守卫 |
+| `src/App.vue`、`src/main.ts`          | 应用外壳与 UniApp 约定入口                                           |
+| `src/pages.json`、`src/manifest.json` | 页面与平台声明                                                       |
+| `Resources/`                          | 内容根：清单、故事、音频、视频、图片（**不随包体分发**）             |
+| `scripts/serve-project.mjs`           | 开发期内容服务                                                       |
+| `src/host/**`                         | 浏览器形态的宿主，本形态不使用（见「已知残留」）                     |
+
+## 起工程
+
+先起内容服务：它把 `Resources/` 按宿主的取法提供出去（`GET /project` 一次返回
+`{manifest, stories}`，`GET /<资源 id>` 取素材本体）。
+
+```bash
+node scripts/serve-project.mjs        # 缺省 127.0.0.1:5273，--port / --host / --root 可改
+```
+
+再编译页面，用微信开发者工具导入产物目录：
+
+```bash
+pnpm dev:mp        # 等价 uni -p mp-weixin，产物在 dist/dev/mp-weixin
+pnpm build:mp      # 生产产物在 dist/build/mp-weixin
+```
+
+想在浏览器里先看效果（同一份页面代码）：
+
+```bash
+pnpm dev:h5        # 等价 uni
+```
+
+开发者工具里需要勾上「不校验合法域名」（开发期），生产换成自己的 HTTPS 域名；
+`manifest.json` 的 `appid` 是空的，导入时填自己的。
+
+内容服务只是开发期的替代品：生产形态由静态托管 + 后端接口承担同一套取法
+（`GET <基址>/project`、`GET <基址>/<资源 id>`），宿主只换基址。基址用环境变量
+`VITE_PROJECT_BASE_URL` 覆盖，缺省指向上面那个本地端口。
+
+## 与浏览器形态的差别
+
+- **谁渲染页面结构**：浏览器形态由 `index.html` 的静态节点承接 `must("#id")` 契约；这里由
+  `src/components/**` 承接（`stage-canvas`、`stage-video` 两个 id 落在组件模板里）。
+- **帧源**：浏览器用 `requestAnimationFrame`；这里取 `canvas` 的 2d 节点，取不到（或 300ms
+  内没拿到）就退回 16ms 定时器，叙事照常推进，动画粒度略粗。
+- **尺寸单位**：页面样式按平台惯例用 `rpx`（宽度基准 750），横屏媒体查询里换回 `px`。舞台盒
+  的缩放与平移仍由 `computeStageLayout` 算，与单位无关。
+- **平台能力入口**：`uni.*` 只在 `src/mp/platform.ts` 出现一处，其余全是端口；换端只改那一处。
+
+## 包体只有代码
+
+故事与素材不随包分发：内容走工程接口，素材走资源端口按 id 取（`Audio/x.mp3` →
+`<基址>/Audio/x.mp3`）。改内容不必重新提审发版。
+
+构建配置因此是 `publicDir: "Resources"` + `build.copyPublicDir: false`：资源根仍指向同一个
+目录（H5 形态直接读它），但不进包体。
+
+## 有意不做的事
+
+- **不写原生 WXML/WXSS**：页面一律是 Vue 3 SFC，由 uni 编译成平台节点，H5 与小程序共用同一份
+  页面代码。
+- **不做节点树以外的渲染**：舞台元素走递归节点树（`view`/`text`/`rich-text`/`image`），不接管
+  WebGL/Canvas 绘制。需要自定义绘制时另开端口，别塞进宿主。
+- **不内建登录/支付/分享**：这里只做叙事播放面，平台能力按需另接。
+
+## 依赖钉版
+
+`@dcloudio/vite-plugin-uni` 的 peer 把 `vite` 钉在 `5.2.8`、`@vue/shared` 钉在 `3.4.21`，
+与仓库根的 `vite ^8` / `vue ^3.5` 不是一代。本工程因此自带一份 `vite 5.2.8` 与 `vue 3.4.21`，
+靠包管理器的隔离安装各用各的（`package.json` 里是把这些包写进 `create.pinned` 才保住的：
+不钉住，脚手架会统一改写成 `^最新`，peer 立刻就破）。
+
+代价：`vite.config.ts` 不能跟着升到 8，脚本与插件类型按 5 的形态写；上游哪天跟进新 vite，
+这三处（`vite`、`vue`、插件）要成对改完再放开钉版。
+
+## 已知残留
+
+`src/host/**` 与 `src/styles/stage.css` 是骨架的浏览器宿主，本形态不使用：没有人 import 它们，
+`tsconfig.json` 已把两者排除，类型检查不会碰。脚手架目前只做「同路径覆盖」、没有删除能力，
+所以它们会留在工程里；删掉不影响运行。
+
+## 验收这条链路
+
+```bash
+pnpm typecheck                                   # vue-tsc + tsc（含 vite.config.ts）
+node scripts/serve-project.mjs --root Resources
+curl http://127.0.0.1:5273/project | head -c 200
+```
+
+`pnpm dev:mp` 之后用开发者工具导入 `dist/dev/mp-weixin`，模拟器里应当直接进标题页。
+
+---
+
+本工程由脚手架按「框架无关骨架 + 小程序叠加层」生成：`src/mp/**`、`src/components/**`、
+`src/pages/**`、`index.html` 与 `package.json` 的增量来自该层，其余来自骨架。
+改模板请在模板仓库里改，不要只改这一个工程。

package/template/overlays/miniprogram/index.html

@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no"
+    />
+    <title>__PROJECT__</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/template/overlays/miniprogram/package.patch.json

@@ -0,0 +1,40 @@
+{
+  "dependencies": {
+    "@dcloudio/uni-app": "3.0.0-4080720251210001",
+    "@dcloudio/uni-components": "3.0.0-4080720251210001",
+    "@dcloudio/uni-h5": "3.0.0-4080720251210001",
+    "@dcloudio/uni-mp-weixin": "3.0.0-4080720251210001",
+    "@lingfan-engine/shell": "^0.1.0",
+    "vue": "3.4.21"
+  },
+  "devDependencies": {
+    "@dcloudio/types": "3.4.19",
+    "@dcloudio/uni-cli-shared": "3.0.0-4080720251210001",
+    "@dcloudio/vite-plugin-uni": "3.0.0-4080720251210001",
+    "vite": "5.2.8",
+    "vue-tsc": "^3.3.5"
+  },
+  "scripts": {
+    "dev": "uni -p mp-weixin",
+    "dev:h5": "uni",
+    "dev:mp": "uni -p mp-weixin",
+    "build": "uni build -p mp-weixin",
+    "build:h5": "uni build -p h5",
+    "build:mp": "uni build -p mp-weixin",
+    "typecheck": "vue-tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.node.json"
+  },
+  "create": {
+    "pinned": [
+      "@dcloudio/types",
+      "@dcloudio/uni-app",
+      "@dcloudio/uni-cli-shared",
+      "@dcloudio/uni-components",
+      "@dcloudio/uni-h5",
+      "@dcloudio/uni-mp-weixin",
+      "@dcloudio/vite-plugin-uni",
+      "typescript",
+      "vite",
+      "vue"
+    ]
+  }
+}

package/template/overlays/miniprogram/scripts/serve-project.mjs

@@ -0,0 +1,273 @@
+#!/usr/bin/env node
+/**
+ * 本地开发服务：把工程根下的 `Resources/` 按小程序宿主的取法提供出去（仅开发用）。
+ *
+ * 两条路由，对应宿主的两类请求：
+ * - `GET /project` → `{ manifest, stories }`：清单 + 全部故事原文合成一次响应
+ *   （故事原文不解析，解析归引擎的组装器——与线上接口的约定一致）；
+ * - `GET /<资源 id>` → 资源文件本体（`Audio/x.mp3`、`Video/x.mp4`…），支持 Range
+ *   （视频拖动、在线播放都要它）。
+ *
+ * 内容根缺省指工程的资源根 `Resources/`：与骨架 `vite.config.ts` 的 `publicDir` 同一处，
+ * 一个工程只有一份内容，开发服务与浏览器形态读的是同一批文件。
+ *
+ * 生产形态不需要这个脚本：同一套取法由静态托管 + 后端接口承担，宿主只换基址。
+ *
+ * 用法：`node scripts/serve-project.mjs [--port 5273] [--host 127.0.0.1] [--root <目录>]`
+ */
+import { createReadStream } from "node:fs";
+import { readFile, readdir, stat } from "node:fs/promises";
+import { createServer } from "node:http";
+import { extname, join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** 内容根（缺省 = 工程根下的 `Resources/`） */
+const DEFAULT_ROOT = resolve(
+  fileURLToPath(new URL(".", import.meta.url)),
+  "..",
+  "Resources",
+);
+/** 缺省端口：与宿主 `project-source.ts` 的缺省基址一致 */
+const DEFAULT_PORT = 5273;
+/** 缺省只绑回环：开发服务不对外 */
+const DEFAULT_HOST = "127.0.0.1";
+/** 故事目录（相对内容根） */
+const STORIES_DIR = "Stories";
+/** 扩展名 → Content-Type */
+const MIME_TYPES = new Map([
+  [".json", "application/json; charset=utf-8"],
+  [".story", "text/plain; charset=utf-8"],
+  [".mp3", "audio/mpeg"],
+  [".mp4", "video/mp4"],
+  [".webm", "video/webm"],
+  [".m4a", "audio/mp4"],
+  [".ogg", "audio/ogg"],
+  [".png", "image/png"],
+  [".jpg", "image/jpeg"],
+  [".jpeg", "image/jpeg"],
+  [".webp", "image/webp"],
+  [".ttf", "font/ttf"],
+  [".otf", "font/otf"],
+  [".woff2", "font/woff2"],
+]);
+
+const options = parseArgs(process.argv.slice(2));
+const root = resolve(options.root ?? DEFAULT_ROOT);
+
+const server = createServer((request, response) => {
+  handle(request, response).catch((error) => {
+    console.error(
+      `[serve-project] ${request.method} ${request.url} 失败：${error}`,
+    );
+    sendJson(response, 500, { error: "服务内部错误" });
+  });
+});
+
+server.listen(
+  options.port ?? DEFAULT_PORT,
+  options.host ?? DEFAULT_HOST,
+  () => {
+    const address = server.address();
+    const port = typeof address === "object" && address ? address.port : "?";
+    console.log(
+      `[serve-project] 已启动：http://${options.host ?? DEFAULT_HOST}:${port}/`,
+    );
+    console.log(`[serve-project] 内容根：${root}`);
+    console.log(`[serve-project] 工程接口：http://127.0.0.1:${port}/project`);
+  },
+);
+
+/**
+ * 路由：`/project` 是工程接口，其余按静态资源处理。
+ * @param {import("node:http").IncomingMessage} request
+ * @param {import("node:http").ServerResponse} response
+ */
+async function handle(request, response) {
+  if (request.method !== "GET" && request.method !== "HEAD") {
+    sendJson(response, 405, { error: "只支持 GET/HEAD" });
+    return;
+  }
+  const pathname = decodeURIComponent(
+    new URL(request.url ?? "/", "http://127.0.0.1").pathname,
+  );
+  if (pathname === "/project") {
+    await sendProject(response);
+    return;
+  }
+  await sendFile(response, pathname, request.headers.range);
+}
+
+/** 工程接口：清单与全部故事原文 */
+async function sendProject(response) {
+  const manifestText = await readFile(join(root, "project.json"), "utf8");
+  let manifest;
+  try {
+    manifest = JSON.parse(manifestText);
+  } catch {
+    throw new Error("project.json 不是合法 JSON");
+  }
+  const stories = await readStories(root);
+  sendJson(response, 200, { manifest, stories });
+}
+
+/**
+ * 递归收齐故事文件：逻辑路径（`Stories/…`）→ 原始文本。
+ * @param {string} directory 内容根
+ * @returns {Promise<Record<string, string>>}
+ */
+async function readStories(directory) {
+  const storiesRoot = join(directory, STORIES_DIR);
+  const files = await walk(storiesRoot);
+  const stories = {};
+  for (const file of files) {
+    const relative = file
+      .slice(directory.length + 1)
+      .split(sep)
+      .join("/");
+    stories[relative] = await readFile(file, "utf8");
+  }
+  return stories;
+}
+
+/**
+ * 递归列文件（只收 .json 与 .story：故事文件的两种形态）。
+ * @param {string} directory
+ * @returns {Promise<string[]>}
+ */
+async function walk(directory) {
+  const entries = await readdir(directory, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const path = join(directory, entry.name);
+    if (entry.isDirectory()) files.push(...(await walk(path)));
+    else if (
+      extname(entry.name) === ".json" ||
+      extname(entry.name) === ".story"
+    )
+      files.push(path);
+  }
+  return files.sort();
+}
+
+/**
+ * 静态资源：路径必须落在内容根之内（拒绝 `..` 与绝对路径逃逸），带 Range 支持。
+ * @param {import("node:http").ServerResponse} response
+ * @param {string} pathname 请求路径（已解码）
+ * @param {string | undefined} rangeHeader
+ */
+async function sendFile(response, pathname, rangeHeader) {
+  const target = resolve(join(root, pathname));
+  if (target !== root && !target.startsWith(root + sep)) {
+    sendJson(response, 400, { error: "路径越出内容根" });
+    return;
+  }
+  let info;
+  try {
+    info = await stat(target);
+  } catch {
+    sendJson(response, 404, { error: `没有这个资源：${pathname}` });
+    return;
+  }
+  if (!info.isFile()) {
+    sendJson(response, 404, { error: `不是文件：${pathname}` });
+    return;
+  }
+  const type =
+    MIME_TYPES.get(extname(target).toLowerCase()) ?? "application/octet-stream";
+  const headers = {
+    "Content-Type": type,
+    "Accept-Ranges": "bytes",
+    "Cache-Control": "no-store",
+    "Access-Control-Allow-Origin": "*",
+  };
+  const range = parseRange(rangeHeader, info.size);
+  if (range === "invalid") {
+    headers["Content-Range"] = `bytes */${info.size}`;
+    sendJson(response, 416, { error: "Range 不合法" }, headers);
+    return;
+  }
+  if (range === null) {
+    headers["Content-Length"] = String(info.size);
+    response.writeHead(200, headers);
+    createReadStream(target).pipe(response);
+    return;
+  }
+  headers["Content-Range"] = `bytes ${range.start}-${range.end}/${info.size}`;
+  headers["Content-Length"] = String(range.end - range.start + 1);
+  response.writeHead(206, headers);
+  createReadStream(target, { start: range.start, end: range.end }).pipe(
+    response,
+  );
+}
+
+/**
+ * 解析 `Range: bytes=a-b`：返回闭区间、`null`（无 Range）或 `"invalid"`。
+ * @param {string | undefined} header
+ * @param {number} size
+ * @returns {{ start: number; end: number } | null | "invalid"}
+ */
+function parseRange(header, size) {
+  if (typeof header !== "string" || !header.startsWith("bytes=")) return null;
+  const spec = header.slice("bytes=".length).split(",")[0].trim();
+  const dash = spec.indexOf("-");
+  if (dash < 0) return "invalid";
+  const startText = spec.slice(0, dash).trim();
+  const endText = spec.slice(dash + 1).trim();
+  let start;
+  let end;
+  if (startText === "") {
+    // `bytes=-N`：最后 N 字节
+    const tail = Number(endText);
+    if (!Number.isFinite(tail) || tail <= 0) return "invalid";
+    start = Math.max(0, size - tail);
+    end = size - 1;
+  } else {
+    start = Number(startText);
+    end = endText === "" ? size - 1 : Number(endText);
+  }
+  if (!Number.isFinite(start) || !Number.isFinite(end)) return "invalid";
+  if (start < 0 || end < start || start >= size) return "invalid";
+  return { start, end: Math.min(end, size - 1) };
+}
+
+/**
+ * 回一份 JSON。
+ * @param {import("node:http").ServerResponse} response
+ * @param {number} status
+ * @param {unknown} body
+ * @param {import("node:http").OutgoingHttpHeaders} [extra]
+ */
+function sendJson(response, status, body, extra = {}) {
+  const text = JSON.stringify(body);
+  response.writeHead(status, {
+    "Content-Type": "application/json; charset=utf-8",
+    "Content-Length": Buffer.byteLength(text),
+    "Access-Control-Allow-Origin": "*",
+    "Cache-Control": "no-store",
+    ...extra,
+  });
+  response.end(text);
+}
+
+/**
+ * 命令行参数：`--port` / `--host` / `--root`，也认 `--key=value` 形态。
+ * @param {string[]} argv
+ * @returns {{ port?: number; host?: string; root?: string }}
+ */
+function parseArgs(argv) {
+  /** @type {{ port?: number; host?: string; root?: string }} */
+  const out = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    const paired = arg.startsWith("--") && arg.includes("=");
+    const key = paired ? arg.slice(2, arg.indexOf("=")) : arg.slice(2);
+    const value = paired ? arg.slice(arg.indexOf("=") + 1) : argv[index + 1];
+    if (!paired) index += 1;
+    if (value === undefined) throw new Error(`参数缺少取值：${arg}`);
+    if (key === "port") out.port = Number(value);
+    else if (key === "host") out.host = value;
+    else if (key === "root") out.root = value;
+    else throw new Error(`未知参数：${arg}`);
+  }
+  return out;
+}

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

@@ -0,0 +1,23 @@
+<script setup lang="ts">
+/**
+ * 应用外壳：只定全局底色与文字默认值。
+ *
+ * 与桌面宿主同一套口径——层自己带外观，不靠继承：小程序里 `page` 就是那层「窗口底色」，
+ * 舞台层与 UI 层各自把自己需要的颜色写清楚。
+ */
+import { onLaunch } from "@dcloudio/uni-app";
+
+onLaunch(() => {
+  // 宿主自检入口：装载与装配都归页面（`pages/index/index.vue`），这里不做叙事接线。
+});
+</script>
+
+<style>
+page {
+  width: 100%;
+  height: 100%;
+  background: #0a0a10;
+  color: #e6e6f0;
+  font-size: 30rpx;
+}
+</style>