bun-app-window 0.6.0 → 0.6.1

package/CHANGELOG.md

@@ -6,7 +6,105 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
-_(nothing yet)_
+## [0.6.1] - 2026-10-22
+
+### Added
+
+- **The caption buttons now draw Win 11's actual glyphs at Win 11's actual size, and the component has all five states instead of two.** The previous defaults were two independent misses that compounded.
+
+    **The glyphs were wrong for the platform, not just "less pretty".** `TITLEBAR_GLYPHS.unicode` renders `─ □ ❐ ✕` — geometric symbols from whatever text font is loaded. Their ink fills about half the em box: measured on `baw-mvp` at @192dpi, `\u25A1` came out **10×9 physical** and `\u25B1` **16×2**, against Win 11's **20×20** and **20×2** (measured on the Settings app, same machine). The fix is not a bigger `font-size` — `10px` was already correct — it is the font. `TITLEBAR_GLYPHS.fluent` holds `E921` / `E922` / `E923` / `E8BB`, which `Segoe Fluent Icons` (Win 11) and `Segoe MDL2 Assets` (Win 10) draw at **the same code points**, so one table covers both systems.
+
+    `fluent` was previously opt-in because a missing font renders private-use code points as tofu. `detectIconSet()` now checks `document.fonts` for either face and only falls back to `unicode` when neither is present; with no `FontFaceSource` to ask, it assumes `fluent`, since the component targets Windows. The result on `baw-mvp`: **20×20 / 20×20 / 20×2 physical**, identical to the system's own buttons, with horizontal centring at 0.0 px.
+
+    **Two states became five.** Hover and pressed backplates move from `0.0605` / `0.0419` to **`0.102` / `0.200`** of the foreground colour — the old values were faint enough that hovering looked like nothing happened. `setActive()` dims the glyph to `0.447` when the window loses focus, and `setEnabled(action, enabled)` drops it to `0.361` and stops dispatching. All four numbers, and the close button's red, come from Windows' own implementation as cross-checked against `egoist/mygo`'s `internal/windows/titlebar.go` (`colors()`).
+
+    **Focus dimming is expressed as a custom property, not a specificity fight.** `.ws-titlebar__btn` sets `color: var(--ws-tb-btn-fg)`, and `[data-active="false"]` on the root re-points that variable. Writing `color: var(--ws-tb-inactive)` straight onto the button would have lost to the `:hover` rule below it, and the fix for that would have been `:not()` chains or `!important` — the kind of thing that works until the next state arrives.
+
+    `setEnabled` guards in **two** places on purpose: CSS `pointer-events: none` stops the mouse, but a keyboard user tabbing to the button and pressing Enter still reaches the click handler. The `aria-disabled` attribute is the single source both read.
+
+    Verification: 38 assertions in `tests/titlebar.test.ts` (up from 25), including `detectIconSet` in all four combinations, the five-state CSS values asserted **inside their rule blocks**, and the disabled button not firing. Reverse-verified by restoring `--ws-tb-hover: 0.0605` — exactly one assertion went red, the rest stayed green.
+
+    **Still manual:** whether the focus-dimmed glyph actually renders dimmer on screen. The check needs the window to lose foreground, and in this session `SetForegroundWindow` never took it away from the host chat window — both readings came back at full brightness, i.e. the window never left the active state, so the probe measured nothing. The logic is covered by unit tests and the CSS is a plain attribute selector, but the end-to-end path (native `focused` bit → `windowState` push → `setActive` → repaint) has not been observed.
+
+- **Caption buttons on a frameless window now answer `HTMAXBUTTON`, so Windows 11 Snap Layouts works.** The only documented trigger is `WM_NCHITTEST` returning `HTMAXBUTTON` for the maximize/restore button (*Support snap layouts for desktop apps on Windows 11*). Previously `hit_test_client` returned only the eight resize codes and `HTCLIENT`, so hovering maximize never opened the layout picker — the last piece of "looks like a Win 11 app" that CSS cannot buy.
+
+    Three constants became a single source of truth in `types.ts` — `CAPTION_BAR_HEIGHT` (32), `CAPTION_BUTTON_WIDTH` (46), `CAPTION_BUTTONS` (`close` / `maximize` / `minimize`, right to left). Two copies follow it: `kCaptionBarHeight` / `kCaptionButtonWidth` plus the `caption_button_at()` order in `native/shell.cc` (C++ cannot import TS), and the `32px` / `46px` in `titlebar.css`.
+
+    **Order matters more than the numbers.** If the hit-test order and the DOM order disagree, clicking "close" maximizes the window — and the buttons look identical, so nothing about the symptom points at a constant.
+
+    **`HTMAXBUTTON` cannot ship alone.** Once `WM_NCHITTEST` answers that code, the point is non-client: a press delivers `WM_NCLBUTTONDOWN` instead of `WM_LBUTTONDOWN`, so the page receives no pointer or click event at all. Changing only the hit test turns the button into a black hole that eats clicks — the symptom reads as "clicking maximize does nothing", which is exactly backwards from the intent. `shell_wnd_proc` therefore handles `WM_NCLBUTTONDOWN` for the three button codes and performs the action itself; every other code still falls through to `DefWindowProc` so caption dragging and edge resizing keep working.
+
+    The caption check is deliberately placed **before** the resize-border check and is **not** gated on `g_resizable` / `IsZoomed`. The old guard opened with `!g_frameless || !g_resizable || IsZoomed(hwnd) → HTCLIENT`; reusing it would make the maximize button unhittable precisely when the window is maximized — which is when the user needs it to restore.
+
+    Measured with a one-off FFI probe against `dist/libshell.dll` and `user32.dll` (7/7):
+
+    ```text
+    A. scan from the right edge (physical px, 200% scale)
+      x=1799 → HTCLOSE
+      x=1708 → HTMAXBUTTON
+      x=1616 → HTMINBUTTON
+      x=1524 → HTTOP          ← inside the resize border
+      button width 91/92, expected 92 (= CSS 46px × scale)
+
+    B. WM_NCLBUTTONDOWN
+      HTMAXBUTTON → maximized   state=1
+      again       → restored    state=0
+      HTMINBUTTON → minimized   state=2, win=314x50 (sentinel — really minimized)
+    ```
+
+    **Still manual**: whether the Snap flyout actually *appears* on hover. It is a DWM-owned popup, so `PrintWindow` cannot capture it and no readout exposes it. Automating the hover was attempted and blocked — the Windows MCP refused the cursor move (`USER_CONTROL`, `state: user`), and `SetCursorPos` landed 216 px away, i.e. the pointer was in use. What is verified is the precondition the documentation names; what is not verified is the flyout itself.
+
+    One measurement worth keeping: the outer 13 physical pixels of the window are the resize border, so the title bar's top ~6.5 logical pixels answer `HTTOP` rather than the button code. Caption buttons win where they overlap (they are checked first), but a probe that samples `y=1` will read `HTTOP` and should not be read as "the button is missing".
+
+### Fixed
+
+- **The caption buttons sat 18 CSS px left of where they belong, and the title bar was squeezed to a third of its height — because a consumer's `header { … }` rule leaked into the component.** The component mounts on `<header class="ws-titlebar">`, and `baw-mvp`'s page has an element-selector rule for its own page header: `header { padding: 12px 18px 10px; gap: 12px }`. `.ws-titlebar` never declared `padding`, so the 18px right padding pushed all three buttons left by 18 CSS px (measured: 36 physical px @192dpi), and under `box-sizing: border-box` the 12/10 vertical padding squeezed the 32px bar down to 9px of content, shrinking the buttons to 18 physical px tall.
+
+    **It reads as "the glyph is not centred", and that diagnosis is wrong.** Measuring the hover backplate — `background` covers the whole button, so its edges *are* the button's edges — put the backplate at 92 physical px wide with the glyph's centre and the backplate's centre both at `d=137.5`: the glyph was centred all along. The whole group was displaced, then squashed.
+
+    **Specificity is not the mechanism.** An element selector (`0,0,1`) does lose to a class selector (`0,1,0`) — but only where the component *declares* the property. An undeclared property does not compete at all, so it is handed to the consumer. The mounting tag is part of the public contract, and `<header>` / `<button>` / `<div>` are exactly the tags consumers write global rules for.
+
+    The fix declares `margin` / `padding` / `gap` on `.ws-titlebar` and `margin` on `.ws-titlebar__btn`. The consumer sides changes too: `header { … }` becomes `.app-header { … }`, and `button { … }` becomes `button:not(.ws-titlebar__btn)` — the latter also stops `button:active { transform: translateY(1px) }` from reaching the caption buttons, which had been sinking the glyph 1px on press where Win 11 only swaps the backplate.
+
+    Three assertions guard it in `tests/titlebar.test.ts`, and they must be made **inside the rule block** (`cssBlock(css, ".ws-titlebar")` before `toContain("padding: 0")`). Writing `expect(css).toContain("padding: 0")` would be satisfied by the identically-valued declaration already in `.ws-titlebar__btn` — the guard would silently become a tautology, and this stylesheet happens to contain exactly that coincidence.
+
+    Verified by reverse: dropping `padding: 0` from `.ws-titlebar` turned **exactly one** assertion red and left the other 24 green; restoring it gave 25/25. On a real window the centring offsets went from `-35.5 / -36.0 / -36.0` to `0.5 / 0.0 / 0.0` physical px, and the close button now ends flush with the client area's right edge.
+
+- **`getBounds()` returned the Win32 minimised sentinel rectangle, and `attachPlacementStore` wrote it straight to disk.** `format_bounds()` only took `WINDOWPLACEMENT.rcNormalPosition` when `IsZoomed()` was true. A minimised window is not zoomed, so it fell through to `GetWindowRect()` — which for a minimised window reports `-32000,-32000` plus an icon-sized box (measured: `314x50`). `IsIconic()` was never consulted.
+
+    Those values look entirely valid: integer coordinates, positive dimensions. The existing shape checks (finite numbers, size > 0) cannot distinguish them from a real rectangle. So `window.json` became `{"x":-32000,"y":-32000,"width":314,"height":50,"dpi":192}`, and the next launch restored a 314×50 window — observed on `baw-mvp` as a 666×471 window with the page wrapped and scrolling.
+
+    Fixed at two layers:
+
+    - **Native.** The condition is now "minimised **or** maximised" instead of "maximised", and `IsIconic()` is explicit. The `maximized` bit comes from `WPF_RESTORETOMAXIMIZED` while minimised, because `IsZoomed()` is always false there — without it, "maximise → minimise → close" silently dropped the maximised state.
+    - **`state.ts`.** `parseBounds()` and `parsePlacement()` reject any coordinate at or below `-30000`. The first stops new bad values being recorded; the second invalidates files already written by earlier versions, so upgrading repairs the existing bad state rather than only preventing new ones. The threshold is a range, not an exact `-32000`, because the sentinel carries a few pixels of offset depending on DPI and theme. It cannot collide with real coordinates: an 8K display is 7680 wide, and even a long multi-monitor row stays far below 30000.
+
+    Three tests added, and verified by removing the guard — exactly those three go red, including the `-31996` offset variant. The companion cases that must keep passing are pinned too: a legitimate negative `x` (secondary monitor to the left) still parses.
+
+    Verified on a real window with a one-off FFI probe against `dist/libshell.dll` (bypassing every TS wrapper):
+
+    ```text
+    normal              → 147,147,1826,1271,0,192
+    minimised           → 147,147,1826,1271,0,192   ← no sentinel, restore rect
+    maximised           → 147,147,1826,1271,1,192
+    maximised → minimise → 147,147,1826,1271,1,192   ← maxed bit preserved
+    ```
+
+- **The caption buttons are now drawn and hit-tested by the shell on its own layered child window, so a consumer can stop faking them with DOM.** `FLAG_NATIVE_CAPTIONS` (512) creates a `WS_EX_LAYERED | WS_CHILD` window named `webview_shell_caption`, anchored to the client area's top-right corner at exactly `3 × CAPTION_BUTTON_WIDTH` by `CAPTION_BAR_HEIGHT` in logical pixels (`276×64` physical at @192dpi). It answers `WM_NCHITTEST` itself with `HTCLOSE` / `HTMAXBUTTON` / `HTMINBUTTON`; the title strip and the client area still report `Chrome_RenderWidgetHostHWND`, so the page keeps receiving mouse input. `mountTitleBar({ captions: "native" })` skips creating the three buttons and only reserves their footprint.
+
+    It supersedes `FLAG_TITLEBAR_RESERVE` for consumers that draw their own title bar. `baw-mvp` now runs `flags = 573`; the DLL grows to `1,025,536 B` with its 34 exports unchanged, and `gdi32` joins the subsystem library list (ten now).
+
+    Three details it depends on, each pinned by an assertion in `tests/nav-guard.test.ts`:
+
+    - **`UpdateLayeredWindow` must be given an explicit `SIZE`.** Passing `nullptr` returns `true`, sets no error, and leaves the surface `0×0` — the window then exists, is visible, sits at the top of the child chain, has a correct rectangle, and is hit-transparent anyway. The window under it receives every click. See `docs/pitfalls.md` 2.21 for the A/B and for why the documented "the size does not change" does not cover "never was set".
+    - **The rest fill is `alpha = 1`, not 0.** A fully transparent layered window is hit-transparent: measured 0/3 hits at `alpha = 0`, 3/3 for every value from 1 to 255. Rest state is invisible at 1/255 either way, so the value exists only to keep the window hittable.
+    - **`WM_NCMOUSEMOVE` breaks to `DefWindowProcW` instead of returning 0.** That is where the Snap hover detection happens; short-circuiting it costs the layout picker while leaving the window looking completely normal.
+
+    Clicks go through `WM_SYSCOMMAND` from the shell process, and only fire when released over the same button. Once `WM_NCHITTEST` answers `HTMAXBUTTON` the point is non-client — the press arrives as `WM_NCLBUTTONDOWN`, not `WM_LBUTTONDOWN` — so the page never sees a `click` and the shell has to perform the action itself. This is also why the three buttons are children of the shell rather than elements of the page: a DOM button cannot return a non-client hit code.
+
+    Measured on `baw-mvp` at @192dpi maximised: `WindowFromPoint` lands on `webview_shell_caption` 3/3, the three hit codes are exact, glyph boxes are `20×20 / 20×20 / 20×2` physical (`10×10 / 10×10 / 10×1` logical) with `0.0` centring offsets, and the hover backplate moves `32.0 → 55.1` (`+23.1`, against `+22.7` expected). Gate: `72 files`, `603 pass / 0 fail`, `VERIFY-PACK PASSED (7 checks)`.
+
+    **Snap Layouts was confirmed by a real mouse, and that is the interesting part.** Four automated probes reported zero new top-level windows while hovering and were read as "a child window cannot trigger Snap" — which was wrong. The flyout is a DWM-owned popup, so window enumeration never sees it and the probe could not have reported anything else. The rule this leaves behind (`docs/pitfalls.md` 2.21, fourth section): a guard that reports `0` must first prove it is not blind, by reporting non-zero on a sample known to be true.
 
 ## [0.6.0] - 2026-10-21
 
@@ -532,7 +630,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.6.0...HEAD
+[Unreleased]: https://github.com/TiancongLx/bun-app-window/compare/v0.6.1...HEAD
+[0.6.1]: https://github.com/TiancongLx/bun-app-window/compare/v0.6.0...v0.6.1
 [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

package/package.json

@@ -1,7 +1,7 @@
 {
     "$schema": "https://json.schemastore.org/package.json",
     "name": "bun-app-window",
-    "version": "0.6.0",
+    "version": "0.6.1",
     "description": "Native WebView2 window shell for Bun — frameless or system-decorated windows, DPI-aware geometry, typed IPC, system-accurate title bar",
     "type": "module",
     "license": "MIT",

package/src/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

@@ -72,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` 使用）。
@@ -176,6 +238,37 @@ export 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;

package/src/ui/titlebar.ts

@@ -45,6 +45,13 @@ export type TitleBarDocument = {
     body?: TitleBarElement;
     getElementById(id: string): TitleBarElement | null;
     querySelector(selector: string): TitleBarElement | null;
+    /**
+     * 可选：字体可用性探测，通常是 `document.fonts`。
+     *
+     * 缺省时 {@link detectIconSet} 按 `fluent` 处理（Win 10 / 11 都自带其中一个
+     * icon 字体）。传了就按探测结果选字形，两个字体都不在时退回 `unicode`。
+     */
+    fonts?: TitleBarFonts;
 };
 
 type EventLike = {
@@ -55,18 +62,60 @@ type EventLike = {
 
 export type TitleBarIconSet = "unicode" | "fluent";
 
+/**
+ * Win 11 caption 字形所用的字体栈。
+ *
+ * `Segoe Fluent Icons` 是 Win 11 的，`Segoe MDL2 Assets` 是 Win 10 的，
+ * 而 `E921` / `E922` / `E923` / `E8BB` 这几个人码位在两者里**是同一个位置**——
+ * 所以同一份码位在两代系统上都能正确显示。这一点是照着
+ * `egoist/mygo` 的 `internal/windows/titlebar.go` 核实的：它同时支持 Win 10 / 11，
+ * 用的就是这一份码位表，只换字体名。
+ */
+export const TITLEBAR_ICON_FONT_STACK = '"Segoe Fluent Icons", "Segoe MDL2 Assets"';
+
 /**
  * 按钮字形。
  *
- * `unicode` 是几何符号，任何字体都有，零依赖；
- * `fluent` 是 Segoe Fluent Icons 的私有区码位，观感更接近 Win 11 原生，
- * 但该字体缺失时会显示成豆腐块——所以不是默认值。
+ * `unicode` 是几何符号，任何字体都有，零依赖，但**撑不满 em 框**——
+ * 实测在 10px 字号下 `\u25A1` 的墨迹只有 5×4.5 逻辑 px，
+ * 而 Win 11 的 caption 字形是 10×10。这是「字形看起来偏小」的根因，不是字号问题。
+ *
+ * `fluent` 是 Segoe Fluent Icons / Segoe MDL2 Assets 的私有区码位，字形填满 em 框，
+ * 观感与 Win 11 原生一致。真正的风险只剩「两个字体都没有」的环境
+ * （非 Windows 宿主、极旧系统），那时 PUA 码位会渲染成豆腐块——
+ * 所以由 {@link detectIconSet} 探测，探测不到才退回 `unicode`。
  */
 export const TITLEBAR_GLYPHS = {
     unicode: { minimize: "\u2500", maximize: "\u25A1", restore: "\u2750", close: "\u2715" },
     fluent: { minimize: "\uE921", maximize: "\uE922", restore: "\uE923", close: "\uE8BB" },
 } as const;
 
+/**
+ * 只问一件事的字体探测接口（`document.fonts` 的结构子集）。
+ *
+ * 单独抽出来而不是直接依赖 `FontFaceSet`：组件刻意不依赖 DOM 类型声明
+ * （`tsconfig` 的 `lib` 只有 ESNext），这一层最小接口既够用又能被测试注入。
+ */
+export type TitleBarFonts = {
+    check(font: string): boolean;
+};
+
+/**
+ * 选字形集：优先 `fluent`，两个 icon 字体都不在时才退化到 `unicode`。
+ *
+ * 没有探测能力（`fonts` 缺省）时按 `fluent` 处理——目标平台是 Windows，
+ * Win 10 与 Win 11 都自带其中之一。冒险的只有「非 Windows 宿主 + 不传 fonts」，
+ * 那本来也不是这个组件的目标场景。
+ */
+export function detectIconSet(fonts?: TitleBarFonts): TitleBarIconSet {
+    if (!fonts) {
+        return "fluent";
+    }
+    const hasFluent = fonts.check(`10px "Segoe Fluent Icons"`);
+    const hasMdl2 = fonts.check(`10px "Segoe MDL2 Assets"`);
+    return hasFluent || hasMdl2 ? "fluent" : "unicode";
+}
+
 /**
  * 取某个按钮当前该显示的字形。
  *
@@ -111,10 +160,22 @@ export function titleBarCss(): string {
     --ws-tb-bg: #202020;
     --ws-tb-fg: #ffffff;
     --ws-tb-dim: rgba(255, 255, 255, 0.786);
-    --ws-tb-hover: rgba(255, 255, 255, 0.0605);
-    --ws-tb-active: rgba(255, 255, 255, 0.0419);
+    /* ---- 五个状态 ----------------------------------------------------------
+       Win 11 的 caption 背板是「前景色 + 一份 alpha」，不是固定灰；
+       数值取自 Windows 自己的实现，与 egoist/mygo 的
+       internal/windows/titlebar.go（colors()）一致：hover 0x1A、pressed 0x33。
+       旧值 0.0605 / 0.0419 偏淡到几乎看不见悬停。
+       失焦只降字形（0x72），禁用再降一档（0x5C）；hot / pressed 优先于失焦。 */
+    --ws-tb-hover: rgba(255, 255, 255, 0.102);
+    --ws-tb-active: rgba(255, 255, 255, 0.200);
     --ws-tb-close-hover: #c42b1c;
     --ws-tb-close-active: #b02a1c;
+    --ws-tb-inactive: rgba(255, 255, 255, 0.447);
+    --ws-tb-disabled: rgba(255, 255, 255, 0.361);
+    /* 字形当前色。做成自定义属性而不是直接写 color，
+       这样「失焦变淡」与「hover 恢复满强度」可以靠继承关系表达，
+       不必给 hover 规则堆特异性去压过 [data-active="false"]。 */
+    --ws-tb-btn-fg: var(--ws-tb-fg);
     --ws-tb-border: rgba(255, 255, 255, 0.08);
 
     display: flex;
@@ -125,6 +186,17 @@ export function titleBarCss(): string {
     font: 400 12px/1 "Segoe UI Variable Text", "Segoe UI", system-ui, sans-serif;
     user-select: none;
     -webkit-user-select: none;
+    /* 下面四条**必须显式声明**。
+       挂载点是 <header>，而消费方常写元素选择器「header { padding: ... }」做自己的页头。
+       元素选择器的特异性低于类选择器，但只在组件**声明了**该属性时才被压住——
+       没写的属性等于把控制权交给消费方。
+       实测（baw-mvp）：它的「header { padding: 12px 18px 10px }」漏进来，
+       18px 右内边距把三个按钮整体推左 18 CSS px（@192dpi = 36 物理 px），
+       12/10 的上下内边距又把 32px 的标题栏压成 9px 内容高，按钮跟着缩到 18 物理 px。
+       两者合起来看起来像「字形没有居中」，而字形在按钮内其实是居中的。 */
+    margin: 0;
+    padding: 0;
+    gap: 0;
     border-bottom: 1px solid var(--ws-tb-border);
     box-sizing: border-box;
 }
@@ -133,11 +205,18 @@ export function titleBarCss(): string {
     --ws-tb-bg: #f3f3f3;
     --ws-tb-fg: #000000;
     --ws-tb-dim: rgba(0, 0, 0, 0.6063);
-    --ws-tb-hover: rgba(0, 0, 0, 0.0373);
-    --ws-tb-active: rgba(0, 0, 0, 0.0241);
+    --ws-tb-hover: rgba(0, 0, 0, 0.102);
+    --ws-tb-active: rgba(0, 0, 0, 0.200);
+    --ws-tb-inactive: rgba(0, 0, 0, 0.447);
+    --ws-tb-disabled: rgba(0, 0, 0, 0.361);
     --ws-tb-border: rgba(0, 0, 0, 0.0578);
 }
 
+/* 窗口失焦：只降字形，背板照旧（hover / pressed 仍然优先，见下） */
+.ws-titlebar[data-active="false"] {
+    --ws-tb-btn-fg: var(--ws-tb-inactive);
+}
+
 .ws-titlebar__lead {
     display: flex;
     align-items: center;
@@ -170,14 +249,31 @@ export function titleBarCss(): string {
     flex: none;
 }
 
+/* ---- 原生 caption（FLAG_NATIVE_CAPTIONS）----------------------------------
+   三个按钮由壳层画在一个 layered 子窗口里、盖在窗口右上角。页面这边要做的唯一
+   一件事是**把位置留出来**——否则标题文字会被那层子窗口压住。
+   宽度是 46 × 3，与 .ws-titlebar__btn 的 width 同源（后者由
+   tests/types.test.ts 钉在 CAPTION_BUTTON_WIDTH 上）。
+   为什么不用 padding 而是给控件容器定宽：按钮区是「贴住客户区右边缘」的，
+   用容器定宽更直白，也不会与标题栏自己的 padding 相互影响。 */
+.ws-titlebar[data-captions="native"] .ws-titlebar__controls {
+    width: calc(46px * 3);
+}
+
 .ws-titlebar__btn {
     width: 46px;
     height: 100%;
+    /* margin 必须显式清零：消费方常写「button { margin: ... }」之类，
+       元素选择器只在组件没声明该属性时生效。与 .ws-titlebar 那一组同理。 */
+    margin: 0;
     border: 0;
     padding: 0;
     background: transparent;
-    color: var(--ws-tb-dim);
+    color: var(--ws-tb-btn-fg);
     font: inherit;
+    /* Win 11 的 caption 字形是 10 DIP。在这个字号下，
+       Fluent 图标字体把 10×10 逻辑 px 填满（实测墨迹填满 em 框），
+       而几何符号的墨迹只占 5×4.5——所以换字体才是「字形偏小」的解。 */
     font-size: 10px;
     line-height: 1;
     display: grid;
@@ -187,7 +283,7 @@ export function titleBarCss(): string {
 }
 
 .ws-titlebar__btn:hover { background: var(--ws-tb-hover); color: var(--ws-tb-fg); }
-.ws-titlebar__btn:active { background: var(--ws-tb-active); }
+.ws-titlebar__btn:active { background: var(--ws-tb-active); color: var(--ws-tb-fg); }
 
 .ws-titlebar__btn--close:hover { background: var(--ws-tb-close-hover); color: #ffffff; }
 .ws-titlebar__btn--close:active { background: var(--ws-tb-close-active); color: #ffffff; }
@@ -197,8 +293,22 @@ export function titleBarCss(): string {
     outline-offset: -2px;
 }
 
+/* 禁用：字形再淡一档，且不响应悬停 / 按下。Win 11 用 aria-disabled 语义即可，
+   不必另造一个属性名。 */
+.ws-titlebar__btn[aria-disabled="true"] {
+    color: var(--ws-tb-disabled);
+    pointer-events: none;
+}
+.ws-titlebar__btn[aria-disabled="true"]:hover,
+.ws-titlebar__btn[aria-disabled="true"]:active {
+    background: transparent;
+    color: var(--ws-tb-disabled);
+}
+
 .ws-titlebar[data-icons="fluent"] .ws-titlebar__btn {
-    font-family: "Segoe Fluent Icons", "Segoe MDL2 Assets", sans-serif;
+    font-family: ${TITLEBAR_ICON_FONT_STACK}, sans-serif;
+    /* 图标字体的字形是等宽方框，不要被消费方的 letter-spacing 拉开 */
+    letter-spacing: 0;
 }
 `.trim();
 }
@@ -212,8 +322,26 @@ export type TitleBarOptions = {
     bridge: TitleBarBridge;
     /** 初始是否已最大化 */
     maximized?: boolean;
-    /** 按钮字形，默认 `unicode` */
+    /** 窗口初始是否处于激活状态（决定字形是否变淡）。缺省 `true` */
+    active?: boolean;
+    /** 按钮字形，缺省由 {@link detectIconSet} 按字体可用性决定（通常 `fluent`） */
     icons?: TitleBarIconSet;
+    /**
+     * 三个 caption 按钮由谁画。
+     *
+     * - `"dom"`（缺省）：组件自己渲染按钮，行为完全由 `bridge` 决定
+     * - `"native"`：**不渲染按钮**，只在右侧留出 `46 × 3` 的空白，
+     *   由壳层的 `FLAG_NATIVE_CAPTIONS` 把按钮画上去
+     *
+     * 什么时候要 `"native"`：需要 Snap Layouts 的时候。`WM_NCHITTEST` 走光标下
+     * 最深那层，而 WebView2 的渲染子窗口在**别的进程**里、返回 `HTCLIENT`，
+     * 页面画的按钮永远拿不到 `HTMAXBUTTON`（`pitfalls` 2.14）。壳层会盖一个
+     * 自己的子窗口在按钮位置上，命中就落在壳层手里。
+     *
+     * 两者必须配套：壳层开了 `FLAG_NATIVE_CAPTIONS` 而这里仍用 `"dom"`，
+     * 会看到两套按钮叠在一起；反过来则是一块点不到的空区。
+     */
+    captions?: "dom" | "native";
     /** 主题，缺省跟随 `prefers-color-scheme` */
     theme?: "light" | "dark";
     /** 挂载容器，缺省 `document.body` */
@@ -228,6 +356,23 @@ export type TitleBarHandle = {
     setMaximized(maximized: boolean): void;
     /** 组件最后一次被设置的最大化状态。用于核对与宿主推送是否同步 */
     isMaximized(): boolean;
+    /**
+     * 窗口是否处于激活（聚焦）状态。失焦时字形降到 45% 不透明度，
+     * 这是 Win 11 与「永远满强度」的一处可见差别。
+     *
+     * 接 `windowState` 推送里的 `focused`：用户点别的窗口时它会变，
+     * 页面自己看不到这件事。
+     */
+    setActive(active: boolean): void;
+    /** 组件最后一次被设置的激活状态 */
+    isActive(): boolean;
+    /**
+     * 按 Win 11 的规则禁用某个按钮。
+     *
+     * 用途是「这个窗口不能最大化」这类情形——禁用后字形变淡、且不再派发动作。
+     * 用 `aria-disabled` 而不是另造属性：它同时是给辅助技术的语义。
+     */
+    setEnabled(action: "minimize" | "maximize" | "close", enabled: boolean): void;
     setTheme(theme: "light" | "dark"): void;
     /** 移除 DOM 与事件监听。样式表保留（可能是别的实例注入的） */
     destroy(): void;
@@ -275,7 +420,9 @@ function inControls(target: unknown): boolean {
  */
 export function mountTitleBar(opts: TitleBarOptions): TitleBarHandle {
     const doc = resolveDocument(opts.document);
-    const icons: TitleBarIconSet = opts.icons ?? "unicode";
+    // 缺省按字体探测：Win 10 / 11 都有 icon 字体，看到的就是原生字形；
+    // 两个都没有才退回几何符号（`unicode`）。
+    const icons: TitleBarIconSet = opts.icons ?? detectIconSet(doc.fonts);
 
     // 样式只注入一次。多个标题栏实例（多窗口页面）共用同一份
     if (!doc.getElementById(STYLE_ID)) {
@@ -288,6 +435,14 @@ export function mountTitleBar(opts: TitleBarOptions): TitleBarHandle {
     const root = doc.createElement("header");
     root.className = "ws-titlebar";
     root.setAttribute("data-icons", icons);
+    // 缺省按激活处理：窗口刚创建时就是前台，写成 false 会让标题栏一开始是灰的。
+    root.setAttribute("data-active", opts.active === false ? "false" : "true");
+    // 原生 caption 模式：不渲染按钮，只在右侧留位（CSS 按这个属性选择器定宽）。
+    // 属性只在 native 时出现，所以缺省形态的 DOM 与引入本位之前**逐字相同**。
+    const nativeCaptions = opts.captions === "native";
+    if (nativeCaptions) {
+        root.setAttribute("data-captions", "native");
+    }
     if (opts.theme) {
         root.setAttribute("data-theme", opts.theme);
     }
@@ -318,16 +473,21 @@ export function mountTitleBar(opts: TitleBarOptions): TitleBarHandle {
     controls.setAttribute("data-ws-tb-controls", "");
 
     const buttons: Partial<Record<"minimize" | "maximize" | "close", TitleBarElement>> = {};
-    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.setAttribute("type", "button");
-        btn.setAttribute("data-act", action);
-        btn.textContent = glyphFor(icons, action, opts.maximized === true);
-        btn.setAttribute("aria-label", labelFor(action, opts.maximized === true));
-        buttons[action] = btn;
-        controls.appendChild(btn);
+    // `captions: "native"` 时一个按钮都不建：那三个由壳层的 layered 子窗口画，
+    // 页面上再画一份就是两套叠在一起。控件容器仍然保留——它是「留位」的载体
+    // （CSS 给它 46×3 的宽度），也是拖拽判定里 `inControls` 的锚点。
+    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.setAttribute("type", "button");
+            btn.setAttribute("data-act", action);
+            btn.textContent = glyphFor(icons, action, opts.maximized === true);
+            btn.setAttribute("aria-label", labelFor(action, opts.maximized === true));
+            buttons[action] = btn;
+            controls.appendChild(btn);
+        }
     }
 
     root.append(lead, controls);
@@ -347,6 +507,24 @@ export function mountTitleBar(opts: TitleBarOptions): TitleBarHandle {
     /** 当前是否最大化。供调用方在本地校验状态是否同步 */
     const isMaximized = (): boolean => maximizedState;
 
+    let activeState = opts.active !== false;
+
+    /** 当前是否处于激活状态 */
+    const isActive = (): boolean => activeState;
+
+    const applyActive = (next: boolean): void => {
+        activeState = next;
+        root.setAttribute("data-active", next ? "true" : "false");
+    };
+
+    const applyEnabled = (action: "minimize" | "maximize" | "close", enabled: boolean): void => {
+        const btn = buttons[action];
+        if (!btn) {
+            return;
+        }
+        btn.setAttribute("aria-disabled", enabled ? "false" : "true");
+    };
+
     const onPointerDown = (ev: EventLike): void => {
         if (ev.button !== undefined && ev.button !== 0) {
             return;
@@ -368,6 +546,11 @@ export function mountTitleBar(opts: TitleBarOptions): TitleBarHandle {
     const onControlsClick = (ev: EventLike): void => {
         const node = ev.target as { closest?: (s: string) => { getAttribute(n: string): string | null } | null } | null;
         const btn = typeof node?.closest === "function" ? node.closest("[data-act]") : null;
+        // 禁用的按钮不派发动作。CSS 已经用 pointer-events: none 拦住鼠标，
+        // 但键盘（Tab 到按钮上按 Enter/Space）仍会走到这里，所以判定必须在这里也做一次。
+        if (btn?.getAttribute("aria-disabled") === "true") {
+            return;
+        }
         const act = btn?.getAttribute("data-act");
         if (act === "minimize") {
             opts.bridge.minimize();
@@ -398,6 +581,9 @@ export function mountTitleBar(opts: TitleBarOptions): TitleBarHandle {
         },
         setMaximized: applyMaximized,
         isMaximized,
+        setActive: applyActive,
+        isActive,
+        setEnabled: applyEnabled,
         setTheme(theme: "light" | "dark"): void {
             root.setAttribute("data-theme", theme);
         },