bun-app-window 0.7.0 → 0.9.0

package/src/shell/types.ts

@@ -171,14 +171,14 @@ export const BROWSER_UI_ALL =
  * `Shell.beginResize()` 在 TS 层查表转换，本常量成为真正的入参契约。
  */
 export const RESIZE_EDGE = {
-  LEFT: 10,
-  RIGHT: 11,
-  TOP: 12,
-  TOPLEFT: 13,
-  TOPRIGHT: 14,
-  BOTTOM: 15,
-  BOTTOMLEFT: 16,
-  BOTTOMRIGHT: 17,
+    LEFT: 10,
+    RIGHT: 11,
+    TOP: 12,
+    TOPLEFT: 13,
+    TOPRIGHT: 14,
+    BOTTOM: 15,
+    BOTTOMLEFT: 16,
+    BOTTOMRIGHT: 17,
 } as const;
 
 export type ResizeEdge = (typeof RESIZE_EDGE)[keyof typeof RESIZE_EDGE];
@@ -201,14 +201,14 @@ export type ResizeEdge = (typeof RESIZE_EDGE)[keyof typeof RESIZE_EDGE];
  * 时需要它，而那种时候手写映射必然抄错。
  */
 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,
+    [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,
 };
 
 /**
@@ -218,7 +218,7 @@ export const RESIZE_INDEX: Readonly<Record<number, number>> = {
  * `rc=-1`，与「窗口已销毁」是同一个外部表现，调用方按 `rc` 处理即可。
  */
 export function resizeIndex(edge: number): number {
-  return RESIZE_INDEX[edge] ?? -1;
+    return RESIZE_INDEX[edge] ?? -1;
 }
 
 /**
@@ -230,9 +230,7 @@ export function resizeIndex(edge: number): number {
  *
  * 过去消费者只能自己抄一份（抄了 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;
+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];
@@ -275,74 +273,201 @@ export const STATE_MINIMIZED = 2;
 export const STATE_FOCUSED = 4;
 
 export type WindowState = {
-  raw: number;
-  maximized: boolean;
-  minimized: boolean;
-  focused: boolean;
-  /** 系统当前是否深色（原生侧读 AppsUseLightTheme，并随 WM_SETTINGCHANGE 刷新） */
-  dark: boolean;
+    raw: number;
+    maximized: boolean;
+    minimized: boolean;
+    focused: boolean;
+    /** 系统当前是否深色（原生侧读 AppsUseLightTheme，并随 WM_SETTINGCHANGE 刷新） */
+    dark: boolean;
 };
 
+/**
+ * 窗口矩形的一次读数（物理像素，屏幕坐标）。
+ *
+ * 与 `WindowState` 的分工：`WindowState` 是廉价的位掩码（最大化 / 最小化 / 焦点 /
+ * 深色），不含几何；本类型是几何快照，唯一来源是 `Shell.getRect()` 对原生那行
+ * 文本的解析。
+ *
+ * `maximized` 与 `dpi` 跟矩形来自**同一次**原生读取，所以一起返回：判「这次读到的
+ * 尺寸是不是整屏」时不必再发一次 FFI 问 `state()`，也不会在两拍之间撞上状态变化，
+ * 读出一个 `x` 是旧的、`maximized` 是新的的撕裂值。最大化时四个数值是「还原后」的
+ * 矩形，不是整屏尺寸。
+ */
+export type WindowRect = {
+    /** 物理像素，屏幕坐标。主屏在右、副屏在左时 `x` 真的是负数，属正常 */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** 最大化时 `x/y/width/height` 为「还原后」的矩形 */
+    maximized: boolean;
+    /** 读取时的窗口 DPI；跨缩放比恢复矩形时用它换算 */
+    dpi: number;
+};
+
+/**
+ * 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 的最小化哨兵坐标。任一维命中即判否——两维是同时写的。
+ *
+ * 导出是因为**读原生字符串**与**读磁盘 JSON** 两条路都必须判同一对值：
+ * `parseBounds()` 判前者，`./state` 的 `parsePlacement()` 判后者。两条路各抄一份
+ * 阈值，某天调了一处就是其中一条静默失效。
+ */
+export function isMinimizedSentinel(x: number, y: number): boolean {
+    return x <= MINIMIZED_SENTINEL || y <= MINIMIZED_SENTINEL;
+}
+
+/**
+ * 把原生 `shell_get_bounds()` 返回的一行文本解析成 `WindowRect`；格式不对返回 `null`。
+ *
+ * 输入形如 `"x,y,w,h,maximized,dpi"`（物理像素）。三种返回 `null` 的情形都是
+ * **实测会真的出现**的，不是防御性编程：
+ *
+ * | 输入 | 成因 | 为什么不能给个默认值 |
+ * | --- | --- | --- |
+ * | 空串 | 窗口未启动或已销毁：原生 `format_bounds` 里 `!g_hwnd` 直接返回 0 | 编个矩形出来会让调用方以为窗口还在 |
+ * | 尺寸或 DPI 为 0 | 窗口还没建好，同一帧里读到的中途态 | 0 宽高的矩形画不对任何东西，DPI 为 0 也没法换算 |
+ * | 最小化哨兵坐标 | 见 `MINIMIZED_SENTINEL` | 那对数字形状合法，但不是位置 |
+ *
+ * 放在 `types.ts` 而不是 `./state` 的理由是分层：主入口要调用它，而 `./state`
+ * 依赖 `node:fs`（持久化按定义是副作用），主入口不能反过来依赖那个可选件。
+ * 本函数纯计算、零 import，主入口与页面侧都拿得动。
+ */
+export function parseBounds(text: string): WindowRect | null {
+    const parts = text.trim().split(",");
+    if (parts.length !== 6) {
+        return null;
+    }
+    const nums = parts.map((p) => Number(p));
+    if (nums.some((n) => !Number.isFinite(n))) {
+        return null;
+    }
+    const [x, y, width, height, maximized, dpi] = nums as [number, number, number, number, number, number];
+    // 尺寸为 0 或负数说明窗口还没建好（原生在无窗口时返回 0 长度文本，这里再兜一层）
+    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 };
+}
+
+/**
+ * 窗口的最小尺寸（**逻辑像素**，96 DPI 基准）。
+ *
+ * 与 `WindowRect` 分开：后者的四个数值是物理像素的屏幕坐标，本类型是逻辑像素的
+ * 约束值。两者混用会让高 DPI 下的窗口大小差一倍，而症状只是「比我设的小」。
+ */
+export type WindowSize = {
+    /** 逻辑像素，96 DPI 基准 */
+    width: number;
+    height: number;
+};
+
+/**
+ * 把原生 `shell_get_min_size()` 返回的 `"w,h"` 解析成 `WindowSize`；格式不对返回 `null`。
+ *
+ * 为什么原生给字符串而不是两个输出参数：与 `shell_get_bounds` 同一种「写入文本 +
+ * 返回长度」的形态，`bun:ffi` 侧一行 `readBuffer` 就够，不必为它引入第二套指针传参。
+ *
+ * 尺寸为 0 或负数返回 `null`：`shell_set_min_size()` 对非正值是忽略的（保持旧值），
+ * 所以真出现 0 说明数据来自别处（比如被手改过的持久化文件），不该当成合法约束。
+ */
+export function parseSize(text: string): WindowSize | null {
+    const parts = text.trim().split(",");
+    if (parts.length !== 2) {
+        return null;
+    }
+    const [width, height] = parts.map((p) => Number(p)) as [number, number];
+    if (!Number.isFinite(width) || !Number.isFinite(height)) {
+        return null;
+    }
+    if (width <= 0 || height <= 0) {
+        return null;
+    }
+    return { width, height };
+}
+
 /** 原生库的解析结果 */
 export type NativeLibInfo = {
-  path: string;
-  /**
-   * explicit  — 调用方显式指定
-   * dev       — 本仓开发态（build/ 或 dist/）
-   * package   — 包内 dist/ 或可执行文件同级
-   * embedded  — 从编译产物内嵌字节释放
-   * 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;
-  pruned: string[];
+    path: string;
+    /**
+     * explicit  — 调用方显式指定
+     * dev       — 本仓开发态（build/ 或 dist/）
+     * package   — 包内 dist/ 或可执行文件同级
+     * embedded  — 从编译产物内嵌字节释放
+     * 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;
+    pruned: string[];
 };
 
 export type ShellOptions = {
-  /** 要加载的 URL（通常是本地回环地址） */
-  url: string;
-  title?: string;
-  width?: number;
-  height?: number;
-  /** FLAG_* 位组合 */
-  flags?: number;
-  /** 启动后立即设置的最小尺寸（逻辑像素） */
-  minWidth?: number;
-  minHeight?: number;
-  /**
-   * 原生库路径。给定时跳过所有自动解析。
-   * 用于测试或多副本部署。
-   */
-  nativeLibPath?: string;
-  /**
-   * 运行时数据目录名（`%LOCALAPPDATA%\<appName>\runtime`）。
-   * 同一机器上多个应用共用一个包时应各自指定，避免互相清理 DLL 副本。
-   */
-  appName?: string;
-  /**
-   * 关闭哪些浏览器行为，取 `BROWSER_UI_*` 的按位或。缺省 0（保持 WebView2 默认）。
-   *
-   * 桌面应用一般传 `BROWSER_UI_ALL`：关掉右键 Edge 菜单、`Ctrl+P`/`Ctrl+F`/`Ctrl+S`、
-   * 左下角状态栏、触控板滑动导航与表单自动填充。关掉默认右键菜单后若要右键有反应，
-   * 用 `showContextMenu()` 弹原生菜单。
-   */
-  browserUi?: number;
-  /**
-   * 编译产物内嵌字节的提供者。
-   * 使用 `bun build --compile` 时传入 `embeddedDll`（见 `bun-app-window/embedded`）。
-   */
-  embedded?: () => Promise<Uint8Array | null>;
+    /** 要加载的 URL（通常是本地回环地址） */
+    url: string;
+    title?: string;
+    width?: number;
+    height?: number;
+    /** FLAG_* 位组合 */
+    flags?: number;
+    /** 启动后立即设置的最小尺寸（逻辑像素） */
+    minWidth?: number;
+    minHeight?: number;
+    /**
+     * 原生库路径。给定时跳过所有自动解析。
+     * 用于测试或多副本部署。
+     */
+    nativeLibPath?: string;
+    /**
+     * 运行时数据目录名（`%LOCALAPPDATA%\<appName>\runtime`）。
+     * 同一机器上多个应用共用一个包时应各自指定，避免互相清理 DLL 副本。
+     */
+    appName?: string;
+    /**
+     * 关闭哪些浏览器行为，取 `BROWSER_UI_*` 的按位或。缺省 0（保持 WebView2 默认）。
+     *
+     * 桌面应用一般传 `BROWSER_UI_ALL`：关掉右键 Edge 菜单、`Ctrl+P`/`Ctrl+F`/`Ctrl+S`、
+     * 左下角状态栏、触控板滑动导航与表单自动填充。关掉默认右键菜单后若要右键有反应，
+     * 用 `showContextMenu()` 弹原生菜单。
+     */
+    browserUi?: number;
+    /**
+     * 编译产物内嵌字节的提供者。
+     * 使用 `bun build --compile` 时传入 `embeddedDll`（见 `bun-app-window/embedded`）。
+     */
+    embedded?: () => Promise<Uint8Array | null>;
 };
 
 export type StartResult = { rc: number; error: string };

package/src/ui/titlebar.ts

@@ -479,8 +479,7 @@ export function mountTitleBar(opts: TitleBarOptions): TitleBarHandle {
     if (!nativeCaptions) {
         for (const action of ["minimize", "maximize", "close"] as const) {
             const btn = doc.createElement("button");
-            btn.className =
-                action === "close" ? "ws-titlebar__btn ws-titlebar__btn--close" : "ws-titlebar__btn";
+            btn.className = action === "close" ? "ws-titlebar__btn ws-titlebar__btn--close" : "ws-titlebar__btn";
             btn.setAttribute("type", "button");
             btn.setAttribute("data-act", action);
             btn.textContent = glyphFor(icons, action, opts.maximized === true);