bun-app-window 0.3.0 → 0.4.1

package/src/shell/app.ts

@@ -0,0 +1,344 @@
+/**
+ * app.ts — 应用骨架：把「起服务 → 开窗 → 接线 → 等退出」收成一次调用
+ *
+ * ## 为什么需要它
+ *
+ * 用这个包做第一个应用时，真正要写的业务代码可能只有 30 行，但**宿主样板**是
+ * 另外 180 行：挑安全端口、生成鉴权 token、处理 WebSocket 升级、把 HTML 当字符串
+ * 吐出去、把 `createIpcServer` 接到 Bun 的 websocket 回调上、拿窗口 flags、
+ * 处理 `openShell` 失败、等窗口关闭（`EVENT_CLOSED`）、按顺序 `stop()` 两次。
+ *
+ * 每一段单看都不难，但它们**必须按特定顺序且互相依赖**——`stop()` 不先等窗口
+ * 销毁就去关服务，下次启动会撞上「进程级单例还在」；WS 升级不在 `fetch` 里做，
+ * 鉴权就没有落点。这些顺序关系在 `src/host.ts` 里被验证过一遍，但没有沉淀成
+ * 可复用的东西，所以每个消费者都要再踩一次。
+ *
+ * ## 两个设计选择
+ *
+ * **不导出到主入口。** 它和 `./state`、`./ipc`、`./titlebar` 一样是可选件，
+ * 走独立子路径 `bun-app-window/app`。好处不只是「按需引入」——`app.ts` 从
+ * `./index` 导入 `openShell`，如果 `index.ts` 反过来导出 `app`，就成了循环。
+ * 单向依赖比运行时安全的循环更值得要。
+ *
+ * **静态资源只吃内联字符串。** 用 `import html from "./index.html" with { type: "text" }`
+ * 得到的是编译期常量：不碰文件系统、不产生临时文件、`bun build --compile` 后仍然成立。
+ * 从目录读则要处理 `import.meta.dir` 在打包后指向 `B:\~BUN\root` 的问题
+ * （`src/host.ts` 里那段 `PACKED` 判断就是为它存在的）。那 5 行留给消费者自己写，
+ * 用 `routes` 就能接。
+ */
+
+import { createIpcServer, type IpcServer, type ServiceMethods } from "./ipc";
+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";
+
+/** 骨架起出来的东西。`shell` 是完整的内核对象，骨架只是帮它把周边接好 */
+export type App = {
+    /** 内核对象。标题、缩放、全屏、原生菜单、位置持久化都从这里拿 */
+    readonly shell: Shell;
+    /**
+     * 窗口生命周期事件流。骨架替你起的**唯一**一个消费者。
+     *
+     * `shell.pollEvents()` 是消费式的，一个窗口只能有一个消费者。要用
+     * `attachPlacementStore` 时传 `{ events: app.events }`，别再自己 attach
+     * 一个泵——两个泵会各自拿到一部分事件。
+     *
+     * 定时器是 keepAlive 的（不 unref）：`wait()` 靠它让进程活到窗口关闭。
+     */
+    readonly events: EventPump;
+    /** 本地服务实际绑定的端口（已避开浏览器受限端口表） */
+    readonly port: number;
+    /** 页面 URL：带鉴权 token 的查询参数，直接交给 `openShell` 用的就是它 */
+    readonly url: string;
+    /** 页面 URL 里的 token。页面侧 `connect()` 默认从这里取 */
+    readonly token: string;
+    /** 给了 `service` 才有；否则为 null */
+    readonly ipc: IpcServer | null;
+    /**
+     * 停止窗口与本地服务。
+     *
+     * 顺序是有意的：先 `shell.stop()`，再**等 `EVENT_CLOSED`**，最后才关服务。
+     * 原生层是进程级单例，`shell_stop()` 只是投了一个 `WM_QUIT`；抢在前面关服务
+     * 或重新 start，会撞上「shell already started」（详见 `pitfalls` 2.4g / 7.1）。
+     *
+     * 等的是事件不是 `isAlive()`：`CLOSED` 由原生侧在 teardown 全部做完、
+     * `g_webview` 已置空之后写进队列，它出现的时刻就等于「单例已释放」。
+     * 仍然保留超时上限——事件通道若因故失效，宿主不能被永久挂住。
+     *
+     * 幂等：重复调用立即返回。
+     */
+    stop(): Promise<void>;
+    /**
+     * 等窗口被关闭（用户点 X，或调用了 `stop()`）。
+     *
+     * 宿主进程不会因为窗口没了就自动退出——它自己起的本地服务还在跑。所以
+     * 「应用该结束了」的判据是收到 `EVENT_CLOSED`，不是任何信号。
+     *
+     * 这个 promise 靠 `events` 的 keepAlive 定时器撑住事件循环；别在等它的同时
+     * 把 `events.stop()` 掉，那样两边都收不到关闭信号。
+     */
+    wait(): Promise<void>;
+};
+
+export type AppOptions = {
+    /**
+     * 页面 HTML，用 `with { type: "text" }` 内联。
+     *
+     * ```ts
+     * import html from "./index.html" with { type: "text" };
+     * ```
+     */
+    html: string;
+    title?: string;
+    width?: number;
+    height?: number;
+    /**
+     * 窗口 flags。缺省 `FLAG_RESIZABLE | FLAG_CENTER`（带边框）。
+     *
+     * 想要自绘标题栏时显式加 `FLAG_FRAMELESS`——骨架不默认它，因为无边框窗口
+     * 没有系统标题栏就**拖不动**，而那需要页面先挂上 `mountTitleBar`。
+     * 默认值选「即使页面什么都不做也能用」的那一侧。
+     */
+    flags?: number;
+    minWidth?: number;
+    minHeight?: number;
+    /** 关掉哪些浏览器行为，取 `BROWSER_UI_*` 的按位或 */
+    browserUi?: number;
+    appName?: string;
+    nativeLibPath?: string;
+    embedded?: () => Promise<Uint8Array | null>;
+    /**
+     * IPC 服务方法表。给了就自动挂 `/ws`（含 token 校验）。
+     *
+     * 页面侧：
+     *
+     * ```ts
+     * import { connect } from "bun-app-window/ipc";
+     * const api = await connect();   // 自动从 ?t= 取 token
+     * ```
+     */
+    service?: ServiceMethods;
+    /** IPC 错误里是否回传 stack。默认关闭 */
+    exposeStack?: boolean;
+    /**
+     * 额外路由。返回 `undefined` 表示「不归我管」，交回骨架的默认处理
+     * （`/` 吐 HTML、`/ws` 处理升级、其余 404）。
+     *
+     * 从磁盘读静态资源、代理上游 API 这类事情写在这里。
+     */
+    routes?: (req: Request) => Response | undefined | Promise<Response | undefined>;
+    /** 窗口建好、服务就绪后调用一次 */
+    onReady?: (app: App) => void;
+};
+
+/** 事件拉取节奏，约一帧 */
+const EVENT_POLL_MS = 16;
+/**
+ * 等 `EVENT_CLOSED` 的上限。
+ *
+ * 实测关闭约 50 ms，5 s 是三个数量级的余量。存在的理由不是「怕关得慢」，
+ * 而是「事件通道若因故失效，宿主不能被永久挂住」——超时后照旧关服务。
+ */
+const CLOSE_TIMEOUT_MS = 5000;
+
+/** 一个只能 resolve 一次的 promise。等窗口关闭用它，比轮询一个布尔值清楚 */
+function defer(): { promise: Promise<void>; resolve: () => void } {
+    let resolve: () => void = () => {};
+    const promise = new Promise<void>((r) => {
+        resolve = r;
+    });
+    return { promise, resolve };
+}
+
+/**
+ * 不给 `flags` 时用的默认值：**带边框** + 可缩放 + 居中。
+ *
+ * 刻意不默认 `FLAG_FRAMELESS`。无边框窗口没有系统标题栏就拖不动，必须由页面先挂上
+ * `mountTitleBar` 才能用；把它设成默认值会让「只写了 HTML」的应用一上来就无法拖动。
+ * 默认值应当选「页面什么都不做也能用」的那一侧。
+ */
+export const DEFAULT_APP_FLAGS = FLAG_RESIZABLE | FLAG_CENTER;
+
+/** 页面 URL。token 放查询参数里，页面侧 `connect()` 默认从这里取 */
+export function buildAppUrl(port: number, token: string): string {
+    return `http://127.0.0.1:${port}/?t=${token}`;
+}
+
+/**
+ * `/ws` 请求的处置结论。
+ *
+ * 抽成纯函数是因为这是整个骨架里**唯一有分支的判据**，而它有三个容易写反的点：
+ * 路径要先比、`ipc` 没开时不能当 403（那是 404）、token 不匹配必须在**升级之前**
+ * 拒绝——升级之后就没有机会说不了。
+ *
+ * token 用普通 `!==` 比较而不是恒定时间比较：它是一次性的本地回环随机值，
+ * 不是长期凭据，时序侧信道在这里没有可换取的东西。
+ */
+export type WsDecision = "not-ws" | "ipc-disabled" | "forbidden" | "upgrade";
+
+export function decideWs(
+    pathname: string,
+    presented: string | null,
+    expected: string,
+    ipcEnabled: boolean,
+): WsDecision {
+    if (pathname !== "/ws") {
+        return "not-ws";
+    }
+    if (!ipcEnabled) {
+        return "ipc-disabled";
+    }
+    return presented === expected ? "upgrade" : "forbidden";
+}
+
+/**
+ * 起服务、开窗、接线，返回一个可以 `wait()` 的 App。
+ *
+ * 失败时抛错，且**不留下半启动状态**——本地服务会被关掉。理由是调用方拿到异常后
+ * 唯一合理的动作是退出，而一个已经绑好的端口会让「重试一次」也失败。
+ */
+export async function createApp(opts: AppOptions): Promise<App> {
+    if (!opts.html || typeof opts.html !== "string") {
+        throw new Error("createApp: html is required (import it with { type: \"text\" })");
+    }
+
+    const token = crypto.randomUUID();
+    const ipc = opts.service
+        ? createIpcServer({
+              service: opts.service,
+              ...(opts.exposeStack === undefined ? {} : { exposeStack: opts.exposeStack }),
+          })
+        : null;
+
+    const server = serveOnSafePort({
+        fetch(req, srv) {
+            return handle(req, srv);
+        },
+        websocket: {
+            open(ws: unknown) {
+                ipc?.attach(ws as { send(d: string): void });
+            },
+            message(ws: unknown, raw: string | Buffer) {
+                void ipc?.handle(ws as { send(d: string): void }, raw);
+            },
+            close(ws: unknown) {
+                ipc?.detach(ws as { send(d: string): void });
+            },
+        } as never,
+    });
+
+    async function handle(req: Request, srv: unknown): Promise<Response | undefined> {
+        const url = new URL(req.url);
+
+        // IPC 通道。校验必须在这里做——升级之后就没有机会拒绝了
+        switch (decideWs(url.pathname, url.searchParams.get("t"), token, ipc !== null)) {
+            case "ipc-disabled":
+                return new Response("ipc not enabled", { status: 404 });
+            case "forbidden":
+                return new Response(null, { status: 403 });
+            case "upgrade": {
+                const upgrade = (srv as { upgrade(r: Request, o: unknown): boolean }).upgrade;
+                if (upgrade.call(srv, req, { data: {} })) {
+                    return undefined; // 已升级，不要再返回 Response
+                }
+                return new Response(null, { status: 400 });
+            }
+            default:
+                break;
+        }
+
+        // 调用方的路由优先，能覆盖 `/`（自绘入口页、SPA fallback 都靠这条）
+        const custom = await opts.routes?.(req);
+        if (custom) {
+            return custom;
+        }
+
+        if (url.pathname === "/") {
+            return new Response(opts.html, {
+                headers: { "content-type": "text/html; charset=utf-8" },
+            });
+        }
+
+        return new Response("not found", { status: 404 });
+    }
+
+    // `Bun.serve` 的 `port` 类型是 `number | undefined`。`serveOnSafePort` 已经
+    // 确认绑定成功，但这里不能顺手断言：一旦为 undefined，拼出来的 URL 会是
+    // `http://127.0.0.1:undefined/?t=...`，而 `openShell` 会把它当合法 URL 交给
+    // WebView2，表现为一个空白窗口——比抛错难查得多。
+    const port = server.port;
+    if (port === undefined) {
+        server.stop(true);
+        throw new Error("createApp: local server did not report a bound port");
+    }
+    const url = buildAppUrl(port, token);
+
+    const shellOpts: ShellOptions = {
+        url,
+        title: opts.title ?? "bun-app-window",
+        width: opts.width ?? 1000,
+        height: opts.height ?? 680,
+        flags: opts.flags ?? DEFAULT_APP_FLAGS,
+        ...(opts.minWidth === undefined ? {} : { minWidth: opts.minWidth }),
+        ...(opts.minHeight === undefined ? {} : { minHeight: opts.minHeight }),
+        ...(opts.browserUi === undefined ? {} : { browserUi: opts.browserUi }),
+        ...(opts.appName === undefined ? {} : { appName: opts.appName }),
+        ...(opts.nativeLibPath === undefined ? {} : { nativeLibPath: opts.nativeLibPath }),
+        ...(opts.embedded === undefined ? {} : { embedded: opts.embedded }),
+    };
+
+    let shell: Shell;
+    try {
+        shell = await openShell(shellOpts);
+    } catch (err) {
+        // 不留半启动状态：窗口没起来，端口也不该继续占着
+        server.stop(true);
+        throw err;
+    }
+
+    let stopped = false;
+
+    // 窗口事件的唯一消费者。`keepAlive: true` 是 `wait()` 成立的前提：
+    // unref 的定时器不撑事件循环，而「等一个永不兑现的 promise」也撑不住——
+    // 宿主会在窗口还开着的时候直接退出。
+    const events = attachEventPump(shell, { intervalMs: EVENT_POLL_MS, keepAlive: true });
+    const closed = defer();
+    events.on((e) => {
+        if (e.type === EVENT_CLOSED) {
+            closed.resolve();
+        }
+    });
+
+    const app: App = {
+        shell,
+        events,
+        port,
+        url,
+        token,
+        ipc,
+        async stop(): Promise<void> {
+            if (stopped) {
+                return;
+            }
+            stopped = true;
+            shell.stop();
+            // 等 `EVENT_CLOSED` 而不是轮询 `isAlive()`：CLOSED 由原生侧在 teardown
+            // 全部做完、g_webview 已置空之后写进队列，它出现的时刻就等于「单例已释放」。
+            // 超时上限保留，且超时后也 resolve 一次——否则 `wait()` 会永远挂着。
+            await Promise.race([closed.promise, Bun.sleep(CLOSE_TIMEOUT_MS)]);
+            closed.resolve();
+            events.stop();
+            server.stop(true);
+        },
+        async wait(): Promise<void> {
+            if (stopped) {
+                return;
+            }
+            await closed.promise;
+        },
+    };
+
+    opts.onReady?.(app);
+    return app;
+}

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();
+    }
+}