bun-app-window 0.2.2 → 0.4.0

package/src/shell/events.ts

@@ -0,0 +1,297 @@
+/**
+ * events.ts — 窗口生命周期事件：解码、游标与拉取节奏
+ *
+ * ## 为什么是队列 + 拉取，而不是回调
+ *
+ * `webview_run` 会阻塞原生 UI 线程，而 `bun:ffi` 的 `JSCallback` 依赖空闲的 JS
+ * 主线程。二者叠加就是跨线程重入死锁（ADR 0002、`AGENTS.md` §5 第 5 条）。所以
+ * 原生层只能往一个定长环里写，宿主在自己的节奏里批量拉走——`shell_poll_events`。
+ *
+ * ## 单读者
+ *
+ * `shell_poll_events` 是**消费式**的：读走的记录不会再来。一个进程里只应有一个
+ * 消费者。要么用本模块的 `attachEventPump()`，要么自己按节奏调 `shell.pollEvents()`，
+ * 别两者都来——两个消费者会各自拿到一部分，谁也看不全。
+ *
+ * 需要多路关心同一批事件时（例如「位置持久化」与「宿主等关闭」），用一个 pump
+ * 加多个 `on()` 订阅，而不是起两个 pump。
+ *
+ * ## 序号与缺口
+ *
+ * 环满时丢最旧（原生侧裁断）。丢掉的记录不会伪装成还在，代价是 `seq` 出现断档——
+ * 这正是「丢了几条」的精确来源：`EventCursor` 把它换算成 `gaps`，比一条合成的
+ * 「溢出事件」信息量更大，也少一个要定义 `seq` 的特殊值。
+ *
+ * 新一次 `shell_start_ex` 会把 `seq` 归零。`seq` 回退即判定为重启（`restarted`），
+ * 缺口不跨重启点计算。
+ */
+
+/**
+ * 一条事件记录的字节数。
+ *
+ * 与 `native/shell.cc` 的 `EventRecord` 严格一一对应（那边有
+ * `static_assert(sizeof(EventRecord) == 32)`）。改布局就是改 ABI。
+ */
+export const EVENT_RECORD_BYTES = 32;
+
+/** 窗口状态变化。载荷是抓取那一刻的快照，不是增量 */
+export const EVENT_STATE = 1;
+/** 窗口已销毁且原生单例已释放。终态：此后不再有任何事件 */
+export const EVENT_CLOSED = 2;
+
+/** 最大化（对应 `SHELL_EV_MAXIMIZED`） */
+export const EV_MAXIMIZED = 1;
+/** 最小化 */
+export const EV_MINIMIZED = 2;
+/** 前台焦点 */
+export const EV_FOCUSED = 4;
+/** 系统深色主题 */
+export const EV_DARK = 8;
+
+/** 状态快照：`EVENT_STATE` 的载荷 */
+export type StateEvent = {
+    readonly type: typeof EVENT_STATE;
+    /** 单调递增，从 1 起；新一次启动归零 */
+    readonly seq: number;
+    /** 客户区宽（物理像素） */
+    readonly width: number;
+    /** 客户区高（物理像素） */
+    readonly height: number;
+    /** 窗口 DPI；页面 CSS 像素 = 物理像素 × 96 / dpi */
+    readonly dpi: number;
+    readonly maximized: boolean;
+    readonly minimized: boolean;
+    readonly focused: boolean;
+    readonly dark: boolean;
+};
+
+/** 终态：`EVENT_CLOSED` 的载荷 */
+export type ClosedEvent = {
+    readonly type: typeof EVENT_CLOSED;
+    readonly seq: number;
+};
+
+export type WindowEvent = StateEvent | ClosedEvent;
+
+/** 原生事件队列的容量。宿主一次拉取超过它没有意义 */
+export const EVENT_QUEUE_CAPACITY = 128;
+
+/**
+ * 把原生写出的定长缓冲解成事件数组。
+ *
+ * `count` 来自 `shell_poll_events` 的返回值。它按契约不会超过 `buf` 能容纳的条数，
+ * 但这里仍然夹一次——`count` 与 `buf` 由两处代码分别决定，夹一下的成本是一次除法，
+ * 换来的是「原生改了布局、TS 忘了同步」时不会越界读。
+ *
+ * 未知 `type` 直接跳过而不是抛错：旧宿主遇到将来新增的事件类型，应该继续工作。
+ */
+export function decodeEvents(buf: Uint8Array, count: number): WindowEvent[] {
+    const room = Math.floor(buf.byteLength / EVENT_RECORD_BYTES);
+    const n = Math.min(Math.max(0, Math.trunc(count)), room);
+    const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+    const out: WindowEvent[] = [];
+
+    for (let i = 0; i < n; i++) {
+        const at = i * EVENT_RECORD_BYTES;
+        const seq = view.getUint32(at, true);
+        const type = view.getUint32(at + 4, true);
+
+        if (type === EVENT_CLOSED) {
+            out.push({ type: EVENT_CLOSED, seq });
+            continue;
+        }
+        if (type !== EVENT_STATE) {
+            continue;
+        }
+
+        const flags = view.getUint32(at + 24, true);
+        out.push({
+            type: EVENT_STATE,
+            seq,
+            width: view.getInt32(at + 8, true),
+            height: view.getInt32(at + 12, true),
+            dpi: view.getInt32(at + 16, true),
+            maximized: (flags & EV_MAXIMIZED) !== 0,
+            minimized: (flags & EV_MINIMIZED) !== 0,
+            focused: (flags & EV_FOCUSED) !== 0,
+            dark: (flags & EV_DARK) !== 0,
+        });
+    }
+    return out;
+}
+
+/** 只要求「能拉一批事件」，不绑定 `Shell`——便于测试与自定义源 */
+export type EventSource = {
+    pollEvents(max?: number): WindowEvent[];
+};
+
+export type EventBatch = {
+    readonly events: readonly WindowEvent[];
+    /** 每项是「这里丢了几条」。空数组表示序号连续 */
+    readonly gaps: readonly number[];
+    /** `seq` 回退，说明原生侧重启过 */
+    readonly restarted: boolean;
+};
+
+/**
+ * 事件游标：把「序号」翻译成「有没有丢」。
+ *
+ * 抽成独立对象是因为这是本模块唯一有状态、且状态正确性不能靠端到端验证的部分——
+ * 真窗口能证明「拉到事件了」，证明不了「丢了事件时能看出来」。
+ */
+export class EventCursor {
+    private last = 0;
+
+    /** 最近一次收到的 `seq`；0 表示还没收到过 */
+    get seq(): number {
+        return this.last;
+    }
+
+    /** 丢弃已记录的位置（换了一个窗口重新开始看时用） */
+    reset(): void {
+        this.last = 0;
+    }
+
+    push(events: readonly WindowEvent[]): EventBatch {
+        const gaps: number[] = [];
+        let restarted = false;
+
+        for (const e of events) {
+            // 序号回退 = 原生侧重启（`reset_events()` 把序号归零）。
+            // 重启后的第一条不检查缺口：新的一轮从 1 开始，把它当成「前面丢了 N 条」
+            // 会把重启本身误报成丢事件。
+            let afterRestart = false;
+            if (this.last > 0 && e.seq <= this.last) {
+                restarted = true;
+                this.last = 0;
+                afterRestart = true;
+            }
+            // last 为 0 且不是重启后的第一条（宿主从未读过）时，首条不是 1 同样说明有丢弃
+            if (!afterRestart && e.seq > this.last + 1) {
+                gaps.push(e.seq - this.last - 1);
+            }
+            this.last = e.seq;
+        }
+
+        return { events, gaps, restarted };
+    }
+}
+
+export type EventPump = {
+    /** 订阅。返回退订函数 */
+    on(fn: (e: WindowEvent) => void): () => void;
+    /** 订阅缺口。丢了多久之后不会再补，只会告诉你有多少条没看见 */
+    onGap(fn: (missing: number) => void): () => void;
+    stop(): void;
+    readonly running: boolean;
+    /** 已消费到的最新序号 */
+    readonly seq: number;
+};
+
+export type EventPumpOptions = {
+    /** 拉取节奏。默认 16 ms，约一帧 */
+    intervalMs?: number;
+    /** 一次最多拉多少条。默认 64，不超过 `EVENT_QUEUE_CAPACITY` */
+    maxBatch?: number;
+    /**
+     * 是否让定时器阻止进程退出。默认 `false`（unref）。
+     *
+     * 设 `true` 的场景只有一种：**靠这个 pump 等窗口关闭**。unref 的定时器不
+     * 阻止退出，而一个永不兑现的 promise 也撑不住事件循环——宿主会在窗口还开着
+     * 的时候直接退出。`./app` 的骨架因此传 `true`。
+     */
+    keepAlive?: boolean;
+};
+
+/**
+ * 按固定节奏从原生侧拉取事件，并分发给订阅者。
+ *
+ * 收到 `EVENT_CLOSED` 后自动 `stop()`：那是终态，之后再拉只有空数组，留着定时器
+ * 只是白烧 CPU。
+ *
+ * 每个窗口只应有一个 pump（见模块头「单读者」）。
+ */
+export function attachEventPump(src: EventSource, opts: EventPumpOptions = {}): EventPump {
+    const intervalMs = opts.intervalMs ?? 16;
+    // 原生环就 EVENT_QUEUE_CAPACITY 条，要更多没有意义：多出来的缓冲永远不会被写满
+    const maxBatch = Math.min(Math.max(1, opts.maxBatch ?? 64), EVENT_QUEUE_CAPACITY);
+    const keepAlive = opts.keepAlive ?? false;
+
+    const cursor = new EventCursor();
+    const listeners = new Set<(e: WindowEvent) => void>();
+    const gapListeners = new Set<(missing: number) => void>();
+    let stopped = false;
+
+    function stop(): void {
+        if (stopped) {
+            return;
+        }
+        stopped = true;
+        clearInterval(timer);
+    }
+
+    const tick = (): void => {
+        if (stopped) {
+            return;
+        }
+        let batch: EventBatch;
+        try {
+            batch = cursor.push(src.pollEvents(maxBatch));
+        } catch {
+            // 原生库已被卸载、窗口正在销毁：这一拍跳过，下一拍再说。
+            // 定时器回调里抛出的异常会直接终止进程，而这里没有任何值得终止的事。
+            return;
+        }
+
+        if (batch.gaps.length > 0) {
+            for (const missing of batch.gaps) {
+                for (const fn of gapListeners) fn(missing);
+            }
+        }
+
+        for (const e of batch.events) {
+            for (const fn of listeners) fn(e);
+            if (e.type === EVENT_CLOSED) {
+                stop();
+                return;
+            }
+        }
+    };
+
+    const timer = setInterval(tick, intervalMs);
+    if (!keepAlive) unrefTimer(timer);
+
+    return {
+        on(fn) {
+            listeners.add(fn);
+            return () => {
+                listeners.delete(fn);
+            };
+        },
+        onGap(fn) {
+            gapListeners.add(fn);
+            return () => {
+                gapListeners.delete(fn);
+            };
+        },
+        stop,
+        get running() {
+            return !stopped;
+        },
+        get seq() {
+            return cursor.seq;
+        },
+    };
+}
+
+/**
+ * 让定时器不阻止进程退出。
+ *
+ * Bun 与 Node 的定时器对象都有 `unref()`，但类型库里 `setInterval` 的返回值在
+ * DOM 与运行时两种声明下不同，所以按结构判断而不是按类型断言。
+ */
+export function unrefTimer(timer: unknown): void {
+    if (typeof timer === "object" && timer !== null && "unref" in timer) {
+        (timer as { unref(): void }).unref();
+    }
+}

package/src/shell/index.ts

@@ -24,6 +24,7 @@ import { cstr, openNativeLib, readBuffer } from "./native";
 import { ptr } from "bun:ffi";
 import type { NativeSymbols } from "./native";
 import { resolveNativeLib } from "./resolve";
+import { EVENT_QUEUE_CAPACITY, EVENT_RECORD_BYTES, decodeEvents, type WindowEvent } from "./events";
 import {
   STATE_FOCUSED,
   STATE_MAXIMIZED,
@@ -41,6 +42,11 @@ export { serveOnSafePort, isRestrictedPort } from "./port";
 export type { ServeOptions } from "./port";
 export { cstr, readCStr } from "./native";
 export type { NativeSymbols, NativeLib } from "./native";
+export type {
+  ClosedEvent,
+  StateEvent,
+  WindowEvent,
+} from "./events";
 
 export type Shell = {
   /** 创建窗口并加载 URL。返回码 0 表示成功；失败原因见 lastError() */
@@ -85,8 +91,31 @@ export type Shell = {
    * `state()` 无法区分「未启动」与「已销毁」（两者都返回全 false），
    * 宿主需要这个信号才能判断窗口是否已被用户关掉，进而回收自己的进程——
    * 窗口销毁后原生 UI 线程会返回，但宿主进程与它起的本地服务不会自己退出。
+   *
+   * 想要「等窗口关闭」而不是「每一拍问一次」时，用 `pollEvents()` 的
+   * `EVENT_CLOSED`（或 `bun-app-window/events` 的 `attachEventPump()`）。
+   * 两者不等价：`isAlive()` 读的是此刻的 `g_webview` 是否为空，而 `CLOSED`
+   * 是原生侧在 teardown 全部做完之后写进队列的显式终态。
    */
   isAlive(): boolean;
+  /**
+   * 批量拉取窗口生命周期事件（`EVENT_STATE` / `EVENT_CLOSED`）。
+   *
+   * **消费式**：读走的记录不会再来。所以一个进程只应有一个消费者——
+   * 要么用 `bun-app-window/events` 的 `attachEventPump()`，要么自己按节奏调
+   * 这个方法，别两者都来：两个消费者会各自拿到一部分，谁也看不全。
+   *
+   * 同步、零分配以外的副作用；`max` 是记录条数，内部夹在
+   * `1..EVENT_QUEUE_CAPACITY`。窗口未启动时返回空数组。
+   *
+   * ```ts
+   * for (const e of shell.pollEvents()) {
+   *   if (e.type === EVENT_CLOSED) break;
+   *   if (e.maximized) { ... }
+   * }
+   * ```
+   */
+  pollEvents(max?: number): WindowEvent[];
   /** 最近一次失败的原因；无错误时为空串。走拷贝式读出，不受并发写影响 */
   lastError(): string;
 
@@ -242,6 +271,14 @@ export async function createShell(opts: ShellOptions): Promise<Shell> {
 
     isAlive: () => symbols.shell_is_alive() !== 0,
 
+    pollEvents(max = 64): WindowEvent[] {
+      // 原生侧环容量是 128，一次要更多没有意义；下限 1 免得 0 变成「永远拉不到」
+      const cap = Math.max(1, Math.min(Math.trunc(max), EVENT_QUEUE_CAPACITY));
+      const buf = new Uint8Array(cap * EVENT_RECORD_BYTES);
+      const n = symbols.shell_poll_events(ptr(buf), cap);
+      return n > 0 ? decodeEvents(buf, n) : [];
+    },
+
     lastError,
 
     setBrowserUi: (mask) => symbols.shell_set_browser_ui(mask),

package/src/shell/native.ts

@@ -10,8 +10,8 @@ import type { Pointer } from "bun:ffi";
 /**
  * 打开 libshell.dll。
  *
- * 导出面说明：DLL 实际导出 33 个符号，其中 `shell_start` 是 1.x 遗留入口，
- * TS 侧不声明、也不对外承诺（故下方声明 32 个）；`shell_debug_*` / `shell_self_*` 属排障面。
+ * 导出面说明：DLL 实际导出 34 个符号，其中 `shell_start` 是 1.x 遗留入口，
+ * TS 侧不声明、也不对外承诺（故下方声明 33 个）；`shell_debug_*` / `shell_self_*` 属排障面。
  */
 export function openNativeLib(path: string) {
   return dlopen(path, {
@@ -29,6 +29,8 @@ export function openNativeLib(path: string) {
     shell_set_min_size: { args: [FFIType.i32, FFIType.i32], returns: FFIType.void },
     shell_get_state: { args: [], returns: FFIType.i32 },
     shell_is_alive: { args: [], returns: FFIType.i32 },
+    // 窗口生命周期事件：批量拉取（消费式），capacity 是记录条数
+    shell_poll_events: { args: [FFIType.ptr, FFIType.i32], returns: FFIType.i32 },
     shell_stop: { args: [], returns: FFIType.void },
     shell_error: { args: [], returns: FFIType.ptr },
     // 系统集成面

package/src/shell/state.ts

@@ -1,6 +1,7 @@
 import { mkdirSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 
+import { EVENT_STATE, attachEventPump, type EventPump, unrefTimer } from "./events";
 import type { Shell } from "./index";
 
 /**
@@ -14,6 +15,21 @@ import type { Shell } from "./index";
  *   - DPI 变化：存的是物理像素 + 当时的 DPI，恢复时按比例换算
  *   - 显示器不在了：矩形要与某块工作区有足够交叠才算可用，否则居中
  *   - 最大化状态：存「还原后」的矩形，而不是整屏尺寸
+ *
+ * ## 为什么现在是事件驱动，不是轮询
+ *
+ * 这个模块曾经每 700 ms 调一次 `getBounds()`。理由是「原生侧的窗口状态推送是发给
+ * **页面**的（shell-msg），宿主拿不到」。0.4.0 起那个理由不成立了：`shell_poll_events`
+ * 给了宿主一条自己的通道。
+ *
+ * 换成事件驱动之后，两件事同时变好：
+ *   - 窗口静止时**一次 FFI 都不发生**（轮询时代是每秒 1.4 次）
+ *   - 拖动期间不再每帧写盘。事件到一条就即时 `getBounds()` 存快照（微秒级），
+ *     但**写盘**攒到停手后 `debounceMs` 才做一次
+ *
+ * 快照与写盘分离是有意的：窗口关闭后原生侧 `getBounds()` 立刻返回空串
+ * （`format_bounds` 里 `!g_hwnd` 直接返回 0），若等到防抖到点才去读，最后那次
+ * 位置变化就永久丢了——用户「拖完立刻点 X」是最常见的关闭方式。
  */
 
 export type WindowPlacement = {
@@ -28,8 +44,10 @@ export type WindowPlacement = {
 };
 
 const DEFAULTS = {
-    /** 轮询间隔。GetWindowRect 是微秒级，700 ms 足够了 */
-    intervalMs: 700,
+    /** 收到变化事件后攒多久再写盘。拖动期间事件每帧一条，攒到停手写一次 */
+    debounceMs: 300,
+    /** 自建事件泵（未由调用方提供）时的拉取节奏 */
+    pumpMs: 16,
 } as const;
 
 /** 把原生返回的一行文本解析成 WindowPlacement；格式不对返回 null。 */
@@ -131,31 +149,60 @@ export async function savePlacement(file: string, p: WindowPlacement): Promise<v
 export type PlacementStore = {
     /** 立即抓一次并写盘（关闭前调用） */
     flush(): Promise<void>;
-    /** 停止轮询。不清盘——最后写入的值保留 */
+    /** 停止拉取事件与防抖定时器。不清盘——最后写入的值保留 */
     dispose(): void;
-    /** 当前已知的 placement（最近一次成功写入的） */
+    /** 当前已知的 placement（最近一次快照） */
     readonly current: WindowPlacement | null;
 };
 
+export type PlacementStoreOptions = {
+    /**
+     * 变化后攒多久再写盘。默认 300 ms。
+     *
+     * 设成 0 表示「每条事件都立刻写」——只适合测试，真实应用会给磁盘造成
+     * 每秒几十次的写入。
+     */
+    debounceMs?: number;
+    /**
+     * 复用宿主已有的事件泵。
+     *
+     * **`shell.pollEvents()` 是消费式的**：一个窗口只该有一个消费者。用
+     * `./app` 的骨架时传 `{ events: app.events }`，别再让它自己起一个——
+     * 两个泵会各自拿到一部分事件，位置持久化会随机漏掉一些变化。
+     *
+     * 不给时本模块自建一个（内部泵定时器 unref，不阻止进程退出）。
+     */
+    events?: EventPump;
+    /** 自建事件泵时的拉取节奏，默认 16 ms。给了 `events` 时忽略 */
+    pumpMs?: number;
+};
+
 /**
- * 轮询窗口矩形并在变化时写盘。
+ * 订阅窗口状态变化并在停手后写盘。
  *
- * 为什么轮询而不是事件：原生侧的窗口状态推送是发给**页面**的（shell-msg），宿主
- * 拿不到；加一条原生→宿主的回调通道要多一套生命周期管理，而 GetWindowRect 是
- * 微秒级调用，700 ms 一次的代价可以忽略。
+ * 变化检测按内容比较：窗口静止时不产生任何磁盘写入，也不产生任何调度。
  *
- * 变化检测按内容比较：窗口静止时不产生任何磁盘写入。
+ * 首次 `attach` 会立刻抓一次快照并写盘——程序若在用户操作前崩溃，也还有
+ * 初始位置可恢复。
  */
 export function attachPlacementStore(
     shell: Shell,
     file: string,
-    opts: { intervalMs?: number } = {},
+    opts: PlacementStoreOptions = {},
 ): PlacementStore {
-    const intervalMs = opts.intervalMs ?? DEFAULTS.intervalMs;
+    const debounceMs = Math.max(0, opts.debounceMs ?? DEFAULTS.debounceMs);
+    const pump =
+        opts.events ??
+        attachEventPump(shell, { intervalMs: Math.max(1, opts.pumpMs ?? DEFAULTS.pumpMs) });
+    const ownsPump = opts.events === undefined;
+
     let last: WindowPlacement | null = null;
     let lastKey = "";
     let disposed = false;
     let pending: Promise<void> = Promise.resolve();
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    /** 已取到快照、但还没写盘的值 */
+    let dirty: WindowPlacement | null = null;
 
     const same = (a: WindowPlacement, b: WindowPlacement): boolean =>
         a.x === b.x &&
@@ -165,15 +212,20 @@ export function attachPlacementStore(
         a.maximized === b.maximized &&
         a.dpi === b.dpi;
 
-    const tick = (): void => {
+    /**
+     * 抓一次快照，变了就记进 `dirty`。
+     *
+     * 与写盘分开：这一步是微秒级的 FFI 读，必须在窗口还活着的时候做。写盘可以晚。
+     */
+    const snapshot = (): void => {
         if (disposed) {
             return;
         }
         const now = capturePlacement(shell);
+        // 窗口销毁过程中会短暂读到 0 尺寸，parseBounds 已过滤
         if (!now) {
             return;
         }
-        // 窗口销毁过程中会短暂读到 0 尺寸，上面已过滤
         if (last && same(now, last)) {
             return;
         }
@@ -183,26 +235,68 @@ export function attachPlacementStore(
         }
         last = now;
         lastKey = key;
+        dirty = now;
+    };
+
+    const write = (): void => {
+        const now = dirty;
+        dirty = null;
+        if (!now) {
+            return;
+        }
         // 串行化写入：并发 rename 同一目标会互相踩
         pending = pending.then(() => savePlacement(file, now)).catch(() => {
-            // 写盘失败不该打断应用；下一次 tick 会重试
+            // 写盘失败不该打断应用；下一次变化会重试
         });
     };
 
-    const timer = setInterval(tick, intervalMs);
-    // 不阻止进程退出：应用退出时不该因为一个定时器挂住
-    if (typeof timer === "object" && timer !== null && "unref" in timer) {
-        (timer as { unref(): void }).unref();
-    }
+    const scheduleWrite = (): void => {
+        if (disposed) {
+            return;
+        }
+        if (timer !== null) {
+            clearTimeout(timer);
+        }
+        timer = setTimeout(() => {
+            timer = null;
+            write();
+        }, debounceMs);
+        unrefTimer(timer);
+    };
+
+    const off = pump.on((e) => {
+        if (e.type !== EVENT_STATE) {
+            return;
+        }
+        // 立刻取快照（窗口还活着），但写盘交给防抖
+        snapshot();
+        scheduleWrite();
+    });
+
+    // 首次快照：不等到第一条事件就有初始值可恢复
+    snapshot();
+    write();
 
     return {
         async flush(): Promise<void> {
-            tick();
+            if (timer !== null) {
+                clearTimeout(timer);
+                timer = null;
+            }
+            snapshot();
+            write();
             await pending;
         },
         dispose(): void {
             disposed = true;
-            clearInterval(timer);
+            off();
+            if (timer !== null) {
+                clearTimeout(timer);
+                timer = null;
+            }
+            if (ownsPump) {
+                pump.stop();
+            }
         },
         get current(): WindowPlacement | null {
             return last;

package/src/shell/types.ts

@@ -42,6 +42,24 @@ export const FLAG_ACCEPT_DROP = 32;
  * 与 `FLAG_CENTER` 同时给时以本项为准（最大化会覆盖位置）。
  */
 export const FLAG_START_MAXIMIZED = 64;
+/**
+ * 允许页面把顶层框架导航到任意 http/https 地址，即**放弃外部导航拦截**。
+ *
+ * 默认（不给本位）时，壳会拦下跨源导航并改交系统默认浏览器：桌面应用没有地址栏、
+ * 没有后退按钮，也没有宿主 API 能把页面拉回来，一次误点外链就等于应用被换成了那个
+ * 网站。这是默认值应该选安全一侧的典型场景。
+ *
+ * 什么时候需要本位：应用本身就是浏览器（多标签、内置地址栏、能自己导航回来）。
+ *
+ * 边界（两条，别指望它能关掉更多）：
+ *
+ * - **只影响顶层框架导航**。`window.open` / `target=_blank` 仍然被拦下并外开，
+ *   因为壳只支持一个顶层窗口（原生层是进程级单例），开出来的新窗口没有任何宿主
+ *   API 能管它。这是能力边界，不是安全策略。
+ * - **不放宽 scheme 白名单**。交给系统浏览器的只有 http/https；`file:`、
+ *   `javascript:`、`ms-*:` 以及自定义 scheme 一律静默取消，与本位无关。
+ */
+export const FLAG_ALLOW_EXTERNAL_NAV = 128;
 
 /**
  * 关闭 WebView2 的浏览器行为（`ShellOptions.browserUi` 使用）。