bun-app-window 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -4,6 +4,48 @@ All notable changes to this project are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.1] - 2026-10-21
+
+### Fixed
+
+- **`bun-app-window/titlebar` no longer breaks `bun check` in your project.** Every consumer whose `tsconfig.json` includes `DOM` — that is, every project with a real page — was stopped by a `TS2352` error pointing at this package's own source, with no way to work around it:
+
+    ```text
+    node_modules/bun-app-window/src/ui/titlebar.ts(237,27): error TS2352:
+    Conversion of type 'typeof globalThis' to type '{ document?: TitleBarDocument; }'
+    may be a mistake because neither type sufficiently overlaps with the other.
+    If this was intentional, convert the expression to 'unknown' first.
+    ```
+
+    `skipLibCheck: true` does not help, because this package ships `.ts` sources rather than `.d.ts` files, so the error is in compiled source and not in a declaration. The component reached `globalThis.document` through a single-layer type assertion; with `DOM` loaded, `globalThis.document` is a full `Document`, and the component's deliberately minimal `TitleBarDocument` does not overlap with it enough to satisfy the checker. It is now a two-layer assertion (`as unknown as`), which states the intent without making the component depend on DOM types. Runtime behaviour is unchanged. Existing code needs no edits — upgrading is enough.
+
+### Changed
+
+- **The three READMEs are corrected in six places.** Everything below was documentation, not code, but each item could cost a consumer real time by making them follow an example that does not work. The pages are `README.md`, `README.zh-CN.md` and `README.zh-TW.md`, and all six corrections are applied to all three.
+
+    **The `titlebar` example contradicted itself.** One section showed the IPC service flat, another showed it nested under a `window` key — inside the same file. The nested form never worked: `service` is a flat method table. The example now uses the flat form, and because `close` is one of the client's reserved names, it exposes `winClose` and maps it back on the page side.
+
+    **`debug.metrics()` and `debug.dpi()` were described as if they returned objects.** They return formatted text — `pos=196,196 win=1960x1400 client=1960x1400 work=3072x1824 border=13x13 round=1` and `awareness=-1 dpi=192 scale=200%`. The example shows the real output now, and says not to build a parser on it: the layout is not part of any contract.
+
+    **`await app.wait()` was shown as the end of a program.** It resolves when the window closes but stops neither the event pump nor the server, and the pump's timer is pinned on purpose — so a program that ends on that line stays alive after the window is gone. The example follows it with `await app.stop()`, which is idempotent and returns immediately once the close has been observed.
+
+    **The IPC client's reserved names were undocumented.** `on`, `off`, `close`, `connected`, `pending` and `then` resolve to the client itself and never reach a remote method. A service that defines one of them is silently unreachable, with no error on either end — and `close` in particular also tears down the channel for every later call. There is a table of them now, and a note that symbol keys are reserved as well.
+
+    **Two traps that pass type checking but do not work** are documented together: the page bundle is an ES module, so a classic `<script>` tag executes nothing while the page still renders; and the title bar listens for `document` clicks on `data-act`, so a host binding `button[data-act]` receives every click twice.
+
+    **The tarball figures were stale** — 19 files / ~0.36 MB against the measured 21 files / ~0.4 MB.
+
+- **The `app` Quick Start no longer reads the HTML at run time.** The old snippet, `import html from "./index.html" with { type: "text" }`, did not compile under TypeScript 7.0.2, because `bun-types` gates the declaration that types this import behind `typesVersions: ">= 7.1"`. The obvious-looking repair, `await Bun.file(...).text()`, would have broken the property that section exists to demonstrate: a compile-time constant travels inside `bun build --compile`, a run-time read does not. The import stays and only the type is bridged, so a single-file executable still carries its HTML:
+
+    ```ts
+    import htmlText from "./index.html" with { type: "text" };
+    const html = htmlText as unknown as string;
+    ```
+
+### Note
+
+- **Nothing to do on upgrade.** No public API changed: the exported surface, the flags, the IPC protocol and `dist/libshell.dll` are byte-for-byte the same as 0.4.0, so `bun update bun-app-window` is the whole procedure. This is a patch because the only code change is the one assertion above, and the rest is documentation.
+
 ## [0.4.0] - 2026-10-21
 
 ### Added
@@ -285,7 +327,8 @@ First public release.
 - Not yet verified in managed environments that enforce AppLocker, WDAC, or third-party EDR behaviour blocking.
 - No commercially trusted code signing: only a self-signed certificate has been exercised end to end.
 
-[Unreleased]: https://github.com/TiancongLx/bun-app-window/compare/v0.4.0...HEAD
+[Unreleased]: https://github.com/TiancongLx/bun-app-window/compare/v0.4.1...HEAD
+[0.4.1]: https://github.com/TiancongLx/bun-app-window/compare/v0.4.0...v0.4.1
 [0.4.0]: https://github.com/TiancongLx/bun-app-window/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/TiancongLx/bun-app-window/compare/v0.2.2...v0.3.0
 [0.2.2]: https://github.com/TiancongLx/bun-app-window/compare/v0.2.1...v0.2.2

package/README.md

@@ -46,7 +46,7 @@ bun add bun-app-window
 
 ### What the tarball contains
 
-The published package holds the prebuilt `dist/libshell.dll` plus the TypeScript sources — 19 files, ~0.36 MB packed. The native C++ layer (`native/`) and the vendored upstream headers (`vendor/`) are **not** shipped: they are only needed to rebuild `libshell.dll`, and rebuilding requires cloning the repository. `bun run build:native` and `build:exe` are therefore repository-only scripts that do nothing useful inside `node_modules`.
+The published package holds the prebuilt `dist/libshell.dll` plus the TypeScript sources — 21 files, roughly 0.4 MB packed. The native C++ layer (`native/`) and the vendored upstream headers (`vendor/`) are **not** shipped: they are only needed to rebuild `libshell.dll`, and rebuilding requires cloning the repository. `bun run build:native` and `build:exe` are therefore repository-only scripts that do nothing useful inside `node_modules`.
 
 ## Quick Start
 
@@ -153,7 +153,12 @@ start hits "already started"). `app` collapses all of it into one call:
 // 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" };
+import htmlText from "./index.html" with { type: "text" };
+
+// `with { type: "text" }` inlines the file at build time, so it survives `bun build --compile`.
+// TS 7.0.2 cannot see that declaration — bun-types gates it behind `typesVersions >= 7.1`,
+// so the import resolves to `HTMLBundle` instead of `string`. Hence the bridge.
+const html = htmlText as unknown as string;
 
 const app = await createApp({
   html,
@@ -167,6 +172,7 @@ const app = await createApp({
 });
 
 await app.wait();                  // resolves when the window closes
+await app.stop();                  // releases the event pump and the server; idempotent
 ```
 
 ```ts
@@ -195,10 +201,18 @@ Notes:
 - **Does not default to `FLAG_FRAMELESS`.** A frameless window has no system title bar, so it cannot
   be dragged until the page mounts `mountTitleBar`. The default is the side that works even when the
   page does nothing.
+- **`wait()` only waits.** It resolves on `EVENT_CLOSED` but does not stop the event pump or the
+  server — and the pump timer is ref'd (`keepAlive: true`), so a process that stops at `wait()`
+  keeps running after the window is gone. Always follow it with `stop()`: it is idempotent and
+  returns immediately once the close has already been observed.
 - **Static assets are inline strings only.** `with { type: "text" }` yields a compile-time constant:
-  nothing touches the filesystem, no temp files, and it survives `bun build --compile`. For
-  anything read from disk, write a `routes` function — five lines, and the path-resolution problem
-  stays yours instead of leaking into the skeleton.
+  nothing touches the filesystem, no temp files, and it survives `bun build --compile`. TS 7.0.2
+  resolves that import to `HTMLBundle` rather than `string` — `bun-types` gates the correct
+  declaration behind `typesVersions >= 7.1` — which is what the `as unknown as string` in the
+  example is for. Do not "fix" it with `Bun.file().text()`: that reads at run time, and the HTML
+  would no longer travel inside the compiled executable. For anything read from disk, write a
+  `routes` function — five lines, and the path-resolution problem stays yours instead of leaking
+  into the skeleton.
 - **Not re-exported from the main entry.** It is a subpath like `./state` and `./ipc`. It imports
   `openShell` from `./index`; exporting it from `index.ts` would make that a cycle.
 
@@ -249,39 +263,59 @@ api.on("windowState", (s) => bar.setMaximized(s.maximized));
 
 By default, `connect()` extracts the auth token from the page URL's `?t=` query parameter and connects to `/ws`. Pass a custom `url` or `channel` option to override this behavior.
 
+#### Reserved client names
+
+The client is a `Proxy`: a handful of names resolve to the client itself and never reach a remote
+method. If your service exposes a method under one of these names, **the server-side method becomes
+unreachable** — the page calls the client's own member instead, and neither end reports an error.
+
+| Name | What the page actually gets |
+| --- | --- |
+| `on` / `off` | Event subscription helpers |
+| `close()` | Closes the WebSocket channel — every later call is rejected |
+| `connected` | `boolean`: whether the channel is open |
+| `pending` | `number` of calls still awaiting a reply |
+| `then` | `undefined`, so `await client` cannot hang on a never-resolving thenable |
+
+Symbol keys are reserved as well. Pick a different service name (`winClose` instead of `close`) and
+map it back on the page side — see the title bar section below.
+
 ### `bun-app-window/titlebar` — Windows 11 Title Bar
 
-Mounts a customizable Windows 11 title bar inside frameless windows:
+Mounts a customizable Windows 11 title bar inside frameless windows. The IPC service is **flat** —
+there is no `window` namespace — and one of the four natural names is taken by the client itself,
+so the host exposes `winClose` and the page maps it back:
 
 ```ts
-// Page
+// Host — flat service; `close` is reserved by the IPC client
+createIpcServer({
+  service: {
+    minimize: () => shell.minimize(),
+    toggleMaximize: () => shell.toggleMaximize(),
+    winClose: () => shell.close(),
+    drag: () => shell.drag(),
+  },
+});
+```
+
+```ts
+// Page — build the bridge explicitly
 import { mountTitleBar, bridgeFromWindowService } from "bun-app-window/titlebar";
 
 const bar = mountTitleBar({
   title: "My App",
   icon: "/icon.svg",
-  bridge: bridgeFromWindowService(api.window),
+  bridge: bridgeFromWindowService({
+    minimize: () => api.minimize(),
+    toggleMaximize: () => api.toggleMaximize(),
+    close: () => api.winClose(),          // mapped back to the bridge's own name
+    drag: () => api.drag(),
+  }),
 });
 
 api.on("windowState", (s) => bar.setMaximized(s.maximized));
 ```
 
-Expose the four corresponding window control methods on the host IPC service:
-
-```ts
-// Host
-createIpcServer({
-  service: {
-    window: {
-      minimize: () => shell.minimize(),
-      toggleMaximize: () => shell.toggleMaximize(),
-      close: () => shell.close(),
-      drag: () => shell.drag(),
-    },
-  },
-});
-```
-
 Implementation notes:
 
 - Native dragging: Calling `shell.drag()` dispatches a native `WM_NCLBUTTONDOWN` (`HTCAPTION`) message, preserving Windows 11 Snap Layouts and double-click maximize behavior.
@@ -375,11 +409,14 @@ Exposes internal metrics and hit-testing utilities. Note: This module is exclude
 import { debugOf } from "bun-app-window/debug";
 
 const d = debugOf(shell);
-d.metrics();   // Returns pos / win / client / work / border / round geometry
-d.dpi();       // Returns DPI awareness level and scaling factor
+d.metrics();   // → "pos=196,196 win=1960x1400 client=1960x1400 work=3072x1824 border=13x13 round=1"
+d.dpi();       // → "awareness=-1 dpi=192 scale=200%"
 d.hittest(x, y);
 ```
 
+`metrics()` and `dpi()` return **formatted text**, not objects. Parse it in throwaway tooling if you
+must; do not put a parser in production code, because the layout is not part of any contract.
+
 ### `bun-app-window/native` — The Prebuilt DLL
 
 Resolves to `dist/libshell.dll` itself, so `import.meta.resolve()` hands you a real path you can copy next to your executable:
@@ -421,13 +458,10 @@ Note: `F11`, `F12`, and `Ctrl±` zoom shortcuts are handled directly by the nati
 After disabling the default browser menu, render native Win32 popup menus (`TrackPopupMenu`) via `showContextMenu`. The page cannot call it directly — expose it through the IPC service first:
 
 ```ts
-// Host: expose the menu capability on the window service
+// Host: expose the menu capability on the flat service
 createIpcServer({
   service: {
-    window: {
-      showContextMenu: (x: number, y: number, items: string) =>
-        shell.showContextMenu(x, y, items),
-    },
+    showContextMenu: (x: number, y: number, items: string) => shell.showContextMenu(x, y, items),
   },
 });
 ```
@@ -436,7 +470,7 @@ createIpcServer({
 // Page: trigger the native menu
 document.addEventListener("contextmenu", async (e) => {
   e.preventDefault();
-  await api.window.showContextMenu(
+  await api.showContextMenu(
     Math.round(e.screenX),
     Math.round(e.screenY),
     "open|Open\nrefresh|Refresh\n-\nquit|Quit"
@@ -508,6 +542,19 @@ Tips:
 - A side-effect import `import "bun-app-window/embedded";` also works automatically.
 - Always pass `--windows-hide-console` for GUI builds; omitting it will spawn a black command prompt window alongside your application.
 
+### 6. Two Traps That Type-Check
+
+Neither of these fails `bun check`; both produce a window that renders and then does nothing.
+
+- **The page bundle is an ES module, so the `<script>` tag needs `type="module"`.** A build with a
+  top-level `await` is a syntax error inside a classic `<script>`, and the **whole script never
+  runs** — while the page still renders, because the markup is static. Nothing on screen points at
+  the cause.
+- **Namespace your own `data-*` selectors.** The title bar renders buttons with
+  `data-act="minimize|maximize|close"` and listens for clicks on `document`. A host that also binds
+  `button[data-act]` receives the same click twice and logs its own "unknown action: maximize".
+  Prefix your attributes (`data-mvp-act`): a generic name is a shared namespace, not yours.
+
 ## Internals & Reference
 
 ### Native Library Resolution Order

package/README.zh-CN.md

@@ -46,7 +46,7 @@ bun add bun-app-window
 
 ### 包内包含什么
 
-发布的 tarball 只有预编译的 `dist/libshell.dll` 与 TypeScript 源码，共 19 个文件（约 0.36 MB）。原生 C++ 层（`native/`）与上游 vendored 头文件（`vendor/`）**不随包分发**：它们只在重编 `libshell.dll` 时需要，而重编必须 clone 仓库。因此 `bun run build:native` 与 `build:exe` 是本仓库专用脚本，装进 `node_modules` 后执行没有意义。
+发布的 tarball 只有预编译的 `dist/libshell.dll` 与 TypeScript 源码，共 21 个文件（约 0.4 MB）。原生 C++ 层（`native/`）与上游 vendored 头文件（`vendor/`）**不随包分发**：它们只在重编 `libshell.dll` 时需要，而重编必须 clone 仓库。因此 `bun run build:native` 与 `build:exe` 是本仓库专用脚本，装进 `node_modules` 后执行没有意义。
 
 ## 快速开始
 
@@ -150,7 +150,12 @@ shell.setTitle("Doing work…");
 // 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" };
+import htmlText from "./index.html" with { type: "text" };
+
+// `with { type: "text" }` 让 Bun 在打包期把文件内联进去，所以 `bun build --compile` 后仍然成立。
+// TS 7.0.2 看不到这条声明——bun-types 把它 gate 在 `typesVersions >= 7.1` 后面，
+// 于是这个 import 被解析成 `HTMLBundle` 而不是 `string`。桥梁就落在这里。
+const html = htmlText as unknown as string;
 
 const app = await createApp({
   html,
@@ -164,6 +169,7 @@ const app = await createApp({
 });
 
 await app.wait();                  // 窗口关闭时 resolve
+await app.stop();                  // 释放事件泵与服务；幂等，已关闭时立即返回
 ```
 
 ```ts
@@ -188,9 +194,15 @@ await api.greet("Ada");
 
 - **默认不带 `FLAG_FRAMELESS`。** 无边框窗口没有系统标题栏就拖不动，必须由页面先挂上
   `mountTitleBar`。默认值选的是「页面什么都不做也能用」的那一侧。
+- **`wait()` 只负责等。** 它在 `EVENT_CLOSED` 上 resolve，但不会停事件泵、也不会关服务——而
+  事件泵的定时器是 ref 的（`keepAlive: true`），所以停在这一行的进程会在窗口消失后继续挂着。
+  必须跟一句 `stop()`：它幂等，且关闭已被观察到时会立即返回。
 - **静态资源只吃内联字符串。** `with { type: "text" }` 得到的是编译期常量：不碰文件系统、
-  不产生临时文件、`bun build --compile` 后仍然成立。要从磁盘读东西就写个 `routes` 函数 ——
-  五行，而且路径解析的问题留在你这边，不会渗进骨架。
+  不产生临时文件、`bun build --compile` 后仍然成立。TS 7.0.2 会把这条 import 解析成
+  `HTMLBundle` 而不是 `string`（`bun-types` 把正确的声明 gate 在 `typesVersions >= 7.1`
+  后面），示例里的 `as unknown as string` 就是为此而写。别用 `Bun.file().text()` 去「修」它：
+  那是运行期读盘，HTML 就不在编译产物里了。要从磁盘读东西就写个 `routes` 函数 —— 五行，
+  而且路径解析的问题留在你这边，不会渗进骨架。
 - **不从主入口导出。** 它和 `./state`、`./ipc` 一样是子路径。它从 `./index` 导入
   `openShell`；若 `index.ts` 反过来导出它，就成了循环。
 
@@ -240,39 +252,58 @@ api.on("windowState", (s) => bar.setMaximized(s.maximized));
 
 默认情况下，`connect` 会从当前页面 URL 的查询参数 `?t=` 中读取鉴权 Token 并连接至 `/ws`。若需自定义连接方式，可显式传入 `url` 或自定义 `channel` 实例。
 
+#### 客户端保留名
+
+客户端是一个 `Proxy`：有几个名字会解析到客户端自己身上，永远到不了远端方法。服务表里若有
+同名方法，**那个服务端方法就永远调不到**——页面调的是客户端自己的成员，两端都不会报错。
+
+| 名字 | 页面实际拿到的东西 |
+| --- | --- |
+| `on` / `off` | 事件订阅辅助函数 |
+| `close()` | 关闭 WebSocket 通道——之后所有调用都会被 reject |
+| `connected` | `boolean`，通道当前是否可用 |
+| `pending` | `number`，尚未收到回复的调用数 |
+| `then` | `undefined`，否则 `await client` 会把这个永不兑现的 thenable 等下去 |
+
+Symbol 键同样保留。给服务方法换个名字（`winClose` 而不是 `close`），在页面侧映射回去 ——
+见下面的标题栏一节。
+
 ### `bun-app-window/titlebar` — Windows 11 风格标题栏
 
-用于在无边框模式下快速挂载符合 Windows 11 视觉规范的自定义标题栏：
+用于在无边框模式下快速挂载符合 Windows 11 视觉规范的自定义标题栏。IPC 服务是**扁平的**——
+没有 `window` 这一层命名空间——而且四个最自然的名字里有一个被客户端自己占了，所以宿主端
+暴露 `winClose`，页面侧再映射回去：
 
 ```ts
-// 页面端
+// 宿主端 —— 扁平服务；`close` 是 IPC 客户端的保留名
+createIpcServer({
+  service: {
+    minimize: () => shell.minimize(),
+    toggleMaximize: () => shell.toggleMaximize(),
+    winClose: () => shell.close(),
+    drag: () => shell.drag(),
+  },
+});
+```
+
+```ts
+// 页面端 —— 显式拼出 bridge
 import { mountTitleBar, bridgeFromWindowService } from "bun-app-window/titlebar";
 
 const bar = mountTitleBar({
   title: "我的应用",
   icon: "/icon.svg",
-  bridge: bridgeFromWindowService(api.window),
+  bridge: bridgeFromWindowService({
+    minimize: () => api.minimize(),
+    toggleMaximize: () => api.toggleMaximize(),
+    close: () => api.winClose(),          // 桥接时再映射回 close
+    drag: () => api.drag(),
+  }),
 });
 
 api.on("windowState", (s) => bar.setMaximized(s.maximized));
 ```
 
-宿主端需在 IPC 服务中暴露对应的四个窗口控制方法：
-
-```ts
-// 宿主端
-createIpcServer({
-  service: {
-    window: {
-      minimize: () => shell.minimize(),
-      toggleMaximize: () => shell.toggleMaximize(),
-      close: () => shell.close(),
-      drag: () => shell.drag(),
-    },
-  },
-});
-```
-
 实现细节：
 
 - 原生拖拽体验：拖拽操作通过调用 `shell.drag()` 交由底层发送 `WM_NCLBUTTONDOWN`（`HTCAPTION`）消息处理，完整保留 Windows 11 贴边分屏（Snap Layouts）与双击最大化等系统级行为。
@@ -358,11 +389,14 @@ pump.onGap((missing) => console.warn(`漏了 ${missing} 条事件`));
 import { debugOf } from "bun-app-window/debug";
 
 const d = debugOf(shell);
-d.metrics();   // 获取 pos / win / client / work / border / round 等几何度量
-d.dpi();       // 获取当前 DPI 感知级别与缩放因子
+d.metrics();   // → "pos=196,196 win=1960x1400 client=1960x1400 work=3072x1824 border=13x13 round=1"
+d.dpi();       // → "awareness=-1 dpi=192 scale=200%"
 d.hittest(x, y);
 ```
 
+`metrics()` 与 `dpi()` 返回的是**格式化文本**，不是对象。真要解析就写进一次性脚本里，别把解析器
+塞进生产代码——这个格式不属于任何契约。
+
 ### `bun-app-window/native` — 预编译动态库本体
 
 该子路径解析到 `dist/libshell.dll` 本身，`import.meta.resolve()` 拿到的是可直接拷到 exe 旁边的真实路径：
@@ -404,13 +438,10 @@ const shell = await openShell({ url, browserUi: BROWSER_UI_ALL });
 禁用默认浏览器菜单后，可通过 `showContextMenu` 唤起基于 Win32 `TrackPopupMenu` 绘制的原生菜单。页面无法直接调用它——需要先在 IPC 服务上暴露：
 
 ```ts
-// 宿主端：把菜单能力挂到 window 服务上
+// 宿主端：把菜单能力挂到扁平服务上
 createIpcServer({
   service: {
-    window: {
-      showContextMenu: (x: number, y: number, items: string) =>
-        shell.showContextMenu(x, y, items),
-    },
+    showContextMenu: (x: number, y: number, items: string) => shell.showContextMenu(x, y, items),
   },
 });
 ```
@@ -419,7 +450,7 @@ createIpcServer({
 // 页面端触发菜单
 document.addEventListener("contextmenu", async (e) => {
   e.preventDefault();
-  await api.window.showContextMenu(
+  await api.showContextMenu(
     Math.round(e.screenX),
     Math.round(e.screenY),
     "open|打开\nrefresh|刷新\n-\nquit|退出"
@@ -489,6 +520,18 @@ bun build --compile --windows-hide-console src/index.ts --outfile dist/app.exe
 - 仅通过副作用导入 `import "bun-app-window/embedded";` 同样生效。
 - 打包桌面端应用时请务必添加 `--windows-hide-console` 参数，否则启动时将伴随弹出黑色命令行控制台窗口。
 
+### 6. 两个类型检查抓不到的坑
+
+这两条都不会让 `bun check` 变红，但都会得到一个「渲染正常、什么也不做」的窗口。
+
+- **页面 bundle 是 ES 模块，`<script>` 标签必须写 `type="module"`。** 带顶层 `await` 的构建
+  产物塞进经典 `<script>` 就是语法错，**整个脚本一行都不执行**——而页面照样渲染，因为 HTML
+  是静态的。屏幕上没有任何东西指向这个原因。
+- **自己的 `data-*` 选择器要给命名空间。** 标题栏的按钮用
+  `data-act="minimize|maximize|close"`，并在 `document` 上挂 click 监听。宿主如果也绑
+  `button[data-act]`，同一次点击会被接两遍，然后打出自己那句「未知动作：maximize」。给自己的
+  属性加前缀（`data-mvp-act`）——泛化属性名是共享命名空间，不是你的地盘。
+
 ## 底层机制与交互参考
 
 ### 原生动态库加载顺序

package/README.zh-TW.md

@@ -46,7 +46,7 @@ bun add bun-app-window
 
 ### 套件內容包含什麼
 
-發佈的 tarball 只有預先編譯的 `dist/libshell.dll` 與 TypeScript 原始碼，共 19 個檔案（約 0.36 MB）。原生 C++ 層（`native/`）與上游 vendored 標頭檔（`vendor/`）**不隨套件散布**：它們只在重新編譯 `libshell.dll` 時需要，而重新編譯必須 clone 儲存庫。因此 `bun run build:native` 與 `build:exe` 是本儲存庫專用指令碼，安裝進 `node_modules` 後執行沒有意義。
+發佈的 tarball 只有預先編譯的 `dist/libshell.dll` 與 TypeScript 原始碼，共 21 個檔案（約 0.4 MB）。原生 C++ 層（`native/`）與上游 vendored 標頭檔（`vendor/`）**不隨套件散布**：它們只在重新編譯 `libshell.dll` 時需要，而重新編譯必須 clone 儲存庫。因此 `bun run build:native` 與 `build:exe` 是本儲存庫專用指令碼，安裝進 `node_modules` 後執行沒有意義。
 
 ## 快速開始
 
@@ -150,7 +150,12 @@ shell.setTitle("Doing work…");
 // 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" };
+import htmlText from "./index.html" with { type: "text" };
+
+// `with { type: "text" }` 讓 Bun 在封裝期把檔案內嵌進去，所以 `bun build --compile` 後仍然成立。
+// TS 7.0.2 看不到這條宣告——bun-types 把它 gate 在 `typesVersions >= 7.1` 之後，
+// 於是這個 import 被解析成 `HTMLBundle` 而不是 `string`。橋樑就落在這裡。
+const html = htmlText as unknown as string;
 
 const app = await createApp({
   html,
@@ -164,6 +169,7 @@ const app = await createApp({
 });
 
 await app.wait();                  // 視窗關閉時 resolve
+await app.stop();                  // 釋放事件泵與服務；冪等，已關閉時立即回傳
 ```
 
 ```ts
@@ -188,9 +194,15 @@ await api.greet("Ada");
 
 - **預設不帶 `FLAG_FRAMELESS`。** 無邊框視窗沒有系統標題列就拖不動，必須由頁面先掛上
   `mountTitleBar`。預設值選的是「頁面什麼都不做也能用」的那一側。
+- **`wait()` 只負責等。** 它在 `EVENT_CLOSED` 上 resolve，但不會停事件泵、也不會關服務——而
+  事件泵的計時器是 ref 的（`keepAlive: true`），所以停在這一行的行程會在視窗消失後繼續掛著。
+  必須跟一句 `stop()`：它冪等，且關閉已被觀察到時會立即回傳。
 - **靜態資源只吃內嵌字串。** `with { type: "text" }` 得到的是編譯期常數：不碰檔案系統、
-  不產生暫存檔、`bun build --compile` 後仍然成立。要從磁碟讀東西就寫個 `routes` 函式 ——
-  五行，而且路徑解析的問題留在你這邊，不會滲進骨架。
+  不產生暫存檔、`bun build --compile` 後仍然成立。TS 7.0.2 會把這條 import 解析成
+  `HTMLBundle` 而不是 `string`（`bun-types` 把正確的宣告 gate 在 `typesVersions >= 7.1`
+  之後），範例裡的 `as unknown as string` 就是為此而寫。別用 `Bun.file().text()` 去「修」它：
+  那是執行期讀磁碟，HTML 就不在編譯產物裡了。要從磁碟讀東西就寫個 `routes` 函式 —— 五行，
+  而且路徑解析的問題留在你這邊，不會滲進骨架。
 - **不從主入口匯出。** 它和 `./state`、`./ipc` 一樣是子路徑。它從 `./index` 匯入
   `openShell`；若 `index.ts` 反過來匯出它，就成了循環。
 
@@ -240,39 +252,58 @@ api.on("windowState", (s) => bar.setMaximized(s.maximized));
 
 預設情況下，`connect` 會從目前頁面 URL 的查詢參數 `?t=` 中讀取驗證 Token 並連線至 `/ws`。若需自訂連線方式，可明確傳入 `url` 或自訂 `channel` 實例。
 
+#### 用戶端保留名稱
+
+用戶端是一個 `Proxy`：有幾個名稱會解析到用戶端自己身上，永遠到不了遠端方法。服務表裡若有
+同名方法，**那個服務端方法就永遠呼叫不到**——頁面呼叫的是用戶端自己的成員，兩端都不會報錯。
+
+| 名稱 | 頁面實際拿到的東西 |
+| --- | --- |
+| `on` / `off` | 事件訂閱輔助函式 |
+| `close()` | 關閉 WebSocket 通道——之後所有呼叫都會被 reject |
+| `connected` | `boolean`，通道目前是否可用 |
+| `pending` | `number`，尚未收到回覆的呼叫數 |
+| `then` | `undefined`，否則 `await client` 會把這個永不兌現的 thenable 等下去 |
+
+Symbol 鍵同樣保留。給服務方法換個名稱（`winClose` 而不是 `close`），在頁面端映射回去 ——
+見下方的標題列一節。
+
 ### `bun-app-window/titlebar` — Windows 11 風格標題列
 
-用於在無邊框模式下快速掛載符合 Windows 11 視覺規範的自訂標題列：
+用於在無邊框模式下快速掛載符合 Windows 11 視覺規範的自訂標題列。IPC 服務是**扁平的**——
+沒有 `window` 這一層命名空間——而且四個最自然的名稱裡有一個被用戶端自己佔了，所以宿主端
+公開 `winClose`，頁面端再映射回去：
 
 ```ts
-// 頁面端
+// 宿主端 —— 扁平服務；`close` 是 IPC 用戶端的保留名稱
+createIpcServer({
+  service: {
+    minimize: () => shell.minimize(),
+    toggleMaximize: () => shell.toggleMaximize(),
+    winClose: () => shell.close(),
+    drag: () => shell.drag(),
+  },
+});
+```
+
+```ts
+// 頁面端 —— 明確拼出 bridge
 import { mountTitleBar, bridgeFromWindowService } from "bun-app-window/titlebar";
 
 const bar = mountTitleBar({
   title: "我的應用程式",
   icon: "/icon.svg",
-  bridge: bridgeFromWindowService(api.window),
+  bridge: bridgeFromWindowService({
+    minimize: () => api.minimize(),
+    toggleMaximize: () => api.toggleMaximize(),
+    close: () => api.winClose(),          // 橋接時再映射回 close
+    drag: () => api.drag(),
+  }),
 });
 
 api.on("windowState", (s) => bar.setMaximized(s.maximized));
 ```
 
-宿主端需在 IPC 服務中公開對應的四個視窗控制方法：
-
-```ts
-// 宿主端
-createIpcServer({
-  service: {
-    window: {
-      minimize: () => shell.minimize(),
-      toggleMaximize: () => shell.toggleMaximize(),
-      close: () => shell.close(),
-      drag: () => shell.drag(),
-    },
-  },
-});
-```
-
 實作細節：
 
 - 原生拖曳體驗：拖曳操作透過呼叫 `shell.drag()` 交由底層發送 `WM_NCLBUTTONDOWN`（`HTCAPTION`）訊息處理，完整保留 Windows 11 貼齊版面配置（Snap Layouts）與連按兩下最大化等系統級行為。
@@ -359,11 +390,14 @@ pump.onGap((missing) => console.warn(`漏了 ${missing} 條事件`));
 import { debugOf } from "bun-app-window/debug";
 
 const d = debugOf(shell);
-d.metrics();   // 取得 pos / win / client / work / border / round 等幾何度量
-d.dpi();       // 取得目前 DPI 感知層級與縮放係數
+d.metrics();   // → "pos=196,196 win=1960x1400 client=1960x1400 work=3072x1824 border=13x13 round=1"
+d.dpi();       // → "awareness=-1 dpi=192 scale=200%"
 d.hittest(x, y);
 ```
 
+`metrics()` 與 `dpi()` 回傳的是**格式化文字**，不是物件。真要解析就寫進一次性指令碼裡，別把
+解析器塞進正式程式碼——這個格式不屬於任何契約。
+
 ### `bun-app-window/native` — 預編譯動態連結程式庫本體
 
 該子路徑解析到 `dist/libshell.dll` 本身，`import.meta.resolve()` 拿到的是可直接複製到 exe 旁邊的真實路徑：
@@ -405,13 +439,10 @@ const shell = await openShell({ url, browserUi: BROWSER_UI_ALL });
 停用預設瀏覽器選單後，可透過 `showContextMenu` 喚起基於 Win32 `TrackPopupMenu` 繪製的原生選單。頁面無法直接呼叫它——需先在 IPC 服務上暴露：
 
 ```ts
-// 宿主端：將選單能力掛載到 window 服務
+// 宿主端：將選單能力掛載到扁平服務上
 createIpcServer({
   service: {
-    window: {
-      showContextMenu: (x: number, y: number, items: string) =>
-        shell.showContextMenu(x, y, items),
-    },
+    showContextMenu: (x: number, y: number, items: string) => shell.showContextMenu(x, y, items),
   },
 });
 ```
@@ -420,7 +451,7 @@ createIpcServer({
 // 頁面端觸發選單
 document.addEventListener("contextmenu", async (e) => {
   e.preventDefault();
-  await api.window.showContextMenu(
+  await api.showContextMenu(
     Math.round(e.screenX),
     Math.round(e.screenY),
     "open|開啟\nrefresh|重新整理\n-\nquit|結束"
@@ -490,6 +521,18 @@ bun build --compile --windows-hide-console src/index.ts --outfile dist/app.exe
 - 僅透過副作用匯入 `import "bun-app-window/embedded";` 同樣生效。
 - 封裝桌面端應用程式時請務必加上 `--windows-hide-console` 參數，否則啟動時將伴隨彈出黑色主控台（Console）視窗。
 
+### 6. 兩個型別檢查抓不到的坑
+
+這兩條都不會讓 `bun check` 變紅，但都會得到一個「渲染正常、什麼也不做」的視窗。
+
+- **頁面 bundle 是 ES 模組，`<script>` 標籤必須寫 `type="module"`。** 帶頂層 `await` 的封裝
+  產物塞進傳統 `<script>` 就是語法錯誤，**整個指令碼一行都不執行**——而頁面照樣渲染，因為
+  HTML 是靜態的。螢幕上沒有任何東西指向這個原因。
+- **自己的 `data-*` 選擇器要給命名空間。** 標題列的按鈕用
+  `data-act="minimize|maximize|close"`，並在 `document` 上掛 click 監聽。宿主如果也綁
+  `button[data-act]`，同一次點擊會被接兩遍，然後打出自己那句「未知動作：maximize」。給自己的
+  屬性加前綴（`data-mvp-act`）——泛化屬性名稱是共享命名空間，不是你的地盤。
+
 ## 底層機制與互動參考
 
 ### 原生動態連結程式庫載入順序

package/package.json

@@ -1,7 +1,7 @@
 {
     "$schema": "https://json.schemastore.org/package.json",
     "name": "bun-app-window",
-    "version": "0.4.0",
+    "version": "0.4.1",
     "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",

package/src/ui/titlebar.ts

@@ -234,7 +234,12 @@ export type TitleBarHandle = {
 };
 
 function resolveDocument(doc?: TitleBarDocument): TitleBarDocument {
-    const found = doc ?? (globalThis as { document?: TitleBarDocument }).document;
+    // 双层断言是必需的，不是笔误：消费者 tsconfig 的 `lib` 含 `DOM` 时，
+    // `globalThis.document` 是完整的 `Document`，与本组件的极简结构不重叠，
+    // 单层 `as` 会被判成 TS2352「两侧类型不够重叠」。`skipLibCheck` 挡不住——
+    // 这是包内 `.ts` 源码，不是 `.d.ts`。本仓 tsconfig 的 lib 只有 ESNext，
+    // 这个错在本仓永远复现不出来，判据落在 tests/titlebar.test.ts 的源码断言上。
+    const found = doc ?? (globalThis as unknown as { document?: TitleBarDocument }).document;
     if (!found) {
         throw new Error("mountTitleBar: no document available; pass options.document");
     }