bun-app-window 0.0.0-stage → 0.2.0

package/src/shell/port.ts

@@ -0,0 +1,77 @@
+/**
+ * port.ts — 为本地回环服务挑选浏览器允许访问的端口
+ *
+ * 背景：`Bun.serve({ port: 0 })` 由系统随意分配，可能拿到 6000、1719、1720 等
+ * 「不安全端口」。WebView2 / Chromium 内核对这批端口一律拒绝连接，页面直接
+ * 显示 ERR_UNSAFE_PORT，表现为窗口打开但白屏。本机实测命中过 1720（H.323 RAS）。
+ *
+ * 策略：40000–60000 区间随机挑选，避开受限端口表；该区间远离常见开发端口。
+ */
+
+import { randomInt } from "node:crypto";
+
+/**
+ * Chromium 的受限端口表（net/base/port_util.cc 的 kRestrictedPorts）。
+ * 凡在此表内的端口，浏览器内核直接拒绝连接，不发任何网络请求。
+ */
+const RESTRICTED_PORTS = new Set<number>([
+  1, 7, 9, 11, 13, 15, 17, 19, 20, 21, 22, 23, 25, 37, 42, 43, 53, 69, 77, 79, 87, 95, 101, 102,
+  103, 104, 109, 110, 111, 113, 115, 117, 119, 123, 135, 137, 138, 139, 143, 161, 179, 389, 427,
+  465, 512, 513, 514, 515, 526, 530, 531, 532, 540, 548, 554, 556, 563, 587, 601, 636, 989, 990,
+  993, 995, 1719, 1720, 1723, 2049, 3659, 4045, 4190, 5060, 5061, 6000, 6566, 6665, 6666, 6667,
+  6668, 6669, 6679, 6697, 10080,
+]);
+
+export function isRestrictedPort(port: number): boolean {
+  return RESTRICTED_PORTS.has(port);
+}
+
+const RANGE_MIN = 40000;
+const RANGE_MAX = 60000;
+
+export type ServeOptions = {
+  hostname?: string;
+  /** 最多尝试几次（默认 20）；超出则抛错 */
+  attempts?: number;
+  fetch: (req: Request, server: unknown) => Response | undefined | Promise<Response | undefined>;
+  websocket?: unknown;
+  error?: (err: Error) => Response;
+};
+
+/**
+ * 用已知安全的端口启动 Bun.serve。
+ * 相比 `Bun.serve({ port: 0 })`，这里保证端口不在浏览器受限表内。
+ */
+export function serveOnSafePort(opts: ServeOptions) {
+  const attempts = opts.attempts ?? 20;
+  let lastErr: unknown = null;
+
+  for (let i = 0; i < attempts; i++) {
+    const port = randomInt(RANGE_MIN, RANGE_MAX);
+    if (isRestrictedPort(port)) continue;
+
+    try {
+      const server = Bun.serve({
+        hostname: opts.hostname ?? "127.0.0.1",
+        port,
+        fetch: opts.fetch as never,
+        ...(opts.websocket === undefined ? {} : { websocket: opts.websocket as never }),
+        ...(opts.error === undefined ? {} : { error: opts.error }),
+      });
+
+      // 双保险：即使指定了端口也再确认一次
+      const bound = server.port;
+      if (bound !== undefined && isRestrictedPort(bound)) {
+        server.stop(true);
+        lastErr = new Error(`allocated restricted port ${bound}`);
+        continue;
+      }
+      return server;
+    } catch (err) {
+      lastErr = err;
+      // 端口被占用等情况，继续尝试下一个
+    }
+  }
+
+  throw new Error(`could not bind a safe port after ${attempts} attempts: ${String(lastErr)}`);
+}

package/src/shell/resolve.ts

@@ -0,0 +1,211 @@
+/**
+ * resolve.ts — 定位可加载的 libshell.dll
+ *
+ * 与旧实现的差别（这是「可作依赖包」的关键）：
+ * 旧实现把 `import dll from "../build/libshell.dll" with { type: "file" }` 写死，
+ * 路径相对仓库结构；装进 node_modules 后会指向 `node_modules/build/`，必崩。
+ * 现在改为按「包自身根目录」解析，仓库结构与安装位置都不影响。
+ *
+ * 解析优先级：
+ *   1. options.nativeLibPath          显式指定，跳过一切推断
+ *   2. 编译产物 + 内嵌字节            释放到 %LOCALAPPDATA%\<appName>\runtime，内容哈希命名
+ *   3. 编译产物 + 可执行文件同级       exe 旁放 libshell.dll（无需内嵌）
+ *   4. 开发态                         包根 .build/libshell.dll → dist/libshell.dll
+ */
+
+import { createHash } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+
+import type { NativeLibInfo } from "./types";
+
+const DLL_PATTERN = /^libshell.*\.dll$/i;
+
+/** 包根目录：src/shell → 上两级。打包态下该值不可用于文件系统访问。 */
+const PKG_ROOT = resolve(import.meta.dir, "..", "..");
+
+/** 从 node_modules 里被引用时，来源应报 package 而不是 dev */
+const INSTALLED = /[\\/]node_modules[\\/]/i.test(PKG_ROOT);
+
+/** 是否运行在 `bun build --compile` 产物内 */
+export function isPackedRuntime(): boolean {
+  return (
+    /^[A-Za-z]:[\\/]~BUN[\\/]/i.test(import.meta.dir) ||
+    import.meta.dir.startsWith("/$bunfs/")
+  );
+}
+
+function sha256Hex(buf: Uint8Array): string {
+  return createHash("sha256").update(buf).digest("hex");
+}
+
+function runtimeDir(appName: string): string {
+  const base =
+    process.env.LOCALAPPDATA && process.env.LOCALAPPDATA.length > 0
+      ? process.env.LOCALAPPDATA
+      : join(homedir(), "AppData", "Local");
+  return join(base, appName, "runtime");
+}
+
+function fromPath(path: string, source: NativeLibInfo["source"]): NativeLibInfo {
+  return {
+    path,
+    source,
+    sha256: "",
+    bytes: statSync(path).size,
+    reused: false,
+    pruned: [],
+  };
+}
+
+/** 写入目标目录；同名同大小视为可复用，写入走临时文件 + rename 保证原子性 */
+function materialize(
+  dir: string,
+  bytes: Uint8Array,
+  sha256: string,
+): { path: string; reused: boolean } {
+  mkdirSync(dir, { recursive: true });
+
+  const finalName = `libshell-${sha256.slice(0, 16)}.dll`;
+  const finalPath = join(dir, finalName);
+
+  if (existsSync(finalPath)) {
+    try {
+      if (statSync(finalPath).size === bytes.length) {
+        return { path: finalPath, reused: true };
+      }
+    } catch {
+      // 读不到就重写
+    }
+  }
+
+  const tmpPath = join(dir, `.tmp-${process.pid}-${Date.now().toString(36)}.dll`);
+  writeFileSync(tmpPath, bytes);
+
+  try {
+    renameSync(tmpPath, finalPath);
+  } catch (err) {
+    // Windows 上目标已存在时 rename 会失败：另一个实例可能刚好抢先写入
+    rmSync(tmpPath, { force: true });
+    if (!existsSync(finalPath)) throw err;
+  }
+
+  return { path: finalPath, reused: false };
+}
+
+/** 删掉与当前哈希不符的旧副本；正被其它实例占用的删除失败则忽略 */
+function pruneOldVersions(dir: string, keepName: string): string[] {
+  const pruned: string[] = [];
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return pruned;
+  }
+
+  for (const name of entries) {
+    if (!DLL_PATTERN.test(name)) continue;
+    if (name === keepName) continue;
+    try {
+      rmSync(join(dir, name), { force: true });
+      pruned.push(name);
+    } catch {
+      // 正被其它实例加载，跳过
+    }
+  }
+  return pruned;
+}
+
+/** 从 Bun.embeddedFiles 找内嵌 DLL；没有则返回 null */
+async function readBunEmbedded(): Promise<Uint8Array | null> {
+  const files = (Bun as unknown as { embeddedFiles?: ReadonlyArray<Blob & { name: string }> })
+    .embeddedFiles;
+  if (!files || files.length === 0) return null;
+
+  const hit = files.find((f) => DLL_PATTERN.test(f.name));
+  if (!hit) return null;
+
+  const buf = new Uint8Array(await hit.arrayBuffer());
+  if (buf.length < 2 || buf[0] !== 0x4d || buf[1] !== 0x5a) {
+    throw new Error(`embedded native library is not a PE file (${hit.name})`);
+  }
+  return buf;
+}
+
+export type ResolveOptions = {
+  nativeLibPath?: string;
+  appName?: string;
+  embedded?: () => Promise<Uint8Array | null>;
+};
+
+export async function resolveNativeLib(opts: ResolveOptions = {}): Promise<NativeLibInfo> {
+  const appName = opts.appName ?? "BunAppWindow";
+
+  // 1. 显式指定
+  if (opts.nativeLibPath) {
+    if (!existsSync(opts.nativeLibPath)) {
+      throw new Error(`nativeLibPath does not exist: ${opts.nativeLibPath}`);
+    }
+    return fromPath(opts.nativeLibPath, "explicit");
+  }
+
+  if (isPackedRuntime()) {
+    // 2. 内嵌字节 → 释放到用户目录
+    const bytes = opts.embedded ? await opts.embedded() : await readBunEmbedded();
+    if (bytes) {
+      const sha256 = sha256Hex(bytes);
+      try {
+        const { path, reused } = materialize(runtimeDir(appName), bytes, sha256);
+        return {
+          path,
+          source: "embedded",
+          sha256,
+          bytes: bytes.length,
+          reused,
+          pruned: pruneOldVersions(dirname(path), basename(path)),
+        };
+      } catch {
+        // %LOCALAPPDATA% 不可写（受限环境）：继续尝试同级文件
+      }
+    }
+
+    // 3. 可执行文件同级
+    for (const candidate of [
+      join(dirname(process.execPath), "libshell.dll"),
+      join(dirname(process.execPath), "dist", "libshell.dll"),
+    ]) {
+      if (existsSync(candidate)) return fromPath(candidate, "package");
+    }
+
+    throw new Error(
+      "cannot locate libshell.dll in a compiled executable. " +
+        "Either place libshell.dll next to the executable, or import " +
+        "`bun-app-window/embedded` so it gets bundled. " +
+        `Searched: ${dirname(process.execPath)}`,
+    );
+  }
+
+  // 4. 开发态 / 包安装态：包根下的 .build/ 再 dist/
+  const source: NativeLibInfo["source"] = INSTALLED ? "package" : "dev";
+  for (const candidate of [
+    join(PKG_ROOT, ".build", "libshell.dll"),
+    join(PKG_ROOT, "dist", "libshell.dll"),
+  ]) {
+    if (existsSync(candidate)) return fromPath(candidate, source);
+  }
+
+  throw new Error(
+    "libshell.dll not found. Build the native layer first: " +
+      "`pwsh -File native/build.ps1`. " +
+      `Searched under ${PKG_ROOT}`,
+  );
+}

package/src/shell/state.ts

@@ -0,0 +1,211 @@
+import { mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+import type { Shell } from "./index";
+
+/**
+ * 窗口位置与尺寸的持久化。
+ *
+ * 单独一个模块而不是塞进 `index.ts`，因为库主体有一条硬约束：不得引入副作用
+ * （不写文件、不起服务、不读 env）。持久化按定义就是副作用，所以它是**显式调用**的
+ * 可选件，你不调用它就不会有任何文件产生。
+ *
+ * 跨会话恢复有三个坑，原生侧已经处理，这里只负责序列化与节流：
+ *   - DPI 变化：存的是物理像素 + 当时的 DPI，恢复时按比例换算
+ *   - 显示器不在了：矩形要与某块工作区有足够交叠才算可用，否则居中
+ *   - 最大化状态：存「还原后」的矩形，而不是整屏尺寸
+ */
+
+export type WindowPlacement = {
+    /** 物理像素，屏幕坐标 */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    maximized: boolean;
+    /** 保存时的窗口 DPI；恢复时用于换算尺寸 */
+    dpi: number;
+};
+
+const DEFAULTS = {
+    /** 轮询间隔。GetWindowRect 是微秒级，700 ms 足够了 */
+    intervalMs: 700,
+} as const;
+
+/** 把原生返回的一行文本解析成 WindowPlacement；格式不对返回 null。 */
+export function parseBounds(text: string): WindowPlacement | null {
+    const parts = text.trim().split(",");
+    if (parts.length !== 6) {
+        return null;
+    }
+    const nums = parts.map((p) => Number(p));
+    if (nums.some((n) => !Number.isFinite(n))) {
+        return null;
+    }
+    const [x, y, width, height, maximized, dpi] = nums as [
+        number,
+        number,
+        number,
+        number,
+        number,
+        number,
+    ];
+    // 尺寸为 0 或负数说明窗口还没建好（原生在无窗口时返回 0 长度文本，这里再兜一层）
+    if (width <= 0 || height <= 0 || dpi <= 0) {
+        return null;
+    }
+    return { x, y, width, height, maximized: maximized !== 0, dpi };
+}
+
+/**
+ * 校验外部来源（磁盘 JSON）里的 placement。
+ *
+ * 配置文件可能是手改坏的、被截断的、或者是旧版本写的。这里做形状校验而不是直接
+ * 相信它：一个 out-of-range 的坐标会让窗口出现在屏幕外，表现为「程序启动了但看不到」。
+ */
+export function parsePlacement(raw: unknown): WindowPlacement | null {
+    if (!raw || typeof raw !== "object") {
+        return null;
+    }
+    const o = raw as Record<string, unknown>;
+    const num = (k: string): number | null => {
+        const v = o[k];
+        return typeof v === "number" && Number.isFinite(v) ? v : null;
+    };
+    const x = num("x");
+    const y = num("y");
+    const width = num("width");
+    const height = num("height");
+    const dpi = num("dpi");
+    if (x === null || y === null || width === null || height === null || dpi === null) {
+        return null;
+    }
+    if (width <= 0 || height <= 0 || dpi <= 0) {
+        return null;
+    }
+    // 物理像素的合理上限：8K 也只有 7680。超过说明文件被污染了
+    if (width > 20000 || height > 20000) {
+        return null;
+    }
+    if (Math.abs(x) > 200000 || Math.abs(y) > 200000) {
+        return null;
+    }
+    return { x, y, width, height, maximized: o.maximized === true, dpi };
+}
+
+/** 读当前窗口矩形；窗口不存在或数据不可解析时返回 null。 */
+export function capturePlacement(shell: Shell): WindowPlacement | null {
+    return parseBounds(shell.getBounds());
+}
+
+/** 把保存的矩形恢复到窗口上（异步生效；原生侧会做 DPI 换算与屏幕校验）。 */
+export function restorePlacement(shell: Shell, p: WindowPlacement): number {
+    return shell.restoreBounds(p.x, p.y, p.width, p.height, p.dpi, p.maximized);
+}
+
+/** 从磁盘读。文件不存在、损坏、形状不对一律返回 null，不抛错。 */
+export async function loadPlacement(file: string): Promise<WindowPlacement | null> {
+    try {
+        const f = Bun.file(file);
+        if (!(await f.exists())) {
+            return null;
+        }
+        return parsePlacement(JSON.parse(await f.text()));
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * 写磁盘。先写临时文件再改名——窗口位置在关闭时写，如果正好被强杀，
+ * 半截 JSON 会让下次启动读不到位置；改名是原子的，至少保证要么旧值要么新值。
+ */
+export async function savePlacement(file: string, p: WindowPlacement): Promise<void> {
+    const target = resolve(file);
+    mkdirSync(dirname(target), { recursive: true });
+    const tmp = `${target}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(p, null, 4)}\n`, "utf8");
+    renameSync(tmp, target);
+}
+
+export type PlacementStore = {
+    /** 立即抓一次并写盘（关闭前调用） */
+    flush(): Promise<void>;
+    /** 停止轮询。不清盘——最后写入的值保留 */
+    dispose(): void;
+    /** 当前已知的 placement（最近一次成功写入的） */
+    readonly current: WindowPlacement | null;
+};
+
+/**
+ * 轮询窗口矩形并在变化时写盘。
+ *
+ * 为什么轮询而不是事件：原生侧的窗口状态推送是发给**页面**的（shell-msg），宿主
+ * 拿不到；加一条原生→宿主的回调通道要多一套生命周期管理，而 GetWindowRect 是
+ * 微秒级调用，700 ms 一次的代价可以忽略。
+ *
+ * 变化检测按内容比较：窗口静止时不产生任何磁盘写入。
+ */
+export function attachPlacementStore(
+    shell: Shell,
+    file: string,
+    opts: { intervalMs?: number } = {},
+): PlacementStore {
+    const intervalMs = opts.intervalMs ?? DEFAULTS.intervalMs;
+    let last: WindowPlacement | null = null;
+    let lastKey = "";
+    let disposed = false;
+    let pending: Promise<void> = Promise.resolve();
+
+    const same = (a: WindowPlacement, b: WindowPlacement): boolean =>
+        a.x === b.x &&
+        a.y === b.y &&
+        a.width === b.width &&
+        a.height === b.height &&
+        a.maximized === b.maximized &&
+        a.dpi === b.dpi;
+
+    const tick = (): void => {
+        if (disposed) {
+            return;
+        }
+        const now = capturePlacement(shell);
+        if (!now) {
+            return;
+        }
+        // 窗口销毁过程中会短暂读到 0 尺寸，上面已过滤
+        if (last && same(now, last)) {
+            return;
+        }
+        const key = JSON.stringify(now);
+        if (key === lastKey) {
+            return;
+        }
+        last = now;
+        lastKey = key;
+        // 串行化写入：并发 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();
+    }
+
+    return {
+        async flush(): Promise<void> {
+            tick();
+            await pending;
+        },
+        dispose(): void {
+            disposed = true;
+            clearInterval(timer);
+        },
+        get current(): WindowPlacement | null {
+            return last;
+        },
+    };
+}

package/src/shell/types.ts

@@ -0,0 +1,144 @@
+/**
+ * types.ts — 内核的公共类型与常量
+ *
+ * 这里的类型是**稳定面**：改动需要按语义化版本对待。
+ * 调试自省类能力单独放在 Shell["debug"] 下，不视为稳定契约。
+ */
+
+/** 无边框：原生层不画标题栏与边框，由页面自绘 */
+export const FLAG_FRAMELESS = 1;
+/** 置顶 */
+export const FLAG_TOPMOST = 2;
+/**
+ * 启动时把窗口居中到所在显示器的工作区（避开任务栏）。
+ *
+ * 带边框与无边框两种模式都生效。窗口比工作区大时会先收缩到工作区内再居中——
+ * 高 DPI 下这很常见（900×940 逻辑像素在 200% 缩放加边框就是 1950 物理像素高，
+ * 超过 1824 的工作区），不收缩只能贴顶，垂直方向看不出居中。
+ */
+export const FLAG_CENTER = 4;
+/** 可缩放（配合无边框时，边框拖拽区由 shell_begin_resize 提供） */
+export const FLAG_RESIZABLE = 8;
+/**
+ * 创建后先不显示，等调用方确认页面就绪再 `shell.show()`。
+ * 用于消除「空窗口先出现、内容后填上」的首帧闪烁。
+ */
+export const FLAG_DEFER_SHOW = 16;
+/**
+ * 接受文件/文件夹拖放。
+ *
+ * 落进来的路径以 shell-msg 推送：`{ t: "drop", paths: ["C:\\a", "C:\\b"] }`。
+ * 提权进程（High 完整性）需要放行 UIPI，壳已用 `ChangeWindowMessageFilterEx`
+ * 处理；否则资源管理器拖过来的消息会被静默拦掉。
+ */
+export const FLAG_ACCEPT_DROP = 32;
+/**
+ * 首次显示时直接以最大化出现。
+ *
+ * 不要用「先 show() 再 toggleMaximize()」代替：那会有一次「小窗闪一下再撑满」
+ * 的跳变。本项把最大化合成到显示的那一次 `ShowWindow`，窗口从隐藏直接变成
+ * 最大化，中间没有可见帧。
+ *
+ * 与 `FLAG_CENTER` 同时给时以本项为准（最大化会覆盖位置）。
+ */
+export const FLAG_START_MAXIMIZED = 64;
+
+/**
+ * 关闭 WebView2 的浏览器行为（`ShellOptions.browserUi` 使用）。
+ *
+ * WebView2 默认是**浏览器**语义：右键弹 Edge 菜单、Ctrl+P 打印网页、左下角跳状态栏、
+ * 触控板横滑前进后退、表单自动填充。这些在浏览器里都对，在桌面应用里每一条都是
+ * 「这是个网页」的破绽。位定义与原生 `ShellBrowserUi` 逐位一致。
+ */
+export const BROWSER_UI_MENU = 1;
+export const BROWSER_UI_KEYS = 2;
+export const BROWSER_UI_STATUSBAR = 4;
+export const BROWSER_UI_SWIPE = 8;
+export const BROWSER_UI_AUTOFILL = 16;
+
+/** 一次性关掉全部浏览器行为。桌面应用通常要这个。 */
+export const BROWSER_UI_ALL =
+    BROWSER_UI_MENU | BROWSER_UI_KEYS | BROWSER_UI_STATUSBAR | BROWSER_UI_SWIPE | BROWSER_UI_AUTOFILL;
+
+/** 缩放边框的 8 个命中边，取值与 Win32 HT* 常量一致 */
+export const RESIZE_EDGE = {
+  LEFT: 10,
+  RIGHT: 11,
+  TOP: 12,
+  TOPLEFT: 13,
+  TOPRIGHT: 14,
+  BOTTOM: 15,
+  BOTTOMLEFT: 16,
+  BOTTOMRIGHT: 17,
+} as const;
+
+export type ResizeEdge = (typeof RESIZE_EDGE)[keyof typeof RESIZE_EDGE];
+
+/** window state 位掩码（与原生 shell_get_state 一致） */
+export const STATE_MAXIMIZED = 1;
+export const STATE_MINIMIZED = 2;
+export const STATE_FOCUSED = 4;
+
+export type WindowState = {
+  raw: number;
+  maximized: boolean;
+  minimized: boolean;
+  focused: boolean;
+  /** 系统当前是否深色（原生侧读 AppsUseLightTheme，并随 WM_SETTINGCHANGE 刷新） */
+  dark: boolean;
+};
+
+/** 原生库的解析结果 */
+export type NativeLibInfo = {
+  path: string;
+  /**
+   * explicit  — 调用方显式指定
+   * dev       — 本仓开发态（build/ 或 dist/）
+   * package   — 包内 dist/ 或可执行文件同级
+   * embedded  — 从编译产物内嵌字节释放
+   * fallback-tmp — 受限环境下退回 Bun 默认释放
+   */
+  source: "explicit" | "dev" | "package" | "embedded" | "fallback-tmp";
+  sha256: string;
+  bytes: number;
+  reused: boolean;
+  pruned: string[];
+};
+
+export type ShellOptions = {
+  /** 要加载的 URL（通常是本地回环地址） */
+  url: string;
+  title?: string;
+  width?: number;
+  height?: number;
+  /** FLAG_* 位组合 */
+  flags?: number;
+  /** 启动后立即设置的最小尺寸（逻辑像素） */
+  minWidth?: number;
+  minHeight?: number;
+  /**
+   * 原生库路径。给定时跳过所有自动解析。
+   * 用于测试或多副本部署。
+   */
+  nativeLibPath?: string;
+  /**
+   * 运行时数据目录名（`%LOCALAPPDATA%\<appName>\runtime`）。
+   * 同一机器上多个应用共用一个包时应各自指定，避免互相清理 DLL 副本。
+   */
+  appName?: string;
+  /**
+   * 关闭哪些浏览器行为，取 `BROWSER_UI_*` 的按位或。缺省 0（保持 WebView2 默认）。
+   *
+   * 桌面应用一般传 `BROWSER_UI_ALL`：关掉右键 Edge 菜单、`Ctrl+P`/`Ctrl+F`/`Ctrl+S`、
+   * 左下角状态栏、触控板滑动导航与表单自动填充。关掉默认右键菜单后若要右键有反应，
+   * 用 `showContextMenu()` 弹原生菜单。
+   */
+  browserUi?: number;
+  /**
+   * 编译产物内嵌字节的提供者。
+   * 使用 `bun build --compile` 时传入 `embeddedDll`（见 `bun-app-window/embedded`）。
+   */
+  embedded?: () => Promise<Uint8Array | null>;
+};
+
+export type StartResult = { rc: number; error: string };