bun-app-window 0.5.1 → 0.6.1

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/state.ts

@@ -50,6 +50,30 @@ const DEFAULTS = {
     pumpMs: 16,
 } as const;
 
+/**
+ * Win32 的「窗口已最小化」哨兵坐标。
+ *
+ * 窗口最小化时 `GetWindowRect` 返回的不是真实位置，而是一对哨兵值——实测
+ * `-32000,-32000` 加一个图标尺寸（典型 `314x50`）。它们**看起来完全合法**：
+ * 坐标是整数，尺寸也大于 0，所以只判「非有限 / 尺寸 ≤ 0」的形状校验拦不住。
+ *
+ * 成因在原生 `format_bounds`：它只在 `IsZoomed` 为真时走
+ * `WINDOWPLACEMENT.rcNormalPosition`，最小化时 `IsZoomed` 返回 false，于是落进
+ * `GetWindowRect` 分支——**`IsIconic` 从未被判断**。于是这对哨兵值会一路写成
+ * `{"x":-32000,"y":-32000,"width":314,"height":50}`，下次启动恢复成一个畸形小窗
+ * （实测：666×471，页面被挤到换行并出现滚动条）。
+ *
+ * 阈值取 -30000 而不是精确 -32000：不同 DPI / 主题下这对值会带几个像素偏移。
+ * 真实坐标到不了这个量级——8K 屏横向也只有 7680，多屏横排也远不到 30000，
+ * 所以用阈值不会误伤合法的负坐标（主屏在右、副屏在左时 x 确实是负数）。
+ */
+const MINIMIZED_SENTINEL = -30000;
+
+/** 是不是 Win32 的最小化哨兵坐标。任一维命中即判否——两维是同时写的 */
+function isMinimizedSentinel(x: number, y: number): boolean {
+    return x <= MINIMIZED_SENTINEL || y <= MINIMIZED_SENTINEL;
+}
+
 /** 把原生返回的一行文本解析成 WindowPlacement；格式不对返回 null。 */
 export function parseBounds(text: string): WindowPlacement | null {
     const parts = text.trim().split(",");
@@ -72,6 +96,10 @@ export function parseBounds(text: string): WindowPlacement | null {
     if (width <= 0 || height <= 0 || dpi <= 0) {
         return null;
     }
+    // 最小化时原生给的是哨兵坐标，不是真实位置——宁可返回 null 让调用方保留上一次的值
+    if (isMinimizedSentinel(x, y)) {
+        return null;
+    }
     return { x, y, width, height, maximized: maximized !== 0, dpi };
 }
 
@@ -108,6 +136,10 @@ export function parsePlacement(raw: unknown): WindowPlacement | null {
     if (Math.abs(x) > 200000 || Math.abs(y) > 200000) {
         return null;
     }
+    // 已写进磁盘的哨兵坐标同样不可用：旧版本写过这种文件，读的时候要判否而不是恢复它
+    if (isMinimizedSentinel(x, y)) {
+        return null;
+    }
     return { x, y, width, height, maximized: o.maximized === true, dpi };
 }
 

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` 用一条静态断言守住这条。
  */
 
 /** 无边框：原生层不画标题栏与边框，由页面自绘 */
@@ -60,6 +72,68 @@ export const FLAG_START_MAXIMIZED = 64;
  *   `javascript:`、`ms-*:` 以及自定义 scheme 一律静默取消，与本位无关。
  */
 export const FLAG_ALLOW_EXTERNAL_NAV = 128;
+/**
+ * 顶部让出一条给自绘标题栏：把 WebView2 的容器子窗口整体下移 caption 高度（32 逻辑像素）。
+ *
+ * ## 为什么需要它（命中测试的硬约束，不是布局偏好）
+ *
+ * WebView2 的容器子窗口（widget）铺满整个客户区，它内部还有三层 Chrome 窗口，
+ * 而**真实鼠标的 `WM_NCHITTEST` 走光标下最深那层**：
+ *
+ * ```text
+ * webview_widget → Chrome_WidgetWin_0 → Chrome_WidgetWin_1
+ * → Chrome_RenderWidgetHostHWND → Intermediate D3D Window
+ * ```
+ *
+ * 后三层在**别的进程**里（实测 pid 各不相同），`SetWindowLongPtr` 够不着，
+ * 所以「把 `HTTRANSPARENT` 一路传上去」这条子类化路线走不通。它们返回 `HTCLIENT`，
+ * 顶层窗口那套 `HTMAXBUTTON` 逻辑永远没机会被问到——**Snap Layouts 因此不弹**。
+ *
+ * 让 widget 别盖住标题栏，光标就落在顶层窗口自己身上，命中测试正常走到
+ * `hit_test_client` → `caption_button_at` → `HTMAXBUTTON`。
+ *
+ * ## 什么时候该给
+ *
+ * 只在**自绘标题栏**、而且标题栏真的在客户区顶部时。无边框不等于要自绘标题栏：
+ * 有的应用整窗都是内容区，无条件让位会在顶部留一条点不到的死区。
+ *
+ * ## 与 `FLAG_FRAMELESS` 的关系
+ *
+ * 本位只在 `FLAG_FRAMELESS` 同时给出时生效——带边框模式的标题栏由系统画，
+ * widget 本来就在客户区内，不存在遮挡。
+ */
+export const FLAG_TITLEBAR_RESERVE = 256;
+
+/**
+ * 在客户区右上角盖一层**原生绘制**的 caption 按钮（关闭 / 最大化 / 最小化）。
+ *
+ * ## 它解决的是「页面拿不到 Snap Layouts」
+ *
+ * `WM_NCHITTEST` 走光标下最深那层，而 WebView2 的渲染子窗口在**别的进程**里、
+ * 返回 `HTCLIENT`，光标的查询根本到不了顶层窗口（`pitfalls` 2.14 的实测链）。
+ * 盖一个壳层自己的 layered 子窗口在按钮位置上，命中就落在壳层手里，
+ * `HTMAXBUTTON` 才生效，Snap 面板才会弹。
+ *
+ * ## 它与 `FLAG_TITLEBAR_RESERVE` 是**替代关系**，不要同时给
+ *
+ * `TITLEBAR_RESERVE` 的做法是把 WebView2 的容器子窗口整体下移 caption 高度，
+ * 让光标落到顶层窗口。那条路实测也能让 Snap 弹，但它把页面内容整体下移 32 逻辑
+ * 像素，而 caption 命中区固定在客户区 `y ∈ [0, 32)` —— 页面自己画的标题栏会与
+ * 命中区**错位 32px**，想对齐只能给页面负偏移，那已经出了 widget 客户区、
+ * 被子窗口裁掉。所以「HTML 画标题栏 + 让位」在几何上不成立。
+ *
+ * 本位不动布局：子窗口只是**盖在**按钮位置上，页面该怎么排还怎么排，
+ * 缩放边框也不受影响。
+ *
+ * ## 消费方要配合的一件事
+ *
+ * 用了本位就别再让页面画那三个按钮了，改由壳层画；页面的标题栏要在右侧留出
+ * `CAPTION_BUTTON_WIDTH * 3` 的空白（`mountTitleBar` 的 `captions: "native"`
+ * 就是做这件事的）。否则会看到两套按钮叠在一起。
+ *
+ * 只在 `FLAG_FRAMELESS` 同时给出时生效——带边框模式的标题栏由系统画。
+ */
+export const FLAG_NATIVE_CAPTIONS = 512;
 
 /**
  * 关闭 WebView2 的浏览器行为（`ShellOptions.browserUi` 使用）。
@@ -78,7 +152,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 +183,92 @@ 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];
+
+/**
+ * 自绘标题栏的几何规格（**逻辑像素**，96 DPI 基准）。
+ *
+ * 这两个值有**三处**副本，`tests/types.test.ts` 用判据把它们钉在一起：
+ *
+ * | 处 | 用途 | 为什么不能省 |
+ * | --- | --- | --- |
+ * | 这里 | 页面侧布局与命中测试的共同事实源 | 页面要按它画，原生要按它算 |
+ * | `src/ui/titlebar.ts` 的 CSS | 视觉尺寸 | 页面真正渲染的是 CSS |
+ * | `native/shell.cc` 的 `kCaptionBarHeight` / `kCaptionButtonWidth` | `WM_NCHITTEST` 命中区 | C++ 无法 import TS |
+ *
+ * 为什么必须一致：`HTMAXBUTTON` 是「悬停弹 Snap Layouts」的**唯一**触发条件
+ * （微软文档明写 Win32 应用要返回它）。命中区与视觉按钮错位，表现为
+ * 「悬停位置偏了才弹」或「悬停不弹」——两种都极难从现象反推回常量。
+ *
+ * 规格取自 Win 11：标题栏 32 px、caption button 46×32。
+ */
+export const CAPTION_BAR_HEIGHT = 32;
+export const CAPTION_BUTTON_WIDTH = 46;
+
+/**
+ * 从右往左的三个 caption button，与 Win 11 的顺序一致。
+ *
+ * 顺序不是审美选择：`close` 贴右上角，`maximize` 在它左边，`minimize` 再左。
+ * `WM_NCHITTEST` 按这个顺序算矩形，页面 CSS 也按这个顺序排 DOM。
+ */
+export const CAPTION_BUTTONS = ["close", "maximize", "minimize"] as const;
+
+/** `CAPTION_BUTTONS` 的成员名 */
+export type CaptionButton = (typeof CAPTION_BUTTONS)[number];
+
 /** window state 位掩码（与原生 shell_get_state 一致） */
 export const STATE_MAXIMIZED = 1;
 export const STATE_MINIMIZED = 2;
@@ -117,6 +294,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;