bunite-core 0.12.1 → 0.16.0

package/src/native/win-webview2/webview2_internal.h

@@ -17,6 +17,7 @@
 #include <fstream>
 #include <functional>
 #include <map>
+#include <unordered_map>
 #include <memory>
 #include <mutex>
 #include <optional>
@@ -86,6 +87,28 @@ struct ViewHost {
 
   std::atomic<bool> ready{false};
   std::atomic<bool> closing{false};
+
+  // Download policy: 0=auto, 1=ask, 2=block. Default block (current behavior).
+  std::atomic<int32_t> download_policy{2};
+  std::string download_dir;  // optional; falls back to backend default temp dir.
+
+  // Pending page-initiated dialogs (alert/confirm/prompt/beforeunload).
+  // ScriptDialogOpening hands us a `Deferral` we Complete() on host response.
+  struct PendingDialog {
+    ComPtr<ICoreWebView2ScriptDialogOpeningEventArgs> args;
+    ComPtr<ICoreWebView2Deferral> deferral;
+  };
+  std::unordered_map<uint32_t, PendingDialog> pending_dialogs;
+  uint32_t next_dialog_request_id = 1;
+
+  // OOPIF input dispatch — populated by Target.attachedToTarget events after
+  // lazy Target.setAutoAttach. frameId → sessionId for flatten:true routing.
+  std::atomic<bool> oopif_autoattach_armed{false};
+  std::mutex oopif_sessions_mutex;
+  std::unordered_map<std::string, std::string> oopif_sessions;
+  EventRegistrationToken target_attached_token{};
+  EventRegistrationToken target_detached_token{};
+  bool oopif_event_tokens_registered = false;
 };
 
 struct WindowHost {
@@ -106,6 +129,7 @@ struct RuntimeState {
   std::atomic<bool> initialized{false};
   std::atomic<bool> shutting_down{false};
   HWND message_window = nullptr;
+  HWND popup_parent = nullptr;  // hidden top-level parking parent for popup-minted controllers.
 
   std::mutex task_mutex;
   std::deque<std::function<void()>> queued_tasks;
@@ -205,6 +229,7 @@ std::wstring exeDir();
 uint32_t permissionKindToBuniteBit(COREWEBVIEW2_PERMISSION_KIND kind);
 COREWEBVIEW2_PERMISSION_STATE buniteStateToWebView2(uint32_t state);
 
+bool shouldAlwaysAllowNavigationUrl(const std::string& url);
 bool shouldAllowNavigation(const ViewHost* view, const std::string& url);
 
 }  // namespace bunite_webview2

package/src/native/win-webview2/webview2_runtime.cpp

@@ -1,6 +1,7 @@
 #include "webview2_internal.h"
 
 #include <algorithm>
+#include <unordered_map>
 
 using Microsoft::WRL::Callback;
 using Microsoft::WRL::ComPtr;
@@ -10,6 +11,14 @@ namespace bunite_webview2 {
 
 RuntimeState g_runtime;
 
+// Pending nav URI by (view_id, nav_id) — NavigationCompleted's get_Source()
+// returns the previous committed URL on provisional failure, so we stash the
+// URI at NavigationStarting and look it up on completion.
+static std::unordered_map<uint64_t, std::string> g_nav_uris;
+static uint64_t navKey(uint32_t view_id, uint64_t nav_id) {
+  return (static_cast<uint64_t>(view_id) << 56) ^ nav_id;
+}
+
 static HINSTANCE g_module = nullptr;
 static bool g_co_initialized = false;
 
@@ -121,7 +130,28 @@ bool registerWindowClasses() {
                                               0, 0, 0, 0, 0,
                                               HWND_MESSAGE, nullptr,
                                               getCurrentModuleHandle(), nullptr);
-  return g_runtime.message_window != nullptr;
+  if (!g_runtime.message_window) return false;
+
+  // Popup parking parent — a hidden top-level window. Children of HWND_MESSAGE
+  // can't render (WebView2 child controllers won't initialize), so popup-minted
+  // controllers live here until accept reparents to the user-visible host.
+  g_runtime.popup_parent = CreateWindowExW(
+      WS_EX_TOOLWINDOW, mc.lpszClassName, L"BunitePopupPark",
+      WS_POPUP, 0, 0, 0, 0,
+      nullptr, nullptr, getCurrentModuleHandle(), nullptr);
+  if (!g_runtime.popup_parent) return false;
+
+  // `bun run` passes STARTF_USESHOWWINDOW + SW_HIDE; Win documented behavior
+  // is for the first ShowWindow call to use STARTUPINFO.wShowWindow instead
+  // of the requested nCmdShow. Consume it here on the message window so the
+  // first user-visible window's ShowWindow honors its argument.
+  STARTUPINFOW si{};
+  si.cb = sizeof(si);
+  GetStartupInfoW(&si);
+  if ((si.dwFlags & STARTF_USESHOWWINDOW) && si.wShowWindow == SW_HIDE) {
+    ShowWindow(g_runtime.message_window, SW_HIDE);
+  }
+  return true;
 }
 
 // ---- environment bootstrap -----------------------------------------------
@@ -282,6 +312,19 @@ LRESULT CALLBACK messageProc(HWND hwnd, UINT msg, WPARAM wp, LPARAM lp) {
 
 // ---- init / shutdown ----------------------------------------------------
 
+// KILL_ON_JOB_CLOSE — Edge helpers die with bun.exe instead of holding the
+// UDF SingletonLock. Handle leaked intentionally (kernel closes on exit).
+static void reapChildrenOnExit() {
+  HANDLE job = CreateJobObjectW(nullptr, nullptr);
+  if (!job) return;
+  JOBOBJECT_EXTENDED_LIMIT_INFORMATION info{};
+  info.BasicLimitInformation.LimitFlags = JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE;
+  if (!SetInformationJobObject(job, JobObjectExtendedLimitInformation, &info, sizeof(info)) ||
+      !AssignProcessToJobObject(job, GetCurrentProcess())) {
+    CloseHandle(job);  // already in a non-nestable job, etc — give up.
+  }
+}
+
 bool initRuntime(const char* engine_dir, bool /*hide_console*/,
                  bool popup_blocking, const char* engine_config_json) {
   buniteApplyEnvLogLevel();
@@ -289,6 +332,8 @@ bool initRuntime(const char* engine_dir, bool /*hide_console*/,
               (engine_dir && *engine_dir) ? engine_dir : "(null)");
   if (g_runtime.initialized.load()) return true;
 
+  reapChildrenOnExit();
+
   HRESULT co = CoInitializeEx(nullptr, COINIT_APARTMENTTHREADED | COINIT_DISABLE_OLE1DDE);
   if (SUCCEEDED(co)) g_co_initialized = true;
   else if (co != RPC_E_CHANGED_MODE) {
@@ -598,15 +643,42 @@ static void wireView(ViewHost* view, std::function<void()> on_attached) {
             //  - main frame only (matching CEF's OnContextCreated main-frame gate)
             //  - origin allowlist when `preload_origins` is non-empty
             // Empty allowlist = inject on every main frame (CEF parity default).
-            if (!v->preload_script.empty() && v->webview) {
+            //
+            // AddScriptToExecuteOnDocumentCreated is async — registration must
+            // complete BEFORE Navigate() or the first document load runs without
+            // the preload. Defer Navigate into the completion handler.
+            const bool inject = !v->preload_script.empty() && v->webview;
+            auto doInitialNav = [v]() {
+              if (!v->url.empty()) {
+                BUNITE_INFO("webview2/preload-race: view=%u t=%llu navigate-call url=%.200s%s",
+                            v->id, static_cast<unsigned long long>(GetTickCount64()),
+                            v->url.c_str(), v->url.size() > 200 ? "..." : "");
+                v->webview->Navigate(utf8ToWide(v->url).c_str());
+              } else if (!v->html.empty()) {
+                BUNITE_INFO("webview2/preload-race: view=%u t=%llu navigate-tostring-call",
+                            v->id, static_cast<unsigned long long>(GetTickCount64()));
+                v->webview->NavigateToString(utf8ToWide(v->html).c_str());
+              }
+            };
+            if (inject) {
               std::string allowlist = "[";
               for (size_t i = 0; i < v->preload_origins.size(); ++i) {
                 if (i) allowlist += ",";
                 allowlist += "\"" + escapeJsonString(v->preload_origins[i]) + "\"";
               }
               allowlist += "]";
+              // Diagnostic IIFE-start/end markers, gated by log level. Leading
+              // `;` defends against preload_script with no trailing semicolon.
+              const bool emitMarkers = buniteShouldLog(BuniteLogLevel::Info);
+              const char* markerStart = emitMarkers
+                  ? ";try{(self.chrome&&chrome.webview&&chrome.webview.postMessage)&&chrome.webview.postMessage('__bunite_preload_iife_start__');}catch(_){}"
+                  : "";
+              const char* markerEnd = emitMarkers
+                  ? ";try{(self.chrome&&chrome.webview&&chrome.webview.postMessage)&&chrome.webview.postMessage('__bunite_preload_iife_end__');}catch(_){}"
+                  : "";
               std::string body =
-                  "(function(){if(window.self!==window.top)return;"
+                  "(function(){"
+                  "if(window.self!==window.top)return;"
                   "var __a=" + allowlist +
                   ",__o=location.origin;"
                   "if(__a.length){var __m=function(p,v){var i=0,j=0,s=-1,k=0,L=function(c){return c.charCodeAt(0)|32;};"
@@ -616,26 +688,32 @@ static void wireView(ViewHost* view, std::function<void()> on_attached) {
                   "while(i<p.length&&p[i]===\"*\")i++;return i===p.length;};"
                   "var __ok=false;for(var i=0;i<__a.length;i++){if(__m(__a[i],__o)){__ok=true;break;}}"
                   "if(!__ok)return;}"
-                  + v->preload_script +
+                  + markerStart
+                  + v->preload_script
+                  + markerEnd +
                   "})();";
               std::wstring wpreload = utf8ToWide(body);
               auto lt = lifetime;
+              BUNITE_INFO("webview2/preload-race: view=%u t=%llu addscript-request",
+                          view_id, static_cast<unsigned long long>(GetTickCount64()));
               v->webview->AddScriptToExecuteOnDocumentCreated(
                   wpreload.c_str(),
                   Callback<ICoreWebView2AddScriptToExecuteOnDocumentCreatedCompletedHandler>(
-                      [lt, view_id](HRESULT, LPCWSTR id) -> HRESULT {
+                      [lt, view_id, doInitialNav](HRESULT hr, LPCWSTR id) -> HRESULT {
                         if (!lt || !lt->alive.load()) return S_OK;
+                        if (FAILED(hr)) {
+                          BUNITE_ERROR("AddScriptToExecuteOnDocumentCreated failed hr=0x%08x", static_cast<unsigned>(hr));
+                        }
                         ViewHost* vv = getView(view_id);
                         if (vv && id) vv->add_script_id = id;
+                        BUNITE_INFO("webview2/preload-race: view=%u t=%llu addscript-completion hr=0x%08x",
+                                    view_id, static_cast<unsigned long long>(GetTickCount64()),
+                                    static_cast<unsigned>(hr));
+                        doInitialNav();
                         return S_OK;
                       }).Get());
-            }
-
-            // Initial navigation.
-            if (!v->url.empty()) {
-              v->webview->Navigate(utf8ToWide(v->url).c_str());
-            } else if (!v->html.empty()) {
-              v->webview->NavigateToString(utf8ToWide(v->html).c_str());
+            } else {
+              doInitialNav();
             }
 
             emitWebviewEvent(v->id, "view-ready");
@@ -719,6 +797,19 @@ void destroyView(uint32_t id) {
     vs.erase(std::remove(vs.begin(), vs.end(), v), vs.end());
   }
 
+  // Remove DevTools event-receiver tokens before tearing down the webview to
+  // avoid AVs on event delivery after controller release.
+  if (v->oopif_event_tokens_registered && v->webview) {
+    ComPtr<ICoreWebView2DevToolsProtocolEventReceiver> attached_r, detached_r;
+    if (SUCCEEDED(v->webview->GetDevToolsProtocolEventReceiver(L"Target.attachedToTarget", &attached_r))) {
+      attached_r->remove_DevToolsProtocolEventReceived(v->target_attached_token);
+    }
+    if (SUCCEEDED(v->webview->GetDevToolsProtocolEventReceiver(L"Target.detachedFromTarget", &detached_r))) {
+      detached_r->remove_DevToolsProtocolEventReceived(v->target_detached_token);
+    }
+    v->oopif_event_tokens_registered = false;
+  }
+
   // Defer Close() → container destroy → delete across three pump ticks. Edge
   // gets at least one tick after Close() to settle before its parent HWND
   // vanishes; see shutdownRuntime's staged drains for the same reason.
@@ -766,9 +857,13 @@ static void attachControllerCallbacks(ViewHost* view) {
   if (!view->webview) return;
   auto lifetime = g_runtime.lifetime;
   uint32_t view_id = view->id;
+  // Token reuse OK — controller->Close() releases all add_* handlers.
   EventRegistrationToken tok;
 
-  // NavigationStarting — enforce navigation rules, emit "will-navigate" event.
+  // NavigationStarting — emit "will-navigate" (parity with CEF/mac/linux,
+  // which fire regardless of allow), then cancel if nav rules say block.
+  // Also emit "load-start" for the surfaceEvents stream + stash URI for
+  // NavigationCompleted lookup (failure case: get_Source() returns prior URL).
   view->webview->add_NavigationStarting(
       Callback<ICoreWebView2NavigationStartingEventHandler>(
           [lifetime, view_id](ICoreWebView2*, ICoreWebView2NavigationStartingEventArgs* args) -> HRESULT {
@@ -779,34 +874,149 @@ static void attachControllerCallbacks(ViewHost* view) {
             args->get_Uri(&uri_raw);
             std::string url = wideToUtf8(uri_raw);
             if (uri_raw) CoTaskMemFree(uri_raw);
+            BUNITE_INFO("webview2/preload-race: view=%u t=%llu nav-starting url=%.200s%s",
+                        view_id, static_cast<unsigned long long>(GetTickCount64()),
+                        url.c_str(), url.size() > 200 ? "..." : "");
+            emitWebviewEvent(v->id, "will-navigate", url);
             if (!shouldAllowNavigation(v, url)) {
               args->put_Cancel(TRUE);
               return S_OK;
             }
-            emitWebviewEvent(v->id, "will-navigate", url);
+            UINT64 nav_id = 0;
+            args->get_NavigationId(&nav_id);
+            g_nav_uris[navKey(view_id, nav_id)] = url;
+            emitWebviewEvent(v->id, "load-start", url);
             return S_OK;
           }).Get(),
       &tok);
 
-  // NavigationCompleted — surfaced as did-navigate + dom-ready (CEF parity).
-  view->webview->add_NavigationCompleted(
-      Callback<ICoreWebView2NavigationCompletedEventHandler>(
-          [lifetime, view_id](ICoreWebView2* wv, ICoreWebView2NavigationCompletedEventArgs* args) -> HRESULT {
+  // SourceChanged — URL commit point; map to did-navigate (surfaceEvents
+  // `navigate` arm). Distinct from NavigationCompleted which fires later.
+  view->webview->add_SourceChanged(
+      Callback<ICoreWebView2SourceChangedEventHandler>(
+          [lifetime, view_id](ICoreWebView2* wv, ICoreWebView2SourceChangedEventArgs*) -> HRESULT {
             if (!lifetime || !lifetime->alive.load()) return S_OK;
-            BOOL ok = FALSE;
-            args->get_IsSuccess(&ok);
-            if (!ok) return S_OK;
             LPWSTR src_raw = nullptr;
             if (wv) wv->get_Source(&src_raw);
             std::string url = wideToUtf8(src_raw);
             if (src_raw) CoTaskMemFree(src_raw);
             emitWebviewEvent(view_id, "did-navigate", url);
-            emitWebviewEvent(view_id, "dom-ready", url);
             return S_OK;
           }).Get(),
       &tok);
 
-  // DocumentTitleChanged — surface for automation `titleChanged` stream.
+  // NavigationCompleted — load lifecycle terminator. Success → load-finish
+  // + dom-ready; failure → load-fail with WebErrorStatus as reason. Use the
+  // URI we stashed at NavigationStarting — get_Source() returns the prior
+  // committed URL on provisional-navigation failure.
+  view->webview->add_NavigationCompleted(
+      Callback<ICoreWebView2NavigationCompletedEventHandler>(
+          [lifetime, view_id](ICoreWebView2* wv, ICoreWebView2NavigationCompletedEventArgs* args) -> HRESULT {
+            if (!lifetime || !lifetime->alive.load()) return S_OK;
+            BOOL ok = FALSE;
+            args->get_IsSuccess(&ok);
+            UINT64 nav_id = 0;
+            args->get_NavigationId(&nav_id);
+            BUNITE_INFO("webview2/preload-race: view=%u t=%llu nav-completed ok=%d nav_id=%llu",
+                        view_id, static_cast<unsigned long long>(GetTickCount64()),
+                        ok ? 1 : 0, static_cast<unsigned long long>(nav_id));
+            std::string url;
+            auto it = g_nav_uris.find(navKey(view_id, nav_id));
+            if (it != g_nav_uris.end()) {
+              url = std::move(it->second);
+              g_nav_uris.erase(it);
+            } else {
+              LPWSTR src_raw = nullptr;
+              if (wv) wv->get_Source(&src_raw);
+              url = wideToUtf8(src_raw);
+              if (src_raw) CoTaskMemFree(src_raw);
+            }
+            if (ok) {
+              emitWebviewEvent(view_id, "load-finish", url);
+              emitWebviewEvent(view_id, "dom-ready", url);
+            } else {
+              COREWEBVIEW2_WEB_ERROR_STATUS status = COREWEBVIEW2_WEB_ERROR_STATUS_UNKNOWN;
+              args->get_WebErrorStatus(&status);
+              std::string payload = "{\"url\":\"" + escapeJsonString(url) +
+                                    "\",\"reason\":\"WebErrorStatus_" + std::to_string(static_cast<int>(status)) + "\"}";
+              emitWebviewEvent(view_id, "load-fail", payload);
+            }
+            return S_OK;
+          }).Get(),
+      &tok);
+
+  // Disable default WV2 dialog UI so ScriptDialogOpening drives all dialogs.
+  ComPtr<ICoreWebView2Settings> settings;
+  if (SUCCEEDED(view->webview->get_Settings(&settings)) && settings) {
+    settings->put_AreDefaultScriptDialogsEnabled(FALSE);
+  }
+
+  // ScriptDialogOpening — alert / confirm / prompt / beforeunload. Defer the
+  // event so host can decide via `respondToDialog`.
+  HRESULT dlg_hr = view->webview->add_ScriptDialogOpening(
+      Callback<ICoreWebView2ScriptDialogOpeningEventHandler>(
+          [lifetime, view_id](ICoreWebView2*, ICoreWebView2ScriptDialogOpeningEventArgs* args) -> HRESULT {
+            if (!lifetime || !lifetime->alive.load()) return S_OK;
+            ViewHost* v = getView(view_id);
+            if (!v) return S_OK;
+            ComPtr<ICoreWebView2Deferral> deferral;
+            args->GetDeferral(&deferral);
+            COREWEBVIEW2_SCRIPT_DIALOG_KIND kind = COREWEBVIEW2_SCRIPT_DIALOG_KIND_ALERT;
+            args->get_Kind(&kind);
+            LPWSTR msg_raw = nullptr;
+            args->get_Message(&msg_raw);
+            std::string message = wideToUtf8(msg_raw);
+            if (msg_raw) CoTaskMemFree(msg_raw);
+            LPWSTR def_raw = nullptr;
+            args->get_DefaultText(&def_raw);
+            std::string default_prompt = wideToUtf8(def_raw);
+            if (def_raw) CoTaskMemFree(def_raw);
+            const char* kind_str = (kind == COREWEBVIEW2_SCRIPT_DIALOG_KIND_CONFIRM) ? "confirm"
+                                 : (kind == COREWEBVIEW2_SCRIPT_DIALOG_KIND_PROMPT) ? "prompt"
+                                 : (kind == COREWEBVIEW2_SCRIPT_DIALOG_KIND_BEFOREUNLOAD) ? "beforeunload"
+                                 : "alert";
+            const uint32_t rid = v->next_dialog_request_id++;
+            v->pending_dialogs[rid] = ViewHost::PendingDialog{ args, std::move(deferral) };
+            BUNITE_INFO("webview2/dialog: ScriptDialogOpening view=%u kind=%s rid=%u",
+                        view_id, kind_str, rid);
+            std::string payload = "{\"requestId\":" + std::to_string(rid) +
+                                  ",\"kind\":\"" + kind_str +
+                                  "\",\"message\":\"" + escapeJsonString(message) + "\"";
+            if (kind == COREWEBVIEW2_SCRIPT_DIALOG_KIND_PROMPT) {
+              payload += ",\"defaultPrompt\":\"" + escapeJsonString(default_prompt) + "\"";
+            }
+            payload += "}";
+            emitWebviewEvent(view_id, "dialog", payload);
+            return S_OK;
+          }).Get(),
+      &tok);
+  BUNITE_INFO("webview2/dialog: add_ScriptDialogOpening view=%u hr=0x%08x token=%lld",
+              view_id, static_cast<unsigned>(dlg_hr), static_cast<long long>(tok.value));
+
+  // Capture preload IIFE markers. Production IPC is on the encrypted WS, so
+  // skip registering entirely when markers aren't emitted.
+  if (buniteShouldLog(BuniteLogLevel::Info)) {
+    view->webview->add_WebMessageReceived(
+        Callback<ICoreWebView2WebMessageReceivedEventHandler>(
+            [lifetime, view_id](ICoreWebView2*, ICoreWebView2WebMessageReceivedEventArgs* args) -> HRESULT {
+              if (!lifetime || !lifetime->alive.load()) return S_OK;
+              LPWSTR raw = nullptr;
+              if (FAILED(args->TryGetWebMessageAsString(&raw)) || !raw) return S_OK;
+              std::string s = wideToUtf8(raw);
+              CoTaskMemFree(raw);
+              if (s == "__bunite_preload_iife_start__") {
+                BUNITE_INFO("webview2/preload-race: view=%u t=%llu preload-iife-start",
+                            view_id, static_cast<unsigned long long>(GetTickCount64()));
+              } else if (s == "__bunite_preload_iife_end__") {
+                BUNITE_INFO("webview2/preload-race: view=%u t=%llu preload-iife-end",
+                            view_id, static_cast<unsigned long long>(GetTickCount64()));
+              }
+              return S_OK;
+            }).Get(),
+        &tok);
+  }
+
+  // DocumentTitleChanged — surface for automation surfaceEvents title-change arm.
   view->webview->add_DocumentTitleChanged(
       Callback<ICoreWebView2DocumentTitleChangedEventHandler>(
           [lifetime, view_id](ICoreWebView2* wv, IUnknown*) -> HRESULT {
@@ -853,19 +1063,87 @@ static void attachControllerCallbacks(ViewHost* view) {
           }).Get(),
       &tok);
 
-  // NewWindowRequested — block by default (matches plan), bubble event so the
-  // host can decide to open externally.
+  // NewWindowRequested — eager-mint a popup ViewHost with the requested
+  // CoreWebView2 (preserves window.opener) and emit `popup-requested`. Host
+  // adopts via `bunite_view_popup_accept` or rejects via `bunite_view_popup_dismiss`;
+  // SurfaceManager arms a 5s timer for the auto-dismiss safety net.
   view->webview->add_NewWindowRequested(
       Callback<ICoreWebView2NewWindowRequestedEventHandler>(
-          [lifetime, view_id](ICoreWebView2*, ICoreWebView2NewWindowRequestedEventArgs* args) -> HRESULT {
+          [lifetime, view_id](ICoreWebView2*, ICoreWebView2NewWindowRequestedEventArgs* args_raw) -> HRESULT {
             if (!lifetime || !lifetime->alive.load()) return S_OK;
-            args->put_Handled(TRUE);
+            ComPtr<ICoreWebView2NewWindowRequestedEventArgs> args(args_raw);
             LPWSTR uri_raw = nullptr;
             args->get_Uri(&uri_raw);
             std::string url = wideToUtf8(uri_raw);
             if (uri_raw) CoTaskMemFree(uri_raw);
-            std::string payload = "{\"url\":\"" + escapeJsonString(url) + "\"}";
-            emitWebviewEvent(view_id, "new-window-open", payload);
+            ComPtr<ICoreWebView2Deferral> deferral;
+            args->GetDeferral(&deferral);
+            args->put_Handled(TRUE);
+            // Popup IDs live in the upper u32 half; TS allocator stays below.
+            static std::atomic<uint32_t> g_popup_seq{0x80000000u};
+            uint32_t new_view_id = g_popup_seq.fetch_add(1);
+            auto* popup_raw = new ViewHost();
+            popup_raw->id = new_view_id;
+            popup_raw->window = nullptr;
+            popup_raw->bounds = RECT{0, 0, 0, 0};
+            popup_raw->auto_resize = false;
+            popup_raw->container_hwnd = CreateWindowExW(
+                0, kViewContainerClass, L"", WS_CHILD | WS_CLIPCHILDREN,
+                0, 0, 0, 0, g_runtime.popup_parent,
+                nullptr, getCurrentModuleHandle(), nullptr);
+            {
+              std::lock_guard<std::mutex> g(g_runtime.object_mutex);
+              g_runtime.views_by_id[new_view_id] = popup_raw;
+            }
+            auto cleanupPopup = [new_view_id]() {
+              auto* p = getView(new_view_id);
+              if (!p) return;
+              if (p->container_hwnd) DestroyWindow(p->container_hwnd);
+              {
+                std::lock_guard<std::mutex> g(g_runtime.object_mutex);
+                g_runtime.views_by_id.erase(new_view_id);
+              }
+              delete p;
+            };
+            HRESULT sync_hr = g_runtime.env->CreateCoreWebView2Controller(
+                popup_raw->container_hwnd,
+                Callback<ICoreWebView2CreateCoreWebView2ControllerCompletedHandler>(
+                    [lifetime, view_id, new_view_id, url, args, deferral, cleanupPopup](HRESULT hr, ICoreWebView2Controller* controller) -> HRESULT {
+                      if (!lifetime || !lifetime->alive.load()) {
+                        if (deferral) deferral->Complete();
+                        if (controller) controller->Close();  // close the orphan controller too.
+                        cleanupPopup();
+                        return S_OK;
+                      }
+                      auto* popup = getView(new_view_id);
+                      if (!popup || FAILED(hr) || !controller) {
+                        if (deferral) deferral->Complete();
+                        if (controller) controller->Close();  // popup was dismissed during creation — close the orphan.
+                        cleanupPopup();
+                        return S_OK;
+                      }
+                      popup->controller = controller;
+                      controller->get_CoreWebView2(&popup->webview);
+                      if (popup->webview) {
+                        args->put_NewWindow(popup->webview.Get());
+                      }
+                      controller->put_IsVisible(FALSE);
+                      RECT zero{0,0,0,0};
+                      controller->put_Bounds(zero);
+                      attachControllerCallbacks(popup);
+                      attachAppResFilter(popup);
+                      popup->ready.store(true);
+                      if (deferral) deferral->Complete();
+                      std::string payload = "{\"newSurfaceId\":" + std::to_string(new_view_id) +
+                                            ",\"url\":\"" + escapeJsonString(url) +
+                                            "\",\"disposition\":\"popup\"}";
+                      emitWebviewEvent(view_id, "popup-requested", payload);
+                      return S_OK;
+                    }).Get());
+            if (FAILED(sync_hr)) {
+              if (deferral) deferral->Complete();
+              cleanupPopup();
+            }
             return S_OK;
           }).Get(),
       &tok);
@@ -881,13 +1159,15 @@ static void attachControllerCallbacks(ViewHost* view) {
           }).Get(),
       &tok);
 
-  // DownloadStarting (ICoreWebView2_4) — suppress by default.
+  // DownloadStarting (ICoreWebView2_4) — policy-driven: block | auto | ask.
+  // Default block preserves the original behavior.
   ComPtr<ICoreWebView2_4> wv4;
   view->webview->QueryInterface(IID_PPV_ARGS(&wv4));
   if (wv4) {
+    static std::atomic<uint32_t> g_download_seq{1};
     wv4->add_DownloadStarting(
         Callback<ICoreWebView2DownloadStartingEventHandler>(
-            [lifetime, view_id](ICoreWebView2*, ICoreWebView2DownloadStartingEventArgs* args) -> HRESULT {
+            [lifetime, view_id, view](ICoreWebView2*, ICoreWebView2DownloadStartingEventArgs* args) -> HRESULT {
               if (!lifetime || !lifetime->alive.load()) return S_OK;
               ComPtr<ICoreWebView2DownloadOperation> op;
               args->get_DownloadOperation(&op);
@@ -895,9 +1175,98 @@ static void attachControllerCallbacks(ViewHost* view) {
               if (op) op->get_Uri(&uri_raw);
               std::string url = wideToUtf8(uri_raw);
               if (uri_raw) CoTaskMemFree(uri_raw);
-              args->put_Cancel(TRUE);
-              std::string payload = "{\"url\":\"" + escapeJsonString(url) + "\"}";
-              emitWebviewEvent(view_id, "download-blocked", payload);
+              int32_t policy = view->download_policy.load();
+              const std::string id = "wv2-" + std::to_string(g_download_seq.fetch_add(1));
+              // Only policy=0 (auto) allows. `ask` (1) falls back to block
+              // until implemented — distinguish via blocked.reason.
+              if (policy != 0) {
+                args->put_Cancel(TRUE);
+                const char* reason = (policy == 1) ? "ask-not-implemented" : "host-policy";
+                std::string payload = "{\"kind\":\"blocked\",\"id\":\"" + id +
+                                      "\",\"url\":\"" + escapeJsonString(url) +
+                                      "\",\"reason\":\"" + reason + "\"}";
+                emitWebviewEvent(view_id, "download-event", payload);
+                return S_OK;
+              }
+              // auto: don't cancel; report started + progress + completed.
+              LPWSTR sugg_raw = nullptr;
+              if (op) op->get_ContentDisposition(&sugg_raw);  // fallback
+              LPWSTR result_path_raw = nullptr;
+              args->get_ResultFilePath(&result_path_raw);
+              std::string suggested = result_path_raw ? wideToUtf8(result_path_raw) : "";
+              // strip dir, keep filename only.
+              auto slash = suggested.find_last_of("/\\");
+              if (slash != std::string::npos) suggested = suggested.substr(slash + 1);
+              if (sugg_raw) CoTaskMemFree(sugg_raw);
+              // Optional host downloadDir override.
+              std::string overrideDir = view->download_dir;
+              if (!overrideDir.empty() && result_path_raw) {
+                std::string base = suggested.empty() ? "download" : suggested;
+                std::string custom = overrideDir;
+                if (!custom.empty() && custom.back() != '\\' && custom.back() != '/') custom.push_back('\\');
+                custom += base;
+                args->put_ResultFilePath(utf8ToWide(custom).c_str());
+              }
+              if (result_path_raw) CoTaskMemFree(result_path_raw);
+              int64_t total = 0;
+              if (op) op->get_TotalBytesToReceive(&total);
+              std::string startPayload = "{\"kind\":\"started\",\"id\":\"" + id +
+                                         "\",\"url\":\"" + escapeJsonString(url) +
+                                         "\",\"suggestedFilename\":\"" + escapeJsonString(suggested) + "\"";
+              if (total > 0) startPayload += ",\"sizeBytes\":" + std::to_string(total);
+              startPayload += "}";
+              emitWebviewEvent(view_id, "download-event", startPayload);
+              if (op) {
+                // Tokens kept in a shared struct so the StateChanged terminal
+                // branch can self-unregister both handlers — breaks the
+                // op→handler→op ComPtr ref cycle that otherwise leaks per download.
+                struct Tokens { EventRegistrationToken b{}; EventRegistrationToken s{}; };
+                auto toks = std::make_shared<Tokens>();
+                op->add_BytesReceivedChanged(
+                    Callback<ICoreWebView2BytesReceivedChangedEventHandler>(
+                        [lifetime, view_id, id, op](ICoreWebView2DownloadOperation*, IUnknown*) -> HRESULT {
+                          if (!lifetime || !lifetime->alive.load()) return S_OK;
+                          INT64 rec = 0; op->get_BytesReceived(&rec);
+                          INT64 tot = 0; op->get_TotalBytesToReceive(&tot);
+                          std::string payload = "{\"kind\":\"progress\",\"id\":\"" + id +
+                                                "\",\"receivedBytes\":" + std::to_string(rec);
+                          if (tot > 0) payload += ",\"totalBytes\":" + std::to_string(tot);
+                          payload += "}";
+                          emitWebviewEvent(view_id, "download-event", payload);
+                          return S_OK;
+                        }).Get(),
+                    &toks->b);
+                op->add_StateChanged(
+                    Callback<ICoreWebView2StateChangedEventHandler>(
+                        [lifetime, view_id, id, op, toks](ICoreWebView2DownloadOperation*, IUnknown*) -> HRESULT {
+                          if (!lifetime || !lifetime->alive.load()) return S_OK;
+                          COREWEBVIEW2_DOWNLOAD_STATE state;
+                          op->get_State(&state);
+                          bool terminal = false;
+                          if (state == COREWEBVIEW2_DOWNLOAD_STATE_COMPLETED) {
+                            terminal = true;
+                            LPWSTR path_raw = nullptr; op->get_ResultFilePath(&path_raw);
+                            std::string path = wideToUtf8(path_raw);
+                            if (path_raw) CoTaskMemFree(path_raw);
+                            std::string payload = "{\"kind\":\"completed\",\"id\":\"" + id +
+                                                  "\",\"localPath\":\"" + escapeJsonString(path) + "\"}";
+                            emitWebviewEvent(view_id, "download-event", payload);
+                          } else if (state == COREWEBVIEW2_DOWNLOAD_STATE_INTERRUPTED) {
+                            terminal = true;
+                            COREWEBVIEW2_DOWNLOAD_INTERRUPT_REASON reason;
+                            op->get_InterruptReason(&reason);
+                            std::string payload = "{\"kind\":\"failed\",\"id\":\"" + id +
+                                                  "\",\"reason\":\"interrupted-" + std::to_string(reason) + "\"}";
+                            emitWebviewEvent(view_id, "download-event", payload);
+                          }
+                          if (terminal) {
+                            op->remove_BytesReceivedChanged(toks->b);
+                            op->remove_StateChanged(toks->s);
+                          }
+                          return S_OK;
+                        }).Get(),
+                    &toks->s);
+              }
               return S_OK;
             }).Get(),
         &tok);