bun-webview2 0.0.0-stage → 0.3.0

package/src/host-ffi.ts

@@ -0,0 +1,244 @@
+/**
+ * Child host process (FFI flavor): owns exactly one native window + webview
+ * driven directly through the C webview library via bun:ffi — no wry, no
+ * tao, no napi addons.
+ *
+ * Command channel: the parent CDP-evaluates bwv2_host_cmd("<json>") in the
+ * page; the C library delivers it to the bind callback re-entrantly on the
+ * GUI thread (the only JS that runs here — webview_run blocks the JS loop by
+ * design, and this host deliberately has no other JS machinery to lose to a
+ * wedged loop). Replies flow back synchronously: webview_return resolves the
+ * page-side promise the parent awaits, so a resolved call IS the ack.
+ *
+ * Lifecycle: user close button or the "close" command ends webview_run; we
+ * emit "closed" on stdout and exit. Stdout JSON lines are the only
+ * host→parent channel needed.
+ */
+
+import { dlopen, FFIType, JSCallback, ptr } from "bun:ffi";
+
+interface HostConfig {
+  readonly title: string;
+  readonly width: number;
+  readonly height: number;
+}
+
+interface HostCommand {
+  readonly op: string;
+  readonly args?: unknown[];
+}
+
+// Config is always the last argv element: [bun, host-ffi.ts, config].
+const config = JSON.parse(process.argv[process.argv.length - 1] ?? "{}") as Partial<HostConfig>;
+
+const dllPath = Bun.env.BWV2_NATIVE_LIB ?? `${import.meta.dir}/../native/webview.dll`;
+
+const webview = dlopen(dllPath, {
+  webview_create: { args: [FFIType.int, FFIType.pointer], returns: FFIType.pointer },
+  webview_run: { args: [FFIType.pointer], returns: FFIType.int },
+  webview_terminate: { args: [FFIType.pointer], returns: FFIType.int },
+  webview_navigate: { args: [FFIType.pointer, FFIType.pointer], returns: FFIType.int },
+  webview_set_title: { args: [FFIType.pointer, FFIType.pointer], returns: FFIType.int },
+  webview_set_size: { args: [FFIType.pointer, FFIType.int, FFIType.int, FFIType.int], returns: FFIType.int },
+  webview_get_window: { args: [FFIType.pointer], returns: FFIType.pointer },
+  webview_bind: { args: [FFIType.pointer, FFIType.pointer, FFIType.pointer, FFIType.pointer], returns: FFIType.int },
+  webview_return: { args: [FFIType.pointer, FFIType.pointer, FFIType.int, FFIType.pointer], returns: FFIType.int },
+});
+
+// Win32 window controls the C API doesn't cover.
+const user32 = dlopen("user32.dll", {
+  SetWindowPos: { args: [FFIType.pointer, FFIType.i64, FFIType.i32, FFIType.i32, FFIType.i32, FFIType.i32, FFIType.u32], returns: FFIType.int },
+  GetWindowLongPtrW: { args: [FFIType.pointer, FFIType.i32], returns: FFIType.i64 },
+  SetWindowLongPtrW: { args: [FFIType.pointer, FFIType.i32, FFIType.i64], returns: FFIType.i64 },
+  GetWindowRect: { args: [FFIType.pointer, FFIType.pointer], returns: FFIType.int },
+  GetClientRect: { args: [FFIType.pointer, FFIType.pointer], returns: FFIType.int },
+  ShowWindow: { args: [FFIType.pointer, FFIType.i32], returns: FFIType.int },
+  SetForegroundWindow: { args: [FFIType.pointer], returns: FFIType.int },
+  CallWindowProcW: { args: [FFIType.pointer, FFIType.pointer, FFIType.u32, FFIType.u64, FFIType.i64], returns: FFIType.i64 },
+  TrackMouseEvent: { args: [FFIType.pointer], returns: FFIType.int },
+  GetKeyState: { args: [FFIType.i32], returns: FFIType.i16 },
+});
+const advapi32 = dlopen("advapi32.dll", {
+  RegGetValueW: { args: [FFIType.pointer, FFIType.pointer, FFIType.pointer, FFIType.u32, FFIType.u32, FFIType.pointer, FFIType.pointer], returns: FFIType.i32 },
+});
+
+const cstr = (s: string) => ptr(Buffer.from(`${s}\0`, "utf8"));
+
+const WEBVIEW_HINT_NONE = 0;
+const SWP_NOSIZE = 0x0001;
+const SWP_NOMOVE = 0x0002;
+const SWP_NOZORDER = 0x0004;
+const SWP_NOACTIVATE = 0x0010;
+const SWP_FRAMECHANGED = 0x0020;
+const GWL_STYLE = -16;
+const WS_OVERLAPPEDWINDOW = 0x00cf0000;
+const SW_MINIMIZE = 6;
+const SW_MAXIMIZE = 3;
+const HWND_TOPMOST = -1;
+const HWND_NOTOPMOST = -2;
+
+if (Bun.env.BWV2_DEBUG === "1") console.error("[host-ffi] started");
+
+const handle = webview.symbols.webview_create(0, null);
+if (handle === 0n || handle === 0) {
+  console.error("[host-ffi] webview_create failed");
+  process.exit(1);
+}
+const hwnd = webview.symbols.webview_get_window(handle);
+
+const emit = (payload: Record<string, unknown>): void => {
+  console.log(JSON.stringify(payload));
+};
+
+// --- Window events via WndProc subclassing -------------------------------
+// The flat C API has no event subscriptions, so the window's own procedure
+// is replaced: interesting messages become stdout events (the parent's
+// generic routing picks them up); everything chains to the original proc.
+
+const GWL_WNDPROC = -4;
+const WM_MOVE = 0x0003;
+const WM_SIZE = 0x0005;
+// Only non-client, window-level messages reach this procedure: input over
+// the page surface goes to the WebView2 child HWND and is delivered to apps
+// as page DOM events instead (src/inject.ts page-event bridge). Keys,
+// mouse, wheel, and file drops therefore have no WndProc cases at all.
+const WM_ACTIVATE = 0x0006;
+const WM_THEMECHANGED = 0x031a;
+
+// personalization: 1 = apps light theme, 0 = dark
+const themeText = (): "light" | "dark" => {
+  const value = Buffer.alloc(4);
+  const size = Buffer.alloc(4);
+  size.writeUInt32LE(4, 0);
+  const subkey = Buffer.from("Software\\Microsoft\\Windows\\CurrentVersion\\Themes\\Personalize\0", "utf16le");
+  const valueName = Buffer.from("AppsUseLightTheme\0", "utf16le");
+  const ok = advapi32.symbols.RegGetValueW(0x80000001n /* HKEY_CURRENT_USER */, ptr(subkey), ptr(valueName), 0x0002 /* RRF_RT_REG_DWORD */, 0, ptr(value), ptr(size));
+  return ok === 0 && value.readUInt32LE(0) === 1 ? "light" : "dark";
+};
+
+const originalProc: { handle: bigint | undefined } = { handle: undefined };
+
+const wndProc = new JSCallback(
+  (hwndArg: number | bigint, msg: number | bigint, wParam: number | bigint, lParam: number | bigint) => {
+    // FFI delivers u64/i64 as number or bigint; normalize once at the boundary
+    const hwnd = BigInt(hwndArg);
+    const msgN = Number(msg);
+    const wp = BigInt.asUintN(64, BigInt(wParam));
+    const lp = BigInt.asIntN(64, BigInt(lParam));
+    switch (msgN) {
+      case WM_MOVE: {
+        const l = BigInt.asUintN(32, lp);
+        emit({ event: "move", x: Number(BigInt.asIntN(16, l & 0xffffn)), y: Number(BigInt.asIntN(16, (l >> 16n) & 0xffffn)) });
+        break;
+      }
+      case WM_SIZE: {
+        const l = BigInt.asUintN(32, lp);
+        emit({ event: "resize", width: Number(l & 0xffffn), height: Number((l >> 16n) & 0xffffn) });
+        break;
+      }
+      case WM_ACTIVATE: {
+        // window activation: clicks on the page activate the top window too,
+        // unlike WM_SETFOCUS which the WebView2 child HWND claims.
+        const active = (BigInt.asUintN(16, wp) & 0xffffn) !== 0n;
+        emit({ event: active ? "focus" : "blur" });
+        break;
+      }
+      case WM_THEMECHANGED:
+        emit({ event: "theme-changed", text: themeText() });
+        break;
+    }
+    // chain everything (handled or not) to the original procedure
+    if (originalProc.handle !== undefined) {
+      return user32.symbols.CallWindowProcW(originalProc.handle, hwnd, msgN, wp, lp);
+    }
+    return 0n;
+  },
+  { args: [FFIType.pointer, FFIType.u32, FFIType.u64, FFIType.i64], returns: FFIType.i64 },
+);
+
+// Subclass the window so the parent receives native window events.
+originalProc.handle = user32.symbols.SetWindowLongPtrW(hwnd, GWL_WNDPROC, BigInt(wndProc.ptr ?? 0));
+
+function applyCommand(command: HostCommand): string {
+  const args = command.args ?? [];
+  switch (command.op) {
+    case "hello":
+      return "true";
+    case "setTitle":
+      return String(webview.symbols.webview_set_title(handle, cstr(String(args[0]))));
+    case "setSize":
+      return String(webview.symbols.webview_set_size(handle, Number(args[0]), Number(args[1]), WEBVIEW_HINT_NONE));
+    case "setPosition": {
+      const result = user32.symbols.SetWindowPos(
+        hwnd,
+        0n,
+        Number(args[0]),
+        Number(args[1]),
+        0,
+        0,
+        SWP_NOSIZE | SWP_NOZORDER | SWP_NOACTIVATE,
+      );
+      return String(result);
+    }
+    case "setDecorations": {
+      const current = user32.symbols.GetWindowLongPtrW(hwnd, GWL_STYLE);
+      const decorationsOn = Boolean(args[0]);
+      const masked = BigInt(current) & ~BigInt(WS_OVERLAPPEDWINDOW);
+      const updated = decorationsOn ? masked | BigInt(WS_OVERLAPPEDWINDOW) : masked;
+      const result = user32.symbols.SetWindowLongPtrW(hwnd, GWL_STYLE, updated);
+      user32.symbols.SetWindowPos(hwnd, 0n, 0, 0, 0, 0, SWP_NOMOVE | SWP_NOSIZE | SWP_NOZORDER | SWP_FRAMECHANGED);
+      return String(result);
+    }
+    case "setAlwaysOnTop": {
+      const insertAfter = args[0] ? BigInt(HWND_TOPMOST) : BigInt(HWND_NOTOPMOST);
+      const result = user32.symbols.SetWindowPos(hwnd, insertAfter, 0, 0, 0, 0, SWP_NOMOVE | SWP_NOSIZE);
+      return String(result);
+    }
+    case "focus":
+      return String(user32.symbols.SetForegroundWindow(hwnd));
+    case "minimize":
+      return String(user32.symbols.ShowWindow(hwnd, SW_MINIMIZE));
+    case "maximize":
+      return String(user32.symbols.ShowWindow(hwnd, SW_MAXIMIZE));
+
+    case "close":
+      // restore the original procedure before tearing the window down
+      if (originalProc.handle !== undefined) {
+        user32.symbols.SetWindowLongPtrW(hwnd, GWL_WNDPROC, BigInt(originalProc.handle));
+        originalProc.handle = undefined;
+      }
+      webview.symbols.webview_terminate(handle);
+      return "true";
+    default:
+      return "null";
+  }
+}
+
+const bindCallback = new JSCallback(
+  (id: string, req: string) => {
+    if (Bun.env.BWV2_DEBUG === "1") console.error(`[host-ffi] op: ${req.slice(0, 80)}`);
+    let result = "null";
+    try {
+      const parsed = JSON.parse(req) as unknown[];
+      const payload = typeof parsed[0] === "string" ? (JSON.parse(parsed[0]) as HostCommand) : (parsed[0] as HostCommand);
+      result = applyCommand(payload);
+    } catch (err) {
+      console.error("[host-ffi] command failed:", err);
+    }
+    webview.symbols.webview_return(handle, cstr(id), 0, cstr(result));
+  },
+  { args: [FFIType.cstring, FFIType.cstring, FFIType.pointer], returns: FFIType.void },
+);
+
+webview.symbols.webview_set_title(handle, cstr(config.title ?? "bun-webview2"));
+webview.symbols.webview_set_size(handle, config.width ?? 800, config.height ?? 600, WEBVIEW_HINT_NONE);
+webview.symbols.webview_bind(handle, cstr("bwv2_host_cmd"), bindCallback.ptr, null);
+
+// about:blank keeps the initial document inert; the parent drives all real
+// content over CDP.
+webview.symbols.webview_navigate(handle, cstr("about:blank"));
+
+webview.symbols.webview_run(handle);
+// run() returning means the window closed (user X or the "close" command).
+emit({ event: "closed" });
+process.exit(0);

package/src/index.ts

@@ -0,0 +1,22 @@
+/**
+ * bun-webview2 — desktop apps with Bun on Windows.
+ *
+ * Native WebView2 windows you fully control from Bun: navigation,
+ * evaluation, typed IPC, screenshots, and window chrome, driven over the
+ * Chrome DevTools Protocol. No browser UI, no tab strip, no first-run
+ * nags — and no DevTools escape hatch unless you allow one.
+ */
+
+export { Webview2Window, createWindow } from "./window.ts";
+export type {
+  Webview2WindowOptions,
+  ExposedFunction,
+  ScreenshotFormat,
+  WindowEventPayloads,
+  WindowEventName,
+} from "./window.ts";
+export type { HardeningOptions } from "./inject.ts";
+export { CdpConnection, pickFreePort, waitForPageTarget } from "./cdp.ts";
+export type { CdpTargetInfo } from "./cdp.ts";
+export { serveApp } from "./serve.ts";
+export type { ServedApp } from "./serve.ts";

package/src/inject.ts

@@ -0,0 +1,112 @@
+/**
+ * Scripts injected into every new document via Page.addScriptToEvaluateOnNewDocument.
+ *
+ * Two concerns live here:
+ *
+ * 1. Hardening — bun-webview2 windows are app windows, not browser windows.
+ *    By default the Chromium right-click menu and the browser accelerators
+ *    that leak app-ness (F12, Ctrl+Shift+I/J/C, Ctrl+U/S/P) are disabled.
+ *    Both are gateable per-window via the constructor options.
+ *
+ * 2. IPC bridge — exposes `window.bwv2.call(name, ...args)` returning a
+ *    Promise. Calls travel to Bun through a Runtime binding; results travel
+ *    back through a resolve callback the host evaluates.
+ */
+
+export interface HardeningOptions {
+  /** Allow the native Chromium right-click context menu. Default: false (blocked). */
+  readonly contextMenu?: boolean;
+  /** Allow DevTools/browser accelerators (F12, Ctrl+Shift+I/J/C, Ctrl+U/S/P). Default: false (blocked). */
+  readonly devToolsKeys?: boolean;
+}
+
+export function buildHardeningScript(opts: HardeningOptions): string {
+  const blocks: string[] = ["Object.defineProperty(window, '__bwv2Hardened', { value: true });"];
+
+  if (!opts.contextMenu) {
+    blocks.push(
+      "document.addEventListener('contextmenu', (e) => e.preventDefault(), true);",
+    );
+  }
+
+  if (!opts.devToolsKeys) {
+    blocks.push(`
+window.addEventListener('keydown', (e) => {
+  const reservedCombo =
+    e.key === 'F12' ||
+    (e.ctrlKey && e.shiftKey && ['KeyI', 'KeyJ', 'KeyC'].includes(e.code)) ||
+    (e.ctrlKey && !e.shiftKey && ['KeyU', 'KeyS', 'KeyP'].includes(e.code));
+  if (reservedCombo) e.preventDefault();
+}, true);`,
+    );
+  }
+
+  return `(() => { ${blocks.join("\n")} })();`;
+}
+
+/**
+ * IPC bridge. Always injected; inert until the app calls `window.expose()`.
+ * Payloads are single JSON strings because CDP bindings take one string arg.
+ */
+export function buildIpcBridgeScript(): string {
+  return `(() => {
+  if (window.bwv2) return;
+  const pending = new Map();
+  let nextId = 1;
+  window.bwv2 = {
+    call(name, ...args) {
+      const id = nextId++;
+      const settled = Promise.withResolvers();
+      pending.set(id, settled);
+      window.__bwv2Ipc(JSON.stringify({ id, name, args }));
+      return settled.promise;
+    },
+  };
+  window.__bwv2Resolve = (id, ok, value) => {
+    const entry = pending.get(id);
+    if (!entry) return;
+    pending.delete(id);
+    if (ok) entry.resolve(value);
+    else entry.reject(new Error(typeof value === 'string' ? value : value?.message ?? String(value)));
+  };
+})();`;
+}
+
+/**
+ * Page-surface events: input over the page never reaches the host's window
+ * procedure (the WebView2 child HWND consumes it), so keys, mouse, wheel,
+ * and drag-and-drop are captured as DOM events and forwarded through the
+ * existing __bwv2Ipc binding. DOM events are also richer than the Win32
+ * equivalents: KeyboardEvent carries layout/IME-aware key and code, and
+ * the drop event exposes File objects (readable content) rather than paths.
+ */
+export function buildPageEventsScript(): string {
+  return `(() => {
+  if (window.__bwv2PageEvents) return;
+  Object.defineProperty(window, '__bwv2PageEvents', { value: true });
+  const send = (name, payload) =>
+    window.__bwv2Ipc(JSON.stringify({ id: -1, name: '__event', args: [name, payload] }));
+  const mods = (e) =>
+    (e.shiftKey ? 1 : 0) | (e.ctrlKey ? 2 : 0) | (e.altKey ? 4 : 0) | (e.metaKey ? 8 : 0);
+  document.addEventListener('keydown', (e) =>
+    send('key-down', { key: e.key, code: e.code, modifiers: mods(e), isRepeat: e.repeat }), true);
+  document.addEventListener('keyup', (e) =>
+    send('key-up', { key: e.key, code: e.code, modifiers: mods(e) }), true);
+  document.addEventListener('mousedown', (e) =>
+    send('mouse-down', { x: e.clientX, y: e.clientY, button: e.button, modifiers: mods(e) }), true);
+  document.addEventListener('mouseup', (e) =>
+    send('mouse-up', { x: e.clientX, y: e.clientY, button: e.button, modifiers: mods(e) }), true);
+  document.addEventListener('mouseenter', () => send('mouse-enter', {}), true);
+  document.addEventListener('mouseleave', () => send('mouse-leave', {}), true);
+  document.addEventListener('wheel', (e) =>
+    send('scroll', { deltaX: e.deltaX, deltaY: e.deltaY }), { capture: true, passive: true });
+  // drag-and-drop: the dragover preventDefault is what allows drops at all;
+  // no event is sent while hovering (it would fire dozens of times per second)
+  document.addEventListener('dragover', (e) => e.preventDefault(), true);
+  document.addEventListener('drop', (e) => {
+    e.preventDefault();
+    const files = [...(e.dataTransfer?.files ?? [])].map((f) => ({ name: f.name, size: f.size, type: f.type }));
+    send('file-drop', { files });
+  }, true);
+})();`;
+}

package/src/serve.ts

@@ -0,0 +1,34 @@
+/**
+ * Local content serving — bun-webview2's answer to custom protocols.
+ *
+ * Instead of registering an `app://` scheme handler, serve your frontend from
+ * Bun itself on a free loopback port and point a window at it. Same ergonomics
+ * (fetch-style `Request → Response`, works with Hono or plain handlers),
+ * zero extra machinery: it's just `Bun.serve`.
+ */
+
+export interface ServedApp {
+  /** Navigate a window here: `createWindow({ url: served.url })`. */
+  readonly url: string;
+  readonly port: number;
+  /** Stop the server. Windows navigating to `url` afterwards will fail. */
+  readonly stop: () => void;
+}
+
+/** Serve app content on a free 127.0.0.1 port from a fetch-style handler. */
+export function serveApp(handler: (req: Request) => Response | Promise<Response>): ServedApp {
+  const server = Bun.serve({
+    hostname: "127.0.0.1",
+    port: 0,
+    fetch: (req: Request): Response | Promise<Response> => handler(req),
+  });
+  const { port } = server;
+  if (typeof port !== "number") throw new Error("bun-webview2: Bun.serve did not report an assigned port");
+  return {
+    url: `http://127.0.0.1:${port}`,
+    port,
+    stop: () => {
+      server.stop(true);
+    },
+  };
+}