@tangle-network/browser-agent-driver 0.12.1 → 0.14.0

package/dist/design/audit/types.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Design audit types — Generation 2.
+ *
+ * Core idea: classification → rubric → measurements → evaluation → findings.
+ * Each stage is a pure transformation; the orchestrator (`pipeline.ts`) wires them.
+ */
+import type { DesignFinding, DesignSystemScore } from '../../types.js';
+export type { DesignFinding, DesignSystemScore } from '../../types.js';
+/**
+ * Page classification — produced by a single cheap LLM call before any scoring.
+ * Drives rubric composition and measurement strategy.
+ */
+export interface PageClassification {
+    /** Primary page archetype */
+    type: PageType;
+    /** Application domain (free-form, but canonical values preferred) */
+    domain: string;
+    /** Detected framework, or null if undetectable */
+    framework: string | null;
+    /** Component library / design system in use */
+    designSystem: DesignSystemTag;
+    /** Apparent maturity level — anchors calibration */
+    maturity: Maturity;
+    /** Free-form: what is this page trying to accomplish? */
+    intent: string;
+    /** Classifier confidence 0-1; values < 0.7 fall back to general rubric */
+    confidence: number;
+}
+export type PageType = 'marketing' | 'saas-app' | 'dashboard' | 'docs' | 'ecommerce' | 'social' | 'tool' | 'blog' | 'utility' | 'unknown';
+export type DesignSystemTag = 'shadcn' | 'mui' | 'ant' | 'chakra' | 'tailwind-custom' | 'fully-custom' | 'unstyled' | 'unknown';
+export type Maturity = 'prototype' | 'mvp' | 'shipped' | 'polished' | 'world-class';
+/**
+ * A rubric fragment — loaded from markdown with YAML frontmatter.
+ * Fragments compose into a full rubric based on classification.
+ */
+export interface RubricFragment {
+    /** Unique fragment id (matches filename) */
+    id: string;
+    /** Predicates that decide whether this fragment applies */
+    appliesWhen: AppliesWhen;
+    /** Relative importance when composing */
+    weight: 'low' | 'medium' | 'high' | 'critical';
+    /** Human-readable title for the report */
+    title: string;
+    /** Markdown body — gets injected into the eval prompt */
+    body: string;
+    /**
+     * Optional dimension this fragment contributes to the design system score.
+     * When set, the LLM will be asked to score this dimension 1-10 in addition
+     * to the universal 8 dimensions. Example: a fintech fragment might
+     * contribute "trust-signals", a docs fragment might contribute "readability".
+     */
+    dimension?: string;
+}
+export interface AppliesWhen {
+    /** Match if classification.type is in this set; empty/undefined = always */
+    type?: PageType[];
+    /** Match if classification.domain matches any of these (substring) */
+    domain?: string[];
+    /** Match if classification.maturity is in this set */
+    maturity?: Maturity[];
+    /** Match if classification.designSystem is in this set */
+    designSystem?: DesignSystemTag[];
+    /** Universal fragments — always apply, no predicates needed */
+    universal?: boolean;
+}
+/**
+ * A composed rubric — the full set of fragments selected for one classification,
+ * ready to inject into an LLM eval prompt.
+ */
+export interface ComposedRubric {
+    fragments: RubricFragment[];
+    /** Pre-rendered markdown body, ready for prompt injection */
+    body: string;
+    /** Calibration anchor for this rubric */
+    calibration: string;
+    /** Custom dimensions contributed by fragments (in addition to universal 8) */
+    dimensions: string[];
+}
+/**
+ * Bundle of deterministic measurements taken before LLM evaluation.
+ * The LLM sees these as ground truth and is forbidden from inventing them.
+ */
+export interface MeasurementBundle {
+    contrast: ContrastReport;
+    a11y: A11yReport;
+    /** Computed at gather time, used to short-circuit evaluation if too many failures */
+    hasBlockingIssues: boolean;
+}
+export interface ContrastReport {
+    /** All text-bearing elements with computed text/bg colors */
+    totalChecked: number;
+    /** Failures of WCAG 2.1 AA (4.5:1 normal, 3:1 large) */
+    aaFailures: ContrastFailure[];
+    /** Failures of WCAG 2.1 AAA (7:1 normal, 4.5:1 large) — informational */
+    aaaFailures: ContrastFailure[];
+    /** Quick stats */
+    summary: {
+        aaPassRate: number;
+        aaaPassRate: number;
+    };
+}
+export interface ContrastFailure {
+    /** CSS-style selector pointing to the element */
+    selector: string;
+    /** Truncated visible text */
+    text: string;
+    /** Computed color hex */
+    color: string;
+    /** Computed (resolved) background hex */
+    background: string;
+    /** Calculated WCAG ratio */
+    ratio: number;
+    /** Required ratio for the level being checked */
+    required: number;
+    /** Element font size in px */
+    fontSize: number;
+    /** Whether the element qualifies as "large text" per WCAG */
+    isLargeText: boolean;
+}
+export interface A11yReport {
+    /** axe-core ran successfully */
+    ran: boolean;
+    /** Error message if axe-core failed to run */
+    error?: string;
+    /** Violations grouped by axe impact */
+    violations: A11yViolation[];
+    /** axe pass count for context */
+    passes: number;
+}
+export interface A11yViolation {
+    /** axe rule id */
+    id: string;
+    /** axe impact level */
+    impact: 'critical' | 'serious' | 'moderate' | 'minor';
+    /** Human-readable description */
+    description: string;
+    /** WCAG criterion (e.g. "wcag2aa") */
+    tags: string[];
+    /** First few affected elements */
+    nodes: Array<{
+        selector: string;
+        html: string;
+        failureSummary: string;
+    }>;
+    /** axe help URL */
+    helpUrl: string;
+}
+/**
+ * Per-page audit result.
+ */
+export interface PageAuditResult {
+    url: string;
+    score: number;
+    summary: string;
+    strengths: string[];
+    findings: DesignFinding[];
+    classification?: PageClassification;
+    rubricFragments?: string[];
+    measurements?: MeasurementBundle;
+    designSystemScore?: DesignSystemScore;
+    screenshotPath?: string;
+    tokensUsed?: number;
+    error?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/design/audit/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/design/audit/types.ts"],"names":[],"mappings":"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"}

package/dist/design/audit/types.js

@@ -0,0 +1,8 @@
+/**
+ * Design audit types — Generation 2.
+ *
+ * Core idea: classification → rubric → measurements → evaluation → findings.
+ * Each stage is a pure transformation; the orchestrator (`pipeline.ts`) wires them.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/design/audit/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/design/audit/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

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

@@ -0,0 +1,26 @@
+/**
+ * Cursor + element highlight overlay.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * Toggle via `PlaywrightDriverOptions.showCursor`.
+ */
+/**
+ * The init script that runs in every page. Returned as a string so it can be
+ * passed to `page.addInitScript`. Pure DOM/CSS — no dependencies.
+ */
+export declare const CURSOR_OVERLAY_INIT_SCRIPT = "\n(() => {\n  if (window.__bad_overlay_installed) return;\n  window.__bad_overlay_installed = true;\n\n  const NS = 'http://www.w3.org/2000/svg';\n  const Z = 2147483647; // max i32\n\n  // \u2500\u2500 Root container (absolute, ignores pointer events) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n  const root = document.createElement('div');\n  root.id = '__bad_overlay_root';\n  Object.assign(root.style, {\n    position: 'fixed',\n    inset: '0',\n    width: '100vw',\n    height: '100vh',\n    pointerEvents: 'none',\n    zIndex: String(Z),\n  });\n\n  // \u2500\u2500 Cursor sprite (SVG arrow) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n  const cursor = document.createElementNS(NS, 'svg');\n  cursor.setAttribute('width', '24');\n  cursor.setAttribute('height', '24');\n  cursor.setAttribute('viewBox', '0 0 24 24');\n  cursor.setAttribute('fill', 'none');\n  Object.assign(cursor.style, {\n    position: 'fixed',\n    left: '0',\n    top: '0',\n    transform: 'translate(-100px, -100px)',\n    transition: 'transform 220ms cubic-bezier(0.22, 1, 0.36, 1)',\n    pointerEvents: 'none',\n    filter: 'drop-shadow(0 1px 2px rgba(0,0,0,0.4))',\n  });\n  cursor.innerHTML = `\n    <path d=\"M3 2 L21 12 L13 14 L9 22 Z\" fill=\"#ffffff\" stroke=\"#0b1220\" stroke-width=\"1.5\" stroke-linejoin=\"round\"/>\n  `;\n\n  // \u2500\u2500 Pulse ring (animated on click) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n  const ring = document.createElement('div');\n  Object.assign(ring.style, {\n    position: 'fixed',\n    left: '0',\n    top: '0',\n    width: '0',\n    height: '0',\n    borderRadius: '9999px',\n    border: '3px solid rgba(79, 70, 229, 0.95)',\n    transform: 'translate(-100px, -100px)',\n    pointerEvents: 'none',\n    opacity: '0',\n    transition: 'all 500ms ease-out',\n  });\n\n  // \u2500\u2500 Highlight box (drawn around the target element) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n  const box = document.createElement('div');\n  box.id = '__bad_overlay_box';\n  Object.assign(box.style, {\n    position: 'fixed',\n    left: '0',\n    top: '0',\n    width: '0',\n    height: '0',\n    border: '2px solid rgba(34, 197, 94, 0.95)',\n    borderRadius: '6px',\n    background: 'rgba(34, 197, 94, 0.08)',\n    boxShadow: '0 0 0 4px rgba(34, 197, 94, 0.18)',\n    transform: 'translate(-100px, -100px)',\n    pointerEvents: 'none',\n    transition: 'all 180ms ease-out',\n    opacity: '0',\n  });\n\n  // \u2500\u2500 Action label (shows \"click\" / \"type\" / etc next to cursor) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n  const label = document.createElement('div');\n  Object.assign(label.style, {\n    position: 'fixed',\n    left: '0',\n    top: '0',\n    padding: '4px 10px',\n    background: 'rgba(11, 18, 32, 0.92)',\n    color: '#ffffff',\n    fontFamily: '-apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, sans-serif',\n    fontSize: '12px',\n    fontWeight: '600',\n    borderRadius: '6px',\n    transform: 'translate(-200px, -200px)',\n    pointerEvents: 'none',\n    opacity: '0',\n    transition: 'all 220ms cubic-bezier(0.22, 1, 0.36, 1)',\n    boxShadow: '0 4px 12px rgba(0,0,0,0.3)',\n    whiteSpace: 'nowrap',\n  });\n\n  // Append to documentElement (not body) so the overlay is not affected by\n  // body's stacking context \u2014 many modern sites apply transform/will-change\n  // to body which would clip a max-z-index child appended to body.\n  // Bound the retry loop so a body-less doc (XML, PDF viewer, chrome://)\n  // doesn't spin requestAnimationFrame forever.\n  let attachAttempts = 0;\n  function attach() {\n    const host = document.documentElement || document.body;\n    if (!host) {\n      if (++attachAttempts > 60) return; // ~1 second of attempts\n      requestAnimationFrame(attach);\n      return;\n    }\n    host.appendChild(root);\n    root.appendChild(box);\n    root.appendChild(ring);\n    root.appendChild(cursor);\n    root.appendChild(label);\n  }\n  attach();\n\n  // \u2500\u2500 Public API \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n  window.__bad_overlay = {\n    /**\n     * Highlight a target element by CSS selector. Returns the rect or null.\n     * Used when the caller has a stable CSS selector.\n     */\n    highlight(selector) {\n      try {\n        const el = typeof selector === 'string'\n          ? document.querySelector(selector)\n          : null;\n        if (!el) return null;\n        const rect = el.getBoundingClientRect();\n        if (rect.width === 0 || rect.height === 0) return null;\n        Object.assign(box.style, {\n          width: rect.width + 'px',\n          height: rect.height + 'px',\n          transform: `translate(${rect.left}px, ${rect.top}px)`,\n          opacity: '1',\n        });\n        return { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2, width: rect.width, height: rect.height };\n      } catch { return null; }\n    },\n\n    /**\n     * Highlight an arbitrary rect at given page coordinates. Used when the\n     * caller already computed the rect via Playwright's boundingBox (i.e.,\n     * the @ref selector isn't a real CSS selector).\n     */\n    highlightRect(x, y, width, height) {\n      try {\n        Object.assign(box.style, {\n          width: width + 'px',\n          height: height + 'px',\n          transform: `translate(${x}px, ${y}px)`,\n          opacity: '1',\n        });\n      } catch { /* never let cosmetic overlay break a run */ }\n    },\n\n    /**\n     * Move the cursor to (x, y) and show a label.\n     */\n    moveTo(x, y, labelText) {\n      cursor.style.transform = `translate(${x - 4}px, ${y - 4}px)`;\n      if (labelText) {\n        label.textContent = labelText;\n        Object.assign(label.style, {\n          transform: `translate(${x + 16}px, ${y + 16}px)`,\n          opacity: '1',\n        });\n      }\n    },\n\n    /**\n     * Pulse a click ring at (x, y).\n     */\n    pulseClick(x, y) {\n      // reset\n      Object.assign(ring.style, {\n        width: '0',\n        height: '0',\n        transform: `translate(${x}px, ${y}px)`,\n        opacity: '1',\n      });\n      // expand\n      requestAnimationFrame(() => {\n        Object.assign(ring.style, {\n          width: '60px',\n          height: '60px',\n          transform: `translate(${x - 30}px, ${y - 30}px)`,\n          opacity: '0',\n        });\n      });\n    },\n\n    /**\n     * Hide all overlay elements.\n     */\n    hide() {\n      box.style.opacity = '0';\n      label.style.opacity = '0';\n      ring.style.opacity = '0';\n    },\n\n    /**\n     * Hide just the highlight box (cursor + label stay).\n     */\n    clearHighlight() {\n      box.style.opacity = '0';\n    },\n  };\n})();\n";
+/**
+ * Wait time after `moveTo` so the cursor animation finishes before the
+ * actual action fires. Tuned to match the CSS transition duration.
+ */
+export declare const CURSOR_ANIMATION_MS = 240;
+//# sourceMappingURL=cursor-overlay.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cursor-overlay.d.ts","sourceRoot":"","sources":["../../src/drivers/cursor-overlay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;GAGG;AACH,eAAO,MAAM,0BAA0B,01OAiNtC,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,MAAM,CAAA"}

package/dist/drivers/cursor-overlay.js

@@ -0,0 +1,235 @@
+/**
+ * Cursor + element highlight overlay.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * Toggle via `PlaywrightDriverOptions.showCursor`.
+ */
+/**
+ * The init script that runs in every page. Returned as a string so it can be
+ * passed to `page.addInitScript`. Pure DOM/CSS — no dependencies.
+ */
+export const CURSOR_OVERLAY_INIT_SCRIPT = `
+(() => {
+  if (window.__bad_overlay_installed) return;
+  window.__bad_overlay_installed = true;
+
+  const NS = 'http://www.w3.org/2000/svg';
+  const Z = 2147483647; // max i32
+
+  // ── Root container (absolute, ignores pointer events) ──────────────────
+  const root = document.createElement('div');
+  root.id = '__bad_overlay_root';
+  Object.assign(root.style, {
+    position: 'fixed',
+    inset: '0',
+    width: '100vw',
+    height: '100vh',
+    pointerEvents: 'none',
+    zIndex: String(Z),
+  });
+
+  // ── Cursor sprite (SVG arrow) ──────────────────────────────────────────
+  const cursor = document.createElementNS(NS, 'svg');
+  cursor.setAttribute('width', '24');
+  cursor.setAttribute('height', '24');
+  cursor.setAttribute('viewBox', '0 0 24 24');
+  cursor.setAttribute('fill', 'none');
+  Object.assign(cursor.style, {
+    position: 'fixed',
+    left: '0',
+    top: '0',
+    transform: 'translate(-100px, -100px)',
+    transition: 'transform 220ms cubic-bezier(0.22, 1, 0.36, 1)',
+    pointerEvents: 'none',
+    filter: 'drop-shadow(0 1px 2px rgba(0,0,0,0.4))',
+  });
+  cursor.innerHTML = \`
+    <path d="M3 2 L21 12 L13 14 L9 22 Z" fill="#ffffff" stroke="#0b1220" stroke-width="1.5" stroke-linejoin="round"/>
+  \`;
+
+  // ── Pulse ring (animated on click) ─────────────────────────────────────
+  const ring = document.createElement('div');
+  Object.assign(ring.style, {
+    position: 'fixed',
+    left: '0',
+    top: '0',
+    width: '0',
+    height: '0',
+    borderRadius: '9999px',
+    border: '3px solid rgba(79, 70, 229, 0.95)',
+    transform: 'translate(-100px, -100px)',
+    pointerEvents: 'none',
+    opacity: '0',
+    transition: 'all 500ms ease-out',
+  });
+
+  // ── Highlight box (drawn around the target element) ────────────────────
+  const box = document.createElement('div');
+  box.id = '__bad_overlay_box';
+  Object.assign(box.style, {
+    position: 'fixed',
+    left: '0',
+    top: '0',
+    width: '0',
+    height: '0',
+    border: '2px solid rgba(34, 197, 94, 0.95)',
+    borderRadius: '6px',
+    background: 'rgba(34, 197, 94, 0.08)',
+    boxShadow: '0 0 0 4px rgba(34, 197, 94, 0.18)',
+    transform: 'translate(-100px, -100px)',
+    pointerEvents: 'none',
+    transition: 'all 180ms ease-out',
+    opacity: '0',
+  });
+
+  // ── Action label (shows "click" / "type" / etc next to cursor) ─────────
+  const label = document.createElement('div');
+  Object.assign(label.style, {
+    position: 'fixed',
+    left: '0',
+    top: '0',
+    padding: '4px 10px',
+    background: 'rgba(11, 18, 32, 0.92)',
+    color: '#ffffff',
+    fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
+    fontSize: '12px',
+    fontWeight: '600',
+    borderRadius: '6px',
+    transform: 'translate(-200px, -200px)',
+    pointerEvents: 'none',
+    opacity: '0',
+    transition: 'all 220ms cubic-bezier(0.22, 1, 0.36, 1)',
+    boxShadow: '0 4px 12px rgba(0,0,0,0.3)',
+    whiteSpace: 'nowrap',
+  });
+
+  // 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.
+  // Bound the retry loop so a body-less doc (XML, PDF viewer, chrome://)
+  // doesn't spin requestAnimationFrame forever.
+  let attachAttempts = 0;
+  function attach() {
+    const host = document.documentElement || document.body;
+    if (!host) {
+      if (++attachAttempts > 60) return; // ~1 second of attempts
+      requestAnimationFrame(attach);
+      return;
+    }
+    host.appendChild(root);
+    root.appendChild(box);
+    root.appendChild(ring);
+    root.appendChild(cursor);
+    root.appendChild(label);
+  }
+  attach();
+
+  // ── 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 {
+        const el = typeof selector === 'string'
+          ? document.querySelector(selector)
+          : null;
+        if (!el) return null;
+        const rect = el.getBoundingClientRect();
+        if (rect.width === 0 || rect.height === 0) return null;
+        Object.assign(box.style, {
+          width: rect.width + 'px',
+          height: rect.height + 'px',
+          transform: \`translate(\${rect.left}px, \${rect.top}px)\`,
+          opacity: '1',
+        });
+        return { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2, width: rect.width, height: rect.height };
+      } 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, {
+          width: width + 'px',
+          height: height + 'px',
+          transform: \`translate(\${x}px, \${y}px)\`,
+          opacity: '1',
+        });
+      } 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) {
+        label.textContent = labelText;
+        Object.assign(label.style, {
+          transform: \`translate(\${x + 16}px, \${y + 16}px)\`,
+          opacity: '1',
+        });
+      }
+    },
+
+    /**
+     * 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',
+          height: '60px',
+          transform: \`translate(\${x - 30}px, \${y - 30}px)\`,
+          opacity: '0',
+        });
+      });
+    },
+
+    /**
+     * Hide all overlay elements.
+     */
+    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';
+    },
+  };
+})();
+`;
+/**
+ * Wait time after `moveTo` so the cursor animation finishes before the
+ * actual action fires. Tuned to match the CSS transition duration.
+ */
+export const CURSOR_ANIMATION_MS = 240;
+//# sourceMappingURL=cursor-overlay.js.map

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

@@ -0,0 +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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiNzC,CAAA;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAG,CAAA"}

package/dist/drivers/playwright.d.ts

@@ -43,6 +43,18 @@ export interface PlaywrightDriverOptions {
     visionStrategy?: 'always' | 'never' | 'auto';
     /** Capture a screenshot every N turns for artifact storage (0 = disabled) */
     screenshotInterval?: number;
+    /**
+     * Inject a cursor + element-highlight overlay so screenshots show what bad
+     * is doing. Adds an animated cursor sprite that travels to click targets,
+     * pulse rings on click, and highlight boxes around the target element.
+     *
+     * Default: false. Enable for demo recordings, debugging, and the session viewer.
+     *
+     * **Performance note:** each interactive action waits ~240ms for the cursor
+     * animation to land before executing — over a 50-turn session that's ~12s
+     * of added wall time. Leave off for headless CI; on for screen captures.
+     */
+    showCursor?: boolean;
 }
 export declare class PlaywrightDriver implements Driver {
     private page;
@@ -52,7 +64,27 @@ export declare class PlaywrightDriver implements Driver {
     private cdpFailed;
     private lastTiming;
     private observeCount;
+    /**
+     * Promise that resolves when the cursor overlay finishes installing.
+     * `animateCursorToSelector` awaits this so the first action doesn't race
+     * the init script. Undefined if showCursor is off.
+     */
+    private cursorInstallPromise?;
     constructor(page: Page, options?: PlaywrightDriverOptions);
+    /**
+     * Inject the cursor overlay init script into the current page and into the
+     * browser context, so it survives navigations and applies to popups.
+     */
+    private installCursorOverlay;
+    /**
+     * Animate the cursor to the target element + draw a highlight box, then
+     * pulse a click ring. No-op if showCursor is disabled.
+     *
+     * Uses Playwright's boundingBox to compute the rect (works for any locator,
+     * including @ref selectors that don't map to plain CSS) and drives the
+     * overlay via its public `highlightRect` / `moveTo` / `pulseClick` API.
+     */
+    private animateCursorToSelector;
     /** Get phase-level timing from the last observe() call */
     getLastTiming(): ObserveTiming | undefined;
     getPage(): Page;

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;AAUrD,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;CAC7B;AAED,qBAAa,gBAAiB,YAAW,MAAM;IAQ3C,OAAO,CAAC,IAAI;IACZ,OAAO,CAAC,OAAO;IARjB,OAAO,CAAC,QAAQ,CAA4B;IAC5C,OAAO,CAAC,UAAU,CAA2B;IAC7C,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,UAAU,CAA4B;IAC9C,OAAO,CAAC,YAAY,CAAK;gBAGf,IAAI,EAAE,IAAI,EACV,OAAO,GAAE,uBAA4B;IAG/C,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;IA4DxB;;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;CAkJrD"}
+{"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;AAWrD,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;IAc3C,OAAO,CAAC,IAAI;IACZ,OAAO,CAAC,OAAO;IAdjB,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;gBAGnC,IAAI,EAAE,IAAI,EACV,OAAO,GAAE,uBAA4B;IAU/C;;;OAGG;YACW,oBAAoB;IAWlC;;;;;;;OAOG;YACW,uBAAuB;IA+CrC,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;IA4DxB;;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;CAuJrD"}

package/dist/drivers/playwright.js

@@ -12,6 +12,7 @@ import { AriaSnapshotHelper, dismissOverlays } from './snapshot.js';
 import { ANALYTICS_PATTERNS, IMAGE_PATTERNS, MEDIA_PATTERNS } from './block-patterns.js';
 import { buildCdpSnapshot } from './cdp-snapshot.js';
 import { getPageMetadata } from './cdp-page-state.js';
+import { CURSOR_OVERLAY_INIT_SCRIPT, CURSOR_ANIMATION_MS } from './cursor-overlay.js';
 function isPointerInterceptError(error) {
     return /intercepts pointer events|subtree intercepts pointer events|not receiving pointer events/i.test(error);
 }
@@ -23,9 +24,82 @@ export class PlaywrightDriver {
     cdpFailed = false;
     lastTiming;
     observeCount = 0;
+    /**
+     * Promise that resolves when the cursor overlay finishes installing.
+     * `animateCursorToSelector` awaits this so the first action doesn't race
+     * the init script. Undefined if showCursor is off.
+     */
+    cursorInstallPromise;
     constructor(page, options = {}) {
         this.page = page;
         this.options = options;
+        if (this.options.showCursor) {
+            // Install for the current page AND any future pages this context creates.
+            // We store the promise so callers (animateCursorToSelector) can await it
+            // before driving the overlay — otherwise the first action races the inject.
+            this.cursorInstallPromise = this.installCursorOverlay();
+        }
+    }
+    /**
+     * Inject the cursor overlay init script into the current page and into the
+     * browser context, so it survives navigations and applies to popups.
+     */
+    async installCursorOverlay() {
+        try {
+            // Context-level: applies to all current and future pages
+            await this.page.context().addInitScript({ content: CURSOR_OVERLAY_INIT_SCRIPT });
+            // Page-level: ensure the current page has it now (addInitScript is for new docs)
+            await this.page.evaluate(CURSOR_OVERLAY_INIT_SCRIPT).catch(() => { });
+        }
+        catch {
+            // Strict CSP can block evaluate; init script via context still works on next nav
+        }
+    }
+    /**
+     * Animate the cursor to the target element + draw a highlight box, then
+     * pulse a click ring. No-op if showCursor is disabled.
+     *
+     * Uses Playwright's boundingBox to compute the rect (works for any locator,
+     * including @ref selectors that don't map to plain CSS) and drives the
+     * overlay via its public `highlightRect` / `moveTo` / `pulseClick` API.
+     */
+    async animateCursorToSelector(selector, actionLabel) {
+        if (!this.options.showCursor)
+            return;
+        // Make sure the install promise (fired in the constructor) has resolved
+        // before we try to drive the overlay. Otherwise the first action races
+        // the script injection and the cursor never appears.
+        if (this.cursorInstallPromise) {
+            await this.cursorInstallPromise.catch(() => undefined);
+        }
+        try {
+            const locator = this.snapshot.resolveLocator(this.page, selector);
+            const box = await locator.boundingBox({ timeout: 1000 }).catch(() => null);
+            if (!box)
+                return;
+            const cx = box.x + box.width / 2;
+            const cy = box.y + box.height / 2;
+            await this.page.evaluate(({ x, y, w, h, label, cx: cxArg, cy: cyArg }) => {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const ov = window.__bad_overlay;
+                if (!ov)
+                    return;
+                ov.highlightRect(x, y, w, h);
+                ov.moveTo(cxArg, cyArg, label);
+            }, { x: box.x, y: box.y, w: box.width, h: box.height, label: actionLabel, cx, cy }).catch(() => { });
+            await this.page.waitForTimeout(CURSOR_ANIMATION_MS);
+            if (actionLabel === 'click' || actionLabel === 'type' || actionLabel === 'press') {
+                await this.page.evaluate(({ x, y }) => {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    const ov = window.__bad_overlay;
+                    if (ov)
+                        ov.pulseClick(x, y);
+                }, { x: cx, y: cy }).catch(() => { });
+            }
+        }
+        catch {
+            // Overlay is purely cosmetic — never let it break the action
+        }
     }
     /** Get phase-level timing from the last observe() call */
     getLastTiming() {
@@ -288,6 +362,7 @@ export class PlaywrightDriver {
                 case 'click': {
                     const locator = this.snapshot.resolveLocator(this.page, action.selector);
                     const bounds = await this.captureBounds(locator);
+                    await this.animateCursorToSelector(action.selector, 'click');
                     // Listen for popups but don't block: collect any that fire during the click
                     let popupPage = null;
                     const onPopup = (page) => { popupPage = page; };
@@ -320,6 +395,7 @@ export class PlaywrightDriver {
                 case 'type': {
                     const locator = this.snapshot.resolveLocator(this.page, action.selector);
                     const bounds = await this.captureBounds(locator);
+                    await this.animateCursorToSelector(action.selector, 'type');
                     try {
                         await this.withOverlayRecovery(async () => {
                             await locator.click({ timeout });
@@ -346,6 +422,7 @@ export class PlaywrightDriver {
                 case 'press': {
                     const locator = this.snapshot.resolveLocator(this.page, action.selector);
                     const bounds = await this.captureBounds(locator);
+                    await this.animateCursorToSelector(action.selector, 'press');
                     await this.withOverlayRecovery(async () => {
                         await locator.press(action.key, { timeout });
                     });
@@ -354,12 +431,14 @@ export class PlaywrightDriver {
                 case 'hover': {
                     const locator = this.snapshot.resolveLocator(this.page, action.selector);
                     const bounds = await this.captureBounds(locator);
+                    await this.animateCursorToSelector(action.selector, 'hover');
                     await locator.hover({ timeout });
                     return { success: true, bounds };
                 }
                 case 'select': {
                     const locator = this.snapshot.resolveLocator(this.page, action.selector);
                     const bounds = await this.captureBounds(locator);
+                    await this.animateCursorToSelector(action.selector, 'select');
                     await locator.selectOption(action.value, { timeout });
                     return { success: true, bounds };
                 }