bun-webview2 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.4.0 — 2026-10-14
+
+- **The window host is now a native executable.** After the 2026-10-14 Windows security updates, WebView2 environment creation faults at address 0x0 inside `EmbeddedBrowserWebView.dll` when hosted by `bun.exe` — any thread, any loader mode — while plain native executables work (verified by differential testing: C# WinForms ✅, plain C++ statically linked ✅, plain C++ via `LoadLibrary` ✅, Bun ❌). The host (`src/host-ffi.ts`, a Bun process driving the C library via `bun:ffi`) is replaced by `native/runner.exe`: a ~250-line C++ executable compiled with `zig c++` against the vendored webview library.
+- The runner owns the window, the Win32 message loop, the WndProc subclass, and the native command handler; events flow as JSON lines on stdout. `src/host-ffi.ts` and `native/webview.dll` are gone — the runner statically links the C library. `native/` now ships `runner.exe`, `WebView2Loader.dll`, and the `runner.cc` source (build command in its header).
+- Vendored C library patches, required for the updated OS/runtime combo: a real `ICoreWebView2EnvironmentOptions` object (null options fault after the update; the object must also report a `TargetCompatibleBrowserVersion`, e.g. the SDK's, or the runtime rejects creation with `E_INVALIDARG`), and the standalone WebView2 runtime (`EdgeWebView\Application`) preferred over the Edge channel's stale copy when the user hasn't chosen one explicitly.
+- Public API unchanged: verify 21/21. Benchmarks: cold start ~0.85–0.9 s, evaluate ~0.8 ms, IPC ~0.75 ms, navigation ~140 ms — same class as the previous architecture, and the runner process is ~4 MB instead of a ~40 MB Bun child per window.
+- `icon` window option: path to an `.ico` file, applied by the runner via `WM_SETICON` + class icon + an AppUserModelID derived from the title (taskbar groups/labels your app, not "runner"). The window belongs to the runner process, so application icons must be set this way — `rcedit` on your own exe no longer reaches the window.
+
 ## 0.3.1 — 2026-10-13
 
 - `minWidth`/`minHeight` window options: minimum window size in client

package/LICENSE

@@ -2,7 +2,7 @@ MIT License
 
 Copyright (c) 2026 bun-webview2 contributors
 
-The bundled native/webview.dll incorporates source code from the webview
+The bundled native/runner.exe statically incorporates source code from the webview
 project (https://github.com/webview/webview), Copyright (c) 2017 Serge
 Zaitsev, Copyright (c) 2022 Steffen André Langnes, licensed under the MIT
 License. The WebView2 SDK headers used to compile it are Copyright (c)

package/README.md

@@ -4,7 +4,7 @@ Desktop apps with Bun on Windows — native **WebView2** windows you fully contr
 
 No browser UI. No tab strip, no address bar, no Edge "App bar", no first-run nags. Your window, your icon, your process — and sub-millisecond control of the page inside it.
 
-Zero npm runtime dependencies: the window layer is the [C `webview` library](https://github.com/webview/webview) — a single ~540 KB DLL, built once with `zig c++` (no MSVC, no cmake) and driven directly through `bun:ffi`.
+Zero npm runtime dependencies: the window layer is the [C `webview` library](https://github.com/webview/webview) compiled into a ~1 MB native runner, built once with `zig c++` (no MSVC, no cmake).
 
 ## Quick start
 
@@ -50,23 +50,23 @@ Run it with `bun run`. Close the window (or call `win.close()`) and the process
 
 ## How it works
 
-Each window is owned by a dedicated **host process** — a tiny Bun script shipped with the library (`src/host-ffi.ts`) that creates one native window through the C webview library via `bun:ffi` and nothing else. Your process drives the page over CDP:
+Each window is owned by a dedicated **host process** — `runner.exe`, a ~250-line native executable shipped with the library that creates one window through the C webview library and nothing else. Your process drives the page over CDP:
 
 ```mermaid
 graph TB
-    A["Your Bun app"] -- "spawns one per window" --> H1["host process #1\n(C webview lib via bun:ffi)"]
-    A -- "spawns one per window" --> H2["host process #2\n(C webview lib via bun:ffi)"]
+    A["Your Bun app"] -- "spawns one per window" --> H1["runner.exe #1\n(native, owns the message loop)"]
+    A -- "spawns one per window" --> H2["runner.exe #2\n(native, owns the message loop)"]
     A -- "CDP over ws://127.0.0.1:<port>" --> P1["page target #1"]
     A -- "CDP over ws://127.0.0.1:<port>" --> P2["page target #2"]
     H1 -- "renders" --> P1
     H2 -- "renders" --> P2
 ```
 
-- **One host process per window** — buys per-window crash isolation: a dying window never takes your app down.
+- **One native runner per window** — `runner.exe` (C++, ~1 MB, built with `zig c++`) owns the window and the Win32 message loop. Per-window crash isolation: a dying window never takes your app down. Native by necessity: after the 2026-10-14 Windows security updates, WebView2 environment creation faults inside `bun.exe` processes (any thread, any loader mode) while plain native executables work — verified by differential testing.
 - **Debug port** — the library passes `--remote-debugging-port` and the data folder to each host via the WebView2 loader environment variables (`WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS` / `WEBVIEW2_USER_DATA_FOLDER`). All windows of an app share one WebView2 browser process and one port; each window claims its own page target.
 - **Everything else is CDP.** Navigation, evaluation, IPC, and screenshots flow over a loopback WebSocket using Bun's built-in client. No native module is loaded in your process.
-- **Window commands ride the page.** The host's only JS runs re-entrantly inside `webview_run` — the C library's plain Win32 `GetMessage` pump, so there is no JS event loop to lose at all. Commands are CDP-evaluated as `bwv2_host_cmd(...)` in the page; the C library delivers them to the host's bind callback natively, and `webview_return` resolves the page-side promise the parent awaits — a resolved call IS the delivery confirmation. (This design came from a hard lesson: the previous wry/tao-based host's "non-blocking" pump could freeze the whole JS event loop; the C library has no loop to freeze.)
-- **Events are split by layer.** Window-level events (`move`, `resize`, `focus`/`blur` via `WM_ACTIVATE`, `theme-changed`) are forwarded from the host's subclassed window procedure. Page-surface events (`key-down`/`key-up`, `mouse-*`, `scroll`, `file-drop`) are captured as DOM events by an injected bridge and forwarded over the existing CDP binding — richer than Win32 could report (layout-aware `key`/`code`, readable `File` objects on drop) and working everywhere input actually lands, including cross-origin documents.
+- **Window commands ride the page.** Commands are CDP-evaluated as `bwv2_host_cmd(...)` in the page; the C library delivers them to the runner's native bind callback, and `webview_return` resolves the page-side promise the parent awaits — a resolved call IS the delivery confirmation. The message loop lives in pure native code: no JS event loop exists in the window-owning process at all, so neither the wry/tao pump freeze (the original architecture's failure mode) nor the Bun-process incompatibility can occur.
+- **Events are split by layer.** Window-level events (`move`, `resize`, `focus`/`blur` via `WM_ACTIVATE`, `theme-changed`) are forwarded from the runner's subclassed window procedure over stdout. Page-surface events (`key-down`/`key-up`, `mouse-*`, `scroll`, `file-drop`) are captured as DOM events by an injected bridge and forwarded over the existing CDP binding — richer than Win32 could report (layout-aware `key`/`code`, readable `File` objects on drop) and working everywhere input actually lands, including cross-origin documents.
 
 ### Why all content flows through CDP (and why windows are "primed")
 
@@ -85,6 +85,7 @@ Related, and also handled for you: on a never-navigated webview target, CDP comm
 | `title` | `string` | `"bun-webview2"` | Window title |
 | `width` / `height` | `number` | `800` / `600` | Initial window size |
 | `minWidth` / `minHeight` | `number` | — | Minimum window size (client coordinates); enforced on drags and `setSize` alike. Both must be set together. |
+| `icon` | `string` | — | Path to an `.ico` file for the window/taskbar icon. The runner (which owns the window) applies it along with an AppUserModelID derived from the title, so taskbar entries group and label as your app. |
 | `url` | `string` | — | Initial URL to load |
 | `html` | `string` | — | Initial inline HTML (loaded as a `data:` URL) |
 | `contextMenu` | `boolean` | `false` | Allow the native Chromium right-click menu (blocked by default) |
@@ -157,19 +158,14 @@ route "new window" to the running instance instead of spawning again.
 
 ## Distribution
 
-- Each window spawns a host process. In development that's `bun` running the library's `src/host.ts`; your machine needs Bun on the PATH-compatible `process.execPath`.
-- For `bun build --compile` executables, compile the host separately and point the `BWV2_HOST_EXE` environment variable at it:
-  ```bash
-  bun build --compile --minify src/host-ffi.ts --outfile host.exe   # inside node_modules: copy out first
-  BWV2_HOST_EXE=./host.exe ./your-app.exe
-  ```
-- `native/webview.dll` (and the host script, unless compiled) must ship **alongside** your binary — `bun build --compile` embeds neither.
-- Give the exe a custom icon with [rcedit](https://github.com/electron/rcedit); the window inherits the process icon.
+- Each window spawns `runner.exe` from the package's `native/` directory. End-user machines need only the WebView2 runtime (preinstalled on Windows 11 and current Windows 10).
+- `native/runner.exe` and `native/WebView2Loader.dll` must ship **alongside** your binary — `bun build --compile` embeds neither. For custom builds, compile `native/runner.cc` yourself (the build command is in its header comment) and point `BWV2_HOST_EXE` at it.
+- Give the app a custom icon with the `icon` option — the window belongs to the runner process, so `rcedit`-ing your own exe does not reach it.
 - WebView2 writes its user-data folder per app; if you need to control where (e.g. Program Files installs), patch `userDataFolder` at the window layer.
 
 ## Costs, honestly
 
-- Every window costs one Bun process (~40 MB) plus its share of the shared WebView2 browser tree. For 1–3 windows this is desktop-app normal.
+- Every window costs one native runner process (~4 MB) plus its share of the shared WebView2 browser tree. For 1–3 windows this is desktop-app normal.
 - One WebView2 browser process per app means one app instance at a time (see the data-folder section above).
 - The CDP debug port is a local-loopback control channel: fine for desktop apps, not for hostile multi-user machines (see security notes).
 

package/native/runner.cc

@@ -0,0 +1,349 @@
+// bun-webview2 native runner — owns one window + webview + message loop.
+//
+// This is the process that MUST NOT be a Bun process: after the 2026-10-14
+// Windows security updates, WebView2 environment creation faults at address
+// 0x0 inside EmbeddedBrowserWebView.dll when hosted by bun.exe (any thread,
+// any loader mode), while plain native executables work. The runner is a
+// plain C++ executable; the parent Bun process keeps full control of the
+// page over CDP and receives window events as JSON lines on stdout.
+//
+// Protocol (identical to the TypeScript host it replaces):
+//   argv[last]        = JSON config {title, width, height, minWidth?, minHeight?}
+//   stdout            = one JSON object per line: window events + {"event":"closed"}
+//   page -> runner    = bwv2_host_cmd("<command json>") via webview_bind;
+//                       reply flows through webview_return, so the page-side
+//                       promise the parent awaits resolves = command applied
+//
+// Build (zig c++, no MSVC, no cmake):
+//   zig c++ -std=c++17 -O2 -DWEBVIEW_MSWEBVIEW2_BUILTIN_IMPL=0 \
+//     -I <webview-src>/core/include -I <webview-src>/compatibility/mingw/include \
+//     -I <webview2-sdk>/build/native/include \
+//     native/runner.cc <webview-src>/core/src/webview.cc \
+//     <webview2-sdk>/build/native/x64/WebView2Loader.dll.lib \
+//     -ladvapi32 -lole32 -lshell32 -lshlwapi -luser32 -lversion \
+//     -o native/runner.exe
+
+#include "webview/webview.h"
+#include "webview/detail/json.hh"
+
+#include <windows.h>
+#include <shellapi.h>
+#include <propsys.h>
+#include <shobjidl.h>
+#include <propkey.h>
+#include <shlwapi.h>
+#include <cstdio>
+#include <cstring>
+#include <filesystem>
+#include <string>
+
+namespace {
+
+// --- window events via WndProc subclassing ---------------------------------
+// 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 by the parent's injected bridge.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+void emit(const std::string &line) {
+  std::fputs(line.c_str(), stdout);
+  std::fputc('\n', stdout);
+  std::fflush(stdout);
+}
+
+void emit_event(const std::string &name, const std::string &fields = "") {
+  emit("{\"event\":\"" + name + "\"" + (fields.empty() ? "" : "," + fields) + "}");
+}
+
+std::string number(double v) {
+  auto as_long = static_cast<long long>(v);
+  if (v == static_cast<double>(as_long)) {
+    return std::to_string(as_long);
+  }
+  return std::to_string(v);
+}
+
+webview_t g_handle = nullptr;
+HWND g_hwnd = nullptr;
+WNDPROC g_original_proc = nullptr;
+
+std::string theme_text() {
+  DWORD value = 0;
+  DWORD size = sizeof(value);
+  if (RegGetValueW(HKEY_CURRENT_USER,
+                   L"Software\\Microsoft\\Windows\\CurrentVersion\\Themes\\Personalize",
+                   L"AppsUseLightTheme", RRF_RT_REG_DWORD, nullptr, &value, &size) == 0 &&
+      value == 1) {
+    return "light";
+  }
+  return "dark";
+}
+
+LRESULT CALLBACK runner_wndproc(HWND hwnd, UINT msg, WPARAM wp, LPARAM lp) {
+  switch (msg) {
+  case WM_MOVE:
+    emit_event("move",
+               "\"x\":" + std::to_string(static_cast<short>(LOWORD(lp))) +
+                   ",\"y\":" + std::to_string(static_cast<short>(HIWORD(lp))));
+    break;
+  case WM_SIZE:
+    emit_event("resize",
+               "\"width\":" + std::to_string(LOWORD(lp)) +
+                   ",\"height\":" + std::to_string(HIWORD(lp)));
+    break;
+  case WM_ACTIVATE:
+    // window activation: clicks on the page activate the top window too,
+    // unlike WM_SETFOCUS which the WebView2 child HWND claims
+    emit_event(LOWORD(wp) != 0 ? "focus" : "blur");
+    break;
+  case WM_THEMECHANGED:
+    emit_event("theme-changed", "\"text\":\"" + theme_text() + "\"");
+    break;
+  default:
+    break;
+  }
+  if (g_original_proc != nullptr) {
+    return CallWindowProcW(g_original_proc, hwnd, msg, wp, lp);
+  }
+  return DefWindowProcW(hwnd, msg, wp, lp);
+}
+
+// --- command channel: page -> webview_bind -> here ------------------------
+
+std::string apply_command(const std::string &op, const std::string &args_json) {
+  const auto arg = [&args_json](int index) {
+    return webview::detail::json_parse(args_json, "", index);
+  };
+  if (op == "hello") {
+    return "true";
+  }
+  if (op == "setTitle") {
+    webview_set_title(g_handle, arg(0).c_str());
+    return "0";
+  }
+  if (op == "setSize") {
+    webview_set_size(g_handle, std::atoi(arg(0).c_str()), std::atoi(arg(1).c_str()),
+                     WEBVIEW_HINT_NONE);
+    return "0";
+  }
+  if (op == "setPosition") {
+    SetWindowPos(g_hwnd, nullptr, std::atoi(arg(0).c_str()), std::atoi(arg(1).c_str()), 0, 0,
+                 SWP_NOSIZE | SWP_NOZORDER | SWP_NOACTIVATE);
+    return "0";
+  }
+  if (op == "setDecorations") {
+    auto current = GetWindowLongPtrW(g_hwnd, GWL_STYLE);
+    auto masked = current & ~WS_OVERLAPPEDWINDOW;
+    auto updated = arg(0) == "true" ? masked | WS_OVERLAPPEDWINDOW : masked;
+    SetWindowLongPtrW(g_hwnd, GWL_STYLE, updated);
+    SetWindowPos(g_hwnd, nullptr, 0, 0, 0, 0,
+                 SWP_NOMOVE | SWP_NOSIZE | SWP_NOZORDER | SWP_FRAMECHANGED);
+    return "0";
+  }
+  if (op == "setAlwaysOnTop") {
+    SetWindowPos(g_hwnd, arg(0) == "true" ? HWND_TOPMOST : HWND_NOTOPMOST, 0, 0, 0, 0,
+                 SWP_NOMOVE | SWP_NOSIZE);
+    return "0";
+  }
+  if (op == "focus") {
+    return std::to_string(SetForegroundWindow(g_hwnd));
+  }
+  if (op == "minimize") {
+    return std::to_string(ShowWindow(g_hwnd, SW_MINIMIZE));
+  }
+  if (op == "maximize") {
+    return std::to_string(ShowWindow(g_hwnd, SW_MAXIMIZE));
+  }
+  if (op == "close") {
+    // restore the original procedure before tearing the window down
+    if (g_original_proc != nullptr) {
+      SetWindowLongPtrW(g_hwnd, GWLP_WNDPROC, reinterpret_cast<LONG_PTR>(g_original_proc));
+      g_original_proc = nullptr;
+    }
+    webview_terminate(g_handle);
+    return "true";
+  }
+  return "null";
+}
+
+void on_command(const char *id, const char *req, void * /*arg*/) {
+  // req is a JSON array of the call arguments; element 0 is our command payload
+  auto payload = webview::detail::json_parse(req, "", 0);
+  const auto op = webview::detail::json_parse(payload, "op", 0);
+  const auto args = webview::detail::json_parse(payload, "args", 0);
+  std::string result = "null";
+  try {
+    result = apply_command(op, args);
+  } catch (const std::exception &e) {
+    std::fprintf(stderr, "[runner] command '%s' failed: %s\n", op.c_str(), e.what());
+  }
+  webview_return(g_handle, id, 0, result.c_str());
+}
+
+// --- app icon and taskbar identity -----------------------------------------
+// The runner owns the HWND, so the app's icon must be applied here: the C
+// library sets a generic stock icon on its window class. An AppUserModelID
+// makes Windows group and label the window as the app, not as "runner".
+
+bool apply_icon(const std::string &icon_path, const std::string &app_name) {
+  if (icon_path.empty()) {
+    return false;
+  }
+  std::wstring wide_path(icon_path.size(), L'\0');
+  auto path_len = MultiByteToWideChar(CP_UTF8, MB_ERR_INVALID_CHARS, icon_path.c_str(),
+                                      static_cast<int>(icon_path.size()), wide_path.data(),
+                                      static_cast<int>(icon_path.size()));
+  if (path_len <= 0) {
+    return false;
+  }
+  wide_path.resize(path_len);
+  auto big = LoadImageW(nullptr, wide_path.c_str(), IMAGE_ICON, GetSystemMetrics(SM_CXICON),
+                         GetSystemMetrics(SM_CYICON), LR_LOADFROMFILE);
+  auto small = LoadImageW(nullptr, wide_path.c_str(), IMAGE_ICON, 16, 16, LR_LOADFROMFILE);
+  if (big == nullptr && small == nullptr) {
+    std::fprintf(stderr, "[runner] icon load failed: %s (GetLastError=%lu)\n",
+                  icon_path.c_str(), GetLastError());
+    return false;
+  }
+  if (big != nullptr) {
+    SendMessageW(g_hwnd, WM_SETICON, ICON_BIG, reinterpret_cast<LPARAM>(big));
+  }
+  if (small != nullptr) {
+    SendMessageW(g_hwnd, WM_SETICON, ICON_SMALL, reinterpret_cast<LPARAM>(small));
+  }
+  // update the class icon so future windows of the same class inherit it
+  if (big != nullptr) {
+    SetClassLongPtrW(g_hwnd, GCLP_HICON, reinterpret_cast<LONG_PTR>(static_cast<HICON>(big)));
+  }
+
+  // AppUserModelID: taskbar groups by this, so set it per app (falls back to
+  // the runner's identity when absent)
+  if (!app_name.empty()) {
+    std::wstring aumid(L"bun-webview2.");
+    aumid += std::wstring(app_name.begin(), app_name.end());
+    for (auto &c : aumid) {
+      if (c == L' ' || c == L'.' || c == L'\\' || c == L'/') {
+        c = L'_';
+      }
+    }
+    // the shell reads AUMID from the property store — the only mechanism
+    // that matters; SetPropW would be a no-op that leaks a global atom
+    IPropertyStore *store = nullptr;
+    auto hwnd_ptr = static_cast<HWND>(g_hwnd);
+    if (SUCCEEDED(SHGetPropertyStoreForWindow(hwnd_ptr, IID_IPropertyStore,
+                                             reinterpret_cast<void **>(&store)))) {
+      PROPVARIANT variant;
+      PropVariantInit(&variant);
+      variant.vt = VT_LPWSTR;
+      variant.pwszVal = const_cast<LPWSTR>(aumid.c_str());
+      store->SetValue(PKEY_AppUserModel_ID, variant);
+      store->Release();
+    }
+  }
+  return true;
+}
+
+// --- standalone runtime resolution -----------------------------------------
+// Windows Update services the standalone WebView2 runtime
+// (EdgeWebView\Application) while the Edge channel's copy can go stale and
+// crash on environment creation. Prefer the standalone tree when present.
+
+void resolve_standalone_runtime() {
+  if (GetEnvironmentVariableW(L"WEBVIEW2_BROWSER_EXECUTABLE_FOLDER", nullptr, 0) != 0) {
+    return; // explicit user choice
+  }
+  const std::wstring root = L"C:\\Program Files (x86)\\Microsoft\\EdgeWebView\\Application";
+  std::error_code ec;
+  if (!std::filesystem::is_directory(root, ec)) {
+    return;
+  }
+  std::wstring newest;
+  for (const auto &entry : std::filesystem::directory_iterator(root, ec)) {
+    if (!entry.is_directory()) {
+      continue;
+    }
+    const auto dir = entry.path().filename().wstring();
+    if (dir.find_first_not_of(L"0123456789.") != std::wstring::npos) {
+      continue; // version-shaped names only
+    }
+    if (!std::filesystem::exists(entry.path() / L"msedgewebview2.exe", ec)) {
+      continue;
+    }
+    if (newest.empty() || dir > newest) {
+      newest = dir;
+    }
+  }
+  if (!newest.empty()) {
+    const auto folder = root + L"\\" + newest;
+    SetEnvironmentVariableW(L"WEBVIEW2_BROWSER_EXECUTABLE_FOLDER", folder.c_str());
+  }
+}
+
+} // namespace
+
+int main(int argc, char **argv) {
+  const std::string config =
+      argc > 1 ? argv[argc - 1] : "{}";
+  const auto title = webview::detail::json_parse(config, "title", 0);
+  const auto width = webview::detail::json_parse(config, "width", 0);
+  const auto height = webview::detail::json_parse(config, "height", 0);
+  const auto min_width = webview::detail::json_parse(config, "minWidth", 0);
+  const auto min_height = webview::detail::json_parse(config, "minHeight", 0);
+  const auto icon_path = webview::detail::json_parse(config, "icon", 0);
+
+  resolve_standalone_runtime();
+
+  g_handle = webview_create(0, nullptr);
+  if (g_handle == nullptr) {
+    std::fprintf(stderr, "[runner] webview_create failed\n");
+    return 1;
+  }
+  g_hwnd = static_cast<HWND>(webview_get_window(g_handle));
+  g_original_proc = reinterpret_cast<WNDPROC>(SetWindowLongPtrW(
+      g_hwnd, GWLP_WNDPROC, reinterpret_cast<LONG_PTR>(runner_wndproc)));
+
+  webview_set_title(g_handle,
+                     (title.empty() ? "bun-webview2" : title).c_str());
+  webview_set_size(g_handle, width.empty() ? 800 : std::atoi(width.c_str()),
+                   height.empty() ? 600 : std::atoi(height.c_str()), WEBVIEW_HINT_NONE);
+  if (!min_width.empty() && !min_height.empty()) {
+    // the track-size minimum is in OUTER coordinates; compensate the frame
+    // so the minimum applies to the client area
+    RECT outer{};
+    RECT inner{};
+    GetWindowRect(g_hwnd, &outer);
+    GetClientRect(g_hwnd, &inner);
+    const auto frame_w = (outer.right - outer.left) - (inner.right - inner.left);
+    const auto frame_h = (outer.bottom - outer.top) - (inner.bottom - inner.top);
+    webview_set_size(g_handle, std::atoi(min_width.c_str()) + frame_w,
+                     std::atoi(min_height.c_str()) + frame_h, WEBVIEW_HINT_MIN);
+  }
+  webview_bind(g_handle, "bwv2_host_cmd", on_command, nullptr);
+  apply_icon(icon_path, title.empty() ? "app" : title);
+  // inert initial document; the parent drives all real content over CDP
+  webview_navigate(g_handle, "about:blank");
+
+  webview_run(g_handle);
+  // run() returning means the window closed (user close or the "close" op)
+  emit_event("closed");
+  return 0;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bun-webview2",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "main": "./src/index.ts",
   "module": "./src/index.ts",
   "devDependencies": {

package/src/window.ts

@@ -33,6 +33,8 @@ export interface Webview2WindowOptions extends HardeningOptions {
   readonly minWidth?: number;
   /** @see minWidth */
   readonly minHeight?: number;
+  /** Path to an .ico file shown as the window/taskbar icon. The runner owns the HWND, so it applies it there. */
+  readonly icon?: string;
   /** Initial URL to load. */
   readonly url?: string;
   /** Initial inline HTML to load (delivered as a data: URL). */
@@ -128,21 +130,30 @@ class WindowHost {
   readonly #eventWaiters = new Set<(event: string, payload: unknown) => void>();
 
   constructor(
-    readonly options: { title: string; width: number; height: number; minWidth?: number; minHeight?: number },
+    readonly options: {
+      title: string;
+      width: number;
+      height: number;
+      minWidth?: number;
+      minHeight?: number;
+      icon?: string;
+    },
   ) {
     const config = JSON.stringify(options);
-    // Compiled executables re-run themselves instead of acting as a runtime,
-    // so shipped apps point BWV2_HOST_EXE at a pre-compiled host binary.
-    // host-ffi.ts drives the C webview library directly via bun:ffi.
+    // The runner is a plain native executable: after the 2026-10-14 Windows
+    // security updates, WebView2 environment creation faults inside bun.exe
+    // processes (any thread, any loader mode) while native executables work.
+    // Shipped apps can point BWV2_HOST_EXE at their own runner build.
     const command = Bun.env.BWV2_HOST_EXE
       ? [Bun.env.BWV2_HOST_EXE]
-      : [process.execPath, `${import.meta.dir}/host-ffi.ts`];
+      : [`${import.meta.dir}/../native/runner.exe`];
     this.#child = Bun.spawn([...command, config], {
       stdin: "ignore",
       stdout: "pipe",
       stderr: "inherit",
       env: {
         ...Bun.env,
+        // runner.exe resolves WebView2Loader.dll from its own directory
         WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS: `--remote-debugging-port=${activePort}`,
         WEBVIEW2_USER_DATA_FOLDER: activeDataDir,
       },
@@ -278,6 +289,7 @@ export class Webview2Window {
       height: opts.height ?? 600,
       minWidth: opts.minWidth,
       minHeight: opts.minHeight,
+      icon: opts.icon,
     });
 
     const target: CdpTargetInfo = await waitForPageTarget(activePort, claimedTargets, 15_000, activeDataDir);

package/src/host-ffi.ts

@@ -1,264 +0,0 @@
-/**
- * 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;
-  readonly minWidth?: number;
-  readonly minHeight?: 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 WEBVIEW_HINT_MIN = 1;
-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);
-if (typeof config.minWidth === "number" && typeof config.minHeight === "number") {
-  // WEBVIEW_HINT_MIN stores m_minsz; WM_GETMINMAXINFO enforces it on drags
-  // and programmatic resizes alike. The track size is in OUTER coordinates,
-  // so the frame delta is added to keep the minimum a CLIENT-size minimum.
-  const outer = Buffer.alloc(16);
-  const inner = Buffer.alloc(16);
-  user32.symbols.GetWindowRect(hwnd, ptr(outer));
-  user32.symbols.GetClientRect(hwnd, ptr(inner));
-  const frameW = outer.readInt32LE(8) - outer.readInt32LE(0) - (inner.readInt32LE(8) - inner.readInt32LE(0));
-  const frameH = outer.readInt32LE(12) - outer.readInt32LE(4) - (inner.readInt32LE(12) - inner.readInt32LE(4));
-  webview.symbols.webview_set_size(
-    handle,
-    Math.max(1, config.minWidth + frameW),
-    Math.max(1, config.minHeight + frameH),
-    WEBVIEW_HINT_MIN,
-  );
-}
-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);