bun-app-window 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -4,7 +4,113 @@ 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).
 
-## [Unreleased]
+## [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
+
+- `bun-app-window/events` — window lifecycle events, and the end of polling. Until this release the host had exactly one way to learn that the window changed: ask again. `shell.isAlive()` every 50 ms to notice a close, and `attachPlacementStore` calling `getBounds()` every 700 ms. The module comment in `state.ts` gave the reason — "the native side pushes window state to the **page** (shell-msg); the host cannot see it, and adding a native→host callback channel means a whole lifecycle to manage".
+
+    A callback is not available: `webview_run` blocks the native UI thread while `bun:ffi`'s `JSCallback` needs an idle JS thread, and the two together deadlock (ADR 0002). So the channel is a fixed ring plus a pull:
+
+    ```text
+    native: UI thread appends 32-byte records to a 128-slot ring,
+            holding one SRWLOCK for at most a 4 KiB copy
+    host:   shell_poll_events(buf, capacity) → shell.pollEvents() / attachEventPump()
+    ```
+
+    Four decisions, each with a failure mode behind it:
+
+    **Capacity 128, drop the oldest.** A one-second drag at a 16 ms cadence is about 60 events, so 128 is a two-fold margin. Dropping the *newest* instead would freeze the ring at a stale state and the host would see "the window never changed" — far worse than losing history. Losses are reported as gaps in `seq` rather than synthesised into an overflow event: the gap carries the exact count, and no new `seq` special case is needed.
+
+    **`CLOSED` is emitted after teardown completes.** That is the whole point: "saw `CLOSED`" must be equivalent to "the process-wide singleton is released, restart is safe". It follows that `shell_poll_events` must **not** return -1 when `g_webview` is null, unlike every other export — `CLOSED` is produced precisely after the handle is gone.
+
+    **Both window procedures enqueue.** `shell_wnd_proc` is only registered for the `webview_shell` class, which only `FLAG_FRAMELESS` uses. A framed window is created by the webview library, and only the `toplevel_proc` subclass sees its `WM_SIZE`. Enqueueing next to `push_state()` alone would leave the **default** configuration permanently silent about size and maximize events, with every test green.
+
+    **The event side keeps its own change-detection cache.** `push_state` compares against `g_pushed` to throttle cross-process `webview_eval`. Recording the same state into the ring is a memory write, and the consumers differ: sharing the cache would let the page push's "unchanged, skip" swallow the host's events too.
+
+- `shell.pollEvents(max?)` on the main entry — the raw pull primitive. Synchronous, consuming, and documented as single-consumer: drained records never come back, so a process should have exactly one reader.
+
+- `EventCursor` and `attachEventPump()` — the cursor turns `seq` into "how many did I miss", and the pump supplies a cadence with multi-subscriber fan-out (`on()` / `onGap()`), stopping itself once `CLOSED` arrives.
+
+- `bun-app-window/app` — an application skeleton, and the answer to a specific number: **180**. That is how much host boilerplate a first app needed before this release, against roughly 30 lines of business code. Picking a browser-safe port, minting a per-run auth token, handling the WebSocket upgrade, serving HTML as a string, wiring `createIpcServer` into Bun's websocket callbacks, composing window flags, handling `openShell` failure, waiting for window close, and calling `stop()` on two things — each piece is easy, but they are only correct in one order. `createApp()` collapses it:
+
+    ```ts
+    const app = await createApp({ html, service: { greet: (n) => `hi ${n}` } });
+    await app.wait();
+    ```
+
+    Three decisions worth recording:
+
+    **It does not default to `FLAG_FRAMELESS`.** A frameless window has no system title bar, so it cannot be dragged until the page mounts `mountTitleBar`. A skeleton whose default value breaks the "hello world" case is worse than no skeleton, so the default is `FLAG_RESIZABLE | FLAG_CENTER` — the side that works even when the page does nothing.
+
+    **It is not re-exported from the main entry.** `app.ts` imports `openShell` from `./index`; exporting it back from `index.ts` would make that a cycle. It is a subpath like `./state` and `./ipc`, and a static assertion in `tests/app.test.ts` keeps it that way.
+
+    **Static assets are inline strings only.** `import html from "./index.html" with { type: "text" }` yields a compile-time constant: nothing touches the filesystem, no temp files, and it survives `bun build --compile`. Reading from a directory has to cope with `import.meta.dir` pointing at `B:\~BUN\root` after packing — the `PACKED` branch in `src/host.ts` exists precisely for that. Five lines in a `routes` callback is a better trade than leaking that problem into the skeleton.
+
+- `decideWs()` — the `/ws` decision, extracted as a pure function because it is the only branch in the skeleton and it has three ways to be wrong. `/ws` with IPC disabled is a **404, not a 403**: a 403 advertises that a channel exists. The token check must happen **before** the upgrade — after upgrading there is no chance to refuse. And the path comparison must come first, or a caller's catch-all route (the usual SPA fallback) swallows the upgrade request, leaving a page that can never connect while HTTP looks perfectly healthy.
+
+### Changed
+
+- `attachPlacementStore` is now event-driven. It used to call `getBounds()` every 700 ms; it now takes a snapshot the moment a `STATE` event arrives and batches the disk write until 300 ms after the window settles. A window at rest costs zero native calls and zero disk writes, and a drag no longer writes on every frame. The `intervalMs` option is replaced by `debounceMs` (write delay) and `pumpMs` (internal pump cadence) — a 0.x minor is allowed to break that, and the old name would now be a lie.
+
+    Snapshot and write are deliberately separate. Once the window is destroyed, `format_bounds()` returns an empty string because `!g_hwnd`; reading at debounce time would therefore drop the last change — exactly the one made by "drag, then immediately click X", which is how most people close a window.
+
+- `createApp`'s `stop()` and `wait()` wait for `EVENT_CLOSED` instead of polling `isAlive()` every 50 ms. The 5-second ceiling stays: if the event channel ever fails, the host must not hang forever, and the timeout also resolves the close promise so `wait()` cannot hang on a dead channel. `isAlive()` keeps its symbol and its API — it is still a legitimate instant snapshot — but it is no longer the waiting criterion. `app.events` is exposed as the single consumer, so `attachPlacementStore(shell, file, { events: app.events })` reuses it instead of starting a second one.
+
+- Exported symbols 33 → 34 and TypeScript declarations 32 → 33 (`shell_poll_events`). `native-surface.test.ts`'s hand-written `DECLARED` list and its total-count assertion moved with it.
+
+- Twelve assertions in `tests/app.test.ts` plus seven in `scripts/consumer-probe.ts`. The probe now also exercises `bun-app-window/app` from the installed package.
+- Three hardcoded counts in the docs are gone (`40 assertions`, `8 subpaths`, `182 test cases`): all three had already drifted. The consumer probe reports its own count now, and `AGENTS.md` says so.
+
+### Note
+
+- The pump timer's `unref` is not an implementation detail. An unref'd timer does not hold the event loop open, and a promise that never resolves does not either — so a host that `await`s for close while relying on an unref'd pump will exit with the window still open, which looks like "the app flashes and quits". `./state` unrefs (a persistence timer should not keep a process alive); `./app` pins the timer with `keepAlive: true` because waiting for close is exactly what it needs to survive.
+
+- The acceptance for this release was bidirectional rather than one-sided. Commenting out `emit_event(SHELL_EVENT_STATE, ...)`, rebuilding, and running `scripts/probe-window-events.ts` turned it from 21/21 green to 11/21 red with `exit=1` — while the ten `CLOSED` assertions stayed green, confirming the injection was isolated to the state path. Restoring and rebuilding returned 21/21, and `verify-dll.ts` reported the same sha256 as before the injection, which also proves the build is reproducible. `docs/pitfalls.md` 2.4k records the four failure modes found along the way.
+
+- This is **not** a competitor to `Bun.WebView`, and the READMEs now say so explicitly. `Bun.WebView` is a *headless* browser for automation, testing and scraping: it has no window, and it can only screenshot its own page. This package draws a real desktop window — system title bar, DPI awareness, snap layouts, taskbar identity — and its capture tool can photograph **any** window, which is the whole point for computer-use. Comparing API surface between the two is comparing different problems.
 
 ## [0.3.0] - 2026-10-21
 
@@ -221,7 +327,9 @@ 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.3.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
 [0.2.1]: https://github.com/TiancongLx/bun-app-window/compare/v0.2.0...v0.2.1

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
 
@@ -84,7 +84,8 @@ Note: `createShell(opts)` only resolves and loads the native DLL without opening
 | `start()` | Opens the window and returns `{ rc, error }`. Returns immediately while the UI message loop runs on a dedicated native thread |
 | `stop()` | Destroys the window and releases native resources. Safe to call multiple times (idempotent) |
 | `show()` | Reveals the window. Typically paired with `FLAG_DEFER_SHOW` to display the window only after the web UI is ready |
-| `isAlive()` | Checks whether the native window still exists (unlike `state()`, which cannot distinguish between unstarted and destroyed states) |
+| `isAlive()` | Checks whether the native window still exists (unlike `state()`, which cannot distinguish between unstarted and destroyed states). To wait for close, use `pollEvents()` and watch for `CLOSED` instead of polling this |
+| `pollEvents(max?)` | Drains window lifecycle events (`STATE` / `CLOSED`); synchronous and consuming. See "Window events" below |
 | `state()` | Returns current window state: `{ maximized, minimized, focused, dark, raw }` |
 | `lastError()` | Returns the most recent failure message, or an empty string if no error occurred |
 | `setTitle` / `minimize` / `toggleMaximize` / `close` | Standard window control operations; each returns a status code `rc` |
@@ -138,6 +139,88 @@ the default picks the safe side.
 
 Additional capabilities outside core window management are modularized into dedicated subpath exports.
 
+### `bun-app-window/app` — Application Skeleton
+
+The first app you write with this package is about 30 lines of business code and **180 lines of
+host boilerplate**: picking a safe port, minting an auth token, handling the WebSocket upgrade,
+serving the HTML as a string, wiring `createIpcServer` into Bun's websocket callbacks, composing
+window flags, handling `openShell` failure, waiting for close (`EVENT_CLOSED`), and calling
+`stop()` on two things in the right order. Each piece is easy; they are only correct in a specific
+order (`stop()` must wait for the window to actually die before closing the server, or the next
+start hits "already started"). `app` collapses all of it into one call:
+
+```ts
+// main.ts
+import { createApp } from "bun-app-window/app";
+import { BROWSER_UI_ALL, FLAG_FRAMELESS } from "bun-app-window";
+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,
+  title: "My App",
+  flags: FLAG_FRAMELESS,          // opt in to a self-drawn title bar
+  browserUi: BROWSER_UI_ALL,
+  service: {
+    greet: (name: string) => `hi ${name}`,
+    pickFolder: () => app.shell.pickFolder(),
+  },
+});
+
+await app.wait();                  // resolves when the window closes
+await app.stop();                  // releases the event pump and the server; idempotent
+```
+
+```ts
+// page.ts — inside index.html's bundle
+import { connect } from "bun-app-window/ipc";
+const api = await connect();       // token comes from the page URL's ?t=
+await api.greet("Ada");
+```
+
+What it does for you:
+
+- Binds a browser-safe port (never one that yields `ERR_UNSAFE_PORT`) and serves your HTML.
+- Generates a per-run token and guards `/ws` with it **before** the upgrade — after upgrading there
+  is no chance to refuse. `/ws` with IPC disabled is a `404`, not a `403`: a 403 would advertise
+  that a channel exists.
+- Wires `createIpcServer` into the websocket `open` / `message` / `close` callbacks so
+  `ipc.emit()` reaches the page.
+- `stop()` is ordered and idempotent: `shell.stop()` → wait for `EVENT_CLOSED` (5 s ceiling) →
+  `server.stop()`.
+- Starts exactly one window-event pump: `app.events`. It is also what waits for close, so it is
+  the single consumer. Pass `{ events: app.events }` when you need `attachPlacementStore`.
+- Startup failures leave nothing half-started: if `openShell` throws, the bound port is released.
+
+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`. 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.
+
+This is **not** a replacement for `Bun.WebView`. That one is a *headless* browser for automation,
+testing and scraping — it has no window, and it can only screenshot its own page. This package
+draws a real desktop window with a system title bar, DPI awareness, snap layouts and taskbar
+identity. The two do not compete.
+
 ### `bun-app-window/ipc` — Typed RPC & Event Bus
 
 Share a single TypeScript contract between the host and the web page for compile-time verification of method signatures and event payloads:
@@ -180,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.
@@ -233,7 +336,7 @@ if (saved) restorePlacement(shell, saved);
 
 shell.show();
 
-const store = attachPlacementStore(shell, FILE);   // Polls state; skips disk writes when idle
+const store = attachPlacementStore(shell, FILE);   // Subscribes to window events; writes once the drag settles
 process.on("beforeExit", () => store.flush());
 ```
 
@@ -243,7 +346,60 @@ The native placement layer handles edge cases automatically:
 - Translates coordinates across monitors with different DPI scaling factors.
 - Validates and clamps off-screen coordinates when monitor topology changes.
 
-For one-off reads and writes without polling timers, use `capturePlacement` and `savePlacement` directly.
+Writes are event-driven: a state change takes a snapshot **immediately** (a microsecond-scale
+read), and the disk write is batched 300 ms after the window settles. A window at rest costs
+neither a native call nor a disk write. Tune the write delay with `debounceMs`; tune the
+internal event pump's cadence with `pumpMs`.
+
+If you already have an event pump (for example from `createApp`), pass it in so two consumers
+do not race for the same events:
+
+```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 });
+```
+
+For one-off reads and writes without any subscription, use `capturePlacement` and
+`savePlacement` directly.
+
+### Window events
+
+The host does not have to poll to learn that the window changed — `pollEvents()` returns the
+event stream directly:
+
+```ts
+import { EVENT_CLOSED, EVENT_STATE } from "bun-app-window/events";
+
+for (const e of shell.pollEvents()) {
+  if (e.type === EVENT_CLOSED) break;          // window is gone, the native singleton is released
+  if (e.type === EVENT_STATE && e.maximized) { /* ... */ }
+}
+```
+
+`pollEvents()` is **consuming**: drained records never come back, so a process should have
+exactly one consumer. For a fixed cadence plus multi-subscriber fan-out, use
+`attachEventPump()` from `./events`:
+
+```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(`missed ${missing} events`));
+```
+
+- A `STATE` payload is a **snapshot**: `width` / `height` / `dpi` plus four flags
+  (`maximized` / `minimized` / `focused` / `dark`).
+- `CLOSED` is terminal. It is emitted by the native layer after teardown has fully completed
+  and the window handle is gone, so "seeing `CLOSED`" is equivalent to "safe to restart the
+  window" — that is what makes it stronger than `isAlive()`.
+- The native ring buffer holds 128 records and drops the oldest when full. Losses are reported
+  faithfully as gaps in `seq` (via `onGap`), never disguised as "nothing happened".
+- The pump timer is `unref`'d by default (it will not keep the process alive). Pass
+  `keepAlive: true` when you rely on it to wait for window close.
 
 ### `bun-app-window/debug` — Diagnostics
 
@@ -253,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:
@@ -299,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),
   },
 });
 ```
@@ -314,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"
@@ -386,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
@@ -421,7 +590,7 @@ bun run scripts/gate.ts --clean      # same gates, but inside a fresh clone of H
 
 `-Clean` reproduces the conditions a hosted runner would provide: it clones `HEAD` into `%TEMP%`, installs from the lockfile, and runs the gates there, so local artefacts (`.build/`, `node_modules/`, `vendor/webview2/`) cannot mask a missing file. It takes about two seconds. Uncommitted changes are reported and excluded — run without `-Clean` to verify the working tree as-is.
 
-The gate has three stages: `bun check`, `bun test`, and consumer acceptance (`scripts/verify-pack.ts`). The third packs the tarball, installs it into a scratch project under `%TEMP%`, type-checks that project, and runs `scripts/consumer-probe.ts` against the installed package — 40 assertions covering every subpath, the DLL actually being `dlopen`-ed out of `node_modules`, and `libInfo.source === "package"`. It runs offline in about 0.4 s and denies by default: a file packed without being listed in the allow-list fails the gate. Pass `-SkipPack` only when the gate itself is what you are changing.
+The gate has three stages: `bun check`, `bun test`, and consumer acceptance (`scripts/verify-pack.ts`). The third packs the tarball, installs it into a scratch project under `%TEMP%`, type-checks that project, and runs `scripts/consumer-probe.ts` against the installed package — assertions covering every subpath, the DLL actually being `dlopen`-ed out of `node_modules`, and `libInfo.source === "package"` (the probe reports its own count). It runs offline in about 0.4 s and denies by default: a file packed without being listed in the allow-list fails the gate. Pass `-SkipPack` only when the gate itself is what you are changing.
 
 The underlying commands remain available directly: