bunite-core 0.14.0 → 0.16.0

package/src/native/mac/bunite_mac_view.mm

@@ -3,6 +3,7 @@
 #import "bunite_mac_internal.h"
 
 #include "webview_storage.h"
+#include <objc/runtime.h>
 
 @implementation BunitePendingPermission
 @end
@@ -27,6 +28,125 @@
 using bunite_mac::g_runtime;
 using bunite_mac::utf8ToNSString;
 
+// WKDownload delegate — decideDestination gates host policy + emits
+// started/blocked, KVO on download.progress emits progress, didFinish/didFail
+// emit terminal events.
+@interface BuniteDownloadDelegate : NSObject <WKDownloadDelegate>
+@property (nonatomic) uint32_t viewId;
+@property (nonatomic) uint64_t downloadId;
+@property (nonatomic, strong) NSString* destinationPath;
+@property (nonatomic, weak) NSProgress* observedProgress;
+@property (nonatomic) int64_t lastReportedBytes;
+@property (atomic) BOOL terminalReached;
+@end
+
+static char kBuniteProgressCtx;
+
+@implementation BuniteDownloadDelegate
+
+- (void)download:(WKDownload*)download
+    decideDestinationUsingResponse:(NSURLResponse*)response
+                 suggestedFilename:(NSString*)suggested
+                 completionHandler:(void (^)(NSURL*))completionHandler
+{
+  auto* st = bunite_mac::findView(self.viewId);
+  if (!st) { completionHandler(nil); return; }
+  const int32_t policy = st->download_policy.load();
+  NSString* url = download.originalRequest.URL.absoluteString ?: @"";
+  std::string url_s = url.UTF8String ?: "";
+  if (policy != 0) {
+    const char* reason = (policy == 1) ? "ask-not-implemented" : "host-policy";
+    std::string payload = "{\"kind\":\"blocked\",\"id\":\"mac-" + std::to_string(self.downloadId) +
+                          "\",\"url\":\"" + bunite_mac::escapeJsonString(url_s) +
+                          "\",\"reason\":\"" + reason + "\"}";
+    bunite_mac::emitWebviewEvent(self.viewId, "download-event", payload);
+    completionHandler(nil);
+    return;
+  }
+  NSString* dirStr = st->download_dir.empty() ? nil : [NSString stringWithUTF8String:st->download_dir.c_str()];
+  if (!dirStr || dirStr.length == 0) {
+    NSArray<NSURL*>* paths = [NSFileManager.defaultManager URLsForDirectory:NSDownloadsDirectory inDomains:NSUserDomainMask];
+    dirStr = paths.firstObject.path ?: NSTemporaryDirectory();
+  }
+  NSString* fname = suggested.length > 0 ? suggested : @"download";
+  NSString* path = [dirStr stringByAppendingPathComponent:fname];
+  self.destinationPath = path;
+  std::string mime = (response.MIMEType ?: @"").UTF8String ?: "";
+  long long total = response.expectedContentLength > 0 ? (long long)response.expectedContentLength : 0;
+  std::string started = "{\"kind\":\"started\",\"id\":\"mac-" + std::to_string(self.downloadId) +
+                        "\",\"url\":\"" + bunite_mac::escapeJsonString(url_s) +
+                        "\",\"suggestedFilename\":\"" + bunite_mac::escapeJsonString(fname.UTF8String ?: "") +
+                        "\",\"mimeType\":\"" + bunite_mac::escapeJsonString(mime) + "\"";
+  if (total > 0) started += ",\"sizeBytes\":" + std::to_string(total);
+  started += "}";
+  bunite_mac::emitWebviewEvent(self.viewId, "download-event", started);
+  NSProgress* prog = download.progress;
+  if (prog) {
+    self.observedProgress = prog;
+    self.lastReportedBytes = 0;
+    [prog addObserver:self
+           forKeyPath:@"completedUnitCount"
+              options:NSKeyValueObservingOptionNew
+              context:&kBuniteProgressCtx];
+  }
+  completionHandler([NSURL fileURLWithPath:path]);
+}
+
+- (void)observeValueForKeyPath:(NSString*)keyPath
+                      ofObject:(id)object
+                        change:(NSDictionary*)change
+                       context:(void*)context
+{
+  if (context != &kBuniteProgressCtx) {
+    [super observeValueForKeyPath:keyPath ofObject:object change:change context:context];
+    return;
+  }
+  if (self.terminalReached) return;
+  NSProgress* prog = (NSProgress*)object;
+  int64_t received = prog.completedUnitCount;
+  int64_t total = prog.totalUnitCount;
+  if (received <= self.lastReportedBytes) return;
+  self.lastReportedBytes = received;
+  std::string payload = "{\"kind\":\"progress\",\"id\":\"mac-" + std::to_string(self.downloadId) +
+                        "\",\"receivedBytes\":" + std::to_string(received);
+  if (total > 0) payload += ",\"totalBytes\":" + std::to_string(total);
+  payload += "}";
+  bunite_mac::emitWebviewEvent(self.viewId, "download-event", payload);
+}
+
+- (void)_detachProgressObserver {
+  NSProgress* prog = self.observedProgress;
+  if (!prog) return;
+  @try {
+    [prog removeObserver:self forKeyPath:@"completedUnitCount" context:&kBuniteProgressCtx];
+  } @catch (NSException* ex) {}  // tolerate over-remove on edge lifecycles
+  self.observedProgress = nil;
+}
+
+- (void)downloadDidFinish:(WKDownload*)download {
+  self.terminalReached = YES;
+  [self _detachProgressObserver];
+  std::string dest = self.destinationPath ? std::string(self.destinationPath.UTF8String ?: "") : "";
+  std::string payload = "{\"kind\":\"completed\",\"id\":\"mac-" + std::to_string(self.downloadId) +
+                        "\",\"localPath\":\"" + bunite_mac::escapeJsonString(dest) + "\"}";
+  bunite_mac::emitWebviewEvent(self.viewId, "download-event", payload);
+}
+
+- (void)download:(WKDownload*)download didFailWithError:(NSError*)error resumeData:(NSData*)resumeData {
+  self.terminalReached = YES;
+  [self _detachProgressObserver];
+  std::string reason = error ? std::string(error.localizedDescription.UTF8String ?: "unknown") : "unknown";
+  std::string payload = "{\"kind\":\"failed\",\"id\":\"mac-" + std::to_string(self.downloadId) +
+                        "\",\"reason\":\"" + bunite_mac::escapeJsonString(reason) + "\"}";
+  bunite_mac::emitWebviewEvent(self.viewId, "download-event", payload);
+}
+
+- (void)dealloc {
+  [self _detachProgressObserver];
+}
+
+@end
+
 @interface BuniteNavigationDelegate : NSObject <WKNavigationDelegate>
 @end
 
@@ -92,6 +212,24 @@ decidePolicyForNavigationAction:(WKNavigationAction*)action
   bunite_mac::emitWebviewEvent(view_id, "load-fail", payload);
 }
 
+- (void)webView:(WKWebView*)wv navigationAction:(WKNavigationAction*)action didBecomeDownload:(WKDownload*)download {
+  static std::atomic<uint64_t> g_seq{1};
+  BuniteDownloadDelegate* d = [BuniteDownloadDelegate new];
+  d.viewId = bunite_mac::viewIdForWebView(wv);
+  d.downloadId = g_seq.fetch_add(1);
+  download.delegate = d;
+  objc_setAssociatedObject(download, "bunite.dl.delegate", d, OBJC_ASSOCIATION_RETAIN);
+}
+
+- (void)webView:(WKWebView*)wv navigationResponse:(WKNavigationResponse*)response didBecomeDownload:(WKDownload*)download {
+  static std::atomic<uint64_t> g_seq{0x80000000ULL};
+  BuniteDownloadDelegate* d = [BuniteDownloadDelegate new];
+  d.viewId = bunite_mac::viewIdForWebView(wv);
+  d.downloadId = g_seq.fetch_add(1);
+  download.delegate = d;
+  objc_setAssociatedObject(download, "bunite.dl.delegate", d, OBJC_ASSOCIATION_RETAIN);
+}
+
 @end
 
 @interface BuniteTitleObserver : NSObject
@@ -132,14 +270,44 @@ createWebViewWithConfiguration:(WKWebViewConfiguration*)config
               forNavigationAction:(WKNavigationAction*)action
                    windowFeatures:(WKWindowFeatures*)features
 {
-  (void)config; (void)features;
-  uint32_t view_id = bunite_mac::viewIdForWebView(wv);
+  (void)features;
+  uint32_t opener_view_id = bunite_mac::viewIdForWebView(wv);
   NSString* url = action.request.URL.absoluteString ?: @"";
-  // Match win OnBeforePopup/OnOpenURLFromTab: emit, cancel; JS decides via load_url.
-  std::string payload = "{\"url\":\"" +
-    bunite_mac::escapeJsonString(url.UTF8String ?: "") + "\"}";
-  bunite_mac::emitWebviewEvent(view_id, "new-window-open", payload);
-  return nil;
+  if (bunite_mac::g_runtime.popup_blocking) {
+    std::string payload = "{\"url\":\"" + bunite_mac::escapeJsonString(url.UTF8String ?: "") + "\"}";
+    bunite_mac::emitWebviewEvent(opener_view_id, "new-window-open", payload);
+    return nil;
+  }
+  static std::atomic<uint32_t> g_popup_seq{0x80000000u};
+  const uint32_t new_view_id = g_popup_seq.fetch_add(1);
+  WKWebView* popup = [[WKWebView alloc] initWithFrame:NSMakeRect(0, 0, 1, 1) configuration:config];
+  popup.navigationDelegate = wv.navigationDelegate;
+  popup.UIDelegate = wv.UIDelegate;
+  if (!bunite_mac::g_runtime.parked_popups) {
+    bunite_mac::g_runtime.parked_popups = [NSMutableDictionary dictionary];
+  }
+  if (!bunite_mac::g_runtime.popup_parent) {
+    bunite_mac::g_runtime.popup_parent =
+        [[NSWindow alloc] initWithContentRect:NSMakeRect(0, 0, 1, 1)
+                                    styleMask:NSWindowStyleMaskBorderless
+                                      backing:NSBackingStoreBuffered
+                                        defer:YES];
+  }
+  bunite_mac::g_runtime.parked_popups[@(new_view_id)] = popup;
+  [bunite_mac::g_runtime.popup_parent.contentView addSubview:popup];
+  bunite_mac::registerWebViewId(popup, new_view_id);
+  {
+    std::lock_guard<std::mutex> lock(bunite_mac::g_runtime.object_mutex);
+    auto& st = bunite_mac::g_runtime.views[new_view_id];
+    st.webview = popup;
+    st.container = nil;       // bound on adoption
+    st.window_id = 0;
+  }
+  std::string payload = "{\"newSurfaceId\":" + std::to_string(new_view_id) +
+                        ",\"url\":\"" + bunite_mac::escapeJsonString(url.UTF8String ?: "") +
+                        "\",\"disposition\":\"popup\"}";
+  bunite_mac::emitWebviewEvent(opener_view_id, "popup-requested", payload);
+  return popup;
 }
 
 // --- Dialog handlers (alert / confirm / prompt). beforeunload is not
@@ -279,6 +447,14 @@ uint32_t viewIdForWebView(WKWebView* wv) {
   return id ? id.unsignedIntValue : 0;
 }
 
+void registerWebViewId(WKWebView* wv, uint32_t view_id) {
+  [webviewIdTable() setObject:@(view_id) forKey:wv];
+}
+
+void unregisterWebViewId(WKWebView* wv) {
+  [webviewIdTable() removeObjectForKey:wv];
+}
+
 bool createView(uint32_t view_id, uint32_t window_id,
                 NSString* url, NSString* html, NSString* preload, NSString* appres_root,
                 NSString* navigation_rules_json, NSString* preload_origins_json,
@@ -364,6 +540,50 @@ bool createView(uint32_t view_id, uint32_t window_id,
   return true;
 }
 
+bool acceptParkedPopup(uint32_t new_view_id, uint32_t host_window_id, double x, double y, double w, double h) {
+  WKWebView* popup = nil;
+  if (g_runtime.parked_popups) {
+    popup = g_runtime.parked_popups[@(new_view_id)];
+    if (popup) [g_runtime.parked_popups removeObjectForKey:@(new_view_id)];
+  }
+  if (!popup) return false;
+  WindowState* host = findWindow(host_window_id);
+  if (!host || !host->window) return false;
+  [popup removeFromSuperview];
+  BunitePassthroughContainer* container = [[BunitePassthroughContainer alloc] init];
+  container.frame = NSMakeRect(x, y, w, h);
+  popup.frame = NSMakeRect(0, 0, w, h);
+  popup.autoresizingMask = NSViewWidthSizable | NSViewHeightSizable;
+  [container addSubview:popup];
+  [host->window.contentView addSubview:container];
+  {
+    std::lock_guard<std::mutex> lock(g_runtime.object_mutex);
+    auto& st = g_runtime.views[new_view_id];
+    st.container = container;
+    st.webview = popup;
+    st.window_id = host_window_id;
+  }
+  // Re-emit view-ready so TS BrowserView.adopt resolves — the initial
+  // did-navigate fired before the adopter registered.
+  emitWebviewEvent(new_view_id, "view-ready", "");
+  return true;
+}
+
+void dismissParkedPopup(uint32_t new_view_id) {
+  WKWebView* popup = nil;
+  if (g_runtime.parked_popups) {
+    popup = g_runtime.parked_popups[@(new_view_id)];
+    if (popup) [g_runtime.parked_popups removeObjectForKey:@(new_view_id)];
+  }
+  if (!popup) return;
+  [popup removeFromSuperview];
+  unregisterWebViewId(popup);
+  {
+    std::lock_guard<std::mutex> lock(g_runtime.object_mutex);
+    g_runtime.views.erase(new_view_id);
+  }
+}
+
 void removeView(uint32_t view_id) {
   __strong WKWebView* wv = nil;
   __strong NSView* container = nil;

package/src/native/shared/ffi_exports.h

@@ -15,29 +15,7 @@
 extern "C" {
 #endif
 
-/** ABI version. Bump on any breaking change to symbol set / signatures.
- *  v9 (2026-05): adds `bunite_view_mouse` (move/down/up primitives for drag &
- *                hover) + `bunite_view_respond_dialog`. Webview event names
- *                expand to include `dialog` (alert/confirm/prompt/beforeunload)
- *                and `console-message` (the latter is RPC-pushed by preload,
- *                not emitted by native — listed here for the host-side event
- *                channel completeness). Capability bits add `MOUSE` (1<<11),
- *                `DIALOGS` (1<<12), `CONSOLE` (1<<13). `NATIVE_INPUT_TRUSTED`
- *                meaning stretches to include `mouse` (click/type/press/mouse
- *                all produce isTrusted=true on supporting backends; scroll and
- *                screenshot remain outside that guarantee).
- *  v8 (2026-05): `bunite_view_press` gains `action` (down/up/both), `extended`
- *                (Win 0xE0 scancode prefix), `location` (DOM KeyboardEvent
- *                location, 0/1/2/3) params. Webview event names expand to
- *                include `load-start` / `load-finish` / `load-fail`. Capability
- *                bit 2 renamed `TITLE_CHANGED` → `SURFACE_EVENTS` — value
- *                unchanged but semantic is now "unified surfaceEvents stream
- *                supported". A surface fires `load-finish` OR `load-fail` per
- *                navigation, never both.
- *  v7 (2026-05): adds `bunite_view_screenshot` + `bunite_view_capabilities`
- *                + capability bitset (`BuniteCapBit`).
- *  v6 (2026-05): adds input dispatch — `bunite_view_click/type/press/scroll`.
- *  v5 (2026-05): adds `bunite_view_evaluate` + `evaluate-result` webview event. */
+/** ABI version. Bump on any breaking change to symbol set / signatures. */
 BUNITE_EXPORT int32_t bunite_abi_version(void);
 BUNITE_EXPORT void bunite_set_log_level(int32_t level);
 BUNITE_EXPORT bool bunite_init(
@@ -222,24 +200,33 @@ BUNITE_EXPORT void bunite_view_respond_dialog(
 	const char* text
 );
 
-/** Per-view automation capability bitset. Each backend returns the bits it
- *  actually supports — TS layer decodes to `SurfaceCapabilities` object.
- *  Bits are locked at ABI v6; append-only. */
+/** Per-view automation capability bitset. Two categories: method gate
+ *  (bit=false → method must not be called) and property advertise (bit=false
+ *  → method runs, property degrades). See `.agents/architecture.md`. */
 enum BuniteCapBit {
+	/* method gate */
 	BUNITE_CAP_EVALUATE             = 1u << 0,
-	BUNITE_CAP_CROSS_ORIGIN_EVAL    = 1u << 1,
 	BUNITE_CAP_SURFACE_EVENTS       = 1u << 2,
-	BUNITE_CAP_NATIVE_INPUT_TRUSTED = 1u << 3,  /* click/type/press/mouse all isTrusted=true */
 	BUNITE_CAP_CLICK                = 1u << 4,
 	BUNITE_CAP_TYPE                 = 1u << 5,
 	BUNITE_CAP_PRESS                = 1u << 6,
 	BUNITE_CAP_SCROLL               = 1u << 7,
 	BUNITE_CAP_SCREENSHOT           = 1u << 8,
-	BUNITE_CAP_FORMAT_PNG           = 1u << 9,
-	BUNITE_CAP_FORMAT_JPEG          = 1u << 10,
 	BUNITE_CAP_MOUSE                = 1u << 11,
 	BUNITE_CAP_DIALOGS              = 1u << 12,
 	BUNITE_CAP_CONSOLE              = 1u << 13,
+	BUNITE_CAP_AX                   = 1u << 15,
+	BUNITE_CAP_BOUNDING_RECT        = 1u << 16,
+	BUNITE_CAP_FRAMES               = 1u << 17,
+	BUNITE_CAP_DOWNLOADS            = 1u << 18,
+	BUNITE_CAP_POPUPS               = 1u << 19,
+	BUNITE_CAP_RESOLVE_AND_CLICK    = 1u << 20,
+
+	/* property advertise */
+	BUNITE_CAP_CROSS_ORIGIN_EVAL    = 1u << 1,
+	BUNITE_CAP_NATIVE_INPUT_TRUSTED = 1u << 3,  /* click/type/press/mouse isTrusted */
+	BUNITE_CAP_FORMAT_PNG           = 1u << 9,
+	BUNITE_CAP_FORMAT_JPEG          = 1u << 10,
 };
 BUNITE_EXPORT uint32_t bunite_view_capabilities(uint32_t view_id);
 
@@ -259,6 +246,82 @@ BUNITE_EXPORT void bunite_view_screenshot(
 	int32_t quality
 );
 
+/** Snapshot the accessibility tree (CDP `Accessibility.getFullAXTree`). Async —
+ *  result reported via webview event handler as `accessibility-result` payload
+ *    { requestId, ok: true, tree: {nodes: [<CDP AXNode flat list>]} }
+ *    { requestId, ok: false, code, message }
+ *  TS builds the nested tree from `childIds`. mac/linux always emit
+ *  `not_supported` (no public ax tree API). `interesting_only` is reserved and
+ *  currently unused on the native side (filter is TS-side). */
+BUNITE_EXPORT void bunite_view_accessibility_snapshot(
+	uint32_t view_id,
+	uint32_t request_id,
+	int32_t interesting_only
+);
+
+/** Enumerate frames in the view. Async — result reported via webview event
+ *  `list-frames-result` payload
+ *    { requestId, ok: true, frames: [{frameId, parentFrameId, origin, url, name?}] }
+ *    { requestId, ok: false, code, message }
+ *  Codes: `not_supported`, `runtime_error`. mac/linux emit `not_supported`. */
+BUNITE_EXPORT void bunite_view_list_frames(uint32_t view_id, uint32_t request_id);
+
+/** Evaluate `script` in the target frame's isolated world (CDP
+ *  `Page.createIsolatedWorld` + `Runtime.evaluate`). Page main-world JS
+ *  variables are NOT visible; DOM access works. Result reused via the
+ *  existing `evaluate-result` event. `frame_id` empty/null delegates to
+ *  `bunite_view_evaluate` (main frame, main world). */
+BUNITE_EXPORT void bunite_view_evaluate_in_frame(
+	uint32_t view_id,
+	uint32_t request_id,
+	const char* script,
+	const char* frame_id
+);
+
+/** Atomic selector resolve + native click. Async via `resolve-and-click-result`:
+ *    { requestId, ok: true, rect, isTrustedEvent }
+ *    { requestId, ok: false, code, message }
+ *  Codes: not_found / not_visible / runtime_error / cross_origin / not_supported.
+ *  `frame_id` non-empty selects a same-origin iframe (rect viewport-normalized);
+ *  cross-origin → `cross_origin`, mac/linux → `not_supported`. scrollIntoView is
+ *  automatic. `isTrustedEvent` is empirical per backend; CEF/WV2 CDP path and
+ *  mac NSEvent direct dispatch all produce trusted events (all `true`). */
+BUNITE_EXPORT void bunite_view_resolve_and_click(
+	uint32_t view_id,
+	uint32_t request_id,
+	const char* selector,
+	const char* frame_id,
+	int32_t button,
+	int32_t click_count,
+	uint32_t modifiers
+);
+
+/** Set per-view download policy. `policy`: 0=auto (allow + emit lifecycle),
+ *  1=ask (not implemented for v10, treated as block), 2=block (default).
+ *  `download_dir` (utf-8) optionally overrides backend default save dir.
+ *  Lifecycle events emit as `download-event` payloads
+ *    { kind: "started"|"progress"|"completed"|"failed"|"blocked", id, ...fields }
+ *  See `DownloadEvent` (TS) for the per-kind field set. */
+BUNITE_EXPORT void bunite_view_set_download_policy(
+	uint32_t view_id,
+	int32_t policy,
+	const char* download_dir
+);
+
+/** Adopt a popup-minted view. Native must have previously emitted a
+ *  `popup-requested` event (carrying `newSurfaceId`); host calls this to attach
+ *  the pre-minted view to the target window + bounds. `host_window_id` is the
+ *  destination `WindowHost.id`. */
+BUNITE_EXPORT void bunite_view_popup_accept(
+	uint32_t new_view_id,
+	uint32_t host_window_id,
+	double x, double y, double w, double h
+);
+
+/** Discard a popup-minted view that wasn't adopted (or that host wants to
+ *  reject). Native destroys the controller/browser. Idempotent. */
+BUNITE_EXPORT void bunite_view_popup_dismiss(uint32_t new_view_id);
+
 BUNITE_EXPORT void bunite_view_open_devtools(uint32_t view_id);
 BUNITE_EXPORT void bunite_view_close_devtools(uint32_t view_id);
 BUNITE_EXPORT void bunite_view_toggle_devtools(uint32_t view_id);

package/src/native/win/native_host_cef.cpp

@@ -86,7 +86,8 @@ class BuniteCefClient
     public CefResourceRequestHandler,
     public CefPermissionHandler,
     public CefDisplayHandler,
-    public CefJSDialogHandler {
+    public CefJSDialogHandler,
+    public CefDownloadHandler {
 public:
   // BuniteCefClient is constructed 1:1 with a `ViewHost*`; `last_title_` is
   // therefore per-view. OnTitleChange runs on the CEF UI thread (single).
@@ -99,6 +100,68 @@ public:
   CefRefPtr<CefPermissionHandler> GetPermissionHandler() override { return this; }
   CefRefPtr<CefDisplayHandler> GetDisplayHandler() override { return this; }
   CefRefPtr<CefJSDialogHandler> GetJSDialogHandler() override { return this; }
+  CefRefPtr<CefDownloadHandler> GetDownloadHandler() override { return this; }
+
+  bool OnBeforeDownload(CefRefPtr<CefBrowser>, CefRefPtr<CefDownloadItem> item,
+                        const CefString& suggested_name,
+                        CefRefPtr<CefBeforeDownloadCallback> callback) override {
+    CEF_REQUIRE_UI_THREAD();
+    int32_t policy = view_->download_policy.load();
+    std::string id = "cef-" + std::to_string(item->GetId());
+    std::string url = item->GetURL().ToString();
+    std::string mime = item->GetMimeType().ToString();
+    int64_t total = item->GetTotalBytes();
+    std::string suggested = suggested_name.ToString();
+    // Only policy=0 (auto) allows. `ask` (1) falls back to block — distinguished
+    // via blocked.reason so callers can detect the unsupported policy path.
+    if (policy != 0) {
+      const char* reason = (policy == 1) ? "ask-not-implemented" : "host-policy";
+      std::string payload = "{\"kind\":\"blocked\",\"id\":\"" + id +
+                            "\",\"url\":\"" + bunite_win::escapeJsonString(url) +
+                            "\",\"reason\":\"" + reason + "\"}";
+      bunite_win::emitWebviewEvent(view_->id, "download-event", payload);
+      return true;  // not calling callback->Continue → cancels.
+    }
+    // auto: build target path. If host set download_dir, use it; else CEF defaults to user Downloads.
+    std::string target = view_->download_dir;
+    if (!target.empty()) {
+      if (target.back() != '\\' && target.back() != '/') target.push_back('\\');
+      target += suggested;
+    }
+    callback->Continue(target, false);  // false = no Save-As dialog.
+    std::string payload = "{\"kind\":\"started\",\"id\":\"" + id +
+                          "\",\"url\":\"" + bunite_win::escapeJsonString(url) +
+                          "\",\"suggestedFilename\":\"" + bunite_win::escapeJsonString(suggested) +
+                          "\",\"mimeType\":\"" + bunite_win::escapeJsonString(mime) + "\"";
+    if (total > 0) payload += ",\"sizeBytes\":" + std::to_string(total);
+    payload += "}";
+    bunite_win::emitWebviewEvent(view_->id, "download-event", payload);
+    return true;
+  }
+
+  void OnDownloadUpdated(CefRefPtr<CefBrowser>, CefRefPtr<CefDownloadItem> item,
+                         CefRefPtr<CefDownloadItemCallback> /*callback*/) override {
+    CEF_REQUIRE_UI_THREAD();
+    std::string id = "cef-" + std::to_string(item->GetId());
+    if (item->IsComplete()) {
+      std::string path = item->GetFullPath().ToString();
+      std::string payload = "{\"kind\":\"completed\",\"id\":\"" + id +
+                            "\",\"localPath\":\"" + bunite_win::escapeJsonString(path) + "\"}";
+      bunite_win::emitWebviewEvent(view_->id, "download-event", payload);
+    } else if (item->IsCanceled()) {
+      std::string payload = "{\"kind\":\"failed\",\"id\":\"" + id +
+                            "\",\"reason\":\"canceled\"}";
+      bunite_win::emitWebviewEvent(view_->id, "download-event", payload);
+    } else if (item->IsInProgress()) {
+      int64_t rec = item->GetReceivedBytes();
+      int64_t tot = item->GetTotalBytes();
+      std::string payload = "{\"kind\":\"progress\",\"id\":\"" + id +
+                            "\",\"receivedBytes\":" + std::to_string(rec);
+      if (tot > 0) payload += ",\"totalBytes\":" + std::to_string(tot);
+      payload += "}";
+      bunite_win::emitWebviewEvent(view_->id, "download-event", payload);
+    }
+  }
 
   bool OnJSDialog(CefRefPtr<CefBrowser>, const CefString& /*origin_url*/,
                   JSDialogType dialog_type, const CefString& message_text,
@@ -110,7 +173,9 @@ public:
                      : (dialog_type == JSDIALOGTYPE_CONFIRM) ? "confirm" : "prompt";
     const uint32_t rid = view_->next_dialog_request_id++;
     view_->pending_dialogs[rid] = callback;
-    suppress_message = true;  // we control the dialog UX; host sends the answer.
+    BUNITE_INFO("cef/dialog: OnJSDialog view=%u kind=%s rid=%u", view_->id, kind, rid);
+    // CEF asserts !suppress_message when return=true (custom dialog path).
+    suppress_message = false;
     std::string payload = "{\"requestId\":" + std::to_string(rid) +
                           ",\"kind\":\"" + kind +
                           "\",\"message\":\"" + bunite_win::escapeJsonString(message_text.ToString()) + "\"";
@@ -254,6 +319,19 @@ public:
     }
 
     bunite_win::emitWebviewEvent(view_->id, "view-ready");
+
+    if (view_->is_popup_pending) {
+      if (view_->popup_dismiss_requested) {
+        view_->closing.store(true);
+        browser->GetHost()->CloseBrowser(true);
+        return;
+      }
+      if (view_->pending_popup_accept) {
+        auto p = *view_->pending_popup_accept;
+        view_->pending_popup_accept.reset();
+        bunite_win::applyPopupAccept(view_, p.host_window_id, p.x, p.y, p.w, p.h);
+      }
+    }
   }
 
   bool DoClose(CefRefPtr<CefBrowser>) override {
@@ -317,19 +395,33 @@ public:
     CefLifeSpanHandler::WindowOpenDisposition,
     bool,
     const CefPopupFeatures&,
-    CefWindowInfo&,
-    CefRefPtr<CefClient>&,
+    CefWindowInfo& window_info,
+    CefRefPtr<CefClient>& client,
     CefBrowserSettings&,
     CefRefPtr<CefDictionaryValue>&,
     bool*
   ) override {
     CEF_REQUIRE_UI_THREAD();
-    bunite_win::emitWebviewEvent(
-      view_->id,
-      "new-window-open",
-      "{\"url\":\"" + bunite_win::escapeJsonString(target_url.ToString()) + "\"}"
-    );
-    return 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 = new ViewHost();
+    popup->id = new_view_id;
+    popup->window = nullptr;
+    popup->is_popup_pending = true;
+    {
+      std::lock_guard<std::mutex> lock(g_runtime.object_mutex);
+      g_runtime.views_by_id[new_view_id] = popup;
+    }
+    // Initial parent = runtime message window; host adopts and reparents later.
+    window_info.SetAsChild(g_runtime.message_window, CefRect{0, 0, 0, 0});
+    window_info.style = WS_CHILD;
+    client = new BuniteCefClient(popup);
+    std::string payload = "{\"newSurfaceId\":" + std::to_string(new_view_id) +
+                          ",\"url\":\"" + bunite_win::escapeJsonString(target_url.ToString()) +
+                          "\",\"disposition\":\"popup\"}";
+    bunite_win::emitWebviewEvent(view_->id, "popup-requested", payload);
+    return false;  // allow CEF to create the popup browser.
   }
 
   void OnLoadStart(CefRefPtr<CefBrowser>, CefRefPtr<CefFrame> frame, TransitionType) override {