@johpaz/hive-sdk 0.1.5 → 0.1.6

package/packages/core/src/tools/web/browser-service.ts

@@ -1,11 +1,18 @@
 /**
- * BrowserService — Browser automation via agent-browser CLI (Rust).
+ * BrowserService — automatización de navegador, con backend intercambiable.
  *
- * Flujo:
+ * `AgentBrowserBackend` (este archivo) habla con el CLI de agent-browser por
+ * subproceso: maneja Chrome de verdad y corre headless, así que es el único que
+ * sirve en Docker o en un servidor sin display. Por eso sigue siendo el default.
+ *
+ * `WebViewBackend` (webview-backend.ts) usa `Bun.WebView` in-process — sin
+ * instalación ni subprocesos, mucho más rápido — pero necesita entorno gráfico.
+ * Se elige con `tools.browser.backend` o `HIVE_BROWSER_BACKEND`.
+ *
+ * Flujo del backend por CLI:
  *  1. Detecta si agent-browser está instalado (lazy install en primer uso).
  *  2. Ejecuta comandos via CLI con --json para output estructurado.
  *  3. El daemon de agent-browser maneja Chrome internamente via CDP.
- *  4. Las herramientas de browser usan AgentBrowserView (API compatible con CDPClient).
  */
 
 import { logger } from "../../utils/logger.ts";
@@ -13,6 +20,13 @@ import type { Config } from "../../config/loader.ts";
 import { existsSync, mkdirSync, readFileSync, rmSync } from "fs";
 import { homedir, tmpdir } from "os";
 import { dirname, join, resolve } from "path";
+import {
+  resolveBackendKind,
+  type BrowserBackend,
+  type BrowserBackendKind,
+  type ScreenshotOptions,
+  type SnapshotOptions,
+} from "./browser-backend.ts";
 
 const log = logger.child("browser-service");
 
@@ -117,7 +131,7 @@ async function ensureChromeInstalled(): Promise<void> {
 
 // ─── AgentBrowserView (API compatible con CDPClient) ──────────────────────────
 
-export class AgentBrowserView {
+export class AgentBrowserView implements BrowserBackend {
   private sessionName: string;
   private _url = "";
 
@@ -162,12 +176,7 @@ export class AgentBrowserView {
     return res.data?.result as T;
   }
 
-  async screenshot(options?: {
-    encoding?: "blob" | "buffer" | "base64" | "shmem";
-    format?: "png" | "jpeg" | "webp";
-    quality?: number;
-    clip?: { x: number; y: number; width: number; height: number; scale: number };
-  }): Promise<string> {
+  async screenshot(options?: ScreenshotOptions): Promise<string> {
     // Build args
     const args: string[] = ["screenshot"];
 
@@ -264,8 +273,21 @@ export class AgentBrowserView {
     if (!res.success) throw new Error(res.error || "resize failed");
   }
 
+  /** Screenshot recortado a un elemento — agent-browser acepta el selector posicional. */
+  async screenshotElement(selector: string): Promise<string> {
+    const res = await this.run(["screenshot", selector]);
+    if (!res.success) throw new Error(res.error || `screenshot failed: ${selector}`);
+
+    const path = res.data?.path as string;
+    if (!path) throw new Error("screenshot did not return a path");
+
+    const base64 = Buffer.from(readFileSync(path)).toString("base64");
+    try { rmSync(path); } catch { /* ignore */ }
+    return base64;
+  }
+
   /** Capture accessibility tree snapshot (compact, AI-optimized). ~200-600 chars vs ~3000+ innerText. */
-  async snapshot(options?: { compact?: boolean; depth?: number; interactiveOnly?: boolean }): Promise<string> {
+  async snapshot(options?: SnapshotOptions): Promise<string> {
     const args = ["snapshot"];
     if (options?.compact !== false) args.push("-c");
     if (options?.depth) args.push("-d", String(options.depth));
@@ -326,11 +348,17 @@ export type LaunchSpec = { kind: "remote"; cdpUrl: string };
 
 // ─── BrowserService (singleton) ───────────────────────────────────────────────
 
-export type BrowserView = AgentBrowserView;
+/** Alias histórico: las tools sólo dependen del contrato, no de la implementación. */
+export type BrowserView = BrowserBackend;
+
+/** Re-export para que quien importe el servicio no tenga que conocer el módulo del contrato. */
+export type { BrowserBackend, BrowserBackendKind } from "./browser-backend.ts";
+export { isWebViewSupported, resolveBackendKind } from "./browser-backend.ts";
 
-let _client: AgentBrowserView | null = null;
+let _client: BrowserBackend | null = null;
 let _available = false;
 let _launching = false;
+let _kind: BrowserBackendKind = "agent-browser";
 
 export class BrowserService {
   private static instance: BrowserService | null = null;
@@ -357,6 +385,17 @@ export class BrowserService {
       return false;
     }
 
+    _kind = resolveBackendKind(b?.backend);
+
+    if (_kind === "webview") {
+      // No hay nada que instalar ni que descargar: el WebView se crea al primer
+      // uso. Si el entorno no lo soporta, ensureView() falla ahí y el servicio
+      // queda no disponible, igual que cuando agent-browser no arranca.
+      _available = true;
+      log.info("✅ Backend de navegador: Bun.WebView (in-process, sin Chrome)");
+      return true;
+    }
+
     const installed = await isAgentBrowserInstalled();
 
     if (!installed) {
@@ -392,8 +431,13 @@ export class BrowserService {
     }
     _launching = true;
     try {
-      const sessionName = this.config.tools?.browser?.sessionName ?? DEFAULT_SESSION_NAME;
-      _client = new AgentBrowserView(sessionName);
+      if (_kind === "webview") {
+        const { WebViewBackend } = await import("./webview-backend.ts");
+        _client = new WebViewBackend({ show: this.config.tools?.browser?.headless === false });
+      } else {
+        const sessionName = this.config.tools?.browser?.sessionName ?? DEFAULT_SESSION_NAME;
+        _client = new AgentBrowserView(sessionName);
+      }
       log.info("✅ Browser abierto — el usuario verá las acciones del agente");
       return true;
     } catch (err) {
@@ -406,20 +450,25 @@ export class BrowserService {
     }
   }
 
-  async getView(): Promise<AgentBrowserView | null> {
+  async getView(): Promise<BrowserBackend | null> {
     if (!_available) return null;
     await this._ensureLaunched();
     return _client;
   }
 
-  getViewSync(): AgentBrowserView | null {
+  getViewSync(): BrowserBackend | null {
     return _client;
   }
 
-  async getPage(): Promise<AgentBrowserView | null> {
+  async getPage(): Promise<BrowserBackend | null> {
     return this.getView();
   }
 
+  /** Qué backend quedó activo — lo reporta `hive doctor` y los tests. */
+  getBackendKind(): BrowserBackendKind {
+    return _kind;
+  }
+
   isAvailable(): boolean {
     return _available;
   }
@@ -428,8 +477,8 @@ export class BrowserService {
     return _available && _client !== null;
   }
 
-  getInfo(): { running: boolean } {
-    return { running: this.isRunning() };
+  getInfo(): { running: boolean; backend: BrowserBackendKind } {
+    return { running: this.isRunning(), backend: _kind };
   }
 
   async stop(): Promise<void> {
@@ -462,7 +511,7 @@ export function getBrowserService(): BrowserService | null {
 // ─── Helpers (misma API que antes) ───────────────────────────────────────────
 
 export async function waitForSelector(
-  view: AgentBrowserView,
+  view: BrowserBackend,
   selector: string,
   timeout = 30000
 ): Promise<void> {
@@ -476,7 +525,7 @@ export async function waitForSelector(
 }
 
 export async function waitForCondition(
-  view: AgentBrowserView,
+  view: BrowserBackend,
   expression: string,
   timeout = 30000
 ): Promise<void> {
@@ -490,19 +539,10 @@ export async function waitForCondition(
 }
 
 export async function screenshotElement(
-  view: AgentBrowserView,
+  view: BrowserBackend,
   selector: string
 ): Promise<string> {
-  const res = await (view as any).run(["screenshot", selector]);
-  if (!res.success) throw new Error(res.error || `screenshot failed: ${selector}`);
-
-  const path = res.data?.path as string;
-  if (!path) throw new Error("screenshot did not return a path");
-
-  const data = readFileSync(path);
-  const base64 = Buffer.from(data).toString("base64");
-
-  try { rmSync(path); } catch { /* ignore */ }
-
-  return base64;
+  // Antes esto hacía `(view as any).run([...])`, atándose a la implementación por
+  // CLI: con dos backends el recorte es responsabilidad de cada uno.
+  return view.screenshotElement(selector);
 }

package/packages/core/src/tools/web/webview-backend.ts

@@ -0,0 +1,412 @@
+/**
+ * WebViewBackend — `BrowserBackend` sobre `Bun.WebView` (Bun >= 1.3).
+ *
+ * Corre in-process: no hay subproceso, ni instalación de ~75 MB, ni descarga de
+ * Chrome. Un `evaluate` cuesta ~0.25 ms contra los ~68 ms de piso que tiene cada
+ * invocación del CLI de agent-browser. A cambio necesita entorno gráfico, así
+ * que no reemplaza a agent-browser en Docker ni en un servidor headless.
+ *
+ * Dos restricciones del motor mandan sobre el diseño de este archivo:
+ *
+ *  1. `Bun.WebView` acepta **una sola operación pendiente por vez**; dos
+ *     llamadas solapadas fallan con `ERR_INVALID_STATE: a simple operation is
+ *     already pending`. Todo pasa por una cola serializada.
+ *  2. No expone árbol de accesibilidad. `snapshot()` se sintetiza recorriendo
+ *     el DOM, imitando el formato que emite agent-browser para que el modelo
+ *     vea lo mismo con cualquiera de los dos backends.
+ */
+
+import { logger } from "../../utils/logger.ts";
+import { resolveWebViewEngine, type BrowserBackend, type ScreenshotOptions, type SnapshotOptions, type WebViewEngine } from "./browser-backend.ts";
+
+const log = logger.child("webview-backend");
+
+/** Tope del texto del snapshot: un DOM grande no puede comerse el contexto. */
+const SNAPSHOT_CHAR_LIMIT = 20_000;
+
+/**
+ * Forma real de `Bun.WebView` en 1.3.14, verificada contra el prototipo.
+ *
+ * No se usan los tipos de `bun-types` a propósito: declaran `back()`/`forward()`
+ * y el runtime expone `goBack()`/`goForward()`. Contra los tipos, la navegación
+ * hacia atrás compila y explota en ejecución.
+ */
+interface BunWebView {
+  navigate(url: string): Promise<void>;
+  evaluate(script: string): Promise<unknown>;
+  screenshot(): Promise<Blob>;
+  cdp(method: string, params?: Record<string, unknown>): Promise<unknown>;
+  click(selector: string): Promise<void>;
+  type(text: string): Promise<void>;
+  press(key: string, modifiers?: Record<string, boolean>): Promise<void>;
+  scroll(dx: number, dy: number): Promise<void>;
+  scrollTo(selector: string): Promise<void>;
+  resize(width: number, height: number): Promise<void>;
+  goBack(): Promise<void>;
+  goForward(): Promise<void>;
+  reload(): Promise<void>;
+  close(): void;
+  readonly url: string;
+  readonly title: string;
+  readonly loading: boolean;
+}
+
+/**
+ * El script que sintetiza el árbol de accesibilidad. Se inyecta como texto, así
+ * que no puede cerrar sobre nada del scope de TypeScript: los parámetros entran
+ * interpolados como literales JSON.
+ */
+function buildSnapshotScript(options: Required<SnapshotOptions>): string {
+  return `(() => {
+  const MAX_DEPTH = ${JSON.stringify(options.depth)};
+  const COMPACT = ${JSON.stringify(options.compact)};
+  const INTERACTIVE_ONLY = ${JSON.stringify(options.interactiveOnly)};
+  const LIMIT = ${SNAPSHOT_CHAR_LIMIT};
+
+  const ROLE_BY_TAG = {
+    A: "link", BUTTON: "button", P: "paragraph", IMG: "img", TEXTAREA: "textbox",
+    SELECT: "combobox", OPTION: "option", UL: "list", OL: "list", LI: "listitem",
+    TABLE: "table", TR: "row", TD: "cell", TH: "columnheader", FORM: "form",
+    NAV: "navigation", MAIN: "main", HEADER: "banner", FOOTER: "contentinfo",
+    ASIDE: "complementary", LABEL: "label", ARTICLE: "article", SECTION: "region",
+    DIALOG: "dialog", SUMMARY: "button", IFRAME: "iframe", VIDEO: "video", AUDIO: "audio",
+  };
+  const INTERACTIVE = new Set(["link", "button", "textbox", "checkbox", "radio", "combobox", "option", "searchbox"]);
+  const SKIP_TAGS = new Set(["SCRIPT", "STYLE", "NOSCRIPT", "TEMPLATE", "HEAD", "META", "LINK", "TITLE", "SVG", "PATH"]);
+
+  function inputRole(el) {
+    const type = (el.getAttribute("type") || "text").toLowerCase();
+    if (type === "checkbox") return "checkbox";
+    if (type === "radio") return "radio";
+    if (type === "search") return "searchbox";
+    if (type === "button" || type === "submit" || type === "reset" || type === "image") return "button";
+    if (type === "hidden") return null;
+    return "textbox";
+  }
+
+  function roleOf(el) {
+    const explicit = el.getAttribute("role");
+    if (explicit) return explicit.trim().split(/\\s+/)[0];
+    if (el.tagName === "INPUT") return inputRole(el);
+    if (/^H[1-6]$/.test(el.tagName)) return "heading";
+    if (el.tagName === "A") return el.hasAttribute("href") ? "link" : null;
+    return ROLE_BY_TAG[el.tagName] || null;
+  }
+
+  function ownText(el) {
+    let text = "";
+    for (const node of el.childNodes) {
+      if (node.nodeType === 3) text += node.nodeValue;
+      // Los inline sin rol propio son parte del nombre del padre, no nodos aparte.
+      else if (node.nodeType === 1 && !roleOf(node) && node.childElementCount === 0) {
+        text += node.textContent || "";
+      }
+    }
+    return text.replace(/\\s+/g, " ").trim();
+  }
+
+  function nameOf(el) {
+    const aria = el.getAttribute("aria-label");
+    if (aria && aria.trim()) return aria.trim();
+
+    const labelledBy = el.getAttribute("aria-labelledby");
+    if (labelledBy) {
+      const parts = labelledBy.split(/\\s+/)
+        .map((id) => { const target = document.getElementById(id); return target ? (target.textContent || "").trim() : ""; })
+        .filter(Boolean);
+      if (parts.length) return parts.join(" ").replace(/\\s+/g, " ");
+    }
+
+    if (el.tagName === "IMG") return (el.getAttribute("alt") || "").trim();
+    if (el.tagName === "INPUT" || el.tagName === "TEXTAREA") {
+      const type = (el.getAttribute("type") || "").toLowerCase();
+      if (type === "button" || type === "submit" || type === "reset") return (el.value || "").trim();
+      const placeholder = (el.getAttribute("placeholder") || "").trim();
+      if (placeholder) return placeholder;
+      if (el.labels && el.labels.length) return (el.labels[0].textContent || "").replace(/\\s+/g, " ").trim();
+      return (el.getAttribute("name") || "").trim();
+    }
+
+    const own = ownText(el);
+    if (own) return own;
+    return (el.getAttribute("title") || "").trim();
+  }
+
+  function visible(el) {
+    if (el.hasAttribute("hidden") || el.getAttribute("aria-hidden") === "true") return false;
+    const style = getComputedStyle(el);
+    if (style.display === "none" || style.visibility === "hidden") return false;
+    return true;
+  }
+
+  function attrsOf(el, role) {
+    const attrs = [];
+    if (role === "heading") attrs.push("level=" + el.tagName.slice(1));
+    if (el.disabled) attrs.push("disabled");
+    if (el.checked) attrs.push("checked");
+    if (el.getAttribute("aria-expanded")) attrs.push("expanded=" + el.getAttribute("aria-expanded"));
+    return attrs;
+  }
+
+  const lines = [];
+  let refSeq = 0;
+  let truncated = false;
+
+  function walk(el, depth) {
+    if (truncated) return;
+    for (const child of el.children) {
+      if (truncated) return;
+      if (SKIP_TAGS.has(child.tagName)) continue;
+      if (!visible(child)) continue;
+
+      const role = roleOf(child);
+      const name = role ? nameOf(child) : "";
+      const interactive = role ? INTERACTIVE.has(role) : false;
+      // Un nodo se emite si aporta algo: un rol con nombre, o algo accionable.
+      let emit = Boolean(role) && (Boolean(name) || interactive);
+      if (INTERACTIVE_ONLY && !interactive) emit = false;
+      if (COMPACT && role && !name && !interactive) emit = false;
+
+      if (emit && depth < MAX_DEPTH) {
+        const attrs = attrsOf(child, role);
+        if (name || interactive) attrs.push("ref=e" + ++refSeq);
+        let label = "- " + role;
+        if (name) {
+          const shown = COMPACT && name.length > 120 ? name.slice(0, 120) + "…" : name;
+          label += ' "' + shown.replace(/"/g, "'") + '"';
+        }
+        if (attrs.length) label += " [" + attrs.join(", ") + "]";
+        const line = "  ".repeat(depth) + label;
+        if (lines.join("\\n").length + line.length > LIMIT) { truncated = true; return; }
+        lines.push(line);
+      }
+
+      // Sin línea propia, los hijos suben de nivel: así el árbol no se llena de
+      // sangría por cada <div> de maquetado.
+      walk(child, emit && depth < MAX_DEPTH ? depth + 1 : depth);
+    }
+  }
+
+  walk(document.body || document.documentElement, 0);
+  if (truncated) lines.push("… (snapshot truncado)");
+  return lines.join("\\n");
+})()`;
+}
+
+export class WebViewBackend implements BrowserBackend {
+  private view: BunWebView | null = null;
+  private _url = "";
+  /** Cola de una sola vía: WebView rechaza operaciones solapadas. */
+  private queue: Promise<unknown> = Promise.resolve();
+
+  constructor(
+    private readonly options: {
+      width?: number;
+      height?: number;
+      show?: boolean;
+      engine?: WebViewEngine;
+    } = {},
+  ) {}
+
+  private ensureView(): BunWebView {
+    if (this.view) return this.view;
+
+    const WebView = (globalThis as { Bun?: { WebView?: unknown } }).Bun?.WebView;
+    if (typeof WebView !== "function") {
+      throw new Error("Bun.WebView no está disponible en este runtime (requiere Bun >= 1.3)");
+    }
+
+    const engine = this.options.engine ?? resolveWebViewEngine();
+    if (!engine) {
+      throw new Error(
+        "Bun.WebView no tiene motor utilizable: WebKit sólo existe en macOS y no se encontró Chrome. " +
+          "Instalá Chrome o definí BUN_CHROME_PATH.",
+      );
+    }
+
+    // `url: false` es obligatorio para automatización desatendida: sin eso el
+    // motor chrome intenta CONECTARSE a un Chrome que ya esté corriendo, y esa
+    // ruta abre un diálogo "Allow remote debugging?" que cuelga el proceso
+    // esperando un click que en un servidor no llega nunca.
+    const backend =
+      engine === "chrome"
+        ? { type: "chrome" as const, url: false as const, stderr: "ignore" as const }
+        : ("webkit" as const);
+
+    // Sin `url` inicial a propósito: construir con uno deja una navegación
+    // pendiente y el primer navigate() explota con ERR_INVALID_STATE.
+    const Ctor = WebView as unknown as new (opts: unknown) => BunWebView;
+    this.view = new Ctor({
+      backend,
+      show: this.options.show ?? false,
+      width: this.options.width ?? 1280,
+      height: this.options.height ?? 800,
+    });
+    log.info(`✅ WebView abierto (motor: ${engine}, in-process)`);
+    return this.view;
+  }
+
+  /** Serializa: cada operación espera a que termine la anterior. */
+  private run<T>(operation: (view: BunWebView) => Promise<T>): Promise<T> {
+    const next = this.queue.then(
+      () => operation(this.ensureView()),
+      () => operation(this.ensureView()),
+    );
+    // La cola no debe romperse porque una operación haya fallado.
+    this.queue = next.catch(() => undefined);
+    return next;
+  }
+
+  get url(): string {
+    return this.view?.url || this._url;
+  }
+
+  get title(): string {
+    return this.view?.title || "";
+  }
+
+  get loading(): boolean {
+    return this.view?.loading ?? false;
+  }
+
+  async navigate(url: string): Promise<void> {
+    const target = /^[a-z]+:/i.test(url) ? url : `https://${url}`;
+    await this.run((view) => view.navigate(target));
+    this._url = this.view?.url || target;
+  }
+
+  async evaluate<T = unknown>(script: string): Promise<T> {
+    const trimmed = script.trim();
+    let wrapped = script;
+    if (/\bawait\b/.test(script) && !trimmed.startsWith("(async") && !trimmed.startsWith("async function")) {
+      wrapped = trimmed.startsWith("return")
+        ? `(async () => { ${script} })()`
+        : `(async () => { return ${script}; })()`;
+    }
+    return (await this.run((view) => view.evaluate(wrapped))) as T;
+  }
+
+  async screenshot(_options?: ScreenshotOptions): Promise<string> {
+    const blob = await this.run((view) => view.screenshot());
+    return Buffer.from(await blob.arrayBuffer()).toString("base64");
+  }
+
+  async screenshotElement(selector: string): Promise<string> {
+    const box = await this.evaluate<{ x: number; y: number; width: number; height: number } | null>(
+      `(() => {
+        const el = document.querySelector(${JSON.stringify(selector)});
+        if (!el) return null;
+        el.scrollIntoView({ block: "center", inline: "center" });
+        const r = el.getBoundingClientRect();
+        return { x: r.x, y: r.y, width: r.width, height: r.height };
+      })()`,
+    );
+    if (!box || box.width <= 0 || box.height <= 0) {
+      throw new Error(`screenshot failed: elemento no visible o inexistente: ${selector}`);
+    }
+
+    // WebView.screenshot() no recorta, pero el puente CDP sí acepta `clip`.
+    const shot = await this.run((view) =>
+      view.cdp("Page.captureScreenshot", {
+        format: "png",
+        clip: { x: box.x, y: box.y, width: box.width, height: box.height, scale: 1 },
+      }),
+    );
+    const data = (shot as { data?: string })?.data;
+    if (!data) throw new Error(`screenshot failed: CDP no devolvió imagen para ${selector}`);
+    return data;
+  }
+
+  async snapshot(options?: SnapshotOptions): Promise<string> {
+    const script = buildSnapshotScript({
+      compact: options?.compact !== false,
+      depth: options?.depth ?? 12,
+      interactiveOnly: options?.interactiveOnly ?? false,
+    });
+    return (await this.evaluate<string>(script)) || "";
+  }
+
+  async click(selector: string, _options?: Record<string, unknown>): Promise<void> {
+    await this.run((view) => view.click(selector));
+  }
+
+  async type(text: string): Promise<void> {
+    await this.run((view) => view.type(text));
+  }
+
+  async typeIn(selector: string, text: string): Promise<void> {
+    const focused = await this.evaluate<boolean>(
+      `(() => { const el = document.querySelector(${JSON.stringify(selector)}); if (!el) return false; el.focus(); return true; })()`,
+    );
+    if (!focused) throw new Error(`type failed: elemento no encontrado: ${selector}`);
+    await this.run((view) => view.type(text));
+  }
+
+  async fill(selector: string, text: string): Promise<void> {
+    // `fill` reemplaza; `type` agrega. Se limpia primero y se disparan los
+    // eventos que esperan React y compañía para registrar el cambio.
+    const ok = await this.evaluate<boolean>(
+      `(() => {
+        const el = document.querySelector(${JSON.stringify(selector)});
+        if (!el) return false;
+        el.focus();
+        el.value = "";
+        el.dispatchEvent(new Event("input", { bubbles: true }));
+        return true;
+      })()`,
+    );
+    if (!ok) throw new Error(`fill failed: elemento no encontrado: ${selector}`);
+    await this.run((view) => view.type(text));
+    await this.evaluate(
+      `(() => {
+        const el = document.querySelector(${JSON.stringify(selector)});
+        if (el) el.dispatchEvent(new Event("change", { bubbles: true }));
+      })()`,
+    );
+  }
+
+  async press(key: string, options?: { modifiers?: string[] }): Promise<void> {
+    const modifiers: Record<string, boolean> = {};
+    for (const modifier of options?.modifiers ?? []) {
+      const normalized = modifier.toLowerCase();
+      if (normalized === "control" || normalized === "ctrl") modifiers.ctrl = true;
+      else if (normalized === "shift") modifiers.shift = true;
+      else if (normalized === "alt") modifiers.alt = true;
+      else if (normalized === "meta" || normalized === "cmd") modifiers.meta = true;
+    }
+    await this.run((view) => view.press(key, modifiers));
+  }
+
+  async scroll(dx: number, dy: number): Promise<void> {
+    await this.run((view) => view.scroll(dx, dy));
+  }
+
+  async scrollTo(selector: string, _options?: { behavior?: "smooth" | "instant" }): Promise<void> {
+    await this.run((view) => view.scrollTo(selector));
+  }
+
+  async back(): Promise<void> {
+    await this.run((view) => view.goBack());
+  }
+
+  async forward(): Promise<void> {
+    await this.run((view) => view.goForward());
+  }
+
+  async reload(): Promise<void> {
+    await this.run((view) => view.reload());
+  }
+
+  async resize(width: number, height: number): Promise<void> {
+    await this.run((view) => view.resize(width, height));
+  }
+
+  close(): void {
+    try {
+      this.view?.close();
+    } catch {
+      /* ya cerrado */
+    }
+    this.view = null;
+  }
+}