bunite-core 0.12.0 → 0.14.0

package/src/rpc/framework.ts

@@ -70,6 +70,16 @@ export const ShellCap = defineCap("bunite.Shell", {
   showItemInFolder: call<{ path: string }, void>(),
 });
 
+/** page → host event sink. Distinct from RuntimeCap (page → host *request* API)
+ *  so future arms like `reportError` / `reportPerformance` don't pollute the
+ *  runtime cap. Mounted as a sub-cap via `RuntimeCap.reporting()`. */
+export const PageReportingCap = defineCap("bunite.PageReporting", {
+  /** preload coalesces console calls in a 16ms window and pushes the batch.
+   *  Fire-and-forget — preload `.catch`es resource_exhausted to avoid throwing
+   *  inside `console.log` (which would corrupt page semantics). */
+  reportConsoleBatch: call<{ entries: ConsoleEntry[] }, void>(),
+});
+
 export type SurfaceMask = { x: number; y: number; w: number; h: number };
 
 /** Automation feature flags reported per surface. Append-only — consumers
@@ -78,22 +88,166 @@ export type SurfaceMask = { x: number; y: number; w: number; h: number };
 export interface SurfaceCapabilities {
   evaluate: boolean;
   crossOriginEval: boolean;
-  titleChanged: boolean;
-  /** Stage A: always false. Set true when SendInput focus choreography lands. */
+  surfaceEvents: boolean;
+  /** click/type/press/mouse produce DOM events with `isTrusted=true` on the page.
+   *  Does NOT cover scroll/screenshot (those may use CDP path with isTrusted=false). */
   nativeInputTrusted: boolean;
   click: boolean;
   type: boolean;
   press: boolean;
   scroll: boolean;
+  /** Raw mouse primitives (move/down/up) — required for drag & hover. */
+  mouse: boolean;
+  /** Page-initiated dialogs (alert/confirm/prompt/beforeunload) routed through
+   *  `dialogs` stream + `respondToDialog`. `beforeunload` is Win-only (WebKit
+   *  handles it through navigation-policy delegate, not script-dialog). */
+  dialogs: boolean;
+  /** Page `console.{log,warn,error,info,debug}` captured via preload proxy.
+   *  Only effective for surfaces whose origin is in the preload allowlist
+   *  (default `appres://app.internal/*`); cross-origin pages don't get preload
+   *  injection, so `consoleEvents` stays empty even though the flag is true. */
+  console: boolean;
   screenshot: boolean;
   /** Present only when `screenshot` is true. */
   formats?: ("png" | "jpeg")[];
 }
 
+/** Surface lifecycle event arm. Backends emit a subset honestly — SPA
+ *  `history.pushState` fires only `navigate`; classic navigation fires
+ *  `load-start` → `navigate` → `load-finish` (order varies per backend hook
+ *  sequence and isn't a strict invariant). A navigation produces `load-finish`
+ *  OR `load-fail`, never both. */
+export type SurfaceEvent =
+  | { type: "navigate"; url: string }
+  | { type: "load-start"; url: string }
+  | { type: "load-finish"; url: string }
+  | { type: "load-fail"; url: string; reason?: string }
+  | { type: "title-change"; title: string };
+
 export type EvaluateResult =
   | { ok: true; value: unknown }
   | { ok: false; code: "cross_origin" | "runtime_error" | "not_supported" | "timeout"; message: string };
 
+/** Modifier bitmask for input dispatch. Backends translate to native form. */
+export type Modifier = "alt" | "ctrl" | "meta" | "shift";
+
+export interface ClickArgs {
+  surfaceId: number;
+  x: number;
+  y: number;
+  button?: "left" | "middle" | "right";
+  clickCount?: number;
+  modifiers?: Modifier[];
+}
+export interface TypeArgs { surfaceId: number; text: string }
+export interface PressArgs {
+  surfaceId: number;
+  key: string;
+  modifiers?: Modifier[];
+  /** "both" (default) emits down→char→up; "down" / "up" emit only that half.
+   *  For Playwright-style modifier-held wrap: keydown → click → keyup. */
+  action?: "down" | "up" | "both";
+}
+export interface MouseArgs {
+  surfaceId: number;
+  /** "move" produces mouseMove only; "down"/"up" produces a single half of
+   *  a mouse-button event. Compose drag = down → move(s) → up. modifiers are
+   *  per-call atomic (no sticky state across calls). */
+  action: "move" | "down" | "up";
+  x: number;
+  y: number;
+  /** Required for "down"/"up"; ignored for "move". */
+  button?: "left" | "middle" | "right";
+  modifiers?: Modifier[];
+}
+
+/** Page-initiated modal dialog. Backend holds page execution until consumer
+ *  calls `respondToDialog` with the matching `requestId`. If no response
+ *  arrives within `setDialogTimeout` (default 5000ms; null = wait forever),
+ *  host auto-dismisses and emits `{kind: "auto-dismissed", originalKind, message}`
+ *  so the consumer learns the page proceeded without explicit answer.
+ *
+ *  `beforeunload` arm support per backend:
+ *  - CEF (Win)         : ✔ — `OnBeforeUnloadDialog`
+ *  - WV2 (Win)         : ✔ — `ScriptDialogOpening` with kind `BEFOREUNLOAD`
+ *  - WKWebView (mac)   : ✘ — handled by WKNavigationDelegate, surfaced as `will-navigate`
+ *  - WebKitGTK (linux) : ✔ — `script-dialog` signal with `BEFORE_UNLOAD_CONFIRM` */
+export type DialogEvent =
+  | {
+      kind: "alert" | "confirm" | "prompt" | "beforeunload";
+      requestId: number;
+      message: string;
+      /** Initial text for `prompt` only. */
+      defaultPrompt?: string;
+    }
+  | {
+      kind: "auto-dismissed";
+      originalKind: "alert" | "confirm" | "prompt" | "beforeunload";
+      message: string;
+    };
+
+export interface RespondToDialogArgs {
+  surfaceId: number;
+  requestId: number;
+  accept: boolean;
+  /** For `prompt` dialogs — the text the page receives. Ignored otherwise. */
+  text?: string;
+}
+
+export interface SetDialogTimeoutArgs {
+  surfaceId: number;
+  /** Milliseconds before unanswered dialog is auto-dismissed. `null` disables
+   *  the safety net — page hangs until consumer responds. Default 5000. */
+  ms: number | null;
+}
+
+export interface WaitForSelectorArgs {
+  surfaceId: number;
+  selector: string;
+  /** Default 5000ms. Polled at 50ms intervals via `evaluate`. */
+  timeoutMs?: number;
+}
+export interface WaitForFunctionArgs {
+  surfaceId: number;
+  /** JS expression returning truthy when satisfied. */
+  expression: string;
+  /** Default 5000ms. */
+  timeoutMs?: number;
+  /** Default 50ms. Increase for heavy expressions to reduce IPC load. */
+  pollIntervalMs?: number;
+}
+export type WaitResult =
+  | { ok: true }
+  | { ok: false; code: "timeout" | "runtime_error" | "cross_origin"; message: string };
+
+export type ConsoleLevel = "log" | "warn" | "error" | "info" | "debug";
+
+export interface ConsoleEntry {
+  level: ConsoleLevel;
+  /** `.toString()` / JSON.stringify-ed arguments — preload doesn't structured-clone. */
+  args: string[];
+  /** Page-side `Date.now()` at capture time. */
+  ts: number;
+}
+export interface ScrollArgs {
+  surfaceId: number;
+  dx: number;
+  dy: number;
+  x?: number;
+  y?: number;
+  modifiers?: Modifier[];
+}
+
+export interface ScreenshotArgs {
+  surfaceId: number;
+  format?: "png" | "jpeg";
+  /** JPEG only; 0–100. Ignored for PNG. */
+  quality?: number;
+}
+export type ScreenshotResult =
+  | { ok: true; data: Uint8Array; mime: string; format: "png" | "jpeg" }
+  | { ok: false; code: "not_supported" | "runtime_error" | "timeout" | "black_frame"; message: string };
+
 export const SurfaceCap = defineCap("bunite.Surface", {
   init: call<{
     src: string;
@@ -114,8 +268,20 @@ export const SurfaceCap = defineCap("bunite.Surface", {
   reload: call<{ surfaceId: number }, void>(),
   evaluate: call<{ surfaceId: number; script: string }, EvaluateResult>(),
   capabilities: call<{ surfaceId: number }, SurfaceCapabilities>(),
-  didNavigate: stream<void, { surfaceId: number; url: string }>(),
-  titleChanged: stream<void, { surfaceId: number; title: string }>(),
+  click: call<ClickArgs, void>(),
+  type: call<TypeArgs, void>(),
+  press: call<PressArgs, void>(),
+  scroll: call<ScrollArgs, void>(),
+  mouse: call<MouseArgs, void>(),
+  screenshot: call<ScreenshotArgs, ScreenshotResult>(),
+  waitForSelector: call<WaitForSelectorArgs, WaitResult>(),
+  waitForFunction: call<WaitForFunctionArgs, WaitResult>(),
+  respondToDialog: call<RespondToDialogArgs, void>(),
+  setDialogTimeout: call<SetDialogTimeoutArgs, void>(),
+  getConsoleBuffer: call<{ surfaceId: number; clear?: boolean }, ConsoleEntry[]>({ idempotent: true }),
+  surfaceEvents: stream<{ surfaceId: number }, SurfaceEvent>(),
+  dialogs: stream<{ surfaceId: number }, DialogEvent>(),
+  consoleEvents: stream<{ surfaceId: number }, ConsoleEntry>(),
 });
 
 export const RuntimeCap = defineCap("bunite.Runtime", {
@@ -128,6 +294,7 @@ export const RuntimeCap = defineCap("bunite.Runtime", {
   theme: call<void, "light" | "dark">({ idempotent: true }),
   themeWatch: stream<void, "light" | "dark">(),
   surface: call<void, typeof SurfaceCap>({ returns: cap(SurfaceCap), idempotent: true }),
+  reporting: call<void, typeof PageReportingCap>({ returns: cap(PageReportingCap), idempotent: true }),
 });
 
 export const FRAMEWORK_TYPE_IDS = {
@@ -139,6 +306,7 @@ export const FRAMEWORK_TYPE_IDS = {
   Shell: 6,
   BrowserWindow: 7,
   Surface: 8,
+  PageReporting: 9,
 } as const;
 
 const FRAMEWORK_CAP_TYPE_IDS = new Map<CapDef<any, any>, number>([
@@ -150,6 +318,7 @@ const FRAMEWORK_CAP_TYPE_IDS = new Map<CapDef<any, any>, number>([
   [ShellCap, FRAMEWORK_TYPE_IDS.Shell],
   [BrowserWindowCap, FRAMEWORK_TYPE_IDS.BrowserWindow],
   [SurfaceCap, FRAMEWORK_TYPE_IDS.Surface],
+  [PageReportingCap, FRAMEWORK_TYPE_IDS.PageReporting],
 ]);
 
 export function frameworkTypeIdOf(cap: CapDef<any, any>): number | undefined {

package/src/rpc/index.ts

@@ -101,6 +101,7 @@ export {
   ClipboardCap,
   ShellCap,
   SurfaceCap,
+  PageReportingCap,
   FRAMEWORK_TYPE_IDS,
 } from "./framework";
 
@@ -109,6 +110,26 @@ export type {
   DialogOpenFileOpts,
   DialogSaveFileOpts,
   DialogMessageOpts,
+  SurfaceCapabilities,
+  SurfaceEvent,
+  SurfaceMask,
+  Modifier,
+  ClickArgs,
+  TypeArgs,
+  PressArgs,
+  ScrollArgs,
+  MouseArgs,
+  DialogEvent,
+  RespondToDialogArgs,
+  SetDialogTimeoutArgs,
+  WaitForSelectorArgs,
+  WaitForFunctionArgs,
+  WaitResult,
+  ConsoleLevel,
+  ConsoleEntry,
+  ScreenshotArgs,
+  ScreenshotResult,
+  EvaluateResult,
 } from "./framework";
 
 export type {

package/src/webview/native.ts

@@ -1,7 +1,10 @@
 // <bunite-webview> custom element — registered in every appres:// page via preload.
 
 import type { ClientOf } from "../rpc/index";
-import type { SurfaceCap, EvaluateResult, SurfaceCapabilities } from "../rpc/framework";
+import type {
+  SurfaceCap, EvaluateResult, SurfaceCapabilities, ScreenshotResult,
+  SurfaceEvent, ConsoleEntry, WaitResult,
+} from "../rpc/framework";
 
 declare const host: {
   runtime(): Promise<ClientOf<typeof import("../rpc/framework").RuntimeCap>>;
@@ -120,6 +123,7 @@ class BuniteWebviewElement extends HTMLElement {
   private _userHidden = false;
   private _layoutObserver: ResizeObserver | null = null;
   private _unsubNavigate: (() => void) | null = null;
+  private _activeStreams: Array<{ cancel?: () => void }> = [];
 
   constructor() {
     super();
@@ -134,39 +138,45 @@ class BuniteWebviewElement extends HTMLElement {
     this._unsubNavigate = () => ctrl.abort();
     void (async () => {
       try {
+        // Wait until *this* connection's init resolves, then capture surfaceId
+        // atomically before subscribing. Re-entrant connects abort prior loops
+        // via `ctrl`, so a stale resolve from a previous cycle can't leak in.
         const s = await getSurfaceCap();
-        const stream = s.didNavigate();
-        for await (const ev of stream) {
+        if (ctrl.signal.aborted) return;
+        await this._waitForSurfaceId(ctrl.signal);
+        const sid = this._surfaceId;
+        if (ctrl.signal.aborted || sid == null) return;
+        const stream = s.surfaceEvents({ surfaceId: sid });
+        this._activeStreams.push(stream as { cancel?: () => void });
+        for await (const event of stream) {
           if (ctrl.signal.aborted) break;
-          if (ev.surfaceId === this._surfaceId) {
-            this.dispatchEvent(new CustomEvent("did-navigate", { detail: { url: ev.url } }));
-          }
+          this.dispatchEvent(new CustomEvent<SurfaceEvent>("surface-event", { detail: event }));
         }
       } catch (err) {
         if ((globalThis as { __BUNITE_DEBUG__?: boolean }).__BUNITE_DEBUG__) {
-          console.warn("[bunite] didNavigate stream failed", err);
-        }
-      }
-    })();
-    void (async () => {
-      try {
-        const s = await getSurfaceCap();
-        const stream = s.titleChanged();
-        for await (const ev of stream) {
-          if (ctrl.signal.aborted) break;
-          if (ev.surfaceId === this._surfaceId) {
-            this.dispatchEvent(new CustomEvent("title-changed", { detail: { title: ev.title } }));
-          }
-        }
-      } catch (err) {
-        if ((globalThis as { __BUNITE_DEBUG__?: boolean }).__BUNITE_DEBUG__) {
-          console.warn("[bunite] titleChanged stream failed", err);
+          console.warn("[bunite] surfaceEvents stream failed", err);
         }
       }
     })();
     this._waitForLayout();
   }
 
+  private async _waitForSurfaceId(signal: AbortSignal): Promise<void> {
+    while (this._surfaceId == null && !signal.aborted) {
+      const pending = this._initPromise;
+      if (pending) {
+        // Await this exact init attempt; if it rejects, bail (init failed —
+        // we'd otherwise spin forever waiting for a surfaceId that never lands).
+        try { await pending; } catch { return; }
+        // After resolve, _surfaceId may still be null if disconnect raced —
+        // the next loop iteration checks signal.aborted to exit cleanly.
+      } else {
+        // No init in flight yet (waiting for layout). Yield then re-check.
+        await new Promise((r) => setTimeout(r, 16));
+      }
+    }
+  }
+
   private _waitForLayout() {
     if (this._layoutObserver) return; // already waiting
 
@@ -198,6 +208,12 @@ class BuniteWebviewElement extends HTMLElement {
     this._aborted = true;
     this._unsubNavigate?.();
     this._unsubNavigate = null;
+    // Cancel pending stream iterators so the `for await` actually unblocks —
+    // AbortController alone only takes effect at the next received chunk.
+    for (const stream of this._activeStreams) {
+      try { stream.cancel?.(); } catch {}
+    }
+    this._activeStreams = [];
     this._layoutObserver?.disconnect();
     this._layoutObserver = null;
     this._syncCtrl?.stop();
@@ -258,14 +274,99 @@ class BuniteWebviewElement extends HTMLElement {
     const sid = this._surfaceId;
     if (sid == null) {
       return {
-        evaluate: false, crossOriginEval: false, titleChanged: false,
+        evaluate: false, crossOriginEval: false, surfaceEvents: false,
         nativeInputTrusted: false, click: false, type: false, press: false,
-        scroll: false, screenshot: false,
+        scroll: false, mouse: false, dialogs: false, console: false,
+        screenshot: false,
       };
     }
     return callSurfaceTyped((s) => s.capabilities({ surfaceId: sid }));
   }
 
+  // Automation input — `send*` prefix avoids clashing with HTMLElement.click() / .scroll().
+  async sendClick(args: {
+    x: number; y: number;
+    button?: "left" | "middle" | "right";
+    clickCount?: number;
+    modifiers?: Array<"alt" | "ctrl" | "meta" | "shift">;
+  }): Promise<void> {
+    const sid = this._surfaceId;
+    if (sid == null) return;
+    await callSurfaceTyped((s) => s.click({ surfaceId: sid, ...args }));
+  }
+
+  async sendType(text: string): Promise<void> {
+    const sid = this._surfaceId;
+    if (sid == null) return;
+    await callSurfaceTyped((s) => s.type({ surfaceId: sid, text }));
+  }
+
+  async sendPress(
+    key: string,
+    modifiers?: Array<"alt" | "ctrl" | "meta" | "shift">,
+    action?: "down" | "up" | "both"
+  ): Promise<void> {
+    const sid = this._surfaceId;
+    if (sid == null) return;
+    await callSurfaceTyped((s) => s.press({ surfaceId: sid, key, modifiers, action }));
+  }
+
+  async sendScroll(args: {
+    dx: number; dy: number; x?: number; y?: number;
+    modifiers?: Array<"alt" | "ctrl" | "meta" | "shift">;
+  }): Promise<void> {
+    const sid = this._surfaceId;
+    if (sid == null) return;
+    await callSurfaceTyped((s) => s.scroll({ surfaceId: sid, ...args }));
+  }
+
+  async sendMouse(args: {
+    action: "move" | "down" | "up";
+    x: number; y: number;
+    button?: "left" | "middle" | "right";
+    modifiers?: Array<"alt" | "ctrl" | "meta" | "shift">;
+  }): Promise<void> {
+    const sid = this._surfaceId;
+    if (sid == null) return;
+    await callSurfaceTyped((s) => s.mouse({ surfaceId: sid, ...args }));
+  }
+
+  async respondToDialog(requestId: number, accept: boolean, text?: string): Promise<void> {
+    const sid = this._surfaceId;
+    if (sid == null) return;
+    await callSurfaceTyped((s) => s.respondToDialog({ surfaceId: sid, requestId, accept, text }));
+  }
+
+  async setDialogTimeout(ms: number | null): Promise<void> {
+    const sid = this._surfaceId;
+    if (sid == null) return;
+    await callSurfaceTyped((s) => s.setDialogTimeout({ surfaceId: sid, ms }));
+  }
+
+  async waitForSelector(selector: string, timeoutMs?: number): Promise<WaitResult> {
+    const sid = this._surfaceId;
+    if (sid == null) return { ok: false, code: "runtime_error", message: "surface not ready" };
+    return callSurfaceTyped((s) => s.waitForSelector({ surfaceId: sid, selector, timeoutMs }));
+  }
+
+  async waitForFunction(expression: string, opts?: { timeoutMs?: number; pollIntervalMs?: number }): Promise<WaitResult> {
+    const sid = this._surfaceId;
+    if (sid == null) return { ok: false, code: "runtime_error", message: "surface not ready" };
+    return callSurfaceTyped((s) => s.waitForFunction({ surfaceId: sid, expression, ...opts }));
+  }
+
+  async getConsoleBuffer(opts?: { clear?: boolean }): Promise<ConsoleEntry[]> {
+    const sid = this._surfaceId;
+    if (sid == null) return [];
+    return (await callSurfaceTyped((s) => s.getConsoleBuffer({ surfaceId: sid, clear: opts?.clear }))) ?? [];
+  }
+
+  async screenshot(args?: { format?: "png" | "jpeg"; quality?: number }): Promise<ScreenshotResult> {
+    const sid = this._surfaceId;
+    if (sid == null) return { ok: false, code: "not_supported", message: "surface not ready" };
+    return callSurfaceTyped((s) => s.screenshot({ surfaceId: sid, ...args }));
+  }
+
   private _applySurfaceHidden() {
     const sid = this._surfaceId;
     if (sid == null) return;