@tangle-network/browser-agent-driver 0.24.1 → 0.25.0

package/dist/drivers/cursor-overlay.js

@@ -1,15 +1,23 @@
 /**
- * Cursor + element highlight overlay.
+ * Agent overlay — cursor + reasoning + verdict badges + progress bar.
  *
- * Injected into every page so screenshots and screencasts show what bad is
- * doing — an animated cursor sprite that travels to click targets, a pulse
- * ring on click, and a highlight box around the target element.
+ * Injected into every page so recordings and screenshots show the agent
+ * narrating its own work. Five concerns, one DOM widget:
  *
- * The overlay is a thin DOM widget added via `page.addInitScript`. It exposes
- * a global `__bad_overlay` object that the driver invokes from
- * `page.evaluate` calls before each action. Everything happens in the page
- * context — the cursor is real DOM, so it shows up in screenshots without
- * any extra plumbing.
+ *   1. Cursor arrow that animates to click targets
+ *   2. Highlight box around the target element
+ *   3. Single-line action label next to cursor ("click · Search")
+ *   4. Reasoning panel (translucent, top-right) with the agent's own
+ *      words for the current turn — "Clicking Search to submit C-003"
+ *   5. Verdict badges (stacked, bottom-left) that fade in when a
+ *      conclusion is reached — "✓ C-003 PUTIN → POSITIVE MATCH"
+ *   6. Progress timeline bar (top edge) — thin strip with a dot per
+ *      completed action and a highlighted current position
+ *
+ * All primitives are DOM. They show up in screenshots, video frames, and
+ * the replayer without extra plumbing. The overlay exposes a single
+ * `window.__bad_overlay` API so the driver can drive everything in one
+ * `page.evaluate` round-trip per turn.
  *
  * Toggle via `PlaywrightDriverOptions.showCursor`.
  */
@@ -35,19 +43,28 @@ export const CURSOR_OVERLAY_INIT_SCRIPT = `
     height: '100vh',
     pointerEvents: 'none',
     zIndex: String(Z),
+    fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
   });
 
-  // ── Cursor sprite (SVG arrow) ──────────────────────────────────────────
-  // ── Idle bounce keyframes ──────────────────────────────────────────
+  // ── Keyframes ──────────────────────────────────────────────────────────
   const style = document.createElement('style');
   style.textContent = \`
     @keyframes __bad_cursor_bob {
       0%, 100% { margin-top: 0px; }
       50% { margin-top: -3px; }
     }
+    @keyframes __bad_badge_in {
+      from { transform: translateX(-20px); opacity: 0; }
+      to   { transform: translateX(0); opacity: 1; }
+    }
+    @keyframes __bad_badge_out {
+      from { transform: translateX(0); opacity: 1; }
+      to   { transform: translateX(20px); opacity: 0; }
+    }
   \`;
   (document.head || document.documentElement).appendChild(style);
 
+  // ── Cursor sprite (SVG arrow) ──────────────────────────────────────────
   const cursor = document.createElementNS(NS, 'svg');
   cursor.setAttribute('width', '24');
   cursor.setAttribute('height', '24');
@@ -111,7 +128,6 @@ export const CURSOR_OVERLAY_INIT_SCRIPT = `
     padding: '5px 12px',
     background: 'rgba(11, 18, 32, 0.95)',
     color: '#ffffff',
-    fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
     fontSize: '13px',
     fontWeight: '600',
     letterSpacing: '0.01em',
@@ -124,6 +140,106 @@ export const CURSOR_OVERLAY_INIT_SCRIPT = `
     whiteSpace: 'nowrap',
   });
 
+  // ── Progress timeline bar (top edge, thin strip) ───────────────────────
+  const progress = document.createElement('div');
+  progress.id = '__bad_overlay_progress';
+  Object.assign(progress.style, {
+    position: 'fixed',
+    top: '0',
+    left: '0',
+    right: '0',
+    height: '3px',
+    background: 'rgba(11, 18, 32, 0.6)',
+    pointerEvents: 'none',
+    opacity: '0',
+    transition: 'opacity 300ms ease',
+  });
+  const progressFill = document.createElement('div');
+  Object.assign(progressFill.style, {
+    position: 'absolute',
+    top: '0',
+    left: '0',
+    height: '100%',
+    width: '0%',
+    background: 'linear-gradient(90deg, #4f46e5 0%, #7aa2ff 100%)',
+    transition: 'width 500ms cubic-bezier(0.4, 0, 0.2, 1)',
+    boxShadow: '0 0 8px rgba(79, 70, 229, 0.6)',
+  });
+  progress.appendChild(progressFill);
+
+  // ── Progress label (turn counter, top-left) ────────────────────────────
+  const progressLabel = document.createElement('div');
+  Object.assign(progressLabel.style, {
+    position: 'fixed',
+    top: '10px',
+    left: '14px',
+    padding: '4px 10px',
+    background: 'rgba(11, 18, 32, 0.88)',
+    color: '#ffffff',
+    fontSize: '11px',
+    fontWeight: '700',
+    letterSpacing: '0.06em',
+    textTransform: 'uppercase',
+    borderRadius: '6px',
+    pointerEvents: 'none',
+    opacity: '0',
+    transition: 'opacity 300ms ease',
+    boxShadow: '0 2px 8px rgba(0,0,0,0.3)',
+  });
+
+  // ── Reasoning panel (top-right, translucent; agent's own words) ────────
+  const reasoning = document.createElement('div');
+  reasoning.id = '__bad_overlay_reasoning';
+  Object.assign(reasoning.style, {
+    position: 'fixed',
+    top: '40px',
+    right: '14px',
+    maxWidth: '360px',
+    minWidth: '220px',
+    padding: '12px 14px',
+    background: 'rgba(11, 18, 32, 0.92)',
+    color: '#e6ebf5',
+    fontSize: '12px',
+    lineHeight: '1.5',
+    borderRadius: '10px',
+    borderLeft: '3px solid #7aa2ff',
+    pointerEvents: 'none',
+    opacity: '0',
+    transform: 'translateY(-6px)',
+    transition: 'opacity 250ms ease, transform 250ms ease',
+    boxShadow: '0 6px 20px rgba(0,0,0,0.35)',
+    backdropFilter: 'blur(4px)',
+  });
+  const reasoningHeader = document.createElement('div');
+  Object.assign(reasoningHeader.style, {
+    fontSize: '10px',
+    fontWeight: '700',
+    letterSpacing: '0.1em',
+    textTransform: 'uppercase',
+    color: '#7aa2ff',
+    marginBottom: '6px',
+  });
+  reasoningHeader.textContent = 'Agent reasoning';
+  const reasoningBody = document.createElement('div');
+  Object.assign(reasoningBody.style, { whiteSpace: 'pre-wrap' });
+  reasoning.appendChild(reasoningHeader);
+  reasoning.appendChild(reasoningBody);
+
+  // ── Verdict badges (bottom-left, stacked) ──────────────────────────────
+  const badges = document.createElement('div');
+  badges.id = '__bad_overlay_badges';
+  Object.assign(badges.style, {
+    position: 'fixed',
+    bottom: '14px',
+    left: '14px',
+    display: 'flex',
+    flexDirection: 'column-reverse',
+    gap: '6px',
+    pointerEvents: 'none',
+    maxHeight: '60vh',
+    overflow: 'hidden',
+  });
+
   // Append to documentElement (not body) so the overlay is not affected by
   // body's stacking context — many modern sites apply transform/will-change
   // to body which would clip a max-z-index child appended to body.
@@ -138,6 +254,10 @@ export const CURSOR_OVERLAY_INIT_SCRIPT = `
       return;
     }
     host.appendChild(root);
+    root.appendChild(progress);
+    root.appendChild(progressLabel);
+    root.appendChild(reasoning);
+    root.appendChild(badges);
     root.appendChild(box);
     root.appendChild(ring);
     root.appendChild(cursor);
@@ -145,11 +265,42 @@ export const CURSOR_OVERLAY_INIT_SCRIPT = `
   }
   attach();
 
+  // ── Badge factory ─────────────────────────────────────────────────────
+  const BADGE_COLORS = {
+    positive: { fg: '#fb7185', bg: 'rgba(251,113,133,0.15)', border: 'rgba(251,113,133,0.5)' },
+    cleared:  { fg: '#4ade80', bg: 'rgba(74,222,128,0.15)',  border: 'rgba(74,222,128,0.5)'  },
+    review:   { fg: '#fbbf24', bg: 'rgba(251,191,36,0.15)',  border: 'rgba(251,191,36,0.5)'  },
+    info:     { fg: '#7aa2ff', bg: 'rgba(122,162,255,0.15)', border: 'rgba(122,162,255,0.5)' },
+  };
+  const MAX_BADGES = 6;
+
+  function makeBadge(kind, text) {
+    const palette = BADGE_COLORS[kind] || BADGE_COLORS.info;
+    const el = document.createElement('div');
+    Object.assign(el.style, {
+      padding: '8px 14px',
+      background: 'rgba(11, 18, 32, 0.92)',
+      color: palette.fg,
+      fontSize: '12px',
+      fontWeight: '700',
+      letterSpacing: '0.02em',
+      borderRadius: '8px',
+      border: '1px solid ' + palette.border,
+      boxShadow: '0 4px 16px rgba(0,0,0,0.35), inset 0 0 0 9999px ' + palette.bg,
+      animation: '__bad_badge_in 300ms cubic-bezier(0.34, 1.56, 0.64, 1) both',
+      whiteSpace: 'nowrap',
+      maxWidth: '480px',
+      overflow: 'hidden',
+      textOverflow: 'ellipsis',
+    });
+    el.textContent = text;
+    return el;
+  }
+
   // ── Public API ─────────────────────────────────────────────────────────
   window.__bad_overlay = {
     /**
      * Highlight a target element by CSS selector. Returns the rect or null.
-     * Used when the caller has a stable CSS selector.
      */
     highlight(selector) {
       try {
@@ -169,11 +320,6 @@ export const CURSOR_OVERLAY_INIT_SCRIPT = `
       } catch { return null; }
     },
 
-    /**
-     * Highlight an arbitrary rect at given page coordinates. Used when the
-     * caller already computed the rect via Playwright's boundingBox (i.e.,
-     * the @ref selector isn't a real CSS selector).
-     */
     highlightRect(x, y, width, height) {
       try {
         Object.assign(box.style, {
@@ -185,9 +331,6 @@ export const CURSOR_OVERLAY_INIT_SCRIPT = `
       } catch { /* never let cosmetic overlay break a run */ }
     },
 
-    /**
-     * Move the cursor to (x, y) and show a label.
-     */
     moveTo(x, y, labelText) {
       cursor.style.transform = \`translate(\${x - 4}px, \${y - 4}px)\`;
       if (labelText) {
@@ -199,18 +342,13 @@ export const CURSOR_OVERLAY_INIT_SCRIPT = `
       }
     },
 
-    /**
-     * Pulse a click ring at (x, y).
-     */
     pulseClick(x, y) {
-      // reset
       Object.assign(ring.style, {
         width: '0',
         height: '0',
         transform: \`translate(\${x}px, \${y}px)\`,
         opacity: '1',
       });
-      // expand
       requestAnimationFrame(() => {
         Object.assign(ring.style, {
           width: '60px',
@@ -222,17 +360,70 @@ export const CURSOR_OVERLAY_INIT_SCRIPT = `
     },
 
     /**
-     * Hide all overlay elements.
+     * Show the agent's reasoning for the current turn. Multi-line text,
+     * word-wrapped, in the top-right panel. Pass empty string or null to
+     * hide the panel.
      */
+    setReasoning(text) {
+      try {
+        const t = (text || '').trim();
+        if (!t) {
+          Object.assign(reasoning.style, { opacity: '0', transform: 'translateY(-6px)' });
+          return;
+        }
+        reasoningBody.textContent = t;
+        Object.assign(reasoning.style, { opacity: '1', transform: 'translateY(0)' });
+      } catch { /* cosmetic */ }
+    },
+
+    /**
+     * Update the progress strip: "current" of "total" actions done.
+     * progressText is optional (e.g., "Turn 27 · C-003").
+     */
+    setProgress(current, total, progressText) {
+      try {
+        const c = Math.max(0, Number(current) || 0);
+        const tot = Math.max(1, Number(total) || 1);
+        const pct = Math.min(100, (c / tot) * 100);
+        progressFill.style.width = pct + '%';
+        progress.style.opacity = '1';
+        if (progressText) {
+          progressLabel.textContent = progressText;
+          progressLabel.style.opacity = '1';
+        }
+      } catch { /* cosmetic */ }
+    },
+
+    /**
+     * Push a verdict badge onto the bottom-left stack. Auto-trims to the
+     * most recent MAX_BADGES. kind is one of "positive" | "cleared" |
+     * "review" | "info".
+     */
+    pushBadge(kind, text) {
+      try {
+        const el = makeBadge(kind, text);
+        badges.appendChild(el);
+        // Trim oldest if over cap (column-reverse means first child = bottom)
+        while (badges.children.length > MAX_BADGES) {
+          const first = badges.firstChild;
+          if (!first) break;
+          badges.removeChild(first);
+        }
+      } catch { /* cosmetic */ }
+    },
+
+    clearBadges() {
+      try {
+        while (badges.firstChild) badges.removeChild(badges.firstChild);
+      } catch { /* cosmetic */ }
+    },
+
     hide() {
       box.style.opacity = '0';
       label.style.opacity = '0';
       ring.style.opacity = '0';
     },
 
-    /**
-     * Hide just the highlight box (cursor + label stay).
-     */
     clearHighlight() {
       box.style.opacity = '0';
     },

package/dist/drivers/cursor-overlay.js.map

@@ -1 +1 @@
-{"version":3,"file":"cursor-overlay.js","sourceRoot":"","sources":["../../src/drivers/cursor-overlay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6NzC,CAAA"}
+{"version":3,"file":"cursor-overlay.js","sourceRoot":"","sources":["../../src/drivers/cursor-overlay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoZzC,CAAA"}

package/dist/drivers/overlay-label.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Cursor-overlay label builder.
+ *
+ * The overlay renders a single short label string next to the animated
+ * cursor. A bare verb (`click`, `type`) leaves 90% of the agent's intent
+ * invisible to anyone watching the recording. Rich labels turn the cursor
+ * into a readable narrative — `click · Search`, `type · "IVANOV ALEKSANDR"`,
+ * `press · Enter`, `nav · sanctionssearch.ofac.treas.gov`.
+ *
+ * Design rules:
+ *   - Labels MUST fit on one line at ~13px. Target max 48 chars rendered.
+ *   - Truncate with an ellipsis; never wrap.
+ *   - Verb-only is the SAFE FALLBACK — never throw, never return empty.
+ *   - Target accessible name goes in the label only when it's short and
+ *     informative. Skip generic names ('button', 'link', 'textbox') that
+ *     restate the role the viewer already sees from context.
+ */
+import type { Action } from '../types.js';
+export interface OverlayLabelContext {
+    /** Accessible name of the target element (from snapshot ref lookup). */
+    targetName?: string;
+    /** ARIA role of the target, used to filter generic names. */
+    targetRole?: string;
+}
+/**
+ * Build a single-line label string for the cursor overlay given an action
+ * and (optionally) the resolved target element's accessible name.
+ *
+ * Always returns a non-empty string. Falls back to the bare verb on any
+ * missing context.
+ */
+export declare function formatOverlayLabel(action: Action, ctx?: OverlayLabelContext): string;
+//# sourceMappingURL=overlay-label.d.ts.map

package/dist/drivers/overlay-label.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay-label.d.ts","sourceRoot":"","sources":["../../src/drivers/overlay-label.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AA0CzC,MAAM,WAAW,mBAAmB;IAClC,wEAAwE;IACxE,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,GAAE,mBAAwB,GAAG,MAAM,CAsCxF"}

package/dist/drivers/overlay-label.js

@@ -0,0 +1,92 @@
+const MAX_LABEL_LEN = 48;
+const MAX_TEXT_PREVIEW = 30;
+const MAX_NAME_PREVIEW = 30;
+/**
+ * Role names that are generic; including them in the label adds no info.
+ * NOTE: "Search" is NOT here — a button labeled "Search" is informative
+ * (OFAC, Google, etc.). "searchbox" IS here — that's the role spilling
+ * through as a name when an input has no label, which just restates what
+ * the viewer already sees from the cursor's position on the textbox.
+ */
+const GENERIC_NAMES = new Set([
+    'button', 'link', 'textbox', 'input', 'field', 'searchbox',
+    'combobox', 'listbox', 'option', 'checkbox', 'radio', 'switch',
+]);
+function truncate(s, max) {
+    const collapsed = s.replace(/\s+/g, ' ').trim();
+    if (collapsed.length <= max)
+        return collapsed;
+    return collapsed.slice(0, max - 1).trimEnd() + '…';
+}
+function cleanName(name) {
+    if (!name)
+        return undefined;
+    const c = name.replace(/\s+/g, ' ').trim();
+    if (!c)
+        return undefined;
+    if (GENERIC_NAMES.has(c.toLowerCase()))
+        return undefined;
+    return truncate(c, MAX_NAME_PREVIEW);
+}
+/** Host of a URL without protocol/trailing-slash. Never throws. */
+function displayHost(url) {
+    try {
+        const u = new URL(url);
+        return u.host || url;
+    }
+    catch {
+        return url.replace(/^https?:\/\//, '').replace(/\/.*$/, '').slice(0, MAX_NAME_PREVIEW);
+    }
+}
+/**
+ * Build a single-line label string for the cursor overlay given an action
+ * and (optionally) the resolved target element's accessible name.
+ *
+ * Always returns a non-empty string. Falls back to the bare verb on any
+ * missing context.
+ */
+export function formatOverlayLabel(action, ctx = {}) {
+    const name = cleanName(ctx.targetName);
+    switch (action.action) {
+        case 'click': {
+            return truncate(name ? `click · ${name}` : 'click', MAX_LABEL_LEN);
+        }
+        case 'type': {
+            const text = truncate(action.text ?? '', MAX_TEXT_PREVIEW);
+            if (text && name)
+                return truncate(`type "${text}" · ${name}`, MAX_LABEL_LEN);
+            if (text)
+                return truncate(`type · "${text}"`, MAX_LABEL_LEN);
+            return name ? truncate(`type · ${name}`, MAX_LABEL_LEN) : 'type';
+        }
+        case 'press': {
+            const key = action.key ?? '';
+            if (key && name)
+                return truncate(`press ${key} · ${name}`, MAX_LABEL_LEN);
+            return truncate(key ? `press · ${key}` : 'press', MAX_LABEL_LEN);
+        }
+        case 'hover': {
+            return truncate(name ? `hover · ${name}` : 'hover', MAX_LABEL_LEN);
+        }
+        case 'select': {
+            const val = truncate(action.value ?? '', MAX_TEXT_PREVIEW);
+            if (val && name)
+                return truncate(`select ${val} · ${name}`, MAX_LABEL_LEN);
+            if (val)
+                return truncate(`select · ${val}`, MAX_LABEL_LEN);
+            return name ? truncate(`select · ${name}`, MAX_LABEL_LEN) : 'select';
+        }
+        case 'scroll': {
+            return truncate(`scroll ${action.direction}`, MAX_LABEL_LEN);
+        }
+        case 'navigate': {
+            return truncate(`nav · ${displayHost(action.url)}`, MAX_LABEL_LEN);
+        }
+        case 'wait': {
+            return truncate(`wait ${action.ms}ms`, MAX_LABEL_LEN);
+        }
+        default:
+            return action.action;
+    }
+}
+//# sourceMappingURL=overlay-label.js.map

package/dist/drivers/overlay-label.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay-label.js","sourceRoot":"","sources":["../../src/drivers/overlay-label.ts"],"names":[],"mappings":"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"}

package/dist/drivers/playwright.d.ts

@@ -11,6 +11,7 @@
 import type { Page } from 'playwright';
 import type { Driver, ActionResult, ResourceBlockingOptions } from './types.js';
 import type { Action, PageState } from '../types.js';
+import type { MacroRegistry } from '../skills/macro-loader.js';
 /** Phase-level timing breakdown for observe() */
 export interface ObserveTiming {
     /** Total observe() time in ms */
@@ -55,6 +56,10 @@ export interface PlaywrightDriverOptions {
      * screenshot lands wherever the transition has reached by then.
      */
     showCursor?: boolean;
+    /** Gen 29: registry of user-defined macros the agent can invoke via
+     * `{action:"macro", name:..., args:...}`. When omitted, macro calls fail
+     * with an error message referencing the missing name. */
+    macros?: MacroRegistry;
 }
 export declare class PlaywrightDriver implements Driver {
     private page;
@@ -94,6 +99,28 @@ export declare class PlaywrightDriver implements Driver {
     private animateCursorToCoord;
     /** Get phase-level timing from the last observe() call */
     getLastTiming(): ObserveTiming | undefined;
+    /**
+     * Set the reasoning panel (top-right) to the agent's current-turn
+     * reasoning. No-op when the overlay is disabled.
+     *
+     * Defensive: wraps page.evaluate with try/catch so navigation races,
+     * closed contexts, or a missing overlay (XML / PDF viewer / chrome://
+     * pages) never crash a run — the overlay is strictly cosmetic.
+     */
+    setOverlayReasoning(text: string): Promise<void>;
+    /**
+     * Update the progress bar + turn counter at the top of the overlay.
+     * `total` is the max-turns budget; `label` is a short status string
+     * (e.g., "Turn 27 · C-003").
+     */
+    setOverlayProgress(current: number, total: number, label?: string): Promise<void>;
+    /**
+     * Push a verdict badge to the bottom-left stack. Used when the agent's
+     * reasoning indicates a conclusion ("POSITIVE MATCH", "CLEARED",
+     * "NEEDS REVIEW") — the driver runner parses reasoning + emits these
+     * to celebrate the moment.
+     */
+    pushOverlayBadge(kind: 'positive' | 'cleared' | 'review' | 'info', text: string): Promise<void>;
     getPage(): Page;
     getUrl(): string;
     inspectSelectorHref(selector: string): Promise<string | undefined>;
@@ -119,6 +146,9 @@ export declare class PlaywrightDriver implements Driver {
     private observePlaywright;
     screenshot(): Promise<Buffer>;
     close(): Promise<void>;
+    /** Expose construction options so runners can clone this driver's config
+     * onto a sub-driver (compound-goal parallel tabs). */
+    getDriverOptions(): PlaywrightDriverOptions;
     /**
      * Execute an action first. If it fails and a blocking overlay is detected,
      * dismiss it and retry once.

package/dist/drivers/playwright.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"playwright.d.ts","sourceRoot":"","sources":["../../src/drivers/playwright.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAc,MAAM,YAAY,CAAC;AACnD,OAAO,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAChF,OAAO,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAyFrD,iDAAiD;AACjD,MAAM,WAAW,aAAa;IAC5B,iCAAiC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,aAAa,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,YAAY,EAAE,MAAM,CAAC;IACrB,qCAAqC;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,qCAAqC;IACrC,YAAY,EAAE,MAAM,CAAC;IACrB,iCAAiC;IACjC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,uBAAuB;IACtC,2BAA2B;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,6CAA6C;IAC7C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,qEAAqE;IACrE,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,sEAAsE;IACtE,cAAc,CAAC,EAAE,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAC;IAC7C,6EAA6E;IAC7E,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;;;;;OAUG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,qBAAa,gBAAiB,YAAW,MAAM;IAgB3C,OAAO,CAAC,IAAI;IACZ,OAAO,CAAC,OAAO;IAhBjB,OAAO,CAAC,QAAQ,CAA4B;IAC5C,OAAO,CAAC,UAAU,CAA2B;IAC7C,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,UAAU,CAA4B;IAC9C,OAAO,CAAC,YAAY,CAAK;IACzB;;;;OAIG;IACH,OAAO,CAAC,oBAAoB,CAAC,CAAgB;IAC7C,uFAAuF;IACvF,OAAO,CAAC,WAAW,CAAoB;gBAG7B,IAAI,EAAE,IAAI,EACV,OAAO,GAAE,uBAA4B;IAU/C;;;OAGG;YACW,oBAAoB;IAWlC;;;;;;;OAOG;YACW,uBAAuB;IA4CrC;;;OAGG;YACW,oBAAoB;IAqBlC,0DAA0D;IAC1D,aAAa,IAAI,aAAa,GAAG,SAAS;IAI1C,OAAO,IAAI,IAAI;IAIf,MAAM,IAAI,MAAM;IAIV,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;YAS1D,SAAS;IAWvB;;;OAGG;IACG,qBAAqB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC;IAuC5E;;;OAGG;YACW,gBAAgB;IAcxB,OAAO,IAAI,OAAO,CAAC,SAAS,CAAC;IAmDnC;;OAEG;YACW,UAAU;IA4ExB;;OAEG;YACW,iBAAiB;IAwCzB,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;IAI7B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAO5B;;;OAGG;YACW,mBAAmB;YAUnB,aAAa;IAUrB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;CAoXrD"}
+{"version":3,"file":"playwright.d.ts","sourceRoot":"","sources":["../../src/drivers/playwright.ts"],"names":[],"mappings":"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"}