bun-app-window 0.0.0-stage → 0.2.0

package/src/shell/ipc.ts

@@ -0,0 +1,569 @@
+/**
+ * ipc.ts — 宿主与页面之间的类型化调用与事件通道
+ *
+ * 三条设计决定：
+ *
+ *   1. **不生成代码。** MyGo 用 Go 写宿主，生成 TypeScript 客户端，是因为
+ *      Go 类型与 TS 类型是两套系统，必须造一座桥。这里宿主与前端**都是
+ *      TypeScript**，共享一份 `type` 声明就够了——生成器只会多出一个
+ *      「生成物与源不一致」的故障源，不带来任何类型信息。
+ *      类型安全由泛型 `connect<Api>()` 在编译期保证，和生成代码等价。
+ *
+ *   2. **传输无关。** 服务端只认「能 send 的对端」，客户端只认 `Channel`。
+ *      两侧核心逻辑都不碰 WebSocket，因此可以在无窗口环境下完整测试。
+ *
+ *   3. **不反射校验签名。** 运行时只按方法名分发，参数原样透传。
+ *      `bun:ffi` 那条教训同样适用：声明对不对只能靠调用验证，
+ *      假装能校验反而会给出错误的信心。
+ */
+
+/** 失败时回给调用方的错误形状。`stack` 仅在 `exposeStack` 开启时出现 */
+export type IpcErrorPayload = {
+    message: string;
+    name?: string;
+    stack?: string;
+};
+
+export type IpcRequestMessage = {
+    t: "ipc:req";
+    id: number;
+    /** 方法名 */
+    m: string;
+    /** 参数数组。原样透传，不做序列化以外的处理 */
+    a: unknown[];
+};
+
+export type IpcReplyMessage =
+    | { t: "ipc:res"; id: number; ok: true; r: unknown }
+    | { t: "ipc:res"; id: number; ok: false; e: IpcErrorPayload };
+
+export type IpcEventMessage = {
+    t: "ipc:evt";
+    /** 事件名 */
+    e: string;
+    /** 载荷。缺省为 null，保证字段始终存在 */
+    p: unknown;
+};
+
+export type IpcMessage = IpcRequestMessage | IpcReplyMessage | IpcEventMessage;
+
+/**
+ * 服务方法的宽松约束。
+ *
+ * 用 `never[]` 而非 `any[]`：任何具体函数 `(name: string) => string` 都能赋给
+ * `(...args: never[]) => unknown`（参数逆变，`never` 可赋给 `string`），
+ * 但反过来调用时需要断言——这正是我们想要的：定义宽松，调用收窄由泛型负责。
+ */
+export type ServiceMethods = Record<string, (...args: never[]) => unknown>;
+
+/** 服务端对「一个连接」的最小要求。Bun 的 `ServerWebSocket` 天然满足 */
+export type IpcPeer = {
+    send(data: string): void;
+};
+
+export type IpcServerOptions = {
+    service: ServiceMethods;
+    /** 错误里是否回传 stack。开发期有用，生产应保持关闭 */
+    exposeStack?: boolean;
+};
+
+export type IpcServer = {
+    /** 处理一条来自连接的原始消息。非 IPC 消息会被静默忽略 */
+    handle(peer: IpcPeer, raw: string | Buffer | Uint8Array): Promise<void>;
+    /** 登记连接，`emit` 才会送到它 */
+    attach(peer: IpcPeer): void;
+    /** 注销连接。close 时必须调，否则 emit 会向死连接写入 */
+    detach(peer: IpcPeer): void;
+    /** 广播事件给所有已登记连接。返回实际投递数 */
+    emit(event: string, payload?: unknown): number;
+    /** 服务暴露的方法名（创建时的快照）。用于自检与文档 */
+    readonly methods: readonly string[];
+    /** 当前登记连接数 */
+    readonly peers: number;
+};
+
+function isRequest(v: unknown): v is IpcRequestMessage {
+    if (!v || typeof v !== "object") {
+        return false;
+    }
+    const o = v as Record<string, unknown>;
+    return (
+        o.t === "ipc:req" &&
+        typeof o.id === "number" &&
+        typeof o.m === "string" &&
+        Array.isArray(o.a)
+    );
+}
+
+/**
+ * 建立 IPC 服务端。
+ *
+ * ```ts
+ * const ipc = createIpcServer({
+ *     service: {
+ *         greet: (name: string) => `Hello ${name}`,
+ *         pickFolder: () => shell.pickFolder(),
+ *     },
+ * });
+ *
+ * Bun.serve({
+ *     websocket: {
+ *         open: (ws) => ipc.attach(ws),
+ *         message: (ws, raw) => ipc.handle(ws, raw),
+ *         close: (ws) => ipc.detach(ws),
+ *     },
+ *     // ...
+ * });
+ * ```
+ */
+export function createIpcServer(opts: IpcServerOptions): IpcServer {
+    const service = opts.service;
+    const exposeStack = opts.exposeStack === true;
+    const connected = new Set<IpcPeer>();
+    // 创建时快照：之后往 service 上挂东西不会改变对外声明
+    const methods = Object.keys(service);
+
+    const send = (peer: IpcPeer, msg: IpcMessage): void => {
+        try {
+            peer.send(JSON.stringify(msg));
+        } catch {
+            // 对端已断开。它会在 close 回调里被 detach，这里不必额外处理
+        }
+    };
+
+    const toPayload = (err: unknown): IpcErrorPayload => {
+        const e = err instanceof Error ? err : new Error(String(err));
+        const payload: IpcErrorPayload = { message: e.message };
+        if (e.name && e.name !== "Error") {
+            payload.name = e.name;
+        }
+        if (exposeStack && e.stack) {
+            payload.stack = e.stack;
+        }
+        return payload;
+    };
+
+    return {
+        async handle(peer, raw): Promise<void> {
+            const text = typeof raw === "string" ? raw : new TextDecoder().decode(raw);
+
+            let parsed: unknown;
+            try {
+                parsed = JSON.parse(text);
+            } catch {
+                // 不是 JSON：这条通道只吃 JSON，别的消息归应用自己处理
+                return;
+            }
+
+            if (!isRequest(parsed)) {
+                return;
+            }
+
+            // hasOwnProperty 而非 `service[m]` 直接取：否则 "constructor" /
+            // "__proto__" / "toString" 这类名字会命中原型链上的函数，
+            // 等于把一个未知形状的东西当服务方法调用。
+            const fn = Object.prototype.hasOwnProperty.call(service, parsed.m)
+                ? service[parsed.m]
+                : undefined;
+
+            if (!fn) {
+                send(peer, {
+                    t: "ipc:res",
+                    id: parsed.id,
+                    ok: false,
+                    e: { message: `unknown method: ${parsed.m}` },
+                });
+                return;
+            }
+
+            try {
+                const result = await fn(...(parsed.a as never[]));
+                // JSON 里 undefined 会被省略成一个缺 r 字段的回复，显式归一成 null
+                send(peer, { t: "ipc:res", id: parsed.id, ok: true, r: result ?? null });
+            } catch (err) {
+                send(peer, { t: "ipc:res", id: parsed.id, ok: false, e: toPayload(err) });
+            }
+        },
+
+        attach(peer): void {
+            connected.add(peer);
+        },
+
+        detach(peer): void {
+            connected.delete(peer);
+        },
+
+        emit(event, payload): number {
+            const msg: IpcEventMessage = { t: "ipc:evt", e: event, p: payload ?? null };
+            const body = JSON.stringify(msg);
+            let delivered = 0;
+            for (const peer of connected) {
+                try {
+                    peer.send(body);
+                    delivered++;
+                } catch {
+                    // 死连接不计入
+                }
+            }
+            return delivered;
+        },
+
+        get methods(): readonly string[] {
+            return methods;
+        },
+
+        get peers(): number {
+            return connected.size;
+        },
+    };
+}
+
+/**
+ * 客户端的最小传输面。
+ *
+ * 只有四个动作——发一条、关掉、收消息、收关闭。测试里换成一个内存实现就能
+ * 完整覆盖客户端的 id 分配、pending 表、超时与错误传播，不需要起真服务。
+ */
+export type Channel = {
+    send(data: string): void;
+    close(): void;
+    /** 注册消息回调。只调一次；重复调用以最后一次为准 */
+    onMessage(fn: (data: string) => void): void;
+    /** 通道关闭（对端断开或本地 close）时触发 */
+    onClose(fn: () => void): void;
+};
+
+/** 把方法表映射成「返回 Promise 的同名方法」 */
+export type ClientMethods<T> = {
+    [K in keyof T]: T[K] extends (...args: infer A) => infer R
+        ? (...args: A) => Promise<Awaited<R>>
+        : never;
+};
+
+export type IpcClient<T, E extends Record<string, unknown> = Record<string, never>> =
+    ClientMethods<T> & {
+        /** 订阅宿主推送的事件。返回取消订阅函数 */
+        on<K extends keyof E & string>(event: K, handler: (payload: E[K]) => void): () => void;
+        /** 取消订阅 */
+        off(event: string, handler: (payload: unknown) => void): void;
+        /** 关闭通道。未完成的调用会被 reject */
+        close(): void;
+        /** 通道当前是否可用 */
+        readonly connected: boolean;
+        /** 尚未收到回复的调用数 */
+        readonly pending: number;
+    };
+
+export type ConnectOptions = {
+    /** 已建立的通道。给了就不再自己连 */
+    channel?: Channel;
+    /** 未给 channel 时的连接地址 */
+    url?: string;
+    /**
+     * 鉴权 token。缺省从页面 URL 的 `?t=` 读取——
+     * 与 `src/host.ts` 里本地服务的约定一致。
+     */
+    token?: string;
+    /** 单次调用超时，毫秒。0 表示不超时。默认 30000 */
+    timeoutMs?: number;
+};
+
+type NativeSocket = {
+    send(data: string): void;
+    close(): void;
+    readonly readyState: number;
+    addEventListener(type: string, listener: (event: unknown) => void): void;
+};
+
+/**
+ * 把一条 WebSocket 包成 `Channel`。
+ *
+ * open 之前到达的消息会先缓冲，`onMessage` 注册时补发——否则
+ * `await webSocketChannel()` 与 `client.onMessage()` 之间那条消息会丢。
+ */
+export function webSocketChannel(url: string): Promise<Channel> {
+    const Ctor = (globalThis as { WebSocket?: new (u: string) => NativeSocket }).WebSocket;
+    if (!Ctor) {
+        throw new Error("webSocketChannel: this runtime has no global WebSocket");
+    }
+
+    const socket = new Ctor(url);
+    const buffer: string[] = [];
+    let sink: ((data: string) => void) | null = null;
+    let onClosed: (() => void) | null = null;
+
+    socket.addEventListener("message", (ev) => {
+        const data = (ev as { data?: unknown }).data;
+        if (typeof data !== "string") {
+            return;
+        }
+        if (sink) {
+            sink(data);
+        } else {
+            buffer.push(data);
+        }
+    });
+
+    socket.addEventListener("close", () => {
+        if (onClosed) {
+            onClosed();
+        }
+    });
+
+    return new Promise<Channel>((resolve, reject) => {
+        let settled = false;
+
+        socket.addEventListener("error", () => {
+            if (!settled) {
+                settled = true;
+                reject(new Error(`webSocketChannel: connection failed (${url})`));
+            }
+        });
+
+        socket.addEventListener("open", () => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            resolve({
+                send: (data) => socket.send(data),
+                close: () => socket.close(),
+                onMessage: (fn) => {
+                    sink = fn;
+                    for (const pending of buffer.splice(0)) {
+                        fn(pending);
+                    }
+                },
+                onClose: (fn) => {
+                    onClosed = fn;
+                },
+            });
+        });
+    });
+}
+
+function toError(payload: unknown): Error {
+    if (payload && typeof payload === "object") {
+        const o = payload as Record<string, unknown>;
+        const message = typeof o.message === "string" ? o.message : "ipc call failed";
+        const err = new Error(message);
+        if (typeof o.name === "string" && o.name) {
+            err.name = o.name;
+        }
+        if (typeof o.stack === "string" && o.stack) {
+            err.stack = o.stack;
+        }
+        return err;
+    }
+    return new Error("ipc call failed");
+}
+
+type Pending = {
+    resolve(value: unknown): void;
+    reject(err: Error): void;
+    timer: ReturnType<typeof setTimeout> | null;
+};
+
+/**
+ * 连接宿主侧的 IPC 服务。
+ *
+ * ```ts
+ * // api.ts —— 宿主与页面共享这一份声明，不需要任何生成步骤
+ * export type Api = {
+ *     greet(name: string): string;
+ *     pickFolder(title?: string): Promise<string | null>;
+ * };
+ * export type Events = {
+ *     windowState: { width: number; height: number; maximized: boolean };
+ * };
+ *
+ * // 页面
+ * const api = await connect<Api, Events>();
+ * const hello = await api.greet("Ada");   // string
+ * api.on("windowState", (s) => console.log(s.maximized));
+ * ```
+ */
+export async function connect<T, E extends Record<string, unknown> = Record<string, never>>(
+    opts: ConnectOptions = {},
+): Promise<IpcClient<T, E>> {
+    const timeoutMs = opts.timeoutMs ?? 30000;
+
+    const channel =
+        opts.channel ??
+        (await webSocketChannel(opts.url ?? deriveUrl(opts.token)));
+
+    const pending = new Map<number, Pending>();
+    const listeners = new Map<string, Set<(payload: unknown) => void>>();
+    let nextId = 1;
+    let open = true;
+
+    const failAll = (message: string): void => {
+        for (const entry of pending.values()) {
+            if (entry.timer) {
+                clearTimeout(entry.timer);
+            }
+            entry.reject(new Error(message));
+        }
+        pending.clear();
+    };
+
+    const call = (method: string, args: unknown[]): Promise<unknown> => {
+        if (!open) {
+            return Promise.reject(new Error(`ipc channel closed: ${method}`));
+        }
+
+        const id = nextId++;
+        nextId = nextId > Number.MAX_SAFE_INTEGER ? 1 : nextId;
+
+        const promise = new Promise<unknown>((resolve, reject) => {
+            const timer =
+                timeoutMs > 0
+                    ? setTimeout(() => {
+                          // 超时后从表里摘掉，迟到的回复会被当成未知 id 丢弃
+                          pending.delete(id);
+                          reject(new Error(`ipc timeout after ${timeoutMs}ms: ${method}`));
+                      }, timeoutMs)
+                    : null;
+            pending.set(id, { resolve, reject, timer });
+        });
+
+        try {
+            channel.send(JSON.stringify({ t: "ipc:req", id, m: method, a: args }));
+        } catch (err) {
+            const entry = pending.get(id);
+            pending.delete(id);
+            if (entry?.timer) {
+                clearTimeout(entry.timer);
+            }
+            return Promise.reject(err instanceof Error ? err : new Error(String(err)));
+        }
+
+        return promise;
+    };
+
+    channel.onMessage((text) => {
+        let parsed: unknown;
+        try {
+            parsed = JSON.parse(text);
+        } catch {
+            return;
+        }
+        if (!parsed || typeof parsed !== "object") {
+            return;
+        }
+        const o = parsed as Record<string, unknown>;
+
+        if (o.t === "ipc:res" && typeof o.id === "number") {
+            const entry = pending.get(o.id);
+            if (!entry) {
+                return;
+            }
+            pending.delete(o.id);
+            if (entry.timer) {
+                clearTimeout(entry.timer);
+            }
+            if (o.ok === true) {
+                entry.resolve(o.r);
+            } else {
+                entry.reject(toError(o.e));
+            }
+            return;
+        }
+
+        if (o.t === "ipc:evt" && typeof o.e === "string") {
+            const handlers = listeners.get(o.e);
+            if (!handlers) {
+                return;
+            }
+            // 复制一份：处理器里调用 off() 不应打乱本次遍历
+            for (const handler of [...handlers]) {
+                try {
+                    handler(o.p);
+                } catch {
+                    // 单个处理器抛错不该打断整条事件通道
+                }
+            }
+        }
+    });
+
+    channel.onClose(() => {
+        open = false;
+        failAll("ipc channel closed");
+    });
+
+    const on = (event: string, handler: (payload: unknown) => void): (() => void) => {
+        let set = listeners.get(event);
+        if (!set) {
+            set = new Set();
+            listeners.set(event, set);
+        }
+        set.add(handler);
+        return () => {
+            set.delete(handler);
+        };
+    };
+
+    const off = (event: string, handler: (payload: unknown) => void): void => {
+        listeners.get(event)?.delete(handler);
+    };
+
+    const close = (): void => {
+        if (!open) {
+            return;
+        }
+        open = false;
+        try {
+            channel.close();
+        } catch {
+            // 已经关掉的情况忽略
+        }
+        failAll("ipc client closed");
+    };
+
+    // 用 Proxy 按方法名动态派发——这样客户端不需要知道任何方法清单，
+    // 方法集合完全由调用方传入的泛型 `T` 在编译期约束。
+    const proxy = new Proxy({} as Record<string | symbol, unknown>, {
+        get(_target, prop) {
+            if (prop === "on") {
+                return on;
+            }
+            if (prop === "off") {
+                return off;
+            }
+            if (prop === "close") {
+                return close;
+            }
+            if (prop === "connected") {
+                return open;
+            }
+            if (prop === "pending") {
+                return pending.size;
+            }
+            // `then` 必须返回 undefined：否则 `await client` 会把它当 thenable
+            // 无限等待下去。Symbol 同理（Symbol.toPrimitive 等）
+            if (prop === "then" || typeof prop === "symbol") {
+                return undefined;
+            }
+            return (...args: unknown[]) => call(prop, args);
+        },
+    });
+
+    return proxy as unknown as IpcClient<T, E>;
+}
+
+/** 从页面 URL 推导 ws 地址。与服务端 `src/host.ts` 的约定一致 */
+function deriveUrl(token?: string): string {
+    const loc = (
+        globalThis as {
+            location?: { search: string; protocol: string; host: string };
+        }
+    ).location;
+
+    if (!loc) {
+        throw new Error("connect: no url given and no global location to derive one from");
+    }
+
+    const t = token ?? new URLSearchParams(loc.search).get("t") ?? "";
+    const proto = loc.protocol === "https:" ? "wss:" : "ws:";
+    return `${proto}//${loc.host}/ws?t=${encodeURIComponent(t)}`;
+}

package/src/shell/native-asset.d.ts

@@ -0,0 +1,18 @@
+/**
+ * native-asset.d.ts — `bun-app-window/native` 子路径的类型声明
+ *
+ * 该子路径的运行时目标是真实的 `dist/libshell.dll`，不是 JavaScript 模块，
+ * TypeScript 无从推导它的形状，消费方会得到 `TS2307: Cannot find module`。
+ * `package.json` 的 `exports["./native"]` 用 `types` 条件把类型指到本文件，
+ * 运行时的 `default` 条件仍指向 DLL 本体——两件事互不干扰。
+ *
+ * 为什么不做成 `.ts` 包装模块：那会让 `import.meta.resolve("bun-app-window/native")`
+ * 返回一个 `.ts` 路径。把 DLL 拷到 exe 旁边是真实用法，解析结果必须仍是 DLL 本身。
+ *
+ * 消费方用法（`with { type: "file" }` 不能省，否则打包器会试着把 DLL 当模块解析）：
+ *
+ *     import nativeLibPath from "bun-app-window/native" with { type: "file" };
+ */
+
+declare const nativeLibPath: string;
+export default nativeLibPath;

package/src/shell/native.ts

@@ -0,0 +1,92 @@
+/**
+ * native.ts — 原生库的 FFI 声明与字符串工具
+ *
+ * 只负责「怎么调」，不负责「库在哪」（后者见 resolve.ts）。
+ */
+
+import { CString, FFIType, dlopen, ptr } from "bun:ffi";
+import type { Pointer } from "bun:ffi";
+
+/**
+ * 打开 libshell.dll。
+ *
+ * 导出面说明：DLL 实际导出 33 个符号，其中 `shell_start` 是 1.x 遗留入口，
+ * TS 侧不声明、也不对外承诺（故下方声明 32 个）；`shell_debug_*` / `shell_self_*` 属排障面。
+ */
+export function openNativeLib(path: string) {
+  return dlopen(path, {
+    shell_start_ex: {
+      args: [FFIType.ptr, FFIType.ptr, FFIType.i32, FFIType.i32, FFIType.i32],
+      returns: FFIType.i32,
+    },
+    shell_post: { args: [FFIType.ptr], returns: FFIType.i32 },
+    shell_title: { args: [FFIType.ptr], returns: FFIType.i32 },
+    shell_minimize: { args: [], returns: FFIType.i32 },
+    shell_toggle_maximize: { args: [], returns: FFIType.i32 },
+    shell_close: { args: [], returns: FFIType.i32 },
+    shell_drag: { args: [], returns: FFIType.i32 },
+    shell_begin_resize: { args: [FFIType.i32], returns: FFIType.i32 },
+    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 },
+    shell_stop: { args: [], returns: FFIType.void },
+    shell_error: { args: [], returns: FFIType.ptr },
+    // 系统集成面
+    shell_show: { args: [], returns: FFIType.i32 },
+    shell_set_app_id: { args: [FFIType.ptr], returns: FFIType.i32 },
+    shell_is_dark: { args: [], returns: FFIType.i32 },
+    shell_pick_folder: { args: [FFIType.ptr, FFIType.ptr, FFIType.i32], returns: FFIType.i32 },
+    shell_error_text: { args: [FFIType.ptr, FFIType.i32], returns: FFIType.i32 },
+
+    // 应用化面（关掉浏览器行为 + 应用自定义右键菜单）
+    shell_set_browser_ui: { args: [FFIType.i32], returns: FFIType.i32 },
+    shell_show_app_menu: { args: [FFIType.i32, FFIType.i32, FFIType.ptr], returns: FFIType.i32 },
+
+    // 窗口位置面
+    shell_get_bounds: { args: [FFIType.ptr, FFIType.i32], returns: FFIType.i32 },
+    shell_restore_bounds: {
+      args: [FFIType.i32, FFIType.i32, FFIType.i32, FFIType.i32, FFIType.i32, FFIType.i32],
+      returns: FFIType.i32,
+    },
+
+    // 输入与视图面
+    shell_set_zoom: { args: [FFIType.f64], returns: FFIType.i32 },
+    shell_get_zoom: { args: [], returns: FFIType.f64 },
+    shell_reload: { args: [], returns: FFIType.i32 },
+    shell_devtools: { args: [], returns: FFIType.i32 },
+    shell_toggle_fullscreen: { args: [], returns: FFIType.i32 },
+
+    // 排障面：不进稳定契约
+    shell_debug_hittest: { args: [FFIType.i32, FFIType.i32], returns: FFIType.i32 },
+    shell_debug_metrics: { args: [FFIType.ptr, FFIType.i32], returns: FFIType.i32 },
+    shell_debug_dpi: { args: [FFIType.ptr, FFIType.i32], returns: FFIType.i32 },
+    shell_self_base: { args: [], returns: FFIType.u64 },
+    shell_self_path: { args: [FFIType.ptr, FFIType.i32], returns: FFIType.i32 },
+  });
+}
+
+export type NativeLib = ReturnType<typeof openNativeLib>;
+export type NativeSymbols = NativeLib["symbols"];
+
+/** JS 字符串 → 以 NUL 结尾的 UTF-8 C 字符串指针 */
+export const cstr = (s: string) => ptr(new TextEncoder().encode(`${s}\0`));
+
+/** C 字符串指针 → JS 字符串；空指针或异常返回空串 */
+export function readCStr(p: unknown): string {
+  if (!p) return "";
+  try {
+    return new CString(p as never).toString();
+  } catch {
+    return "";
+  }
+}
+
+/** 读取原生侧写入定长缓冲的 UTF-8 文本 */
+export function readBuffer(
+  fill: (p: Pointer, len: number) => number,
+  size = 1024,
+): string {
+  const buf = new Uint8Array(size);
+  const n = fill(ptr(buf), buf.length);
+  return n > 0 ? new TextDecoder().decode(buf.subarray(0, n)) : "";
+}