bun-app-window 0.5.1 → 0.6.0

package/CHANGELOG.md

@@ -4,6 +4,74 @@ 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]
+
+_(nothing yet)_
+
+## [0.6.0] - 2026-10-21
+
+**`beginResize` now takes `RESIZE_EDGE` values (10–17) instead of raw native indices, and five sources of consumer boilerplate are gone. The first is a behaviour change; the rest are additive.**
+
+### Added
+
+- **`bun-app-window/types` — a zero-dependency subpath, safe to bundle for the browser.** `src/shell/types.ts` was already import-free, but there was no way to reach it: the main entry pulls in `./native`, which imports `bun:ffi`, and a browser bundle cannot resolve that (`pitfalls` 5.14). So consumers hand-copied constants — `BROWSER_UI_*` (5 bits), `ZOOM_LADDER` (14 steps), the 8 edge indices — with no gate able to notice when a copy drifted from the source.
+
+    The subpath's entire value rests on one invariant: **`types.ts` must stay import-free**. Adding a single `import` silently makes it browser-unsafe, and the symptom is a `Could not resolve "bun:ffi"` several layers away from the cause. `tests/types-purity.test.ts` pins it with a static assertion (comments stripped first — the file's own prose mentions `import` while explaining why it cannot be used), plus a self-check that the predicate can actually fail.
+
+- **`ZOOM_LADDER` / `ZOOM_MIN` / `ZOOM_MAX`.** The ladder previously existed only as `kZoomLadder[]` in `native/shell.cc`. `apply_zoom` clamps to the ends without snapping to intermediate steps, so this table is for UIs that want to walk it — which meant every UI kept its own copy of fourteen numbers.
+
+- **`RESIZE_INDEX` and `resizeIndex(edge)`.** The HT* → native-index map, needed by anything calling `shell.symbols.shell_begin_resize()` directly. Exported because hand-writing it is guaranteed to be wrong: it is not `value - 10` (see Fixed).
+
+- **`NativeLibInfo.version`.** `resolve.ts` reads it from the packaged `package.json`. Consumers used to need `import libPkg from "bun-app-window/package.json"` just to display which version they were talking to.
+
+- **`ackOf(shell, rc)`** on the main entry. Turns a bare `rc` into `{ rc, err }`, and centralises the rule that `lastError()` is only read on failure — the error buffer is not cleared by a successful call, so reading it after one returns the previous fault and displays as a phantom.
+
+- **`App.debug`** — equivalent to `debugOf(app.shell)`, saving a call and a subpath import. The stability promise is unchanged: diagnostics may change at any time and production code should not depend on them.
+
+- **`App.attachPlacement(file, opts?)`** — wires placement persistence to the skeleton's single event pump. Calling `attachPlacementStore(shell, file)` without `{ events }` makes it start a **second** pump, and `shell.pollEvents()` is consumptive: the two pumps each get part of the stream, window position is dropped at random, and neither side reports anything. This was the library's easiest way to fail silently, so the choice was removed rather than documented harder.
+
+- **`bun-app-window/pack`** — the page-script bundler, so consumers stop writing it. `bundlePage({ entry })` returns `{ code, bytes }`; `writePageBundle({ entry, out })` also writes and re-checks the on-disk size. Three things are fixed rather than configurable: `target: "browser"` and `format: "esm"` (that is what a page script *is*), and reporting **bytes** instead of `string.length` — the latter is UTF-16 code units, which on a source containing CJK drifts from the byte count by a wide margin while the unit is printed as `B`. Measured on a consumer: reported `35,085 B`, on-disk `37,319 B`.
+
+    Failure handling covers both shapes `Bun.build` produces, which was not obvious: compile-time diagnostics come back as `{ success: false, logs }`, but an **unreachable entry point throws an `AggregateError`** whose `message` is only `Bundle failed` and whose members live on `.errors` — `.logs` does not exist on that path. Without the second branch, the most common mistake (a wrong entry path) produced a message with no information in it.
+
+- **`AppOptions.page`** — pass the packed page script and `createApp` serves it at `PAGE_JS_PATH` (`/page.js`) with `content-type: text/javascript; charset=utf-8`. This removes the ten-line `routes` callback from every consumer and, more importantly, removes the way it goes wrong: a wrong or missing MIME type makes `<script type="module">` refuse to execute with no syntax error, which reads as "the page logic is broken". A caller's `routes` still wins, so the path stays overridable.
+
+### Changed
+
+- **BREAKING: `Shell.beginResize(edge)` takes `RESIZE_EDGE` values (10–17).** Migrating from 0.5.x:
+
+    | You were passing | Before | Now |
+    | --- | --- | --- |
+    | `RESIZE_EDGE.LEFT` (10) and friends | `rc=-1`, nothing moved | works |
+    | raw indices 0–7 | worked | `rc=-1` |
+
+    If you were passing raw indices, replace them with the matching `RESIZE_EDGE` member — `RESIZE_INDEX` is exported if you need to see the mapping.
+
+- `tests/gate.test.ts` shrank with the stage: `parsePs1Summary` and the `.ps1`-failure short-circuit assertions are gone, and `planStages` now asserts three stages.
+- **A new assertion keeps the deletion honest.** `tests/gate.test.ts` now fails if a `.ps1` appears anywhere in the repository. Deleting a stage and leaving nothing behind would mean the next `.ps1` arrives ungoverned and looks exactly like "the migration is complete". Verified in both directions: creating `scripts/__probe.ps1` turns it red naming that path, removing it returns green.
+- `docs/pitfalls.md` 3.18 keeps all five traps and is re-headed as *retired* rather than *paused* — the values and consequences were measured, so the record outlives the script. 5.2 and 5.6 no longer describe a `.ps1` that might come back.
+- Two ghost instructions surfaced while deleting: `scripts/trust-cert.ts` told the user to run `scripts/test-sign.ts`, a path that never existed, and `native/build-pack.ts` told them to run `scripts/make-icon.ps1`, which was migrated to TypeScript long ago. Both now point at something that exists.
+
+### Fixed
+
+- **`RESIZE_EDGE` and `shell_begin_resize()` were never the same numbering** (`pitfalls` 5.13). `RESIZE_EDGE` is the Win32 `HT*` constants (10–17); the native side reads `codes[edge]` as an **array index 0–7** over `{HTLEFT, HTRIGHT, HTTOP, HTBOTTOM, HTTOPLEFT, HTTOPRIGHT, HTBOTTOMLEFT, HTBOTTOMRIGHT}`. The mapping is therefore not an offset — `HTTOPLEFT` (13) lands at index 4 while `HTBOTTOM` (15) lands at 3. `beginResize` used to pass its argument straight through, so following the documentation produced `rc=-1` and a window that did not resize, while the gate stayed green.
+
+    Fixed in TypeScript, so **the DLL does not need rebuilding**. Three assertions now hold the mapping down, the important one being that it is *not* `value - 10`: subtracting ten happens to be correct for the first three entries (LEFT/RIGHT/TOP → 0/1/2) and wrong from the fourth on, which is exactly how a partial assertion would have given false confidence.
+
+### Removed
+
+**The last two PowerShell scripts are deleted rather than migrated, and the gate's `.ps1` stage went with them.**
+
+- **`scripts/test-sign.ps1` and `scripts/verify-sign-crypto.ps1` are gone — 195 lines that will not be replaced.** The standing decision (`ADR 0014`) was "these two stay PowerShell forever". Both premises failed in the same direction, so the third outcome applies: the capability itself is no longer wanted.
+
+    - `verify-sign-crypto` was ported far enough to prove the port feasible: five constant/structure traps were each resolved against a real sample (`pitfalls` 3.18 has all five, including `CERT_QUERY_CONTENT_FLAG_PKCS7_SIGNED_EMBED` being `0x100` and `CMSG_VERIFY_SIGNER_NULL` being `4`). It stopped at the last step — `CryptMsgControl` wants the signer's certificate context, the message does not embed one, and reconstructing a `PCCERT_CONTEXT` from the store never resolved. That path buys exactly one thing: the three facts in `pitfalls` 4.7 (valid maths is not trust; a tampered file keeps a `VALID` PKCS#7; `HashMismatch` is the only reliable verdict) could be asserted in `bun test`. They are already written down, and re-pinning them changes no behaviour.
+    - `test-sign` needs `SignerSign` / `SignerSignEx2` from `mssign32.dll`, which Microsoft documents nowhere. A `bun:ffi` declaration is validated by writing it from the documentation against a minimal input — there is no documentation to write it from.
+    - Neither was in the release flow: `AGENTS.md` §7.4 records that no commercial code-signing certificate is connected yet. When one is, the tool is `signtool`, not a hand-rolled verifier.
+
+- **The gate's second stage (`.ps1` syntax check) is deleted.** It existed as a migration-period fence for scripts that had neither type checking nor tests. With zero `.ps1` left it scans nothing, and a stage that can only ever report green is dead weight. Stages are now `bun check` → `bun test` → consumer acceptance: 1.3 s versus 1.8 s for four, and **the gate no longer needs `pwsh`** — only `bun` and `git`.
+
+- **The shell's capture remnants are gone (`ADR 0017`).** `native/gdi.ts` lost 142 of its 380 lines: `captureWindow`, `cropBgra`, `parseCrop`, `nonBlackPercent`, and the `GetDIBits` dlopen block that served only them. No caller remained inside the repository — the one test that referenced `cropBgra` was asserting against a function nothing used. Window capture lives in `echoes-of-the-eye` (formerly `agent-eyes`, renamed in the same window); the shell keeps only the icon-extraction closure that `scripts/extract-icon.ts` needs to prove `--windows-icon` works. **Repository-only**: `native/` is not published, so nothing changes for package consumers.
+
 ## [0.5.1] - 2026-10-21
 
 **0.5.0's drag-and-drop fix was wrong and made dropped files be refused outright. This release replaces it, and adds folder support. The public API is unchanged.**
@@ -464,7 +532,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.5.1...HEAD
+[Unreleased]: https://github.com/TiancongLx/bun-app-window/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/TiancongLx/bun-app-window/compare/v0.5.1...v0.6.0
 [0.5.1]: https://github.com/TiancongLx/bun-app-window/compare/v0.5.0...v0.5.1
 [0.5.0]: https://github.com/TiancongLx/bun-app-window/compare/v0.4.1...v0.5.0
 [0.4.1]: https://github.com/TiancongLx/bun-app-window/compare/v0.4.0...v0.4.1

package/README.md

@@ -2,6 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/bun-app-window?color=cb3837&logo=npm)](https://www.npmjs.com/package/bun-app-window)
 [![Bun](https://img.shields.io/badge/Bun-%3E%3D1.4.3-f472b6?logo=bun&logoColor=white)](https://bun.sh)
+[![TypeScript](https://img.shields.io/badge/TypeScript-%3E%3D7.0.2-3178C6?logo=typescript&logoColor=white)](#requirements--design-boundaries)
 [![Platform](https://img.shields.io/badge/Platform-Windows%20x64-0078D6?logo=windows&logoColor=white)](#requirements--design-boundaries)
 [![WebView2](https://img.shields.io/badge/WebView2-System%20Runtime-008080)](#requirements--design-boundaries)
 [![License](https://img.shields.io/badge/License-MIT-2ea44f)](./LICENSE)
@@ -29,6 +30,7 @@ Before adopting this package, please review the following architectural constrai
 | --- | --- |
 | Windows x64 only | Enforced via `os` and `cpu` fields in `package.json` (the platform-neutral package name is reserved for future expansion). A prebuilt `libshell.dll` is shipped in the package; no install-time compilation is required |
 | Bun runtime required | Ships raw TypeScript source files and requires Bun >= 1.4.3. While Node.js can install the package, it cannot execute it |
+| TypeScript >= 7.0.2 to type-check it | The API is designed and checked on TypeScript 7.0.2, pinned exactly in `devDependencies`; no compatibility work is done for older compilers. Above 7.0.2 the outcome is unasserted — `bun-types` only opens its `typesVersions: ">= 7.1"` gate there, which changes what a `with { type: "text" }` import resolves to |
 | Type-checking needs `@types/bun` | Because the package ships `.ts` sources, your own `bun check` compiles them too. Add `bun add -d @types/bun`; without it the checker reports `TS2868: Cannot find name 'Bun'` from inside `node_modules` |
 | Built on `bun:ffi` | `bun:ffi` is marked as experimental in Bun. While Bun recommends Node-API for production stability, this library chooses `bun:ffi` to achieve a zero-dependency footprint |
 
@@ -175,6 +177,28 @@ await app.wait();                  // resolves when the window closes
 await app.stop();                  // releases the event pump and the server; idempotent
 ```
 
+Pass `page` to serve a bundled page script without writing a route yourself. `createApp` answers
+`PAGE_JS_PATH` (`/page.js`) with the right `content-type`, which is the part that silently breaks:
+a module script served as `text/plain` is refused with no syntax error, so the page renders and
+nothing runs.
+
+```ts
+import { bundlePage } from "bun-app-window/pack";
+
+// Build time, not startup — see the `pack` section below.
+const { code } = await bundlePage({ entry: "src/ui/page.ts" });
+
+const app = await createApp({ html, page: code, service });
+```
+
+Two more things on `App` that save a call and a subpath import:
+
+- `app.debug` — the same object `debugOf(app.shell)` returns. Still outside the stability contract.
+- `app.attachPlacement(file)` — wires placement persistence to the skeleton's **single** event pump.
+  Call `attachPlacementStore` yourself and forget `{ events: app.events }`, and it starts a second
+  pump; since `shell.pollEvents()` is consumptive, the two split the stream and window position is
+  dropped at random with no error on either side. This method makes that mistake unrepresentable.
+
 ```ts
 // page.ts — inside index.html's bundle
 import { connect } from "bun-app-window/ipc";
@@ -436,6 +460,47 @@ 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/types` — Constants, Safe for the Browser
+
+A zero-dependency module holding the whole constant surface: `FLAG_*`, `BROWSER_UI_*`, `RESIZE_EDGE`,
+`RESIZE_INDEX`, `ZOOM_LADDER`, `ZOOM_MIN`, `ZOOM_MAX`, `STATE_*`, and the related types.
+
+**Use this subpath on the page side.** The main entry imports `bun:ffi` through `./native`, which a
+browser bundle cannot resolve — so `import { BROWSER_UI_ALL } from "bun-app-window"` inside page code
+fails at bundle time. This subpath exists precisely so the same constants can be shared instead of
+hand-copied:
+
+```ts
+import { BROWSER_UI_ALL, ZOOM_LADDER, RESIZE_EDGE, resizeIndex } from "bun-app-window/types";
+```
+
+Its only invariant is that `src/shell/types.ts` must stay import-free; a static assertion enforces it.
+
+### `bun-app-window/pack` — Bundling the Page Script
+
+Pages have to be bundled before the browser can load them: they import bare module names like
+`bun-app-window/ipc`, which a browser cannot resolve. Do it at **build time**, not at startup —
+after `bun build --compile`, `import.meta.dir` points inside the archive (`B:\~BUN\root`) and the
+`.ts` source is no longer there.
+
+```ts
+import { bundlePage, writePageBundle } from "bun-app-window/pack";
+
+// In memory — hand the string to createApp({ page })
+const { code, bytes } = await bundlePage({ entry: "src/ui/page.ts" });
+
+// Or write it out, e.g. from a `bundle:page` npm script
+await writePageBundle({ entry: "src/ui/page.ts", out: "src/ui/page.bundle.txt" });
+```
+
+`target: "browser"` and `format: "esm"` are fixed, not configurable — that is what a page script is.
+`bytes` is a UTF-8 byte count, not `string.length`; the two differ on any source containing non-ASCII
+text, and a reported size that only looks right is worse than no reported size.
+
+Failure throws with Bun's full diagnostics. Both shapes are handled: compile-time problems come back
+as `{ success: false, logs }`, while an unreachable entry point **throws an `AggregateError`** whose
+`message` is only `Bundle failed` and whose detail lives on `.errors`.
+
 ### `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:

package/README.zh-CN.md

@@ -2,6 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/bun-app-window?color=cb3837&logo=npm)](https://www.npmjs.com/package/bun-app-window)
 [![Bun](https://img.shields.io/badge/Bun-%3E%3D1.4.3-f472b6?logo=bun&logoColor=white)](https://bun.sh)
+[![TypeScript](https://img.shields.io/badge/TypeScript-%3E%3D7.0.2-3178C6?logo=typescript&logoColor=white)](#系统要求与设计边界)
 [![Platform](https://img.shields.io/badge/Platform-Windows%20x64-0078D6?logo=windows&logoColor=white)](#系统要求与设计边界)
 [![WebView2](https://img.shields.io/badge/WebView2-System%20Runtime-008080)](#系统要求与设计边界)
 [![License](https://img.shields.io/badge/License-MIT-2ea44f)](./LICENSE)
@@ -29,6 +30,7 @@ await openShell({ url: `http://127.0.0.1:${server.port}`, flags: FLAG_FRAMELESS
 | --- | --- |
 | 仅支持 Windows x64 | `package.json` 中的 `os` 与 `cpu` 字段已做硬性限制，拒绝在其他平台安装（包名保持平台中立仅为预留命名空间）。预编译动态库 `libshell.dll` 随包分发，无需在安装期编译 |
 | 仅支持 Bun 运行时 | 包内直接发布 TypeScript 源码，要求 Bun ≥ 1.4.3。Node.js 环境虽可完成包安装，但无法直接运行 |
+| 类型检查要求 TypeScript ≥ 7.0.2 | API 在 TypeScript 7.0.2 下设计与检查，`devDependencies` 中精确锁版；不为更旧的编译器做兼容。高于 7.0.2 的结果未作断言——`bun-types` 只在那一侧才打开 `typesVersions: ">= 7.1"` 门控，`with { type: "text" }` 的解析结果会随之改变 |
 | 类型检查需自备 `@types/bun` | 包内是 `.ts` 源文件，消费方的 `bun check` 会一并编译它们。需执行 `bun add -d @types/bun`，否则类型检查会在 `node_modules` 内报 `TS2868: Cannot find name 'Bun'` |
 | 基于 `bun:ffi` 构建 | `bun:ffi` 在 Bun 中仍标记为实验性特性（Experimental）。官方建议生产环境优先采用 Node-API，本项目选择 `bun:ffi` 是为了换取零第三方依赖的轻量架构 |
 
@@ -173,6 +175,27 @@ await app.wait();                  // 窗口关闭时 resolve
 await app.stop();                  // 释放事件泵与服务；幂等，已关闭时立即返回
 ```
 
+传 `page` 就能把打包好的页面脚本交给骨架，不必自己写那条路由。`createApp` 会应答
+`PAGE_JS_PATH`（`/page.js`）并带上正确的 `content-type`——而这里正是静默出错的地方：
+模块脚本以 `text/plain` 送出时会被拒绝执行且不报语法错，页面照常渲染、脚本一行不跑。
+
+```ts
+import { bundlePage } from "bun-app-window/pack";
+
+// 构建期，不是启动时——见下文 pack 一节
+const { code } = await bundlePage({ entry: "src/ui/page.ts" });
+
+const app = await createApp({ html, page: code, service });
+```
+
+`App` 上另有两个成员，各替我省一次调用和一条子路径导入：
+
+- `app.debug` —— 与 `debugOf(app.shell)` 返回同一个对象。同样不在稳定性承诺范围内。
+- `app.attachPlacement(file)` —— 把位置持久化接到骨架的**唯一**事件泵上。自己调
+  `attachPlacementStore` 而忘了传 `{ events: app.events }`，它会起第二个泵；而
+  `shell.pollEvents()` 是消费式的，两个泵各拿一半事件，窗口位置随机丢失，两端都不报错。
+  这个方法让那个错误无法表达。
+
 ```ts
 // page.ts —— index.html 的 bundle 里
 import { connect } from "bun-app-window/ipc";
@@ -420,6 +443,45 @@ d.hittest(x, y);
 `metrics()` 与 `dpi()` 返回的是**格式化文本**，不是对象。真要解析就写进一次性脚本里，别把解析器
 塞进生产代码——这个格式不属于任何契约。
 
+### `bun-app-window/types` — 常量面，浏览器安全
+
+一个零依赖模块，承载全部常量：`FLAG_*`、`BROWSER_UI_*`、`RESIZE_EDGE`、`RESIZE_INDEX`、
+`ZOOM_LADDER`、`ZOOM_MIN`、`ZOOM_MAX`、`STATE_*` 及相关类型。
+
+**页面侧请用这个子路径。** 主入口经 `./native` 引入 `bun:ffi`，浏览器打包器解析不了它——
+所以在页面代码里写 `import { BROWSER_UI_ALL } from "bun-app-window"` 会在打包期失败。
+开这个子路径就是为了让同一份常量被共享，而不是各自手抄：
+
+```ts
+import { BROWSER_UI_ALL, ZOOM_LADDER, RESIZE_EDGE, resizeIndex } from "bun-app-window/types";
+```
+
+它只有一个不变量：`src/shell/types.ts` 必须保持零 import。有静态断言守着。
+
+### `bun-app-window/pack` — 打包页面脚本
+
+页面脚本必须先打包浏览器才加载得了：它会 import `bun-app-window/ipc` 这类裸模块名，
+浏览器解析不了。打包要放在**构建期**，不是启动时——`bun build --compile` 之后
+`import.meta.dir` 指向归档内部（`B:\~BUN\root`），`.ts` 源码已经不在那里了。
+
+```ts
+import { bundlePage, writePageBundle } from "bun-app-window/pack";
+
+// 只在内存里：把字符串交给 createApp({ page })
+const { code, bytes } = await bundlePage({ entry: "src/ui/page.ts" });
+
+// 或者写盘，例如从一个 bundle:page 的 npm script 里调
+await writePageBundle({ entry: "src/ui/page.ts", out: "src/ui/page.bundle.txt" });
+```
+
+`target: "browser"` 与 `format: "esm"` 是固定的，不可配——页面脚本就是这两者。
+`bytes` 是 UTF-8 字节数，不是 `string.length`；源码里只要有非 ASCII 文本两者就不同，
+而一个「看起来对」的体积读数比没有读数更糟。
+
+失败时抛错并带上 Bun 的完整诊断。两种形态都覆盖了：编译期问题以
+`{ success: false, logs }` 返回，而入口本身不可达时**抛 `AggregateError`**，
+它的 `message` 只有一句 `Bundle failed`，细节在 `.errors` 上。
+
 ### `bun-app-window/native` — 预编译动态库本体
 
 该子路径解析到 `dist/libshell.dll` 本身，`import.meta.resolve()` 拿到的是可直接拷到 exe 旁边的真实路径：

package/README.zh-TW.md

@@ -2,6 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/bun-app-window?color=cb3837&logo=npm)](https://www.npmjs.com/package/bun-app-window)
 [![Bun](https://img.shields.io/badge/Bun-%3E%3D1.4.3-f472b6?logo=bun&logoColor=white)](https://bun.sh)
+[![TypeScript](https://img.shields.io/badge/TypeScript-%3E%3D7.0.2-3178C6?logo=typescript&logoColor=white)](#系統需求與設計邊界)
 [![Platform](https://img.shields.io/badge/Platform-Windows%20x64-0078D6?logo=windows&logoColor=white)](#系統需求與設計邊界)
 [![WebView2](https://img.shields.io/badge/WebView2-System%20Runtime-008080)](#系統需求與設計邊界)
 [![License](https://img.shields.io/badge/License-MIT-2ea44f)](./LICENSE)
@@ -29,6 +30,7 @@ await openShell({ url: `http://127.0.0.1:${server.port}`, flags: FLAG_FRAMELESS
 | --- | --- |
 | 僅支援 Windows x64 | `package.json` 中的 `os` 與 `cpu` 欄位已做強制限制，拒絕在其他平台安裝（套件名稱保持平台中立僅為預留命名空間）。預編譯動態連結程式庫 `libshell.dll` 隨套件發佈，無需在安裝期編譯 |
 | 僅支援 Bun 執行環境 | 套件內直接發佈 TypeScript 原始碼，要求 Bun ≥ 1.4.3。Node.js 環境雖可完成套件安裝，但無法直接執行 |
+| 型別檢查要求 TypeScript ≥ 7.0.2 | API 在 TypeScript 7.0.2 下設計與檢查，`devDependencies` 中精確鎖版；不為更舊的編譯器做相容。高於 7.0.2 的結果未作斷言——`bun-types` 只在那一側才開啟 `typesVersions: ">= 7.1"` 閘控，`with { type: "text" }` 的解析結果會隨之改變 |
 | 型別檢查需自備 `@types/bun` | 套件內是 `.ts` 原始碼，消費方的 `bun check` 會一併編譯它們。需執行 `bun add -d @types/bun`，否則型別檢查會在 `node_modules` 內回報 `TS2868: Cannot find name 'Bun'` |
 | 基於 `bun:ffi` 建構 | `bun:ffi` 在 Bun 中仍標記為實驗性功能（Experimental）。官方建議正式環境優先採用 Node-API，本專案選擇 `bun:ffi` 是為了換取零第三方相依性的輕量架構 |
 
@@ -172,6 +174,27 @@ await app.wait();                  // 視窗關閉時 resolve
 await app.stop();                  // 釋放事件泵與服務；冪等，已關閉時立即回傳
 ```
 
+傳 `page` 就能把打包好的頁面指令碼交給骨架，不必自己寫那條路由。`createApp` 會應答
+`PAGE_JS_PATH`（`/page.js`）並帶上正確的 `content-type`——而這裡正是靜默出錯的地方：
+模組指令碼以 `text/plain` 送出時會被拒絕執行且不報語法錯，頁面照常渲染、指令碼一行不跑。
+
+```ts
+import { bundlePage } from "bun-app-window/pack";
+
+// 建置期，不是啟動時——見下文 pack 一節
+const { code } = await bundlePage({ entry: "src/ui/page.ts" });
+
+const app = await createApp({ html, page: code, service });
+```
+
+`App` 上另有兩個成員，各替我省一次呼叫和一條子路徑匯入：
+
+- `app.debug` —— 與 `debugOf(app.shell)` 回傳同一個物件。同樣不在穩定性承諾範圍內。
+- `app.attachPlacement(file)` —— 把位置持久化接到骨架的**唯一**事件泵上。自己呼叫
+  `attachPlacementStore` 而忘了傳 `{ events: app.events }`，它會起第二個泵；而
+  `shell.pollEvents()` 是消費式的，兩個泵各拿一半事件，視窗位置隨機遺失，兩端都不報錯。
+  這個方法讓那個錯誤無法表達。
+
 ```ts
 // page.ts —— index.html 的 bundle 內
 import { connect } from "bun-app-window/ipc";
@@ -420,6 +443,45 @@ d.hittest(x, y);
 `metrics()` 與 `dpi()` 回傳的是**格式化文字**，不是物件。真要解析就寫進一次性指令碼裡，別把
 解析器塞進正式程式碼——這個格式不屬於任何契約。
 
+### `bun-app-window/types` — 常數面，瀏覽器安全
+
+一個零依賴模組，承載全部常數：`FLAG_*`、`BROWSER_UI_*`、`RESIZE_EDGE`、`RESIZE_INDEX`、
+`ZOOM_LADDER`、`ZOOM_MIN`、`ZOOM_MAX`、`STATE_*` 及相關型別。
+
+**頁面側請用這個子路徑。** 主入口經 `./native` 引入 `bun:ffi`，瀏覽器打包器解析不了它——
+所以在頁面程式碼裡寫 `import { BROWSER_UI_ALL } from "bun-app-window"` 會在打包期失敗。
+開這個子路徑就是為了讓同一份常數被共用，而不是各自手抄：
+
+```ts
+import { BROWSER_UI_ALL, ZOOM_LADDER, RESIZE_EDGE, resizeIndex } from "bun-app-window/types";
+```
+
+它只有一個不變量：`src/shell/types.ts` 必須保持零 import。有靜態斷言守著。
+
+### `bun-app-window/pack` — 打包頁面指令碼
+
+頁面指令碼必須先打包瀏覽器才載入得了：它會 import `bun-app-window/ipc` 這類裸模組名，
+瀏覽器解析不了。打包要放在**建置期**，不是啟動時——`bun build --compile` 之後
+`import.meta.dir` 指向封存內部（`B:\~BUN\root`），`.ts` 原始碼已經不在那裡了。
+
+```ts
+import { bundlePage, writePageBundle } from "bun-app-window/pack";
+
+// 只在記憶體裡：把字串交給 createApp({ page })
+const { code, bytes } = await bundlePage({ entry: "src/ui/page.ts" });
+
+// 或者寫入磁碟，例如從一個 bundle:page 的 npm script 裡呼叫
+await writePageBundle({ entry: "src/ui/page.ts", out: "src/ui/page.bundle.txt" });
+```
+
+`target: "browser"` 與 `format: "esm"` 是固定的，不可配置——頁面指令碼就是這兩者。
+`bytes` 是 UTF-8 位元組數，不是 `string.length`；原始碼裡只要有非 ASCII 文字兩者就不同，
+而一個「看起來對」的體積讀數比沒有讀數更糟。
+
+失敗時拋錯並帶上 Bun 的完整診斷。兩種形態都覆蓋了：編譯期問題以
+`{ success: false, logs }` 回傳，而入口本身不可達時**拋 `AggregateError`**，
+它的 `message` 只有一句 `Bundle failed`，細節在 `.errors` 上。
+
 ### `bun-app-window/native` — 預編譯動態連結程式庫本體
 
 該子路徑解析到 `dist/libshell.dll` 本身，`import.meta.resolve()` 拿到的是可直接複製到 exe 旁邊的真實路徑：

package/package.json

@@ -1,7 +1,7 @@
 {
     "$schema": "https://json.schemastore.org/package.json",
     "name": "bun-app-window",
-    "version": "0.5.1",
+    "version": "0.6.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,12 +29,14 @@
     ],
     "exports": {
         ".": "./src/shell/index.ts",
+        "./types": "./src/shell/types.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",
         "./ipc": "./src/shell/ipc.ts",
+        "./pack": "./src/shell/pack.ts",
         "./titlebar": "./src/ui/titlebar.ts",
         "./native": {
             "types": "./src/shell/native-asset.d.ts",

package/src/shell/app.ts

@@ -32,6 +32,8 @@ 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";
+import { debugOf, type ShellDebug } from "./debug";
+import { attachPlacementStore, type PlacementStore } from "./state";
 
 /** 骨架起出来的东西。`shell` 是完整的内核对象，骨架只是帮它把周边接好 */
 export type App = {
@@ -55,6 +57,29 @@ export type App = {
     readonly token: string;
     /** 给了 `service` 才有；否则为 null */
     readonly ipc: IpcServer | null;
+    /**
+     * 排障接口（`hittest` / `metrics` / `dpi` / `selfBase` / `selfPath`）。
+     *
+     * 等价于 `debugOf(app.shell)`，只是省掉一次调用和一条子路径依赖。
+     * 排障面的稳定性承诺与 `bun-app-window/debug` 相同：**随时可能变化，生产代码
+     * 不应依赖**。骨架把它挂上来不改变这个定位，只是让它更好拿。
+     */
+    readonly debug: ShellDebug;
+    /**
+     * 把窗口位置持久化挂到这个 App 上。
+     *
+     * 与直接调 `attachPlacementStore(shell, file, { events })` 的差别只有一件事：
+     * **事件泵由骨架提供**，不可能忘。那条 `{ events }` 参数漏掉的后果是
+     * `attachPlacementStore` 自建第二个泵，而 `shell.pollEvents()` 是消费式的——
+     * 两个泵各自拿到一部分事件，窗口位置会**随机漏掉**一些变化，且两端都不报错。
+     * 这是本库里最容易静默出错的接线点，所以收进骨架。
+     *
+     * ```ts
+     * const store = app.attachPlacement(join(dataDir, "window.json"));
+     * // 关闭前：await store.flush(); store.dispose();
+     * ```
+     */
+    attachPlacement(file: string, opts?: { debounceMs?: number }): PlacementStore;
     /**
      * 停止窗口与本地服务。
      *
@@ -108,6 +133,24 @@ export type AppOptions = {
     appName?: string;
     nativeLibPath?: string;
     embedded?: () => Promise<Uint8Array | null>;
+    /**
+     * 页面脚本（已打包的单文件 ESM 源码）。给了就自动在 `{@link PAGE_JS_PATH}`
+     * 提供它，`content-type` 固定为 `text/javascript; charset=utf-8`。
+     *
+     * 传的是**字符串**，不是路径：构建期由 `bun-app-window/pack` 打好后内联进来，
+     * 运行期不碰磁盘。写成路径会在 `bun build --compile` 之后失效，
+     * 因为那时 `import.meta.dir` 指向 `B:\~BUN\root`。
+     *
+     * ```ts
+     * import pageCode from "./ui/page.bundle.txt" with { type: "text" };
+     * const app = await createApp({ html, page: pageCode as unknown as string });
+     * ```
+     *
+     * 不给时该路径交回 `routes` 与默认处理（即 404），行为与引入本项之前一致。
+     *
+     * 调用方的 `routes` 仍然优于此项：返回非 `undefined` 就能覆盖它。
+     */
+    page?: string;
     /**
      * IPC 服务方法表。给了就自动挂 `/ws`（含 token 校验）。
      *
@@ -165,6 +208,26 @@ export function buildAppUrl(port: number, token: string): string {
     return `http://127.0.0.1:${port}/?t=${token}`;
 }
 
+/**
+ * `AppOptions.page` 的服务路径。
+ *
+ * 固定为 `/page.js` 而不是可配置：页面 HTML 里写的是
+ * `<script type="module" src="/page.js">`，两侧必须一致。留一个可配置项意味着
+ * 多一处「配置与 HTML 对不上」的失败方式，而它换不来任何能力——路径本身没有人关心。
+ *
+ * 导出是为了让调用方的 HTML 与 `routes` 都能引用同一个常量，而不是各写一份字符串。
+ */
+export const PAGE_JS_PATH = "/page.js";
+
+/**
+ * 页面脚本响应的 `content-type`。
+ *
+ * 必须是 `text/javascript`。写成 `application/javascript` 浏览器也接受，但写成
+ * `text/plain` 或漏掉时，`<script type="module">` 会**拒绝执行**且不报语法错——
+ * 表现是页面白屏、控制台只有一条 MIME 类型警告，很容易被当成「脚本逻辑有问题」。
+ */
+const PAGE_JS_CONTENT_TYPE = "text/javascript; charset=utf-8";
+
 /**
  * `/ws` 请求的处置结论。
  *
@@ -254,6 +317,14 @@ export async function createApp(opts: AppOptions): Promise<App> {
             return custom;
         }
 
+        // 页面脚本。给了 `page` 才有这一条；不给时该路径落到底部的 404，
+        // 与引入本项之前的行为一致。
+        if (opts.page !== undefined && url.pathname === PAGE_JS_PATH) {
+            return new Response(opts.page, {
+                headers: { "content-type": PAGE_JS_CONTENT_TYPE },
+            });
+        }
+
         if (url.pathname === "/") {
             return new Response(opts.html, {
                 headers: { "content-type": "text/html; charset=utf-8" },
@@ -317,6 +388,15 @@ export async function createApp(opts: AppOptions): Promise<App> {
         url,
         token,
         ipc,
+        debug: debugOf(shell),
+        attachPlacement(file: string, opts2?: { debounceMs?: number }): PlacementStore {
+            // 事件泵用骨架这一个：`shell.pollEvents()` 是消费式的，再起一个就分票。
+            // 这里不给调用方传 `events` 的机会，正是这个方法存在的全部理由。
+            return attachPlacementStore(shell, file, {
+                events,
+                ...(opts2?.debounceMs === undefined ? {} : { debounceMs: opts2.debounceMs }),
+            });
+        },
         async stop(): Promise<void> {
             if (stopped) {
                 return;

package/src/shell/index.ts

@@ -29,7 +29,9 @@ import {
   STATE_FOCUSED,
   STATE_MAXIMIZED,
   STATE_MINIMIZED,
+  resizeIndex,
   type NativeLibInfo,
+  type ResizeEdge,
   type ShellOptions,
   type StartResult,
   type WindowState,
@@ -48,6 +50,35 @@ export type {
   WindowEvent,
 } from "./events";
 
+/**
+ * 原生调用的回执。
+ *
+ * 刻意不是裸 `number`：`rc` 只回答「有没有投递出去」，`err` 才回答「为什么没投递」。
+ * 把两者分开，调用方才能区分两种完全不同的故障：
+ *
+ * - `rc === 0` 但状态没变 → 时序 / 前置条件问题（原生侧是异步投递到 UI 线程的）
+ * - `rc < 0` 且 `err` 非空 → 调用方用错 API（窗口已销毁、参数越界）
+ *
+ * **`rc === 0` 不等于效果发生了。** 要判效果必须读回状态
+ * （`state()` / `getZoom()` / `getBounds()`）。
+ */
+export type NativeAck = {
+  /** `0` = 已投递给 UI 线程；负数 = 当场被拒（窗口已销毁、参数越界等） */
+  rc: number;
+  /** 失败原因；成功时恒为空串 */
+  err: string;
+};
+
+/**
+ * 把裸 `rc` 包成 `NativeAck`。
+ *
+ * **只在失败时读 `lastError()`**：壳层的错误缓冲区不会被成功的调用清空，
+ * 成功时读它只会拿到上一次的残留——显示出来就是一个假故障。
+ */
+export function ackOf(shell: Shell, rc: number): NativeAck {
+  return { rc, err: rc === 0 ? "" : shell.lastError() };
+}
+
 export type Shell = {
   /** 创建窗口并加载 URL。返回码 0 表示成功；失败原因见 lastError() */
   start(): StartResult;
@@ -59,8 +90,20 @@ export type Shell = {
   close(): number;
   /** 由页面 pointerdown 触发原生拖拽；保留贴边分屏 */
   drag(): number;
-  /** 由页面 pointermove 触发边框缩放；edge 取 RESIZE_EDGE 的值 */
-  beginResize(edge: number): number;
+  /**
+   * 由页面触发的边框缩放（进入 Windows 的模态缩放循环，鼠标被系统接管）。
+   *
+   * **入参是 `RESIZE_EDGE` 的 HT* 值（10–17）**，不是内部数组下标。
+   *
+   * 0.5.x 的实现把入参直传给原生 `shell_begin_resize()`，而原生收的是
+   * `codes[8]` 的**数组下标 0–7**——两者的映射是 `HT*` 常量在 Win32 里的定义顺序，
+   * 既不是恒等也不是「减 10」（`HTTOPLEFT`=13 在下标 4、`HTBOTTOM`=15 在下标 3）。
+   * 于是照着注释传 `RESIZE_EDGE.LEFT`（=10）会被 `edge > 7` 当场拒掉，
+   * `rc=-1`，外部表现是「点了没反应」，而门禁全绿。
+   *
+   * 0.6.0 起由本方法在 TS 层查表转换，原生 DLL 不需要重编。非法值仍然返回 -1。
+   */
+  beginResize(edge: ResizeEdge): number;
   /** 最小尺寸，逻辑像素 */
   setMinSize(width: number, height: number): void;
   /**
@@ -241,7 +284,7 @@ export async function createShell(opts: ShellOptions): Promise<Shell> {
     toggleMaximize: () => symbols.shell_toggle_maximize(),
     close: () => symbols.shell_close(),
     drag: () => symbols.shell_drag(),
-    beginResize: (edge) => symbols.shell_begin_resize(edge),
+    beginResize: (edge) => symbols.shell_begin_resize(resizeIndex(edge)),
     setMinSize: (w, h) => symbols.shell_set_min_size(w, h),
     show: () => symbols.shell_show(),
     setAppId: (appId) => symbols.shell_set_app_id(cstr(appId)),

package/src/shell/pack.ts

@@ -0,0 +1,164 @@
+/**
+ * pack.ts — 把页面脚本打成浏览器可加载的单文件 ESM
+ *
+ * ## 这一步为什么省不掉
+ *
+ * 页面代码要 `import { connect } from "bun-app-window/ipc"`，裸模块名浏览器解析不了，
+ * 必须先打包。而打包只能发生在**构建期**：`bun build --compile` 之后
+ * `import.meta.dir` 指向内嵌文件系统（`B:\~BUN\root`），那里没有 `.ts` 源文件，
+ * 运行期打包会以 `ENOENT: failed to open root directory` 失败。
+ *
+ * 所以流程固定为两段：
+ *
+ * ```text
+ * 构建期   bundlePage()  →  ESM 源码字符串  →  交给 createApp({ page })
+ * 运行期   createApp 从内存里吐出 /page.js，不碰磁盘
+ * ```
+ *
+ * ## 为什么放在壳层而不是各应用自己写
+ *
+ * 三件事每次都一样，且每一件都容易写错：
+ *
+ * 1. `target: "browser"` 与 `format: "esm"` 是「页面脚本」这个场景的硬要求，不是可选项；
+ * 2. 失败时必须带上 Bun 的完整日志——打包失败在运行期只表现为页面白屏，没有日志就
+ *    等于没有任何线索；
+ * 3. 报大小要报**字节数**。`string.length` 是 UTF-16 码元数，源码里有中文时与字节数
+ *    相差可观，而单位通常写成 `B`。
+ *
+ * 第 3 条是本仓在消费者工程上实测到的：某处报 `35,085 B`，磁盘实际 `37,319 B`。
+ *
+ * ## 与 `bun-app-window/types` 的区别
+ *
+ * `./types` 是零 import 的纯常量面，浏览器可以打包它。本模块用 `Bun.build`，
+ * 属于**构建期**工具，不得出现在页面侧代码里。
+ */
+
+import { resolve } from "node:path";
+
+/** 打包结果 */
+export type PageBundle = {
+    /** 单文件 ESM 源码，可直接交给 `createApp({ page })` */
+    code: string;
+    /**
+     * UTF-8 字节数。
+     *
+     * 不是 `code.length`：那是 UTF-16 码元数，源码含中文时两者不等，
+     * 而调用方几乎总是拿这个数当「产物多大」来报。
+     */
+    bytes: number;
+};
+
+export type BundlePageOptions = {
+    /**
+     * 页面脚本入口的绝对路径。
+     *
+     * 相对路径按 `process.cwd()` 解析，但**建议传绝对路径**：打包的模块解析基准是
+     * 入口文件所在目录，而 `cwd` 只影响相对路径的解析。两者混用会让「为什么在这里
+     * 能解析、在那里不能」变成一道推理题。
+     */
+    entry: string;
+    /** 是否压缩。默认 `false`（与不传时的直观预期一致，也便于排查产物） */
+    minify?: boolean;
+};
+
+/**
+ * 从 `Bun.build` 的失败里取出可读线索。
+ *
+ * `Bun.build` 有两种失败形态，**日志位置不同**（2026-10-21 实测）：
+ *
+ * | 形态 | 返回值 | 日志在哪 |
+ * | --- | --- | --- |
+ * | 编译期诊断（语法错、无法解析的导入） | `{ success: false, logs: [...] }` | `result.logs` |
+ * | 入口本身不可达 | **抛 `AggregateError`** | `err.errors`（**没有 `.logs`**） |
+ *
+ * 第二种的 `message` 只有一句 `Bundle failed`，完全无法定位——所以必须读 `.errors`。
+ * 两条路径都要覆盖，否则最常见的一种「入口写错」会变成一句没有信息量的报错。
+ */
+function failureDetail(err: unknown): string {
+    if (err instanceof Error) {
+        // AggregateError 的成员在 .errors 上；普通 Error 没有这个属性
+        const members = (err as { errors?: unknown }).errors;
+        if (Array.isArray(members) && members.length > 0) {
+            return members.map((item) => String(item)).join("\n");
+        }
+        return err.message;
+    }
+    return String(err);
+}
+
+/**
+ * 打包页面脚本，返回 ESM 源码。
+ *
+ * 失败时抛错并附上 Bun 的完整诊断。抛而不是返回 `null`：调用方拿到 `null` 之后
+ * 唯一合理的动作也是终止构建，而返回值多一个空状态就多一处要处理的分支。
+ */
+export async function bundlePage(opts: BundlePageOptions): Promise<PageBundle> {
+    const entry = resolve(opts.entry);
+
+    let result: Awaited<ReturnType<typeof Bun.build>>;
+    try {
+        result = await Bun.build({
+            entrypoints: [entry],
+            target: "browser",
+            format: "esm",
+            ...(opts.minify === undefined ? {} : { minify: opts.minify }),
+        });
+    } catch (err) {
+        // 入口不可达走这条：`Bun.build` 抛 AggregateError 而不是返回 success:false
+        throw new Error(
+            `页面脚本打包失败（entry=${entry}）\n${failureDetail(err)}`,
+        );
+    }
+
+    const first = result.outputs[0];
+    if (!result.success || first === undefined) {
+        const detail = result.logs.map((item) => String(item)).join("\n");
+        throw new Error(
+            `页面脚本打包失败（entry=${entry}）\n${detail || "（Bun 未提供日志）"}`,
+        );
+    }
+
+    const code = await first.text();
+    return { code, bytes: Buffer.byteLength(code, "utf8") };
+}
+
+/**
+ * 打包并写盘，供「产物不入库、由 npm scripts 前置生成」的工程使用。
+ *
+ * ```json
+ * "scripts": {
+ *     "bundle:page": "bun run scripts/bundle-page.ts",
+ *     "build": "bun run bundle:page && bun build --compile …"
+ * }
+ * ```
+ *
+ * ```ts
+ * // scripts/bundle-page.ts
+ * import { writePageBundle } from "bun-app-window/pack";
+ * await writePageBundle({ entry: "src/ui/page.ts", out: "src/ui/page.bundle.txt" });
+ * ```
+ *
+ * 产物是否需要入库由调用方决定。不入库时 `bun check` 仍然通过——类型检查按
+ * `declare module "*.txt"` 解析模块，不访问文件系统；但 `bun build --compile`
+ * 需要文件真实存在，所以前置不可省。
+ */
+export async function writePageBundle(
+    opts: BundlePageOptions & { out: string },
+): Promise<PageBundle & { out: string }> {
+    const out = resolve(opts.out);
+    const bundle = await bundlePage(opts);
+    await Bun.write(out, bundle.code);
+
+    // 复核一次实际字节数：`Bun.write` 的编码行为不由我们控制，
+    // 报出去的数字必须是磁盘上那个，而不是我们以为的那个。
+    const written = Bun.file(out).size;
+    if (written !== bundle.bytes) {
+        throw new Error(
+            `页面产物写入字节数与预期不符：` +
+                `写入 ${out}，预期 ${bundle.bytes} B，实际 ${written} B。` +
+                `若产物被写成了带 BOM 或 CRLF 的形态，先查写入路径。`,
+        );
+    }
+
+    return { ...bundle, out };
+}

package/src/shell/resolve.ts

@@ -27,9 +27,19 @@ import { homedir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 
 import type { NativeLibInfo } from "./types";
+import pkg from "../../package.json";
 
 const DLL_PATTERN = /^libshell.*\.dll$/i;
 
+/**
+ * 本包版本号。取自包内 `package.json`——它是唯一事实源，`NativeLibInfo.version`
+ * 只是把它带到运行期，避免消费者为了显示版本再 `import "…/package.json"`。
+ *
+ * 与 `native/build-pack.ts` 的 `--windows-version` 是两处会写进产物的版本号，
+ * 由 `tests/version.test.ts` 守着同源（那一条和这里无关，别混）。
+ */
+const PKG_VERSION: string = pkg.version;
+
 /** 包根目录：src/shell → 上两级。打包态下该值不可用于文件系统访问。 */
 const PKG_ROOT = resolve(import.meta.dir, "..", "..");
 
@@ -60,6 +70,7 @@ function fromPath(path: string, source: NativeLibInfo["source"]): NativeLibInfo
   return {
     path,
     source,
+    version: PKG_VERSION,
     sha256: "",
     bytes: statSync(path).size,
     reused: false,
@@ -168,6 +179,7 @@ export async function resolveNativeLib(opts: ResolveOptions = {}): Promise<Nativ
         return {
           path,
           source: "embedded",
+          version: PKG_VERSION,
           sha256,
           bytes: bytes.length,
           reused,

package/src/shell/types.ts

@@ -3,6 +3,18 @@
  *
  * 这里的类型是**稳定面**：改动需要按语义化版本对待。
  * 调试自省类能力单独放在 Shell["debug"] 下，不视为稳定契约。
+ *
+ * ## 这个文件必须保持「零 import」
+ *
+ * 它是 `bun-app-window/types` 子路径的全部内容，而开这个子路径的目的是让
+ * **页面侧代码也能 import 这些常量**：主入口 `./index` 从 `./native` 导入
+ * `bun:ffi`，浏览器 bundle 解析不了，所以页面过去只能把位值手抄一遍
+ * （`BROWSER_UI_*` 抄 5 条、缩放阶梯抄 14 档、边框索引抄 8 条），抄漏抄错
+ * 都不会被任何门禁抓到。
+ *
+ * 因此本文件只允许出现 `export const` / `export type` / `export function`
+ * 形式的纯声明，**不得出现任何 `import`**——一旦有了，子路径就不再是浏览器安全的。
+ * `tests/types-purity.test.ts` 用一条静态断言守住这条。
  */
 
 /** 无边框：原生层不画标题栏与边框，由页面自绘 */
@@ -78,7 +90,24 @@ export const BROWSER_UI_AUTOFILL = 16;
 export const BROWSER_UI_ALL =
     BROWSER_UI_MENU | BROWSER_UI_KEYS | BROWSER_UI_STATUSBAR | BROWSER_UI_SWIPE | BROWSER_UI_AUTOFILL;
 
-/** 缩放边框的 8 个命中边，取值与 Win32 HT* 常量一致 */
+/**
+ * 缩放边框的 8 个命中边，取值与 Win32 HT* 常量一致。
+ *
+ * 这是 `Shell.beginResize()` 的**入参取值**。传 `RESIZE_EDGE.LEFT` 即可。
+ *
+ * 历史（0.6.0 修正）：原生 `shell_begin_resize()` 收的是内部数组下标 0–7，
+ * 而本位定义是 HT* 常量 10–17，两者差一个**非线性**映射——
+ *
+ * ```c
+ * static const WPARAM codes[8] = {HTLEFT, HTRIGHT, HTTOP, HTBOTTOM,
+ *                                 HTTOPLEFT, HTTOPRIGHT, HTBOTTOMLEFT, HTBOTTOMRIGHT};
+ * ```
+ *
+ * 注意 `HTTOPLEFT`(13) 在下标 4、`HTBOTTOM`(15) 在下标 3：既不是恒等也不是减 10。
+ * 0.5.x 里 `beginResize` 的注释写「取 RESIZE_EDGE 的值」而实现直传下标，
+ * 照注释写必然被 `edge > 7` 拒掉（`rc=-1`，表现是「点了没反应」）。0.6.0 起由
+ * `Shell.beginResize()` 在 TS 层查表转换，本常量成为真正的入参契约。
+ */
 export const RESIZE_EDGE = {
   LEFT: 10,
   RIGHT: 11,
@@ -92,6 +121,61 @@ export const RESIZE_EDGE = {
 
 export type ResizeEdge = (typeof RESIZE_EDGE)[keyof typeof RESIZE_EDGE];
 
+/**
+ * `RESIZE_EDGE` 的 HT* 值 → 原生 `codes[]` 的**数组下标**。
+ *
+ * 顺序必须与 `native/shell.cc` 里那张表逐项一致：
+ *
+ * ```c
+ * static const WPARAM codes[8] = {HTLEFT, HTRIGHT, HTTOP, HTBOTTOM,
+ *                                 HTTOPLEFT, HTTOPRIGHT, HTBOTTOMLEFT, HTBOTTOMRIGHT};
+ * ```
+ *
+ * **它既不是恒等也不是 `value - 10`**：`HTTOPLEFT`=13 落在下标 4、`HTBOTTOM`=15
+ * 落在下标 3。`tests/types.test.ts` 有一条断言逐项钉住这张表。
+ *
+ * 消费者一般不需要它——`Shell.beginResize()` 已经替你查表了。放在公共面是因为
+ * 它属于「协议的另一半」，逃生机 `shell.symbols.shell_begin_resize()` 要直连原生
+ * 时需要它，而那种时候手写映射必然抄错。
+ */
+export const RESIZE_INDEX: Readonly<Record<number, number>> = {
+  [RESIZE_EDGE.LEFT]: 0,
+  [RESIZE_EDGE.RIGHT]: 1,
+  [RESIZE_EDGE.TOP]: 2,
+  [RESIZE_EDGE.BOTTOM]: 3,
+  [RESIZE_EDGE.TOPLEFT]: 4,
+  [RESIZE_EDGE.TOPRIGHT]: 5,
+  [RESIZE_EDGE.BOTTOMLEFT]: 6,
+  [RESIZE_EDGE.BOTTOMRIGHT]: 7,
+};
+
+/**
+ * HT* 值 → 下标；不认识的值返回 -1。
+ *
+ * 返回 -1 而不是抛错：原生 `shell_begin_resize()` 用 `edge < 0` 把它当场拒掉并回
+ * `rc=-1`，与「窗口已销毁」是同一个外部表现，调用方按 `rc` 处理即可。
+ */
+export function resizeIndex(edge: number): number {
+  return RESIZE_INDEX[edge] ?? -1;
+}
+
+/**
+ * 缩放阶梯，与原生 `native/shell.cc` 的 `kZoomLadder` 逐档一致。
+ *
+ * 原生侧 `apply_zoom` 只把入参夹到首尾两档（0.25 ~ 3.0），不吸附中间档——
+ * 传任意值都能生效。这份表是给「按档位走」的界面用的：`−` / `+` 要按相邻档
+ * 跳，而档位表属于两边都要知道的常量。
+ *
+ * 过去消费者只能自己抄一份（抄了 14 个数，没有任何门禁能发现它与 C++ 漂移）。
+ */
+export const ZOOM_LADDER = [
+  0.25, 0.33, 0.5, 0.67, 0.8, 0.9, 1.0, 1.1, 1.25, 1.5, 1.75, 2.0, 2.5, 3.0,
+] as const;
+
+/** 缩放倍率的上下限（`ZOOM_LADDER` 的首尾两项） */
+export const ZOOM_MIN = ZOOM_LADDER[0];
+export const ZOOM_MAX = ZOOM_LADDER[ZOOM_LADDER.length - 1];
+
 /** window state 位掩码（与原生 shell_get_state 一致） */
 export const STATE_MAXIMIZED = 1;
 export const STATE_MINIMIZED = 2;
@@ -117,6 +201,15 @@ export type NativeLibInfo = {
    * fallback-tmp — 受限环境下退回 Bun 默认释放
    */
   source: "explicit" | "dev" | "package" | "embedded" | "fallback-tmp";
+  /**
+   * `bun-app-window` 自身的版本号（取自包内 `package.json`，不是 DLL 的 PE 版本）。
+   *
+   * 加它的理由：消费者要在界面上显示「连上的确实是这个版本」时，过去只能
+   * `import libPkg from "bun-app-window/package.json"` 再拼字符串——那是一条
+   * 额外的子路径依赖，且 `package.json` 在 `files` 白名单里所以要跟着发布面走。
+   * 现在顺手带出来，页面侧直接读 `shell.libInfo.version`。
+   */
+  version: string;
   sha256: string;
   bytes: number;
   reused: boolean;