bunite-core 0.14.0 → 0.17.0

package/src/host/core/SurfaceManager.ts

@@ -6,9 +6,11 @@ import {
 } from "./SurfaceRegistry";
 import {
   SurfaceCap, type ImplOf, IpcError,
-  type SurfaceEvent, type DialogEvent, type ConsoleEntry,
+  type SurfaceEvent, type SurfaceEventBase, type DialogEvent, type ConsoleEntry,
+  type NavigationState, type DownloadEvent, type WaitForDownloadResult,
 } from "../../rpc/index";
 import { Stream } from "../../rpc/stream";
+import { log } from "../log";
 
 function applyHostOffset(hostView: BrowserView, x: number, y: number) {
   return { x: x + hostView.frame.x, y: y + hostView.frame.y };
@@ -24,10 +26,32 @@ export function onSurfaceInit(cb: SurfaceInitCallback) {
 type SurfaceEventEmit = (event: { surfaceId: number; event: SurfaceEvent }) => void;
 const surfaceEventSubs = new Map<number, Set<SurfaceEventEmit>>();
 
-export function emitSurfaceEvent(hostViewId: number, surfaceId: number, event: SurfaceEvent) {
+export function emitSurfaceEvent(
+  hostViewId: number,
+  surfaceId: number,
+  event: SurfaceEventBase,
+) {
+  // Drop late events after dispose so dead surfaceIds don't resurrect state.
+  if (!getSurfaceRecord(surfaceId)) return;
+  // Mutate before the subscriber guard so `getNavigationState` stays correct.
+  const state = getOrCreateState(surfaceId);
+  if (event.type === "navigate") {
+    state.lastLoadEpoch++;
+    state.currentUrl = event.url;
+  } else if (event.type === "load-start") {
+    state.isLoading = true;
+  } else if (event.type === "load-finish" || event.type === "load-fail") {
+    state.isLoading = false;
+  }
+  const stamped: SurfaceEvent = { ...event, epoch: state.lastLoadEpoch };
   const subs = surfaceEventSubs.get(hostViewId);
   if (!subs) return;
-  for (const emit of subs) emit({ surfaceId, event });
+  for (const emit of subs) emit({ surfaceId, event: stamped });
+}
+
+export function seedNavigationState(surfaceId: number, initialUrl: string) {
+  const state = getOrCreateState(surfaceId);
+  if (state.currentUrl === "") state.currentUrl = initialUrl;
 }
 
 type DialogEmit = (event: { surfaceId: number; event: DialogEvent }) => void;
@@ -36,6 +60,133 @@ const dialogSubs = new Map<number, Set<DialogEmit>>();
 type ConsoleEmit = (event: { surfaceId: number; entry: ConsoleEntry }) => void;
 const consoleSubs = new Map<number, Set<ConsoleEmit>>();
 
+type DownloadEmit = (event: { surfaceId: number; event: DownloadEvent }) => void;
+const downloadSubs = new Map<number, Set<DownloadEmit>>();
+
+type PendingPopup = {
+  newSurfaceId: number;
+  openerHostViewId: number;
+  openerSurfaceId: number;
+  url: string;
+  disposition: "tab" | "window" | "popup";
+  timer: ReturnType<typeof setTimeout> | null;
+  armTs: number;  // arm emit timestamp for the 60s extend cap
+};
+const pendingPopups = new Map<number, PendingPopup>();
+const POPUP_ADOPT_TIMEOUT_MS = 5000;
+const POPUP_EXTEND_CAP_MS = 60_000;
+// Capped log so callers calling extendPopupTimeout after resolution get a
+// distinct error code instead of bare not_found.
+const popupResolutionLog = new Map<number, "adopted" | "dismissed">();
+const POPUP_RESOLUTION_LOG_MAX = 64;
+function recordResolution(id: number, kind: "adopted" | "dismissed") {
+  if (popupResolutionLog.size >= POPUP_RESOLUTION_LOG_MAX) {
+    const firstKey = popupResolutionLog.keys().next().value;
+    if (firstKey !== undefined) popupResolutionLog.delete(firstKey);
+  }
+  popupResolutionLog.set(id, kind);
+  popupCounters[kind] += 1;
+}
+
+// Process-lifetime popup lifecycle counters; surfaced via RuntimeCap.popupMetrics.
+const popupCounters = { armed: 0, adopted: 0, dismissed: 0, timeoutFired: 0, extended: 0 };
+export function getPopupMetricsSnapshot() { return { ...popupCounters }; }
+
+/** Called when a backend mints a popup view. Stashes the pending adoption +
+ *  arms a timer that auto-dismisses if the host doesn't respond. */
+export function emitPopupRequested(
+  hostViewId: number,
+  openerSurfaceId: number,
+  args: { newSurfaceId: number; url: string; disposition: "tab" | "window" | "popup" },
+) {
+  const armTs = Date.now();
+  popupCounters.armed += 1;
+  const entry: PendingPopup = {
+    newSurfaceId: args.newSurfaceId,
+    openerHostViewId: hostViewId,
+    openerSurfaceId,
+    url: args.url,
+    disposition: args.disposition,
+    timer: null,
+    armTs,
+  };
+  entry.timer = setTimeout(() => {
+    if (!pendingPopups.delete(args.newSurfaceId)) return;
+    popupCounters.timeoutFired += 1;
+    recordResolution(args.newSurfaceId, "dismissed");
+    BrowserView.dismissPopupById(args.newSurfaceId);
+  }, POPUP_ADOPT_TIMEOUT_MS);
+  pendingPopups.set(args.newSurfaceId, entry);
+  emitSurfaceEvent(hostViewId, openerSurfaceId, {
+    type: "popup",
+    url: args.url,
+    disposition: args.disposition,
+    openerSurfaceId,
+    newSurfaceId: args.newSurfaceId,
+  });
+}
+type DownloadWaiter = {
+  /** Resolved on the next `completed` event (or `failed`/`blocked`). */
+  resolve: (r: WaitForDownloadResult) => void;
+  /** Captured at registration; only events with `id` started after this are eligible. */
+  pendingId: string | null;
+};
+const downloadWaiters = new Map<number, DownloadWaiter[]>();
+const downloadStartedMeta = new Map<number, Map<string, { url: string; suggestedFilename: string; mimeType?: string; sizeBytes?: number }>>();
+// Recent started events that no waiter has claimed yet — lets a `waitForDownload`
+// registered *after* the started event still bind. Per-surface, trimmed to 30s.
+const recentUnownedStarts = new Map<number, { id: string; ts: number }[]>();
+
+export function emitDownload(hostViewId: number, surfaceId: number, event: DownloadEvent) {
+  if (event.kind === "started") {
+    let bySurface = downloadStartedMeta.get(surfaceId);
+    if (!bySurface) { bySurface = new Map(); downloadStartedMeta.set(surfaceId, bySurface); }
+    bySurface.set(event.id, { url: event.url, suggestedFilename: event.suggestedFilename, mimeType: event.mimeType, sizeBytes: event.sizeBytes });
+    // Track unowned started events so a waitForDownload registering AFTER the
+    // started event can still bind. Trimmed to recent 30s on each insert.
+    let recents = recentUnownedStarts.get(surfaceId);
+    if (!recents) { recents = []; recentUnownedStarts.set(surfaceId, recents); }
+    const now = Date.now();
+    recents.push({ id: event.id, ts: now });
+    while (recents.length && now - recents[0].ts > 30_000) recents.shift();
+    const queue = downloadWaiters.get(surfaceId);
+    if (queue) for (const w of queue) if (w.pendingId === null) {
+      w.pendingId = event.id;
+      // Take the unowned entry out — it's now bound.
+      const idx = recents.findIndex((r) => r.id === event.id);
+      if (idx >= 0) recents.splice(idx, 1);
+      break;
+    }
+  }
+  const subs = downloadSubs.get(hostViewId);
+  if (subs) for (const emit of subs) emit({ surfaceId, event });
+  if (event.kind === "completed" || event.kind === "failed" || event.kind === "blocked") {
+    const queue = downloadWaiters.get(surfaceId);
+    if (queue) {
+      // First match by id (started → terminal pair). Else for blocked-without-started
+      // (policy=block emits only blocked), bind to the first waiting waiter.
+      let idx = queue.findIndex((w) => w.pendingId === event.id);
+      if (idx < 0 && event.kind === "blocked") idx = queue.findIndex((w) => w.pendingId === null);
+      if (idx >= 0) {
+        const [waiter] = queue.splice(idx, 1);
+        if (event.kind === "completed") {
+          const meta = downloadStartedMeta.get(surfaceId)?.get(event.id);
+          waiter.resolve({
+            ok: true, id: event.id, localPath: event.localPath,
+            url: meta?.url ?? "", suggestedFilename: meta?.suggestedFilename ?? "",
+            mimeType: meta?.mimeType, sizeBytes: meta?.sizeBytes,
+          });
+        } else if (event.kind === "failed") {
+          waiter.resolve({ ok: false, code: "failed", message: event.reason });
+        } else {
+          waiter.resolve({ ok: false, code: "blocked", message: event.reason });
+        }
+      }
+    }
+    downloadStartedMeta.get(surfaceId)?.delete(event.id);
+  }
+}
+
 const CONSOLE_BUFFER_LIMIT = 200;
 const DEFAULT_DIALOG_TIMEOUT_MS = 5000;
 
@@ -50,6 +201,9 @@ type SurfaceState = {
   consoleBuffer: ConsoleEntry[];
   dialogTimeoutMs: number | null;  // null = no auto-dismiss
   pendingDialogs: Map<number, PendingDialog>;
+  lastLoadEpoch: number;
+  isLoading: boolean;
+  currentUrl: string;
 };
 
 const surfaceState = new Map<number, SurfaceState>();
@@ -61,6 +215,9 @@ function getOrCreateState(surfaceId: number): SurfaceState {
       consoleBuffer: [],
       dialogTimeoutMs: DEFAULT_DIALOG_TIMEOUT_MS,
       pendingDialogs: new Map(),
+      lastLoadEpoch: 0,
+      isLoading: false,
+      currentUrl: "",
     };
     surfaceState.set(surfaceId, s);
   }
@@ -69,11 +226,17 @@ function getOrCreateState(surfaceId: number): SurfaceState {
 
 export function disposeSurfaceState(surfaceId: number) {
   const s = surfaceState.get(surfaceId);
-  if (!s) return;
-  for (const p of s.pendingDialogs.values()) {
-    if (p.timer) clearTimeout(p.timer);
+  if (s) {
+    for (const p of s.pendingDialogs.values()) if (p.timer) clearTimeout(p.timer);
+    surfaceState.delete(surfaceId);
+  }
+  const waiters = downloadWaiters.get(surfaceId);
+  if (waiters) {
+    for (const w of waiters) w.resolve({ ok: false, code: "not_supported", message: "surface destroyed" });
+    downloadWaiters.delete(surfaceId);
   }
-  surfaceState.delete(surfaceId);
+  downloadStartedMeta.delete(surfaceId);
+  recentUnownedStarts.delete(surfaceId);
 }
 
 // Wire dispose to any untrack path (remove + removeSurfacesForHostView).
@@ -86,6 +249,8 @@ export function clearConsoleBuffer(surfaceId: number) {
 
 export function emitDialog(hostViewId: number, surfaceId: number, event: DialogEvent) {
   const subs = dialogSubs.get(hostViewId);
+  log.debug("dialog/emit hostViewId=" + hostViewId + " surfaceId=" + surfaceId +
+            " kind=" + (event as { kind?: string }).kind + " subscribers=" + (subs?.size ?? 0));
   if (!subs) return;
   for (const emit of subs) emit({ surfaceId, event });
 }
@@ -108,6 +273,8 @@ export function registerDialogRequest(
   surfaceId: number,
   request: { requestId: number; kind: "alert" | "confirm" | "prompt" | "beforeunload"; message: string; defaultPrompt?: string }
 ) {
+  log.debug("dialog/register hostViewId=" + hostViewId + " surfaceId=" + surfaceId +
+            " kind=" + request.kind + " rid=" + request.requestId);
   const state = getOrCreateState(surfaceId);
   const view = getSurfaceRecord(surfaceId)?.view;
 
@@ -174,6 +341,7 @@ export function createSurfaceCapImpl(hostViewId: number): ImplOf<typeof SurfaceC
         autoResize: false,
       });
       trackSurface(view.id, { view, hostViewId, hidden });
+      seedNavigationState(view.id, src);
       try {
         await view.whenReady();
       } catch {
@@ -258,10 +426,10 @@ export function createSurfaceCapImpl(hostViewId: number): ImplOf<typeof SurfaceC
       record?.view.reload();
     },
 
-    evaluate: async ({ surfaceId, script }) => {
+    evaluate: async ({ surfaceId, script, frameId }) => {
       const record = ownedSurface(surfaceId);
       if (!record) return { ok: false, code: "not_supported", message: "surface not found" };
-      return record.view.evaluate(script);
+      return record.view.evaluate(script, frameId);
     },
 
     click: ({ surfaceId, ...args }) => {
@@ -300,17 +468,15 @@ export function createSurfaceCapImpl(hostViewId: number): ImplOf<typeof SurfaceC
       return record.view.screenshot(format, quality);
     },
 
-    waitForSelector: async ({ surfaceId, selector, timeoutMs = 5000 }) => {
+    waitForSelector: async ({ surfaceId, selector, timeoutMs = 5000, frameId }) => {
       const record = ownedSurface(surfaceId);
       if (!record) return { ok: false as const, code: "runtime_error" as const, message: "surface not found" };
       const deadline = Date.now() + timeoutMs;
       const expr = `!!document.querySelector(${JSON.stringify(selector)})`;
       while (Date.now() < deadline) {
-        const res = await record.view.evaluate(expr);
+        const res = await record.view.evaluate(expr, frameId);
         if (res.ok && res.value === true) return { ok: true as const };
         if (!res.ok && res.code !== "timeout") {
-          // Propagate cross_origin distinct from runtime_error — consumer
-          // may want to retry with a same-origin sub-surface vs. fix the script.
           const code = res.code === "cross_origin" ? "cross_origin" as const : "runtime_error" as const;
           return { ok: false as const, code, message: res.message };
         }
@@ -319,12 +485,12 @@ export function createSurfaceCapImpl(hostViewId: number): ImplOf<typeof SurfaceC
       return { ok: false as const, code: "timeout" as const, message: `selector ${JSON.stringify(selector)} not found within ${timeoutMs}ms` };
     },
 
-    waitForFunction: async ({ surfaceId, expression, timeoutMs = 5000, pollIntervalMs = 50 }) => {
+    waitForFunction: async ({ surfaceId, expression, timeoutMs = 5000, pollIntervalMs = 50, frameId }) => {
       const record = ownedSurface(surfaceId);
       if (!record) return { ok: false as const, code: "runtime_error" as const, message: "surface not found" };
       const deadline = Date.now() + timeoutMs;
       while (Date.now() < deadline) {
-        const res = await record.view.evaluate(expression);
+        const res = await record.view.evaluate(expression, frameId);
         if (res.ok && res.value) return { ok: true as const };
         if (!res.ok && res.code !== "timeout") {
           const code = res.code === "cross_origin" ? "cross_origin" as const : "runtime_error" as const;
@@ -365,7 +531,8 @@ export function createSurfaceCapImpl(hostViewId: number): ImplOf<typeof SurfaceC
           evaluate: false, crossOriginEval: false, surfaceEvents: false,
           nativeInputTrusted: false, click: false, type: false, press: false,
           scroll: false, mouse: false, dialogs: false, console: false,
-          screenshot: false,
+          screenshot: false, accessibilitySnapshot: false, getBoundingRect: false,
+          frames: false, downloads: false, popups: false, resolveAndClick: false,
         };
       }
       return record.view.capabilities();
@@ -399,14 +566,188 @@ export function createSurfaceCapImpl(hostViewId: number): ImplOf<typeof SurfaceC
         if (surfaceId === filterId) emit(event);
       };
       subs.add(wrapped);
+      log.debug("dialog/subscribe hostViewId=" + hostViewId + " filterId=" + filterId + " total=" + subs.size);
       signal.addEventListener("abort", () => {
         const set = dialogSubs.get(hostViewId);
         if (!set) return;
         set.delete(wrapped);
+        log.debug("dialog/unsubscribe hostViewId=" + hostViewId + " filterId=" + filterId + " remaining=" + set.size);
         if (set.size === 0) dialogSubs.delete(hostViewId);
       });
     }),
 
+    getNavigationState: ({ surfaceId }): NavigationState => {
+      const record = ownedSurface(surfaceId);
+      if (!record) return { lastLoadEpoch: 0, isLoading: false, currentUrl: "" };
+      const state = getOrCreateState(surfaceId);
+      return {
+        lastLoadEpoch: state.lastLoadEpoch,
+        isLoading: state.isLoading,
+        currentUrl: state.currentUrl,
+      };
+    },
+
+    accessibilitySnapshot: async ({ surfaceId, interestingOnly = true }) => {
+      const record = ownedSurface(surfaceId);
+      if (!record) return { ok: false as const, code: "runtime_error" as const, message: "surface not found" };
+      return record.view.accessibilitySnapshot(interestingOnly);
+    },
+
+    getBoundingRect: async ({ surfaceId, selector, frameId }) => {
+      const record = ownedSurface(surfaceId);
+      if (!record) return { ok: false as const, code: "runtime_error" as const, message: "surface not found" };
+      const expr = `(function(){var el=document.querySelector(${JSON.stringify(selector)});if(!el)return null;var r=el.getBoundingClientRect();return {x:r.x,y:r.y,width:r.width,height:r.height,visible:r.width>0&&r.height>0&&r.bottom>0&&r.right>0&&r.top<innerHeight&&r.left<innerWidth};})()`;
+      const res = await record.view.evaluate(expr, frameId);
+      if (!res.ok) {
+        const code = res.code === "cross_origin" ? "cross_origin" as const
+          : res.code === "not_supported" ? "not_supported" as const
+          : "runtime_error" as const;
+        return { ok: false as const, code, message: res.message };
+      }
+      const v = res.value as null | { x: number; y: number; width: number; height: number; visible: boolean };
+      if (!v) return { ok: false as const, code: "not_found" as const, message: `selector ${JSON.stringify(selector)} not found` };
+      return { ok: true as const, rect: { x: v.x, y: v.y, width: v.width, height: v.height }, visible: v.visible };
+    },
+
+    listFrames: async ({ surfaceId }) => {
+      const record = ownedSurface(surfaceId);
+      if (!record) return { ok: false as const, code: "runtime_error" as const, message: "surface not found" };
+      return record.view.listFrames();
+    },
+
+    resolveAndClick: async (args) => {
+      const record = ownedSurface(args.surfaceId);
+      if (!record) return { ok: false as const, code: "runtime_error" as const, message: "surface not found" };
+      if (!record.view.capabilities().resolveAndClick) {
+        return { ok: false as const, code: "not_supported" as const, message: "resolveAndClick not supported on this backend" };
+      }
+      return record.view.resolveAndClick(args);
+    },
+
+    downloadEvents: ({ surfaceId: filterId }) => Stream.from<DownloadEvent>((emit, signal) => {
+      let subs = downloadSubs.get(hostViewId);
+      if (!subs) { subs = new Set(); downloadSubs.set(hostViewId, subs); }
+      const wrapped: DownloadEmit = ({ surfaceId, event }) => {
+        if (surfaceId === filterId) emit(event);
+      };
+      subs.add(wrapped);
+      signal.addEventListener("abort", () => {
+        const set = downloadSubs.get(hostViewId);
+        if (!set) return;
+        set.delete(wrapped);
+        if (set.size === 0) downloadSubs.delete(hostViewId);
+      });
+    }),
+
+    waitForDownload: async ({ surfaceId, timeoutMs = 30000 }) => {
+      const record = ownedSurface(surfaceId);
+      if (!record) return { ok: false as const, code: "not_supported" as const, message: "surface not found" };
+      if (!record.view.capabilities().downloads) {
+        return { ok: false as const, code: "not_supported" as const, message: "downloads not supported on this backend" };
+      }
+      return new Promise<WaitForDownloadResult>((resolve) => {
+        // If a `started` already arrived without a waiter, consume it.
+        const recents = recentUnownedStarts.get(surfaceId);
+        const claimed = recents?.shift();
+        const waiter: DownloadWaiter = {
+          resolve: (r) => { clearTimeout(timer); resolve(r); },
+          pendingId: claimed?.id ?? null,
+        };
+        let queue = downloadWaiters.get(surfaceId);
+        if (!queue) { queue = []; downloadWaiters.set(surfaceId, queue); }
+        queue.push(waiter);
+        const timer = setTimeout(() => {
+          const q = downloadWaiters.get(surfaceId);
+          if (!q) return;
+          const idx = q.indexOf(waiter);
+          if (idx >= 0) q.splice(idx, 1);
+          resolve({ ok: false, code: "timeout", message: `no download started within ${timeoutMs}ms` });
+        }, timeoutMs);
+      });
+    },
+
+    setDownloadPolicy: ({ surfaceId, policy, downloadDir }) => {
+      const record = ownedSurface(surfaceId);
+      if (!record) return;
+      if (!record.view.capabilities().downloads) return;  // mac/linux silent no-op signal — caller should gate on cap.
+      record.view.setDownloadPolicy(policy, downloadDir);
+    },
+
+    acceptPopup: async ({ newSurfaceId, hostViewId: targetHostId, bounds }) => {
+      const pending = pendingPopups.get(newSurfaceId);
+      if (!pending) return { ok: false as const, code: "not_found" as const, message: "popup not pending" };
+      // Only the opener's host page can adopt the popup. The target host
+      // (where the new pane lands) is a separate decision.
+      if (pending.openerHostViewId !== hostViewId) {
+        return { ok: false as const, code: "not_found" as const, message: "popup not owned by this host" };
+      }
+      const targetHost = BrowserView.getById(targetHostId);
+      if (!targetHost || !targetHost.windowId) {
+        // Don't consume pending state on validation failure — host can retry
+        // with a different target until the auto-dismiss timer fires.
+        return { ok: false as const, code: "host_view_invalid" as const, message: "host view not found" };
+      }
+      const existing = getHostSurfaceIds(targetHostId);
+      if (existing && existing.size >= MAX_SURFACES_PER_HOST) {
+        return { ok: false as const, code: "host_view_invalid" as const, message: `host surface limit reached (${MAX_SURFACES_PER_HOST})` };
+      }
+      if (pending.timer) clearTimeout(pending.timer);
+      pendingPopups.delete(newSurfaceId);
+      recordResolution(newSurfaceId, "adopted");
+      const offset = applyHostOffset(targetHost, bounds.x, bounds.y);
+      const view = BrowserView.adopt({
+        nativeViewId: newSurfaceId,
+        hostWindowId: targetHost.windowId,
+        bounds: { x: offset.x, y: offset.y, width: bounds.width, height: bounds.height },
+        appresRoot: targetHost.appresRoot,
+      });
+      trackSurface(view.id, { view, hostViewId: targetHostId, hidden: false });
+      seedNavigationState(view.id, pending.url);
+      for (const cb of initCallbacks) cb(view.id, targetHostId, view);
+      return { ok: true as const };
+    },
+
+    dismissPopup: ({ newSurfaceId }) => {
+      const pending = pendingPopups.get(newSurfaceId);
+      if (!pending) return;
+      if (pending.openerHostViewId !== hostViewId) return;  // not this host's popup
+      if (pending.timer) clearTimeout(pending.timer);
+      pendingPopups.delete(newSurfaceId);
+      recordResolution(newSurfaceId, "dismissed");
+      BrowserView.dismissPopupById(newSurfaceId);
+    },
+
+    extendPopupTimeout: ({ newSurfaceId, gracePeriodMs }) => {
+      if (!Number.isFinite(gracePeriodMs) || gracePeriodMs <= 0) {
+        return { ok: false as const, code: "not_found" as const, message: "gracePeriodMs must be a positive finite number" };
+      }
+      const pending = pendingPopups.get(newSurfaceId);
+      if (!pending) {
+        const prior = popupResolutionLog.get(newSurfaceId);
+        if (prior === "adopted") return { ok: false as const, code: "already_adopted" as const, message: "popup adopted" };
+        if (prior === "dismissed") return { ok: false as const, code: "already_dismissed" as const, message: "popup dismissed" };
+        return { ok: false as const, code: "not_found" as const, message: "popup not pending" };
+      }
+      if (pending.openerHostViewId !== hostViewId) {
+        return { ok: false as const, code: "not_found" as const, message: "popup not owned by this host" };
+      }
+      const now = Date.now();
+      const requested = now + gracePeriodMs;
+      const cap = pending.armTs + POPUP_EXTEND_CAP_MS;
+      if (requested > cap) {
+        return { ok: false as const, code: "cap_exceeded" as const, message: `extend exceeds ${POPUP_EXTEND_CAP_MS}ms cap since arm` };
+      }
+      if (pending.timer) clearTimeout(pending.timer);
+      pending.timer = setTimeout(() => {
+        if (!pendingPopups.delete(newSurfaceId)) return;
+        popupCounters.timeoutFired += 1;
+        recordResolution(newSurfaceId, "dismissed");
+        BrowserView.dismissPopupById(newSurfaceId);
+      }, gracePeriodMs);
+      popupCounters.extended += 1;
+      return { ok: true as const, deadlineMs: requested };
+    },
+
     consoleEvents: ({ surfaceId: filterId }) => Stream.from<ConsoleEntry>((emit, signal) => {
       let subs = consoleSubs.get(hostViewId);
       if (!subs) {

package/src/host/core/windowCap.ts

@@ -0,0 +1,69 @@
+import { BrowserWindow } from "./BrowserWindow";
+import {
+  BrowserWindowCap, WindowCap, IpcError,
+  type ImplOf, type WindowState,
+} from "../../rpc/index";
+import { Stream } from "../../rpc/stream";
+
+function browserWindowImpl(win: BrowserWindow): ImplOf<typeof BrowserWindowCap> {
+  return {
+    focus: () => win.focus(),
+    close: () => win.close(),
+    setBounds: ({ x, y, w, h }) => win.setFrame(x, y, w, h),
+    setTitle: ({ title }) => win.setTitle(title),
+    id: () => win.id,
+    label: () => win.label,
+    minimize: () => win.minimize(),
+    unminimize: () => win.unminimize(),
+    maximize: () => win.maximize(),
+    unmaximize: () => win.unmaximize(),
+    toggleMaximize: () => win.toggleMaximize(),
+    beginMoveDrag: () => win.beginMoveDrag(),
+    getState: () => win.getState(),
+    stateWatch: () => Stream.from<WindowState>((emit, signal) => {
+      let last = "";
+      const push = () => {
+        const s = win.getState();
+        const key = `${s.maximized}|${s.minimized}|${s.focused}`;
+        if (key === last) return;
+        last = key;
+        emit(s);
+      };
+      push();  // initial snapshot
+      const offs = [
+        win.on("focus", push), win.on("blur", push),
+        win.on("move", push), win.on("resize", push),
+      ];
+      signal.addEventListener("abort", () => { for (const off of offs) off(); });
+    }),
+  };
+}
+
+function resolve(args: { id?: number; label?: string }): BrowserWindow | undefined {
+  if (args.id != null) return BrowserWindow.getById(args.id);
+  if (args.label) return BrowserWindow.getAll().find((w) => w.label === args.label);
+  return undefined;
+}
+
+/** WindowCap impl for the renderer of `viewId`. `current()` resolves the owning
+ *  window host-side from the session's viewId — never from a page-supplied id. */
+export function createWindowCapImpl(viewId: number): ImplOf<typeof WindowCap> {
+  return {
+    create: ({ url, title, bounds, label }, ctx) => {
+      const win = new BrowserWindow({
+        url, title, label,
+        frame: { x: bounds?.x ?? 80, y: bounds?.y ?? 80, width: bounds?.w ?? 1280, height: bounds?.h ?? 900 },
+      });
+      return ctx.exportCap(BrowserWindowCap, browserWindowImpl(win));
+    },
+    list: (_void, ctx) =>
+      BrowserWindow.getAll().map((w) => ctx.exportCap(BrowserWindowCap, browserWindowImpl(w))),
+    current: (_void, ctx) => {
+      const win = BrowserWindow.getByWebviewId(viewId);
+      if (!win) throw new IpcError({ code: "not_found", message: "no window for this view" });
+      return ctx.exportCap(BrowserWindowCap, browserWindowImpl(win));
+    },
+    focus: (args) => { resolve(args)?.focus(); },
+    close: (args) => { resolve(args)?.close(); },
+  };
+}

package/src/host/events/webviewEvents.ts

@@ -15,5 +15,22 @@ export default {
   dialog: (data: { requestId: number; kind: "alert" | "confirm" | "prompt" | "beforeunload"; message: string; defaultPrompt?: string }) =>
     new BuniteEvent("dialog", data),
   consoleMessage: (data: { level: "log" | "warn" | "error" | "info" | "debug"; args: string[]; ts: number }) =>
-    new BuniteEvent("console-message", data)
+    new BuniteEvent("console-message", data),
+  downloadEvent: (data: {
+    kind: "started" | "progress" | "completed" | "failed" | "blocked";
+    id: string;
+    url?: string;
+    suggestedFilename?: string;
+    mimeType?: string;
+    sizeBytes?: number;
+    receivedBytes?: number;
+    totalBytes?: number;
+    localPath?: string;
+    reason?: string;
+  }) => new BuniteEvent("download-event", data),
+  popupRequested: (data: {
+    newSurfaceId: number;
+    url: string;
+    disposition: "tab" | "window" | "popup";
+  }) => new BuniteEvent("popup-requested", data),
 };

package/src/host/log.ts

@@ -8,7 +8,12 @@ const levels: Record<LogLevel, number> = {
   silent: 4
 };
 
-let currentLevel: LogLevel = "warn";
+function initialLevel(): LogLevel {
+  const v = (typeof process !== "undefined" ? process.env?.BUNITE_LOG_LEVEL : undefined);
+  return v === "debug" || v === "info" || v === "warn" || v === "error" || v === "silent" ? v : "warn";
+}
+
+let currentLevel: LogLevel = initialLevel();
 
 function shouldLog(level: LogLevel): boolean {
   return levels[level] >= levels[currentLevel];