bunite-core 0.12.1 → 0.16.0

package/src/native/mac/bunite_mac_ffi.mm

@@ -20,7 +20,7 @@ using bunite_mac::runOnUiThreadSync;
 
 namespace {
 
-constexpr int32_t kBuniteAbiVersion = 5;
+constexpr int32_t kBuniteAbiVersion = 11;
 
 // warn-once — avoid log spam from tight JS call loops.
 #define BUNITE_MAC_TODO(name)                                       \
@@ -273,13 +273,83 @@ extern "C" BUNITE_EXPORT void bunite_view_execute_javascript(uint32_t view_id, c
   });
 }
 
-extern "C" BUNITE_EXPORT void bunite_view_evaluate(uint32_t view_id, uint32_t request_id, const char* /*script*/) {
-  // Stage A: macOS evaluate not yet implemented. Report not_supported so the
-  // JS side's whenReady() resolves with a structured envelope.
-  std::string payload = "{\"requestId\":" + std::to_string(request_id) +
-                        ",\"ok\":false,\"code\":\"not_supported\","
-                        "\"message\":\"macOS evaluate not implemented (Stage A: Windows only)\"}";
-  bunite_mac::emitWebviewEvent(view_id, "evaluate-result", payload);
+extern "C" BUNITE_EXPORT void bunite_view_evaluate(uint32_t view_id, uint32_t request_id, const char* script) {
+  // Wrapper matches WebView2/CEF: try/catch returns JSON envelope string.
+  // WKWebView's `evaluateJavaScript:` delivers the string directly (no outer
+  // re-stringify), so the inner envelope is the completion result.
+  if (!script) {
+    std::string payload = "{\"requestId\":" + std::to_string(request_id) +
+                          ",\"ok\":false,\"code\":\"runtime_error\","
+                          "\"message\":\"null script\"}";
+    bunite_mac::emitWebviewEvent(view_id, "evaluate-result", payload);
+    return;
+  }
+  std::string wrapped =
+      "(function(){try{return JSON.stringify({__bunite_ok:true,value:("
+      + std::string(script) +
+      ")})}catch(e){var c=(e&&e.name===\"SecurityError\")?\"cross_origin\":\"runtime_error\";"
+      "return JSON.stringify({__bunite_ok:false,code:c,"
+      "message:(e&&e.message)?e.message:String(e),"
+      "name:(e&&e.name)||\"\"})}})()";
+  NSString* nsScript = [NSString stringWithUTF8String:wrapped.c_str()];
+  runOnUiThreadSync([=]() {
+    auto* v = bunite_mac::findView(view_id);
+    if (!v || !v->webview) {
+      std::string payload = "{\"requestId\":" + std::to_string(request_id) +
+                            ",\"ok\":false,\"code\":\"not_supported\","
+                            "\"message\":\"view not ready\"}";
+      bunite_mac::emitWebviewEvent(view_id, "evaluate-result", payload);
+      return;
+    }
+    [v->webview evaluateJavaScript:nsScript completionHandler:^(id result, NSError* error) {
+      std::string payload = "{\"requestId\":" + std::to_string(request_id);
+      if (error) {
+        std::string msg = error.localizedDescription.UTF8String ?: "evaluate failed";
+        payload += ",\"ok\":false,\"code\":\"runtime_error\","
+                   "\"message\":\"" + bunite_mac::escapeJsonString(msg) + "\"}";
+      } else if (![result isKindOfClass:[NSString class]]) {
+        payload += ",\"ok\":false,\"code\":\"runtime_error\","
+                   "\"message\":\"wrapper returned non-string\"}";
+      } else {
+        std::string inner = ((NSString*)result).UTF8String ?: "";
+        if (inner.find("\"__bunite_ok\":true") != std::string::npos) {
+          static const std::string prefix = "{\"__bunite_ok\":true,\"value\":";
+          std::string value_json = "null";
+          if (inner.compare(0, prefix.size(), prefix) == 0 &&
+              inner.size() > prefix.size() + 1) {
+            value_json = inner.substr(prefix.size(), inner.size() - prefix.size() - 1);
+          }
+          payload += ",\"ok\":true,\"value\":\"" + bunite_mac::escapeJsonString(value_json) + "\"}";
+        } else {
+          // Anchor extraction at the fixed envelope prefix — user-controlled
+          // e.message could otherwise inject a fake "code" via substring match.
+          static const std::string codePrefix = "{\"__bunite_ok\":false,\"code\":\"";
+          std::string code = "runtime_error";
+          std::string msg = "script threw";
+          if (inner.compare(0, codePrefix.size(), codePrefix) == 0) {
+            size_t start = codePrefix.size();
+            size_t end = start;
+            while (end < inner.size() && inner[end] != '"') ++end;
+            if (end > start) code = inner.substr(start, end - start);
+            static const std::string msgKey = "\",\"message\":\"";
+            if (end + msgKey.size() <= inner.size() &&
+                inner.compare(end, msgKey.size(), msgKey) == 0) {
+              size_t mstart = end + msgKey.size();
+              size_t mend = mstart;
+              while (mend < inner.size()) {
+                if (inner[mend] == '"' && (mend == mstart || inner[mend - 1] != '\\')) break;
+                ++mend;
+              }
+              if (mend > mstart) msg = inner.substr(mstart, mend - mstart);
+            }
+          }
+          payload += ",\"ok\":false,\"code\":\"" + bunite_mac::escapeJsonString(code) + "\","
+                     "\"message\":\"" + bunite_mac::escapeJsonString(msg) + "\"}";
+        }
+      }
+      bunite_mac::emitWebviewEvent(view_id, "evaluate-result", payload);
+    }];
+  });
 }
 
 extern "C" BUNITE_EXPORT void bunite_view_load_url(uint32_t view_id, const char* url) {
@@ -443,6 +513,558 @@ extern "C" BUNITE_EXPORT void bunite_view_remove(uint32_t view_id) {
   runOnUiThreadSync([=]() { bunite_mac::removeView(view_id); });
 }
 
+// Input dispatch — synthesized NSEvent directly to the WKWebView (not via
+// `[NSApp sendEvent:]` — see ctrl-strip note in `bunite_view_click`). WebKit
+// marks these events `isTrusted=true` on the page; capabilities flag matches.
+namespace {
+
+NSEventModifierFlags macModifiers(uint32_t bits) {
+  NSEventModifierFlags m = 0;
+  if (bits & 8) m |= NSEventModifierFlagShift;
+  if (bits & 2) m |= NSEventModifierFlagControl;
+  if (bits & 1) m |= NSEventModifierFlagOption;
+  if (bits & 4) m |= NSEventModifierFlagCommand;
+  return m;
+}
+
+NSEventType macMouseDownType(int32_t button) {
+  switch (button) {
+    case 1: return NSEventTypeOtherMouseDown;
+    case 2: return NSEventTypeRightMouseDown;
+    default: return NSEventTypeLeftMouseDown;
+  }
+}
+NSEventType macMouseUpType(int32_t button) {
+  switch (button) {
+    case 1: return NSEventTypeOtherMouseUp;
+    case 2: return NSEventTypeRightMouseUp;
+    default: return NSEventTypeLeftMouseUp;
+  }
+}
+
+// FFI x/y is CSS px in top-left view space; convert to AppKit window coords.
+// WKWebView is non-flipped, so y flips against bounds.height.
+NSPoint viewPointToWindow(NSView* view, double x, double y) {
+  NSRect bounds = view.bounds;
+  NSPoint local = view.isFlipped ? NSMakePoint(x, y) : NSMakePoint(x, bounds.size.height - y);
+  return [view convertPoint:local toView:nil];
+}
+
+}  // namespace
+
+extern "C" BUNITE_EXPORT void bunite_view_click(uint32_t view_id, double x, double y,
+                                                  int32_t button, int32_t click_count, uint32_t modifiers) {
+  if (click_count < 1) click_count = 1;
+  runOnUiThreadSync([=]() {
+    auto* v = bunite_mac::findView(view_id);
+    if (!v || !v->webview || !v->webview.window) return;
+    NSWindow* win = v->webview.window;
+    NSPoint loc = viewPointToWindow(v->webview, x, y);
+    // Strip the Control bit from mouse-event modifierFlags: AppKit converts
+    // Ctrl+leftMouseDown into a secondary click (context-menu modal),
+    // deadlocking the cooperative pump. Page-side `ctrlKey` will read false
+    // for ctrl-click on mac as a result — callers needing ctrl-click should
+    // wrap with explicit `press("Control")` keydown/keyup.
+    NSEventModifierFlags flags = macModifiers(modifiers) & ~NSEventModifierFlagControl;
+    // dblclick parity: ascending clickCount per pair. Dispatch directly to
+    // the WKWebView — `[win sendEvent:]` enters AppKit's modal mouse-tracking
+    // loop and deadlocks the cooperative pump.
+    for (int i = 1; i <= click_count; ++i) {
+      NSEvent* down = [NSEvent mouseEventWithType:macMouseDownType(button)
+                                         location:loc modifierFlags:flags
+                                        timestamp:[[NSProcessInfo processInfo] systemUptime]
+                                     windowNumber:win.windowNumber context:nil
+                                      eventNumber:0 clickCount:i pressure:1.0];
+      NSEvent* up = [NSEvent mouseEventWithType:macMouseUpType(button)
+                                       location:loc modifierFlags:flags
+                                      timestamp:[[NSProcessInfo processInfo] systemUptime]
+                                   windowNumber:win.windowNumber context:nil
+                                    eventNumber:0 clickCount:i pressure:0.0];
+      // Dispatch directly to WKWebView — `[NSApp sendEvent:]` would translate
+      // Ctrl+leftMouseDown into rightMouseDown (AppKit's emulated secondary
+      // click), entering the context-menu modal run-loop mode and stalling
+      // the cooperative pump indefinitely.
+      if (down) {
+        if (button == 0)      [v->webview mouseDown:down];
+        else if (button == 2) [v->webview rightMouseDown:down];
+        else                  [v->webview otherMouseDown:down];
+      }
+      if (up) {
+        if (button == 0)      [v->webview mouseUp:up];
+        else if (button == 2) [v->webview rightMouseUp:up];
+        else                  [v->webview otherMouseUp:up];
+      }
+    }
+  });
+}
+
+extern "C" BUNITE_EXPORT void bunite_view_type(uint32_t view_id, const char* text) {
+  std::string s = text ? text : "";
+  runOnUiThreadSync([=]() {
+    auto* v = bunite_mac::findView(view_id);
+    if (!v || !v->webview) return;
+    NSString* ns = [NSString stringWithUTF8String:s.c_str()];
+    if (!ns.length) return;
+    // WKWebView conforms to NSTextInputClient — insertText: routes through
+    // its IME chain so DOM input events fire on focused editable elements.
+    if ([v->webview respondsToSelector:@selector(insertText:)]) {
+      [(id)v->webview insertText:ns];
+    }
+  });
+}
+
+extern "C" BUNITE_EXPORT void bunite_view_press(uint32_t view_id, int32_t /*windows_vk_code*/,
+                                                  int32_t mac_key_code, const char* /*key*/, const char* /*code*/,
+                                                  const char* character, uint32_t modifiers,
+                                                  int32_t action, bool /*extended*/, int32_t /*location*/) {
+  std::string char_str = character ? character : "";
+  runOnUiThreadSync([=]() {
+    auto* v = bunite_mac::findView(view_id);
+    if (!v || !v->webview || !v->webview.window) return;
+    NSString* chars = char_str.empty() ? @"" : [NSString stringWithUTF8String:char_str.c_str()];
+    NSEventModifierFlags flags = macModifiers(modifiers);
+    NSWindow* win = v->webview.window;
+    if (action != 1) {
+      NSEvent* down = [NSEvent keyEventWithType:NSEventTypeKeyDown
+                                       location:NSZeroPoint modifierFlags:flags
+                                      timestamp:[[NSProcessInfo processInfo] systemUptime]
+                                   windowNumber:win.windowNumber context:nil
+                                     characters:chars charactersIgnoringModifiers:chars
+                                      isARepeat:NO keyCode:(unsigned short)mac_key_code];
+      if (down) [v->webview keyDown:down];
+    }
+    if (action != 0) {
+      NSEvent* up = [NSEvent keyEventWithType:NSEventTypeKeyUp
+                                     location:NSZeroPoint modifierFlags:flags
+                                    timestamp:[[NSProcessInfo processInfo] systemUptime]
+                                 windowNumber:win.windowNumber context:nil
+                                   characters:chars charactersIgnoringModifiers:chars
+                                    isARepeat:NO keyCode:(unsigned short)mac_key_code];
+      if (up) [v->webview keyUp:up];
+    }
+  });
+}
+
+extern "C" BUNITE_EXPORT void bunite_view_scroll(uint32_t view_id, double dx, double dy,
+                                                   double x, double y, uint32_t modifiers) {
+  runOnUiThreadSync([=]() {
+    auto* v = bunite_mac::findView(view_id);
+    if (!v || !v->webview || !v->webview.window) return;
+    CGEventRef cg = CGEventCreateScrollWheelEvent(NULL, kCGScrollEventUnitPixel, 2,
+                                                  static_cast<int32_t>(-dy),
+                                                  static_cast<int32_t>(-dx));
+    if (!cg) return;
+    // CGEvent location is screen coords; CSS px → window → screen.
+    NSPoint inWin = viewPointToWindow(v->webview, x, y);
+    NSPoint onScreen = [v->webview.window convertPointToScreen:inWin];
+    CGEventSetLocation(cg, CGPointMake(onScreen.x, onScreen.y));
+    CGEventSetFlags(cg, (CGEventFlags)macModifiers(modifiers));
+    NSEvent* ev = [NSEvent eventWithCGEvent:cg];
+    CFRelease(cg);
+    if (ev) [v->webview scrollWheel:ev];
+  });
+}
+
+extern "C" BUNITE_EXPORT void bunite_view_respond_dialog(uint32_t view_id, uint32_t request_id,
+                                                          bool accept, const char* text) {
+  std::string text_str = text ? text : "";
+  runOnUiThreadSync([=]() {
+    auto* v = bunite_mac::findView(view_id);
+    if (!v) return;
+    auto it = v->pending_dialogs.find(request_id);
+    if (it == v->pending_dialogs.end()) return;
+    auto cb = it->second;
+    v->pending_dialogs.erase(it);
+    if (cb) cb(accept, text_str);
+  });
+}
+
+extern "C" BUNITE_EXPORT void bunite_view_mouse(uint32_t view_id, int32_t action,
+                                                  double x, double y, int32_t button,
+                                                  uint32_t modifiers) {
+  runOnUiThreadSync([=]() {
+    auto* v = bunite_mac::findView(view_id);
+    if (!v || !v->webview || !v->webview.window) return;
+    NSWindow* win = v->webview.window;
+    NSPoint loc = viewPointToWindow(v->webview, x, y);
+    // Strip Control bit on mouse events for the same reason as click —
+    // AppKit Ctrl+leftMouseDown maps to secondary-click which enters context
+    // menu modal mode and stalls the cooperative pump.
+    NSEventModifierFlags flags = macModifiers(modifiers) & ~NSEventModifierFlagControl;
+    NSEventType type;
+    if (action == 0) {
+      type = NSEventTypeMouseMoved;
+    } else if (action == 1) {
+      type = macMouseDownType(button);
+    } else {
+      type = macMouseUpType(button);
+    }
+    NSEvent* ev = [NSEvent mouseEventWithType:type
+                                     location:loc modifierFlags:flags
+                                    timestamp:[[NSProcessInfo processInfo] systemUptime]
+                                 windowNumber:win.windowNumber context:nil
+                                  eventNumber:0 clickCount:(action == 0 ? 0 : 1)
+                                     pressure:(action == 1 ? 1.0 : 0.0)];
+    if (!ev) return;
+    // Direct WKWebView dispatch — same modal-tracking concerns as click.
+    if (action == 0) {
+      [v->webview mouseMoved:ev];
+    } else if (action == 1) {
+      if (button == 0) [v->webview mouseDown:ev];
+      else if (button == 1) [v->webview otherMouseDown:ev];
+      else [v->webview rightMouseDown:ev];
+    } else {
+      if (button == 0) [v->webview mouseUp:ev];
+      else if (button == 1) [v->webview otherMouseUp:ev];
+      else [v->webview rightMouseUp:ev];
+    }
+  });
+}
+
+// Screenshot — WKWebView.takeSnapshotWithConfiguration: + NSBitmapImageRep PNG/JPEG.
+namespace {
+
+void emitMacScreenshotError(uint32_t view_id, uint32_t request_id, const char* code, NSString* msg) {
+  std::string m = msg ? (msg.UTF8String ?: "") : "";
+  std::string payload = "{\"requestId\":" + std::to_string(request_id) +
+                        ",\"ok\":false,\"code\":\"" + code + "\","
+                        "\"message\":\"" + bunite_mac::escapeJsonString(m) + "\"}";
+  bunite_mac::emitWebviewEvent(view_id, "screenshot-result", payload);
+}
+
+}  // namespace
+
+extern "C" BUNITE_EXPORT uint32_t bunite_view_capabilities(uint32_t view_id) {
+  // WKWebView — synthetic NSEvent dispatched directly to the view. Empirically
+  // WebKit marks these events `isTrusted=true` on the page (the synthesis bit
+  // matters for AppKit responder routing, not for the DOM trust flag).
+  auto* v = bunite_mac::findView(view_id);
+  if (!v) return 0;
+  return BUNITE_CAP_EVALUATE | BUNITE_CAP_SURFACE_EVENTS |
+         BUNITE_CAP_NATIVE_INPUT_TRUSTED |
+         BUNITE_CAP_CLICK | BUNITE_CAP_TYPE | BUNITE_CAP_PRESS | BUNITE_CAP_SCROLL |
+         BUNITE_CAP_MOUSE | BUNITE_CAP_DIALOGS | BUNITE_CAP_CONSOLE |
+         BUNITE_CAP_SCREENSHOT | BUNITE_CAP_FORMAT_PNG | BUNITE_CAP_FORMAT_JPEG |
+         BUNITE_CAP_BOUNDING_RECT |
+         BUNITE_CAP_RESOLVE_AND_CLICK | BUNITE_CAP_DOWNLOADS | BUNITE_CAP_POPUPS |
+         BUNITE_CAP_AX | BUNITE_CAP_FRAMES;
+}
+
+namespace {
+
+// JS-bridge ax tree (mirrors linux backend) — WKWebView has no public host-side
+// ax API. Walks DOM + ARIA attrs, emits CDP-shaped flat list so TS-side
+// convertAxTree works unchanged. `ignored` always false (interestingOnly no-op).
+NSString* const kAxScript = @"(function(){"
+  "var nodes=[];"
+  "function add(el,parentId){"
+  "if(!el||el.nodeType!==1)return null;"
+  "var id=String(nodes.length+1);"
+  "var node={nodeId:id,parentId:parentId,"
+  "role:{value:el.getAttribute('role')||el.tagName.toLowerCase()},"
+  "name:{value:el.getAttribute('aria-label')||"
+  "(el.tagName==='INPUT'||el.tagName==='TEXTAREA'?'':"
+  "(el.firstChild&&el.firstChild.nodeType===3?el.firstChild.textContent.trim().slice(0,100):''))},"
+  "properties:[],childIds:[],ignored:false};"
+  "var d=el.getAttribute('aria-description');if(d)node.description={value:d};"
+  "if(el.tagName==='INPUT'||el.tagName==='TEXTAREA'){if(el.value)node.value={value:el.value};}"
+  "if(el.getAttribute('aria-disabled')==='true'||el.disabled)node.properties.push({name:'disabled',value:{value:true}});"
+  "var ck=el.getAttribute('aria-checked');"
+  "if(ck==='true')node.properties.push({name:'checked',value:{value:true}});"
+  "else if(ck==='false')node.properties.push({name:'checked',value:{value:false}});"
+  "else if(ck==='mixed')node.properties.push({name:'checked',value:{value:'mixed'}});"
+  "var pr=el.getAttribute('aria-pressed');"
+  "if(pr==='true')node.properties.push({name:'pressed',value:{value:true}});"
+  "else if(pr==='false')node.properties.push({name:'pressed',value:{value:false}});"
+  "else if(pr==='mixed')node.properties.push({name:'pressed',value:{value:'mixed'}});"
+  "if(el.getAttribute('aria-expanded')==='true')node.properties.push({name:'expanded',value:{value:true}});"
+  "if(el.getAttribute('aria-selected')==='true')node.properties.push({name:'selected',value:{value:true}});"
+  "if(el.getAttribute('aria-required')==='true')node.properties.push({name:'required',value:{value:true}});"
+  "if(el.getAttribute('aria-invalid')==='true')node.properties.push({name:'invalid',value:{value:true}});"
+  "var lv=el.getAttribute('aria-level');if(lv)node.properties.push({name:'level',value:{value:parseInt(lv,10)}});"
+  "if(document.activeElement===el)node.properties.push({name:'focused',value:{value:true}});"
+  "nodes.push(node);"
+  "for(var i=0;i<el.children.length;i++){var cid=add(el.children[i],id);if(cid)node.childIds.push(cid);}"
+  "return id;"
+  "}"
+  "add(document.documentElement,null);"
+  "return JSON.stringify({nodes:nodes});"
+  "})()";
+
+// JS-bridge frame tree — walks window.frames into CDP `Page.getFrameTree` shape.
+NSString* const kFramesScript = @"(function(){"
+  "var id=0;"
+  "function walk(win){"
+  "var fid=String(++id);"
+  "var frame={id:fid,securityOrigin:'',url:''};"
+  "try{frame.url=win.location.href;frame.securityOrigin=win.location.origin;"
+  "if(win.frameElement&&win.frameElement.name)frame.name=win.frameElement.name;}catch(e){}"
+  "var children=[];"
+  "try{for(var i=0;i<win.frames.length;i++)children.push(walk(win.frames[i]));}catch(e){}"
+  "return {frame:frame,childFrames:children};"
+  "}"
+  "return JSON.stringify({frameTree:walk(window)});"
+  "})()";
+
+}  // namespace
+
+extern "C" BUNITE_EXPORT void bunite_view_accessibility_snapshot(uint32_t view_id, uint32_t request_id,
+                                                                  int32_t /*interesting_only*/) {
+  runOnUiThreadSync([=]() {
+    auto* v = bunite_mac::findView(view_id);
+    if (!v || !v->webview) {
+      std::string payload = "{\"requestId\":" + std::to_string(request_id) +
+                            ",\"ok\":false,\"code\":\"not_supported\","
+                            "\"message\":\"view not ready\"}";
+      bunite_mac::emitWebviewEvent(view_id, "accessibility-result", payload);
+      return;
+    }
+    [v->webview evaluateJavaScript:kAxScript completionHandler:^(id result, NSError* error) {
+      std::string payload = "{\"requestId\":" + std::to_string(request_id);
+      if (error || ![result isKindOfClass:[NSString class]]) {
+        std::string msg = error ? std::string(error.localizedDescription.UTF8String ?: "evaluate failed")
+                                : std::string("non-string ax result");
+        payload += ",\"ok\":false,\"code\":\"runtime_error\","
+                   "\"message\":\"" + bunite_mac::escapeJsonString(msg) + "\"}";
+      } else {
+        std::string tree_json = ((NSString*)result).UTF8String ?: "{}";
+        payload += ",\"ok\":true,\"tree\":" + tree_json + "}";
+      }
+      bunite_mac::emitWebviewEvent(view_id, "accessibility-result", payload);
+    }];
+  });
+}
+
+extern "C" BUNITE_EXPORT void bunite_view_list_frames(uint32_t view_id, uint32_t request_id) {
+  runOnUiThreadSync([=]() {
+    auto* v = bunite_mac::findView(view_id);
+    if (!v || !v->webview) {
+      std::string payload = "{\"requestId\":" + std::to_string(request_id) +
+                            ",\"ok\":false,\"code\":\"not_supported\","
+                            "\"message\":\"view not ready\"}";
+      bunite_mac::emitWebviewEvent(view_id, "list-frames-result", payload);
+      return;
+    }
+    [v->webview evaluateJavaScript:kFramesScript completionHandler:^(id result, NSError* error) {
+      std::string payload = "{\"requestId\":" + std::to_string(request_id);
+      if (error || ![result isKindOfClass:[NSString class]]) {
+        std::string msg = error ? std::string(error.localizedDescription.UTF8String ?: "evaluate failed")
+                                : std::string("non-string frames result");
+        payload += ",\"ok\":false,\"code\":\"runtime_error\","
+                   "\"message\":\"" + bunite_mac::escapeJsonString(msg) + "\"}";
+      } else {
+        std::string tree_json = ((NSString*)result).UTF8String ?: "{}";
+        payload += ",\"ok\":true,\"raw\":" + tree_json + "}";
+      }
+      bunite_mac::emitWebviewEvent(view_id, "list-frames-result", payload);
+    }];
+  });
+}
+
+extern "C" BUNITE_EXPORT void bunite_view_evaluate_in_frame(uint32_t view_id, uint32_t request_id,
+                                                              const char* script_c, const char* frame_id_c) {
+  std::string script = script_c ? script_c : "";
+  std::string frame_id = frame_id_c ? frame_id_c : "";
+  if (frame_id.empty()) {
+    bunite_view_evaluate(view_id, request_id, script_c);
+    return;
+  }
+  std::string js_target = bunite_mac::escapeJsonString(frame_id);
+  std::string js_script = bunite_mac::escapeJsonString(script);
+  std::string inner =
+    "(function(){var target=\"" + js_target + "\";var id=0;var found=null;"
+    "function walk(win){var fid=String(++id);if(fid===target){found=win;return;}"
+    "try{for(var i=0;i<win.frames.length;i++){walk(win.frames[i]);if(found)return;}}catch(e){}}"
+    "walk(window);"
+    "if(!found)throw new Error('frame not found');"
+    "return found.eval(\"(\"+\"" + js_script + "\"+\")\");"
+    "})()";
+  bunite_view_evaluate(view_id, request_id, inner.c_str());
+}
+
+namespace {
+
+void emitResolveAndClickErrorMac(uint32_t view_id, uint32_t request_id, const char* code, const std::string& msg) {
+  std::string payload = "{\"requestId\":" + std::to_string(request_id) +
+                        ",\"ok\":false,\"code\":\"" + code + "\","
+                        "\"message\":\"" + bunite_mac::escapeJsonString(msg) + "\"}";
+  bunite_mac::emitWebviewEvent(view_id, "resolve-and-click-result", payload);
+}
+
+std::string escapeForJsStringMac(const std::string& s) {
+  std::string out; out.reserve(s.size() + 2);
+  for (char c : s) {
+    if (c == '"' || c == '\\') { out.push_back('\\'); out.push_back(c); }
+    else if (c == '\n') out += "\\n";
+    else if (c == '\r') out += "\\r";
+    else if (c == '\t') out += "\\t";
+    else out.push_back(c);
+  }
+  return out;
+}
+
+}  // namespace
+
+extern "C" BUNITE_EXPORT void bunite_view_resolve_and_click(
+    uint32_t view_id, uint32_t request_id,
+    const char* selector_c, const char* frame_id_c,
+    int32_t button, int32_t click_count, uint32_t modifiers) {
+  std::string selector = selector_c ? selector_c : "";
+  std::string frameId = frame_id_c ? frame_id_c : "";
+  if (!frameId.empty()) {
+    // No frame addressing on WKWebView — sync reject before UI hop.
+    emitResolveAndClickErrorMac(view_id, request_id, "not_supported",
+                                "WKWebView has no frame addressing API");
+    return;
+  }
+  if (click_count < 1) click_count = 1;
+  std::string sel_lit = "\"" + escapeForJsStringMac(selector) + "\"";
+  std::string script =
+    "(function(){"
+      "var el=document.querySelector(" + sel_lit + ");"
+      "if(!el)return{ok:false,code:\"not_found\"};"
+      "el.scrollIntoView({block:\"nearest\",inline:\"nearest\",behavior:\"instant\"});"
+      "var r=el.getBoundingClientRect();"
+      "var vis=r.width>0&&r.height>0&&r.bottom>0&&r.right>0"
+      "&&r.top<innerHeight&&r.left<innerWidth;"
+      "if(!vis)return{ok:false,code:\"not_visible\"};"
+      "return{ok:true,x:r.x,y:r.y,w:r.width,h:r.height,"
+      "cx:r.x+r.width/2,cy:r.y+r.height/2};"
+    "})()";
+  NSString* nsScript = [NSString stringWithUTF8String:script.c_str()];
+  runOnUiThreadSync([=]() {
+    auto* v = bunite_mac::findView(view_id);
+    if (!v || !v->webview || !v->webview.window) {
+      emitResolveAndClickErrorMac(view_id, request_id, "runtime_error", "view not ready");
+      return;
+    }
+    [v->webview evaluateJavaScript:nsScript completionHandler:^(id result, NSError* error) {
+      if (error || ![result isKindOfClass:[NSDictionary class]]) {
+        std::string msg = error ? std::string(error.localizedDescription.UTF8String ?: "evaluate failed")
+                                : std::string("evaluate returned non-object");
+        emitResolveAndClickErrorMac(view_id, request_id, "runtime_error", msg);
+        return;
+      }
+      NSDictionary* d = (NSDictionary*)result;
+      id okVal = d[@"ok"];
+      const bool ok = [okVal respondsToSelector:@selector(boolValue)] && [okVal boolValue];
+      if (!ok) {
+        id codeVal = d[@"code"];
+        std::string code = [codeVal isKindOfClass:[NSString class]]
+                             ? std::string([(NSString*)codeVal UTF8String] ?: "runtime_error")
+                             : std::string("runtime_error");
+        emitResolveAndClickErrorMac(view_id, request_id, code.c_str(), "");
+        return;
+      }
+      auto pickD = [&](NSString* k)->double {
+        id x = d[k];
+        return [x respondsToSelector:@selector(doubleValue)] ? [x doubleValue] : 0.0;
+      };
+      double x = pickD(@"x"), y = pickD(@"y"), w = pickD(@"w"), h = pickD(@"h");
+      double cx = pickD(@"cx"), cy = pickD(@"cy");
+      auto* v2 = bunite_mac::findView(view_id);
+      if (!v2 || !v2->webview || !v2->webview.window) {
+        emitResolveAndClickErrorMac(view_id, request_id, "runtime_error", "view destroyed");
+        return;
+      }
+      NSWindow* win = v2->webview.window;
+      NSPoint loc = viewPointToWindow(v2->webview, cx, cy);
+      NSEventModifierFlags flags = macModifiers(modifiers) & ~NSEventModifierFlagControl;
+      for (int i = 1; i <= click_count; ++i) {
+        NSEvent* down = [NSEvent mouseEventWithType:macMouseDownType(button)
+                                           location:loc modifierFlags:flags
+                                          timestamp:[[NSProcessInfo processInfo] systemUptime]
+                                       windowNumber:win.windowNumber context:nil
+                                        eventNumber:0 clickCount:i pressure:1.0];
+        NSEvent* up = [NSEvent mouseEventWithType:macMouseUpType(button)
+                                         location:loc modifierFlags:flags
+                                        timestamp:[[NSProcessInfo processInfo] systemUptime]
+                                     windowNumber:win.windowNumber context:nil
+                                      eventNumber:0 clickCount:i pressure:0.0];
+        if (down) {
+          if (button == 0)      [v2->webview mouseDown:down];
+          else if (button == 2) [v2->webview rightMouseDown:down];
+          else                  [v2->webview otherMouseDown:down];
+        }
+        if (up) {
+          if (button == 0)      [v2->webview mouseUp:up];
+          else if (button == 2) [v2->webview rightMouseUp:up];
+          else                  [v2->webview otherMouseUp:up];
+        }
+      }
+      std::string payload = "{\"requestId\":" + std::to_string(request_id) +
+                            ",\"ok\":true,\"rect\":{\"x\":" + std::to_string(x) +
+                            ",\"y\":" + std::to_string(y) +
+                            ",\"width\":" + std::to_string(w) +
+                            ",\"height\":" + std::to_string(h) + "},"
+                            "\"isTrustedEvent\":true}";
+      bunite_mac::emitWebviewEvent(view_id, "resolve-and-click-result", payload);
+    }];
+  });
+}
+
+extern "C" BUNITE_EXPORT void bunite_view_set_download_policy(uint32_t view_id, int32_t policy, const char* download_dir) {
+  auto* st = bunite_mac::findView(view_id);
+  if (!st) return;
+  if (policy < 0 || policy > 2) policy = 2;
+  st->download_policy.store(policy);
+  st->download_dir = download_dir ? download_dir : "";
+}
+
+extern "C" 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) {
+  runOnUiThreadSync([=]() { bunite_mac::acceptParkedPopup(new_view_id, host_window_id, x, y, w, h); });
+}
+
+extern "C" BUNITE_EXPORT void bunite_view_popup_dismiss(uint32_t new_view_id) {
+  runOnUiThreadSync([=]() { bunite_mac::dismissParkedPopup(new_view_id); });
+}
+
+extern "C" BUNITE_EXPORT void bunite_view_screenshot(uint32_t view_id, uint32_t request_id,
+                                                       const char* format, int32_t quality) {
+  std::string fmt = format ? format : "png";
+  runOnUiThreadSync([=]() {
+    auto* v = bunite_mac::findView(view_id);
+    if (!v || !v->webview) {
+      emitMacScreenshotError(view_id, request_id, "not_supported", @"view not ready");
+      return;
+    }
+    WKSnapshotConfiguration* cfg = [[WKSnapshotConfiguration alloc] init];
+    cfg.afterScreenUpdates = YES;
+    const bool jpeg = (fmt == "jpeg" || fmt == "jpg");
+    NSString* outFmt = jpeg ? @"jpeg" : @"png";
+    NSString* mime = jpeg ? @"image/jpeg" : @"image/png";
+    [v->webview takeSnapshotWithConfiguration:cfg
+                            completionHandler:^(NSImage* img, NSError* err) {
+      if (err || !img) {
+        emitMacScreenshotError(view_id, request_id, "runtime_error", err ? err.localizedDescription : @"takeSnapshot returned nil");
+        return;
+      }
+      CGImageRef cgImg = [img CGImageForProposedRect:nullptr context:nil hints:nil];
+      if (!cgImg) {
+        emitMacScreenshotError(view_id, request_id, "runtime_error", @"CGImageForProposedRect failed");
+        return;
+      }
+      NSBitmapImageRep* rep = [[NSBitmapImageRep alloc] initWithCGImage:cgImg];
+      NSDictionary* props = jpeg
+        ? @{ NSImageCompressionFactor: @((quality < 0 ? 0.9 : std::min(quality, 100) / 100.0)) }
+        : @{};
+      NSData* data = [rep representationUsingType:(jpeg ? NSBitmapImageFileTypeJPEG : NSBitmapImageFileTypePNG)
+                                       properties:props];
+      if (!data || data.length == 0) {
+        emitMacScreenshotError(view_id, request_id, "runtime_error", @"encode failed");
+        return;
+      }
+      NSString* b64 = [data base64EncodedStringWithOptions:0];
+      std::string payload = "{\"requestId\":" + std::to_string(request_id) +
+                            ",\"ok\":true,\"format\":\"" + outFmt.UTF8String +
+                            "\",\"mime\":\"" + mime.UTF8String +
+                            "\",\"dataBase64\":\"" + (b64.UTF8String ?: "") + "\"}";
+      bunite_mac::emitWebviewEvent(view_id, "screenshot-result", payload);
+    }];
+  });
+}
+
 extern "C" BUNITE_EXPORT void bunite_view_open_devtools(uint32_t view_id) {
   runOnUiThreadSync([=]() {
     if (@available(macOS 13.3, *)) {