bun-app-window 0.2.2 → 0.4.0

package/README.zh-TW.md

@@ -84,7 +84,8 @@ shell.setTitle("Doing work…");
 | `start()` | 建立並啟動視窗，回傳 `{ rc, error }`。呼叫後立即回傳，UI 訊息迴圈執行於獨立原生執行緒 |
 | `stop()` | 銷毀視窗並釋放底層資源，支援冪等重複呼叫 |
 | `show()` | 顯示視窗。常搭配 `FLAG_DEFER_SHOW` 使用，實現在頁面渲染就緒後再展現視窗 |
-| `isAlive()` | 檢測視窗是否存活（註：`state()` 無法區分「尚未啟動」與「已銷毀」狀態） |
+| `isAlive()` | 檢測視窗是否存活（註：`state()` 無法區分「尚未啟動」與「已銷毀」狀態）。等視窗關閉請用 `pollEvents()` 的 `CLOSED`，別輪詢它 |
+| `pollEvents(max?)` | 批次拉取視窗生命週期事件（`STATE` / `CLOSED`），同步、消費式。詳見下文「視窗事件」 |
 | `state()` | 取得目前視窗狀態：`{ maximized, minimized, focused, dark, raw }` |
 | `lastError()` | 取得最近一次操作失敗的錯誤訊息，無錯誤時回傳空字串 |
 | `setTitle` / `minimize` / `toggleMaximize` / `close` | 基礎視窗控制操作，回傳狀態碼 `rc` |
@@ -113,11 +114,90 @@ shell.setTitle("Doing work…");
 | `FLAG_DEFER_SHOW` | 建立視窗後保持隱藏狀態，等待明確呼叫 `show()` |
 | `FLAG_ACCEPT_DROP` | 允許視窗接收外部檔案或資料夾拖放事件 |
 | `FLAG_START_MAXIMIZED` | 視窗首次顯示即處於最大化狀態，避免從一般尺寸跳變至最大化的中間閃爍畫格 |
+| `FLAG_ALLOW_EXTERNAL_NAV` | 放棄外部導覽攔截——用於本身就是瀏覽器的應用程式 |
+
+### 外部導覽預設被攔截
+
+未提供 `FLAG_ALLOW_EXTERNAL_NAV` 時，一個跨來源連結再也無法把應用程式導覽走。殼層會取消該次導覽，
+把位址交給系統預設瀏覽器：
+
+- **同來源**（啟動位址是 `file://` 等無 origin 的形態時，改為判斷「同文件」，即剝除
+  `#fragment` 後與啟動位址逐字相同）留在視窗內導覽，應用程式自身的路由不受影響。
+- **跨來源**會取消導覽並交給系統瀏覽器——但僅限 `http:` / `https:`。`file:`、
+  `javascript:`、`ms-*:` 以及自訂 scheme 一律靜默取消，絕不觸及協定處理常式；
+  `mailto:` / `tel:` 也**不在**放行清單內。
+- **`window.open` / `target=_blank`** 一律被攔下並外開，即使提供了
+  `FLAG_ALLOW_EXTERNAL_NAV` 亦然。那是能力邊界而非策略：殼層僅持有一個頂層視窗
+  （原生層是處理序級單例），多開出來的視窗沒有任何宿主 API 能管理它。
+
+桌面殼層沒有網址列、沒有上一頁按鈕，也沒有任何宿主 API 能把頁面導覽回來——所以一次誤點
+外部連結就等於應用程式被換成了那個網站。這就是預設值選擇安全一側的原因。
 
 ## 子路徑模組
 
 核心視窗控制之外的擴充能力均拆分於獨立子路徑下，可依需求匯入。
 
+### `bun-app-window/app` — 應用程式骨架
+
+用這個套件寫第一個應用程式時，業務程式碼可能只有 30 行，但**宿主樣板是 180 行**：挑安全埠、
+產生驗證 token、處理 WebSocket 升級、把 HTML 當字串吐出去、把 `createIpcServer`
+接到 Bun 的 websocket 回呼上、拼視窗旗標、處理 `openShell` 失敗、等視窗關閉
+（`EVENT_CLOSED`）、依序 `stop()` 兩個東西。每一段單看都不難，但它們**只在特定順序下正確**
+（`stop()` 不先等視窗真的銷毀就關服務，下次啟動會撞上 "already started"）。
+`app` 把這些收成一次呼叫：
+
+```ts
+// main.ts
+import { createApp } from "bun-app-window/app";
+import { BROWSER_UI_ALL, FLAG_FRAMELESS } from "bun-app-window";
+import html from "./index.html" with { type: "text" };
+
+const app = await createApp({
+  html,
+  title: "我的應用程式",
+  flags: FLAG_FRAMELESS,          // 想要自繪標題列就明確加上
+  browserUi: BROWSER_UI_ALL,
+  service: {
+    greet: (name: string) => `hi ${name}`,
+    pickFolder: () => app.shell.pickFolder(),
+  },
+});
+
+await app.wait();                  // 視窗關閉時 resolve
+```
+
+```ts
+// page.ts —— index.html 的 bundle 內
+import { connect } from "bun-app-window/ipc";
+const api = await connect();       // token 從頁面 URL 的 ?t= 取得
+await api.greet("Ada");
+```
+
+它替你做的事：
+
+- 綁定瀏覽器安全的埠（絕不會是 `ERR_UNSAFE_PORT` 那幾個），並把 HTML 服務出去。
+- 每次執行產生一個 token，並在**升級之前**用它校驗 `/ws` —— 升級之後就沒有機會拒絕了。
+  `ipc` 未開啟時 `/ws` 是 `404` 而不是 `403`：403 等於告訴對方「這裡有通道」。
+- 把 `createIpcServer` 接到 websocket 的 `open` / `message` / `close` 上，`ipc.emit()` 才能到頁面。
+- `stop()` 有序且冪等：`shell.stop()` → 等 `EVENT_CLOSED`（帶 5 秒上限）→ `server.stop()`。
+- 起一個視窗事件泵並且只起一個：`app.events`。它同時承擔「等視窗關閉」，
+  所以是唯一的事件消費者；`attachPlacementStore` 要用它時傳 `{ events: app.events }`。
+- 啟動失敗不留半啟動狀態：`openShell` 拋錯時，已綁定的埠會被釋放。
+
+注意事項：
+
+- **預設不帶 `FLAG_FRAMELESS`。** 無邊框視窗沒有系統標題列就拖不動，必須由頁面先掛上
+  `mountTitleBar`。預設值選的是「頁面什麼都不做也能用」的那一側。
+- **靜態資源只吃內嵌字串。** `with { type: "text" }` 得到的是編譯期常數：不碰檔案系統、
+  不產生暫存檔、`bun build --compile` 後仍然成立。要從磁碟讀東西就寫個 `routes` 函式 ——
+  五行，而且路徑解析的問題留在你這邊，不會滲進骨架。
+- **不從主入口匯出。** 它和 `./state`、`./ipc` 一樣是子路徑。它從 `./index` 匯入
+  `openShell`；若 `index.ts` 反過來匯出它，就成了循環。
+
+**這不是 `Bun.WebView` 的替代品。** 那個是 headless 瀏覽器，做自動化 / 測試 / 擷取 ——
+沒有視窗，而且只能截自己的頁面。本專案畫的是真實桌面視窗：系統標題列、DPI 感知、
+貼齊版面配置、工作列歸屬。兩者不在同一條賽道上。
+
 ### `bun-app-window/ipc` — 型別化雙向通訊與事件匯流排
 
 宿主與前端頁面共用同一份 TypeScript 型別宣告，用戶端透過泛型在編譯期完成方法簽章與事件負載驗證：
@@ -213,7 +293,7 @@ if (saved) restorePlacement(shell, saved);
 
 shell.show();
 
-const store = attachPlacementStore(shell, FILE);   // 定時輪詢狀態，視窗靜止時不觸發寫入磁碟
+const store = attachPlacementStore(shell, FILE);   // 訂閱視窗事件，拖曳停下後寫入一次
 process.on("beforeExit", () => store.flush());
 ```
 
@@ -223,7 +303,53 @@ process.on("beforeExit", () => store.flush());
 - 跨顯示器不同縮放比例下的 DPI 座標換算。
 - 螢幕拓撲變化（如拔除外接螢幕）後的螢幕外座標越界驗證與修正。
 
-若無需背景輪詢，亦可直接呼叫 `capturePlacement` 與 `savePlacement` 執行單次手動讀寫。
+寫入是事件驅動的：收到狀態變化**立刻**取得快照（微秒級），寫入磁碟則攢到停下 300 ms 後
+做一次。視窗靜止時既沒有原生呼叫也沒有磁碟寫入。用 `debounceMs` 調整寫入延遲；用
+`pumpMs` 調整內部事件泵的拉取節奏。
+
+若已有事件泵（例如用了 `createApp`），把它傳進來，避免兩個消費者爭搶同一批事件：
+
+```ts
+import { createApp } from "bun-app-window/app";
+import { attachPlacementStore } from "bun-app-window/state";
+
+const app = await createApp({ html });
+const store = attachPlacementStore(app.shell, FILE, { events: app.events });
+```
+
+若無需背景訂閱，亦可直接呼叫 `capturePlacement` 與 `savePlacement` 執行單次手動讀寫。
+
+### 視窗事件
+
+宿主想知道「視窗狀態變了」，不必輪詢——`pollEvents()` 直接給出事件串流：
+
+```ts
+import { EVENT_CLOSED, EVENT_STATE } from "bun-app-window/events";
+
+for (const e of shell.pollEvents()) {
+  if (e.type === EVENT_CLOSED) break;          // 視窗已銷毀，原生單例已釋放
+  if (e.type === EVENT_STATE && e.maximized) { /* ... */ }
+}
+```
+
+`pollEvents()` 是**消費式**的：讀走的記錄不會再來，所以一個行程只應有一個消費者。
+想要固定節奏與多路訂閱時，用 `./events` 的 `attachEventPump()`：
+
+```ts
+import { EVENT_CLOSED, attachEventPump } from "bun-app-window/events";
+
+const pump = attachEventPump(shell, { intervalMs: 16 });
+pump.on((e) => { if (e.type === EVENT_CLOSED) pump.stop(); });
+pump.onGap((missing) => console.warn(`漏了 ${missing} 條事件`));
+```
+
+- `STATE` 酬載是**快照**：`width` / `height` / `dpi` 與四位狀態
+  （`maximized` / `minimized` / `focused` / `dark`）。
+- `CLOSED` 是終態。它由原生側在 teardown 全部做完、視窗代碼已置空之後寫出，所以
+  「看到 `CLOSED`」等價於「可以安全重啟視窗」——這是它優於 `isAlive()` 的地方。
+- 原生側環形佇列容量 128 條，滿時丟最舊。遺失量透過 `seq` 缺口如實上報（`onGap`），
+  不會偽裝成「什麼都沒發生」。
+- 事件泵的計時器預設 `unref`（不阻止行程退出）。若靠它等視窗關閉，傳 `keepAlive: true`。
 
 ### `bun-app-window/debug` — 診斷與除錯介面
 
@@ -399,13 +525,13 @@ bun run scripts/gate.ts --clean      # 同上，但在 HEAD 的乾淨副本內
 
 `-Clean` 重現了託管 runner 的條件：將 `HEAD` clone 到 `%TEMP%`，依 lockfile 安裝相依套件，再於其中執行把關。如此一來，本機產物（`.build/`、`node_modules/`、`vendor/webview2/`）便無法掩蓋缺少的檔案。耗時約兩秒。未提交的變更會被提示並排除於乾淨副本之外——如需驗證工作區現況，請移除 `-Clean`。
 
-品質把關分三段：`bun check`、`bun test`，以及消費方驗收（`scripts/verify-pack.ts`）。第三段會把 tarball 打包到 `%TEMP%`，安裝進一個臨時專案，對該專案執行型別檢查，再執行 `scripts/consumer-probe.ts`——40 條斷言涵蓋全部子路徑、DLL 是否真的從 `node_modules` 被 `dlopen`、以及 `libInfo.source` 是否為 `package`。可離線執行，約 0.4 秒，且預設拒絕：任何未在允許清單登記的檔案被打進套件，把關就會失敗。只有在改動把關腳本本身時才用 `-SkipPack`。
+品質把關分三段：`bun check`、`bun test`，以及消費方驗收（`scripts/verify-pack.ts`）。第三段會把 tarball 打包到 `%TEMP%`，安裝進一個臨時專案，對該專案執行型別檢查，再執行 `scripts/consumer-probe.ts`——斷言涵蓋全部子路徑、DLL 是否真的從 `node_modules` 被 `dlopen`、以及 `libInfo.source` 是否為 `package`（條數由探針自報）。可離線執行，約 0.4 秒，且預設拒絕：任何未在允許清單登記的檔案被打進套件，把關就會失敗。只有在改動把關腳本本身時才用 `-SkipPack`。
 
 底層指令仍可直接呼叫：
 
 ```bash
 bun check          # 執行 TypeScript 型別檢查
-bun test           # 執行自動化測試套件（位於 tests/，共 182 個測試案例）
+bun test           # 執行自動化測試套件（位於 tests/）
 bun run demo       # 啟動互動式自我檢測範例程式（需於桌面工作階段下執行）
 ```
 

package/package.json

@@ -1,7 +1,7 @@
 {
     "$schema": "https://json.schemastore.org/package.json",
     "name": "bun-app-window",
-    "version": "0.2.2",
+    "version": "0.4.0",
     "description": "Native WebView2 window shell for Bun — frameless or system-decorated windows, DPI-aware geometry, typed IPC, system-accurate title bar",
     "type": "module",
     "license": "MIT",
@@ -29,6 +29,8 @@
     ],
     "exports": {
         ".": "./src/shell/index.ts",
+        "./app": "./src/shell/app.ts",
+        "./events": "./src/shell/events.ts",
         "./embedded": "./src/shell/embedded.ts",
         "./debug": "./src/shell/debug.ts",
         "./state": "./src/shell/state.ts",

package/src/shell/app.ts

@@ -0,0 +1,344 @@
+/**
+ * app.ts — 应用骨架：把「起服务 → 开窗 → 接线 → 等退出」收成一次调用
+ *
+ * ## 为什么需要它
+ *
+ * 用这个包做第一个应用时，真正要写的业务代码可能只有 30 行，但**宿主样板**是
+ * 另外 180 行：挑安全端口、生成鉴权 token、处理 WebSocket 升级、把 HTML 当字符串
+ * 吐出去、把 `createIpcServer` 接到 Bun 的 websocket 回调上、拿窗口 flags、
+ * 处理 `openShell` 失败、等窗口关闭（`EVENT_CLOSED`）、按顺序 `stop()` 两次。
+ *
+ * 每一段单看都不难，但它们**必须按特定顺序且互相依赖**——`stop()` 不先等窗口
+ * 销毁就去关服务，下次启动会撞上「进程级单例还在」；WS 升级不在 `fetch` 里做，
+ * 鉴权就没有落点。这些顺序关系在 `src/host.ts` 里被验证过一遍，但没有沉淀成
+ * 可复用的东西，所以每个消费者都要再踩一次。
+ *
+ * ## 两个设计选择
+ *
+ * **不导出到主入口。** 它和 `./state`、`./ipc`、`./titlebar` 一样是可选件，
+ * 走独立子路径 `bun-app-window/app`。好处不只是「按需引入」——`app.ts` 从
+ * `./index` 导入 `openShell`，如果 `index.ts` 反过来导出 `app`，就成了循环。
+ * 单向依赖比运行时安全的循环更值得要。
+ *
+ * **静态资源只吃内联字符串。** 用 `import html from "./index.html" with { type: "text" }`
+ * 得到的是编译期常量：不碰文件系统、不产生临时文件、`bun build --compile` 后仍然成立。
+ * 从目录读则要处理 `import.meta.dir` 在打包后指向 `B:\~BUN\root` 的问题
+ * （`src/host.ts` 里那段 `PACKED` 判断就是为它存在的）。那 5 行留给消费者自己写，
+ * 用 `routes` 就能接。
+ */
+
+import { createIpcServer, type IpcServer, type ServiceMethods } from "./ipc";
+import { EVENT_CLOSED, attachEventPump, type EventPump } from "./events";
+import { openShell, type Shell } from "./index";
+import { serveOnSafePort } from "./port";
+import { FLAG_CENTER, FLAG_RESIZABLE, type ShellOptions } from "./types";
+
+/** 骨架起出来的东西。`shell` 是完整的内核对象，骨架只是帮它把周边接好 */
+export type App = {
+    /** 内核对象。标题、缩放、全屏、原生菜单、位置持久化都从这里拿 */
+    readonly shell: Shell;
+    /**
+     * 窗口生命周期事件流。骨架替你起的**唯一**一个消费者。
+     *
+     * `shell.pollEvents()` 是消费式的，一个窗口只能有一个消费者。要用
+     * `attachPlacementStore` 时传 `{ events: app.events }`，别再自己 attach
+     * 一个泵——两个泵会各自拿到一部分事件。
+     *
+     * 定时器是 keepAlive 的（不 unref）：`wait()` 靠它让进程活到窗口关闭。
+     */
+    readonly events: EventPump;
+    /** 本地服务实际绑定的端口（已避开浏览器受限端口表） */
+    readonly port: number;
+    /** 页面 URL：带鉴权 token 的查询参数，直接交给 `openShell` 用的就是它 */
+    readonly url: string;
+    /** 页面 URL 里的 token。页面侧 `connect()` 默认从这里取 */
+    readonly token: string;
+    /** 给了 `service` 才有；否则为 null */
+    readonly ipc: IpcServer | null;
+    /**
+     * 停止窗口与本地服务。
+     *
+     * 顺序是有意的：先 `shell.stop()`，再**等 `EVENT_CLOSED`**，最后才关服务。
+     * 原生层是进程级单例，`shell_stop()` 只是投了一个 `WM_QUIT`；抢在前面关服务
+     * 或重新 start，会撞上「shell already started」（详见 `pitfalls` 2.4g / 7.1）。
+     *
+     * 等的是事件不是 `isAlive()`：`CLOSED` 由原生侧在 teardown 全部做完、
+     * `g_webview` 已置空之后写进队列，它出现的时刻就等于「单例已释放」。
+     * 仍然保留超时上限——事件通道若因故失效，宿主不能被永久挂住。
+     *
+     * 幂等：重复调用立即返回。
+     */
+    stop(): Promise<void>;
+    /**
+     * 等窗口被关闭（用户点 X，或调用了 `stop()`）。
+     *
+     * 宿主进程不会因为窗口没了就自动退出——它自己起的本地服务还在跑。所以
+     * 「应用该结束了」的判据是收到 `EVENT_CLOSED`，不是任何信号。
+     *
+     * 这个 promise 靠 `events` 的 keepAlive 定时器撑住事件循环；别在等它的同时
+     * 把 `events.stop()` 掉，那样两边都收不到关闭信号。
+     */
+    wait(): Promise<void>;
+};
+
+export type AppOptions = {
+    /**
+     * 页面 HTML，用 `with { type: "text" }` 内联。
+     *
+     * ```ts
+     * import html from "./index.html" with { type: "text" };
+     * ```
+     */
+    html: string;
+    title?: string;
+    width?: number;
+    height?: number;
+    /**
+     * 窗口 flags。缺省 `FLAG_RESIZABLE | FLAG_CENTER`（带边框）。
+     *
+     * 想要自绘标题栏时显式加 `FLAG_FRAMELESS`——骨架不默认它，因为无边框窗口
+     * 没有系统标题栏就**拖不动**，而那需要页面先挂上 `mountTitleBar`。
+     * 默认值选「即使页面什么都不做也能用」的那一侧。
+     */
+    flags?: number;
+    minWidth?: number;
+    minHeight?: number;
+    /** 关掉哪些浏览器行为，取 `BROWSER_UI_*` 的按位或 */
+    browserUi?: number;
+    appName?: string;
+    nativeLibPath?: string;
+    embedded?: () => Promise<Uint8Array | null>;
+    /**
+     * IPC 服务方法表。给了就自动挂 `/ws`（含 token 校验）。
+     *
+     * 页面侧：
+     *
+     * ```ts
+     * import { connect } from "bun-app-window/ipc";
+     * const api = await connect();   // 自动从 ?t= 取 token
+     * ```
+     */
+    service?: ServiceMethods;
+    /** IPC 错误里是否回传 stack。默认关闭 */
+    exposeStack?: boolean;
+    /**
+     * 额外路由。返回 `undefined` 表示「不归我管」，交回骨架的默认处理
+     * （`/` 吐 HTML、`/ws` 处理升级、其余 404）。
+     *
+     * 从磁盘读静态资源、代理上游 API 这类事情写在这里。
+     */
+    routes?: (req: Request) => Response | undefined | Promise<Response | undefined>;
+    /** 窗口建好、服务就绪后调用一次 */
+    onReady?: (app: App) => void;
+};
+
+/** 事件拉取节奏，约一帧 */
+const EVENT_POLL_MS = 16;
+/**
+ * 等 `EVENT_CLOSED` 的上限。
+ *
+ * 实测关闭约 50 ms，5 s 是三个数量级的余量。存在的理由不是「怕关得慢」，
+ * 而是「事件通道若因故失效，宿主不能被永久挂住」——超时后照旧关服务。
+ */
+const CLOSE_TIMEOUT_MS = 5000;
+
+/** 一个只能 resolve 一次的 promise。等窗口关闭用它，比轮询一个布尔值清楚 */
+function defer(): { promise: Promise<void>; resolve: () => void } {
+    let resolve: () => void = () => {};
+    const promise = new Promise<void>((r) => {
+        resolve = r;
+    });
+    return { promise, resolve };
+}
+
+/**
+ * 不给 `flags` 时用的默认值：**带边框** + 可缩放 + 居中。
+ *
+ * 刻意不默认 `FLAG_FRAMELESS`。无边框窗口没有系统标题栏就拖不动，必须由页面先挂上
+ * `mountTitleBar` 才能用；把它设成默认值会让「只写了 HTML」的应用一上来就无法拖动。
+ * 默认值应当选「页面什么都不做也能用」的那一侧。
+ */
+export const DEFAULT_APP_FLAGS = FLAG_RESIZABLE | FLAG_CENTER;
+
+/** 页面 URL。token 放查询参数里，页面侧 `connect()` 默认从这里取 */
+export function buildAppUrl(port: number, token: string): string {
+    return `http://127.0.0.1:${port}/?t=${token}`;
+}
+
+/**
+ * `/ws` 请求的处置结论。
+ *
+ * 抽成纯函数是因为这是整个骨架里**唯一有分支的判据**，而它有三个容易写反的点：
+ * 路径要先比、`ipc` 没开时不能当 403（那是 404）、token 不匹配必须在**升级之前**
+ * 拒绝——升级之后就没有机会说不了。
+ *
+ * token 用普通 `!==` 比较而不是恒定时间比较：它是一次性的本地回环随机值，
+ * 不是长期凭据，时序侧信道在这里没有可换取的东西。
+ */
+export type WsDecision = "not-ws" | "ipc-disabled" | "forbidden" | "upgrade";
+
+export function decideWs(
+    pathname: string,
+    presented: string | null,
+    expected: string,
+    ipcEnabled: boolean,
+): WsDecision {
+    if (pathname !== "/ws") {
+        return "not-ws";
+    }
+    if (!ipcEnabled) {
+        return "ipc-disabled";
+    }
+    return presented === expected ? "upgrade" : "forbidden";
+}
+
+/**
+ * 起服务、开窗、接线，返回一个可以 `wait()` 的 App。
+ *
+ * 失败时抛错，且**不留下半启动状态**——本地服务会被关掉。理由是调用方拿到异常后
+ * 唯一合理的动作是退出，而一个已经绑好的端口会让「重试一次」也失败。
+ */
+export async function createApp(opts: AppOptions): Promise<App> {
+    if (!opts.html || typeof opts.html !== "string") {
+        throw new Error("createApp: html is required (import it with { type: \"text\" })");
+    }
+
+    const token = crypto.randomUUID();
+    const ipc = opts.service
+        ? createIpcServer({
+              service: opts.service,
+              ...(opts.exposeStack === undefined ? {} : { exposeStack: opts.exposeStack }),
+          })
+        : null;
+
+    const server = serveOnSafePort({
+        fetch(req, srv) {
+            return handle(req, srv);
+        },
+        websocket: {
+            open(ws: unknown) {
+                ipc?.attach(ws as { send(d: string): void });
+            },
+            message(ws: unknown, raw: string | Buffer) {
+                void ipc?.handle(ws as { send(d: string): void }, raw);
+            },
+            close(ws: unknown) {
+                ipc?.detach(ws as { send(d: string): void });
+            },
+        } as never,
+    });
+
+    async function handle(req: Request, srv: unknown): Promise<Response | undefined> {
+        const url = new URL(req.url);
+
+        // IPC 通道。校验必须在这里做——升级之后就没有机会拒绝了
+        switch (decideWs(url.pathname, url.searchParams.get("t"), token, ipc !== null)) {
+            case "ipc-disabled":
+                return new Response("ipc not enabled", { status: 404 });
+            case "forbidden":
+                return new Response(null, { status: 403 });
+            case "upgrade": {
+                const upgrade = (srv as { upgrade(r: Request, o: unknown): boolean }).upgrade;
+                if (upgrade.call(srv, req, { data: {} })) {
+                    return undefined; // 已升级，不要再返回 Response
+                }
+                return new Response(null, { status: 400 });
+            }
+            default:
+                break;
+        }
+
+        // 调用方的路由优先，能覆盖 `/`（自绘入口页、SPA fallback 都靠这条）
+        const custom = await opts.routes?.(req);
+        if (custom) {
+            return custom;
+        }
+
+        if (url.pathname === "/") {
+            return new Response(opts.html, {
+                headers: { "content-type": "text/html; charset=utf-8" },
+            });
+        }
+
+        return new Response("not found", { status: 404 });
+    }
+
+    // `Bun.serve` 的 `port` 类型是 `number | undefined`。`serveOnSafePort` 已经
+    // 确认绑定成功，但这里不能顺手断言：一旦为 undefined，拼出来的 URL 会是
+    // `http://127.0.0.1:undefined/?t=...`，而 `openShell` 会把它当合法 URL 交给
+    // WebView2，表现为一个空白窗口——比抛错难查得多。
+    const port = server.port;
+    if (port === undefined) {
+        server.stop(true);
+        throw new Error("createApp: local server did not report a bound port");
+    }
+    const url = buildAppUrl(port, token);
+
+    const shellOpts: ShellOptions = {
+        url,
+        title: opts.title ?? "bun-app-window",
+        width: opts.width ?? 1000,
+        height: opts.height ?? 680,
+        flags: opts.flags ?? DEFAULT_APP_FLAGS,
+        ...(opts.minWidth === undefined ? {} : { minWidth: opts.minWidth }),
+        ...(opts.minHeight === undefined ? {} : { minHeight: opts.minHeight }),
+        ...(opts.browserUi === undefined ? {} : { browserUi: opts.browserUi }),
+        ...(opts.appName === undefined ? {} : { appName: opts.appName }),
+        ...(opts.nativeLibPath === undefined ? {} : { nativeLibPath: opts.nativeLibPath }),
+        ...(opts.embedded === undefined ? {} : { embedded: opts.embedded }),
+    };
+
+    let shell: Shell;
+    try {
+        shell = await openShell(shellOpts);
+    } catch (err) {
+        // 不留半启动状态：窗口没起来，端口也不该继续占着
+        server.stop(true);
+        throw err;
+    }
+
+    let stopped = false;
+
+    // 窗口事件的唯一消费者。`keepAlive: true` 是 `wait()` 成立的前提：
+    // unref 的定时器不撑事件循环，而「等一个永不兑现的 promise」也撑不住——
+    // 宿主会在窗口还开着的时候直接退出。
+    const events = attachEventPump(shell, { intervalMs: EVENT_POLL_MS, keepAlive: true });
+    const closed = defer();
+    events.on((e) => {
+        if (e.type === EVENT_CLOSED) {
+            closed.resolve();
+        }
+    });
+
+    const app: App = {
+        shell,
+        events,
+        port,
+        url,
+        token,
+        ipc,
+        async stop(): Promise<void> {
+            if (stopped) {
+                return;
+            }
+            stopped = true;
+            shell.stop();
+            // 等 `EVENT_CLOSED` 而不是轮询 `isAlive()`：CLOSED 由原生侧在 teardown
+            // 全部做完、g_webview 已置空之后写进队列，它出现的时刻就等于「单例已释放」。
+            // 超时上限保留，且超时后也 resolve 一次——否则 `wait()` 会永远挂着。
+            await Promise.race([closed.promise, Bun.sleep(CLOSE_TIMEOUT_MS)]);
+            closed.resolve();
+            events.stop();
+            server.stop(true);
+        },
+        async wait(): Promise<void> {
+            if (stopped) {
+                return;
+            }
+            await closed.promise;
+        },
+    };
+
+    opts.onReady?.(app);
+    return app;
+}