tabwright 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tommy D. Rossi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bin.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+import './dist/env-compat.js'
+import './dist/cli.js'

package/dist/a11y-client.js

@@ -0,0 +1,204 @@
+(() => {
+  var __defProp = Object.defineProperty;
+  var __getOwnPropNames = Object.getOwnPropertyNames;
+  var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+  var __hasOwnProp = Object.prototype.hasOwnProperty;
+  function __accessProp(key) {
+    return this[key];
+  }
+  var __toCommonJS = (from) => {
+    var entry = (__moduleCache ??= new WeakMap).get(from), desc;
+    if (entry)
+      return entry;
+    entry = __defProp({}, "__esModule", { value: true });
+    if (from && typeof from === "object" || typeof from === "function") {
+      for (var key of __getOwnPropNames(from))
+        if (!__hasOwnProp.call(entry, key))
+          __defProp(entry, key, {
+            get: __accessProp.bind(from, key),
+            enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+          });
+    }
+    __moduleCache.set(from, entry);
+    return entry;
+  };
+  var __moduleCache;
+  var __returnValue = (v) => v;
+  function __exportSetter(name, newValue) {
+    this[name] = __returnValue.bind(null, newValue);
+  }
+  var __export = (target, all) => {
+    for (var name in all)
+      __defProp(target, name, {
+        get: all[name],
+        enumerable: true,
+        configurable: true,
+        set: __exportSetter.bind(all, name)
+      });
+  };
+
+  // src/a11y-client.ts
+  var exports_a11y_client = {};
+  __export(exports_a11y_client, {
+    hideA11yLabels: () => hideA11yLabels
+  });
+  var LABELS_CONTAINER_ID = "__tabwright_labels__";
+  var LABELS_TIMER_KEY = "__tabwright_labels_timer__";
+  var ROLE_COLORS = {
+    link: ["#FFF785", "#FFC542", "#E3BE23"],
+    button: ["#FFE0B2", "#FFCC80", "#FFB74D"],
+    textbox: ["#FFCDD2", "#EF9A9A", "#E57373"],
+    combobox: ["#F8BBD0", "#F48FB1", "#F06292"],
+    searchbox: ["#F8BBD0", "#F48FB1", "#F06292"],
+    checkbox: ["#C8E6C9", "#A5D6A7", "#81C784"],
+    radio: ["#C8E6C9", "#A5D6A7", "#81C784"],
+    slider: ["#BBDEFB", "#90CAF9", "#64B5F6"],
+    spinbutton: ["#BBDEFB", "#90CAF9", "#64B5F6"],
+    switch: ["#D1C4E9", "#B39DDB", "#9575CD"],
+    menuitem: ["#FFE0B2", "#FFCC80", "#FFB74D"],
+    menuitemcheckbox: ["#FFE0B2", "#FFCC80", "#FFB74D"],
+    menuitemradio: ["#FFE0B2", "#FFCC80", "#FFB74D"],
+    option: ["#FFE0B2", "#FFCC80", "#FFB74D"],
+    tab: ["#FFE0B2", "#FFCC80", "#FFB74D"],
+    treeitem: ["#FFE0B2", "#FFCC80", "#FFB74D"],
+    img: ["#B3E5FC", "#81D4FA", "#4FC3F7"],
+    video: ["#B3E5FC", "#81D4FA", "#4FC3F7"],
+    audio: ["#B3E5FC", "#81D4FA", "#4FC3F7"]
+  };
+  var DEFAULT_COLORS = ["#FFF9C4", "#FFF59D", "#FFEB3B"];
+  function renderA11yLabels(labels) {
+    const doc = document;
+    const win = window;
+    if (win[LABELS_TIMER_KEY]) {
+      win.clearTimeout(win[LABELS_TIMER_KEY]);
+      win[LABELS_TIMER_KEY] = null;
+    }
+    doc.getElementById(LABELS_CONTAINER_ID)?.remove();
+    const container = doc.createElement("div");
+    container.id = LABELS_CONTAINER_ID;
+    container.style.cssText = "position:absolute;left:0;top:0;z-index:2147483647;pointer-events:none;";
+    const style = doc.createElement("style");
+    style.textContent = `
+    .__pw_label__ {
+      position: absolute;
+      font: bold 12px Helvetica, Arial, sans-serif;
+      padding: 1px 4px;
+      border-radius: 3px;
+      color: black;
+      text-shadow: 0 1px 0 rgba(255, 255, 255, 0.6);
+      white-space: nowrap;
+    }
+  `;
+    container.appendChild(style);
+    const svg = doc.createElementNS("http://www.w3.org/2000/svg", "svg");
+    svg.style.cssText = "position:absolute;left:0;top:0;pointer-events:none;overflow:visible;";
+    svg.setAttribute("width", `${doc.documentElement.scrollWidth}`);
+    svg.setAttribute("height", `${doc.documentElement.scrollHeight}`);
+    const defs = doc.createElementNS("http://www.w3.org/2000/svg", "defs");
+    svg.appendChild(defs);
+    const markerCache = {};
+    function getArrowMarkerId(color) {
+      if (markerCache[color]) {
+        return markerCache[color];
+      }
+      const markerId = `arrow-${color.replace("#", "")}`;
+      const marker = doc.createElementNS("http://www.w3.org/2000/svg", "marker");
+      marker.setAttribute("id", markerId);
+      marker.setAttribute("viewBox", "0 0 10 10");
+      marker.setAttribute("refX", "9");
+      marker.setAttribute("refY", "5");
+      marker.setAttribute("markerWidth", "6");
+      marker.setAttribute("markerHeight", "6");
+      marker.setAttribute("orient", "auto-start-reverse");
+      const path = doc.createElementNS("http://www.w3.org/2000/svg", "path");
+      path.setAttribute("d", "M 0 0 L 10 5 L 0 10 z");
+      path.setAttribute("fill", color);
+      marker.appendChild(path);
+      defs.appendChild(marker);
+      markerCache[color] = markerId;
+      return markerId;
+    }
+    container.appendChild(svg);
+    const placedLabels = [];
+    const LABEL_HEIGHT = 17;
+    const LABEL_CHAR_WIDTH = 7;
+    const viewportLeft = win.scrollX;
+    const viewportTop = win.scrollY;
+    const viewportRight = viewportLeft + win.innerWidth;
+    const viewportBottom = viewportTop + win.innerHeight;
+    let count = 0;
+    for (const { ref, role, box } of labels) {
+      const rectLeft = box.x;
+      const rectTop = box.y;
+      const rectRight = rectLeft + box.width;
+      const rectBottom = rectTop + box.height;
+      if (box.width <= 0 || box.height <= 0) {
+        continue;
+      }
+      if (rectRight < viewportLeft || rectLeft > viewportRight || rectBottom < viewportTop || rectTop > viewportBottom) {
+        continue;
+      }
+      const labelWidth = ref.length * LABEL_CHAR_WIDTH + 8;
+      const labelLeft = rectLeft;
+      const labelTop = Math.max(0, rectTop - LABEL_HEIGHT);
+      const labelRect = {
+        left: labelLeft,
+        top: labelTop,
+        right: labelLeft + labelWidth,
+        bottom: labelTop + LABEL_HEIGHT
+      };
+      let overlaps = false;
+      for (const placed of placedLabels) {
+        if (labelRect.left < placed.right && labelRect.right > placed.left && labelRect.top < placed.bottom && labelRect.bottom > placed.top) {
+          overlaps = true;
+          break;
+        }
+      }
+      if (overlaps) {
+        continue;
+      }
+      const [gradTop, gradBottom, border] = ROLE_COLORS[role] || DEFAULT_COLORS;
+      const label = doc.createElement("div");
+      label.className = "__pw_label__";
+      label.textContent = ref;
+      label.style.background = `linear-gradient(to bottom, ${gradTop} 0%, ${gradBottom} 100%)`;
+      label.style.border = `1px solid ${border}`;
+      label.style.left = `${labelLeft}px`;
+      label.style.top = `${labelTop}px`;
+      container.appendChild(label);
+      const line = doc.createElementNS("http://www.w3.org/2000/svg", "line");
+      const labelCenterX = labelLeft + labelWidth / 2;
+      const labelBottomY = labelTop + LABEL_HEIGHT;
+      const elementCenterX = rectLeft + box.width / 2;
+      const elementCenterY = rectTop + box.height / 2;
+      line.setAttribute("x1", `${labelCenterX}`);
+      line.setAttribute("y1", `${labelBottomY}`);
+      line.setAttribute("x2", `${elementCenterX}`);
+      line.setAttribute("y2", `${elementCenterY}`);
+      line.setAttribute("stroke", border);
+      line.setAttribute("stroke-width", "1.5");
+      line.setAttribute("marker-end", `url(#${getArrowMarkerId(border)})`);
+      svg.appendChild(line);
+      placedLabels.push(labelRect);
+      count++;
+    }
+    doc.documentElement.appendChild(container);
+    win[LABELS_TIMER_KEY] = win.setTimeout(() => {
+      doc.getElementById(LABELS_CONTAINER_ID)?.remove();
+      win[LABELS_TIMER_KEY] = null;
+    }, 30000);
+    return count;
+  }
+  function hideA11yLabels() {
+    const win = window;
+    if (win[LABELS_TIMER_KEY]) {
+      win.clearTimeout(win[LABELS_TIMER_KEY]);
+      win[LABELS_TIMER_KEY] = null;
+    }
+    document.getElementById(LABELS_CONTAINER_ID)?.remove();
+  }
+  globalThis.__a11y = {
+    renderA11yLabels,
+    hideA11yLabels
+  };
+})();

package/dist/agent-skills/tabwright/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: tabwright
+description: Control the user own Chrome browser via Tabwright extension with Playwright code snippets in a stateful local js sandbox. Use this over other Playwright MCPs to automate the browser because it connects to the user's existing Chrome. Use this for JS-heavy websites, logged-in browser state, saved browser capabilities, and admin/config lookup tasks where saved capability match/routingHint metadata may apply. ALWAYS load this skill before using any tabwright commands, opening admin/config URLs, or answering how to inspect saved Tabwright capabilities.
+---
+
+## Fast Path: Saved Capability Exact Matches
+
+For concrete user tasks, check saved capability contracts before browser automation. If a capability has `routingHint: "exact-match-direct-run"`, its `match` patterns exactly fit the task, and it is autonomously runnable (`trusted`, read-only, no confirmation), run it directly with the extracted input:
+
+```bash
+tabwright capability run <capability-id> --input-json '<json-input>' --json
+```
+
+Do not search, describe, or open a page first for these exact matches. Do not treat every URL as a direct-run signal; this shortcut only applies when capability metadata says so, and it can also apply to non-URL tasks with exact `match` patterns.
+
+If execution is disallowed and the user only asks what the first step would be, say that you would use the matching capability directly and show the exact `tabwright capability run ...` command.
+
+If the exact-match capability index is not already visible, use one lightweight route check as the first step:
+
+```bash
+tabwright capability route "<task-or-url>" --json
+```
+
+When using route output, run the returned `shellCommand` exactly. Do not infer a shell command from the capability id; capability ids are not shell commands.
+
+Do not use `capability search` or `capability describe` for an exact-match direct-run candidate.
+
+In Codex sandboxed environments, `tabwright capability run ...` writes the capability run log and may write artifacts under `~/.tabwright/capabilities/...`. Run trusted capability commands with escalated/unsandboxed permissions immediately instead of trying once in the sandbox and then retrying. `tabwright capability route ... --json` is metadata-only and can run sandboxed.
+
+Capability-specific usage and display rules belong in that capability's own agent skill, not in this general Tabwright skill.
+
+If a described capability has `requiresConfirmation: true`, stop and obtain explicit user approval for the concrete input and side effect. Only after approval may you run it with `--confirm <capability-id>`. The value must exactly match the capability id, and `--force` never bypasses this gate.
+
+## Creating Saved Capabilities
+
+When an AI is creating or refining a saved capability, put machine-readable behavior in the capability contract and executable behavior in `script.js`. Create a capability-specific agent skill only for high-frequency, exact-match, easy-to-misuse, auth-sensitive, or display-sensitive capabilities.
+
+Use the CLI to scaffold and install, but do not treat generated scaffold text as final prose:
+
+```bash
+tabwright capability skill init <capability-id>
+# edit the generated SKILL.md with the real workflow and display rules
+tabwright capability skill install <capability-id>
+```
+
+`capability skill install` refuses untouched scaffold templates. Simple capabilities usually need only a good contract, not a separate agent skill.
+
+## Sharing Saved Capabilities
+
+When the user asks to package, share, export, or install a saved capability, use the capability package commands directly:
+
+```bash
+tabwright capability pack <capability-id>
+tabwright capability install ./<capability-id>.tgz
+tabwright capability install https://example.com/<capability-id>.tgz
+```
+
+`capability pack` includes only the manifest, entry script, optional README, and optional agent skills. It excludes `secrets.json`, `runs.jsonl`, and `artifacts/`. Shared capabilities always install as `draft`. Do not trust one until its contract and script have been inspected and it has passed a `capability run --force` validation. Authentication must be refreshed from the recipient's own browser. Packaged agent skills are not installed unless the user explicitly passes `--with-agent-skill` or later runs `capability skill install <capability-id>`.
+
+## Replay-to-Capability Handoff
+
+Turn a saved user demonstration into a capability through the CLI contract:
+
+```bash
+tabwright replay list --limit 10 --json
+tabwright replay index <replay-id> --json
+tabwright replay make <replay-id> <capability-id> --force --goal '<goal>' --json
+```
+
+`replay index --json` is compact by default; add `--full` only when complete page text and interactive-element evidence is needed. `replay make` returns `status: "compiled"` after writing a draft. An unsupported workflow returns `status: "needs_ai"`, writes no fake capability, and supplies exact `next.inspectCommand` and `next.createCommand` commands. Follow that handoff instead of inventing a workflow.
+
+Generated workflows are draft browser writes. Inspect them and obtain explicit user approval before running the exact returned command, which must include `--browser user --force --confirm <capability-id> --json`:
+
+```bash
+tabwright capability run <capability-id> --browser user --force --confirm <capability-id> --input-json '<json-input>' --json
+```
+
+## Browser Core Protocol
+
+This skill contains the required core protocol. Do not load the 17k-token extended reference before every browser task. Query it only when the task needs a specialized API:
+
+```bash
+# macOS/Linux
+tabwright skill | rg -n -C 20 'working with pages|snapshot|iframe'
+tabwright skill | rg -n -C 20 'network requests|debugger|live edit'
+# Windows PowerShell
+tabwright skill | Select-String -Pattern 'working with pages|snapshot|iframe' -Context 20,20
+```
+
+Follow this order for browser work:
+
+1. Run `tabwright doctor --json` when connection state is unclear, and follow its exact `next` action.
+2. Create a new session for this task. Never reuse an existing session unless the user explicitly handed it to you.
+3. Create and retain your own page in `state`. Pages are shared across sessions, but `state` is not.
+4. Navigate, inspect logs, then snapshot. Use snapshot search when full output would be large.
+5. Copy a role/text/test-id locator from current evidence. Never guess a fixed `aria-ref` from examples or an older snapshot.
+6. Perform the smallest action, then verify the resulting URL, visible state, response, or logs.
+7. Never call `browser.close()` or `context.close()`. Close only pages you created, and delete your task session when finished.
+
+In sandboxed agent environments, browser/relay commands need immediate elevated or unsandboxed execution because they connect to localhost and may update session state. Metadata-only `capability route/search/describe` commands can remain sandboxed.
+
+Use single quotes around `-e` code so the shell does not expand `$`, backticks, or backslashes. Use double quotes for JavaScript strings inside.
+
+## Minimal Browser Example
+
+```bash
+tabwright session new
+SESSION_ID=2 # replace 2 with the new ID printed above
+tabwright -s "$SESSION_ID" -e 'state.page = await context.newPage(); await state.page.goto("https://example.com")'
+tabwright -s "$SESSION_ID" -e 'console.log(await getLatestLogs({ page: state.page }))'
+tabwright -s "$SESSION_ID" -e 'console.log(await snapshot({ page: state.page, search: /learn|more/i }))'
+tabwright -s "$SESSION_ID" -e 'console.log(await state.page.getByRole("link", { name: "Learn more" }).getAttribute("href"))'
+```
+
+If `tabwright` is not found, use `npx tabwright@latest` or `bunx tabwright@latest`.
+
+If the relay, extension, enabled tab, or session state is unclear, run `tabwright doctor --json` and follow its returned `next` step instead of guessing recovery commands.
+
+`tabwright session new` automatically selects a single connected extension. With multiple profiles, it waits briefly for reconnects to settle and auto-selects only when exactly one has enabled tabs; otherwise choose one of the reported browser keys with `--browser <key>`. A restarted relay is ready after it reports the current or a newer compatible Tabwright package version.

package/dist/aria-snapshot.d.ts

@@ -0,0 +1,262 @@
+import type { Page, Locator, ElementHandle, Frame, FrameLocator } from '@xmorse/playwright-core';
+import type { Protocol } from 'devtools-protocol';
+import type { ICDPSession } from './cdp-session.js';
+export type SnapshotFormat = 'raw';
+export declare const DEFAULT_SNAPSHOT_FORMAT: SnapshotFormat;
+export interface AriaRef {
+    role: string;
+    name: string;
+    ref: string;
+    shortRef: string;
+    backendNodeId?: Protocol.DOM.BackendNodeId;
+}
+export type AriaSnapshotNode = {
+    role: string;
+    name: string;
+    locator?: string;
+    ref?: string;
+    shortRef?: string;
+    backendNodeId?: Protocol.DOM.BackendNodeId;
+    children: AriaSnapshotNode[];
+};
+export interface ScreenshotResult {
+    path: string;
+    base64: string;
+    mimeType: 'image/png';
+    snapshot: string;
+    labelCount: number;
+}
+/**
+ * LLM-optimal max dimension. Claude auto-resizes images larger than 1568px
+ * on any edge, adding latency. Token cost: (width * height) / 750.
+ */
+export declare const LLM_MAX_DIMENSION = 1568;
+export interface ResizeImageOptions {
+    /** Input: file path or Buffer */
+    input: string | Buffer;
+    /** Max pixels on longest edge. Default 1568 (Claude-optimal).
+     *  Ignored if explicit width/height provided. */
+    maxDimension?: number;
+    /** Explicit target width in px (aspect ratio preserved unless both width+height set) */
+    width?: number;
+    /** Explicit target height in px */
+    height?: number;
+    /** How to fit when both width+height specified. Default 'inside' (preserve aspect ratio, no crop) */
+    fit?: 'inside' | 'cover' | 'contain' | 'fill';
+    /** JPEG quality 1-100. Default 80 */
+    quality?: number;
+    /** Output format. Default 'jpeg'. Use 'png' for lossless output (e.g. Kitty Graphics). */
+    format?: 'jpeg' | 'png';
+    /** Output file path. Defaults to overwriting the input file (when input is a path) */
+    output?: string;
+}
+export interface ResizeImageResult {
+    buffer: Buffer;
+    mimeType: 'image/png' | 'image/jpeg';
+    /** Only set if output path was provided */
+    path?: string;
+}
+/**
+ * Resize an image using sharp. Useful for shrinking screenshots before reading
+ * them back into context so they consume fewer tokens.
+ *
+ * Default behavior (no width/height): fits within 1568×1568px, preserving
+ * aspect ratio, never upscales. This is optimal for Claude vision.
+ *
+ * Explicit width/height: resizes to those dimensions using the fit strategy.
+ */
+export declare function resizeImageForAgent(options: ResizeImageOptions): Promise<ResizeImageResult>;
+export interface AriaSnapshotResult {
+    snapshot: string;
+    tree: AriaSnapshotNode[];
+    refs: AriaRef[];
+    refToElement: Map<string, {
+        role: string;
+        name: string;
+        shortRef: string;
+    }>;
+    refToSelector: Map<string, string>;
+    /**
+     * Get a CSS selector for a ref. Use with page.locator().
+     * For stable test IDs, returns [data-testid="..."] or [id="..."]
+     * For fallback refs, returns a role-based selector.
+     */
+    getSelectorForRef: (ref: string) => string | null;
+    getRefsForLocators: (locators: Array<Locator | ElementHandle>) => Promise<Array<AriaRef | null>>;
+    getRefForLocator: (locator: Locator | ElementHandle) => Promise<AriaRef | null>;
+    getRefStringForLocator: (locator: Locator | ElementHandle) => Promise<string | null>;
+}
+export declare function buildShortRefMap({ refs }: {
+    refs: Array<{
+        ref: string;
+    }>;
+}): Map<string, string>;
+type DomNodeInfo = {
+    nodeId: Protocol.DOM.NodeId;
+    parentId?: Protocol.DOM.NodeId;
+    backendNodeId: Protocol.DOM.BackendNodeId;
+    nodeName: string;
+    attributes: Map<string, string>;
+};
+export type SnapshotLine = {
+    text: string;
+    baseLocator?: string;
+    hasChildren?: boolean;
+    role?: string;
+    name?: string;
+    indent?: number;
+};
+export type SnapshotNode = {
+    role: string;
+    name: string;
+    baseLocator?: string;
+    ref?: string;
+    backendNodeId?: Protocol.DOM.BackendNodeId;
+    indentOffset?: number;
+    ignored?: boolean;
+    children: SnapshotNode[];
+};
+export declare function buildSnapshotLines(nodes: SnapshotNode[], indent?: number): SnapshotLine[];
+export declare function buildRawSnapshotTree(options: {
+    nodeId: Protocol.Accessibility.AXNodeId;
+    axById: Map<Protocol.Accessibility.AXNodeId, Protocol.Accessibility.AXNode>;
+    isNodeInScope: (node: Protocol.Accessibility.AXNode) => boolean;
+}): SnapshotNode | null;
+export declare function filterInteractiveSnapshotTree(options: {
+    node: SnapshotNode;
+    ancestorNames: string[];
+    labelContext: boolean;
+    refFilter?: (entry: {
+        role: string;
+        name: string;
+    }) => boolean;
+    domByBackendId: Map<Protocol.DOM.BackendNodeId, DomNodeInfo>;
+    promotedContentEditableIds?: Set<Protocol.DOM.BackendNodeId>;
+    createRefForNode: (options: {
+        backendNodeId?: Protocol.DOM.BackendNodeId;
+        role: string;
+        name: string;
+    }) => string | null;
+}): {
+    nodes: SnapshotNode[];
+    names: Set<string>;
+};
+export declare function filterFullSnapshotTree(options: {
+    node: SnapshotNode;
+    ancestorNames: string[];
+    refFilter?: (entry: {
+        role: string;
+        name: string;
+    }) => boolean;
+    domByBackendId: Map<Protocol.DOM.BackendNodeId, DomNodeInfo>;
+    promotedContentEditableIds?: Set<Protocol.DOM.BackendNodeId>;
+    createRefForNode: (options: {
+        backendNodeId?: Protocol.DOM.BackendNodeId;
+        role: string;
+        name: string;
+    }) => string | null;
+}): {
+    nodes: SnapshotNode[];
+    names: Set<string>;
+};
+export declare function finalizeSnapshotOutput(lines: SnapshotLine[], nodes: SnapshotNode[], shortRefMap: Map<string, string>): {
+    snapshot: string;
+    tree: AriaSnapshotNode[];
+};
+/**
+ * Get an accessibility snapshot with utilities to look up refs for elements.
+ * Uses the browser accessibility tree (CDP) and maps nodes to DOM attributes.
+ *
+ * Refs are generated from stable test IDs when available (data-testid, data-test-id, etc.)
+ * or fall back to e1, e2, e3...
+ *
+ * @param page - Playwright page
+ * @param locator - Optional locator to scope the snapshot to a subtree
+ * @param refFilter - Optional filter for which elements get refs
+ *
+ * @example
+ * ```ts
+ * const { snapshot, getSelectorForRef } = await getAriaSnapshot({ page })
+ * // Snapshot shows locators like [id="submit-btn"] or role=button[name="Submit"]
+ * const selector = getSelectorForRef('submit-btn')
+ * await page.locator(selector).click()
+ * ```
+ */
+export declare function getAriaSnapshot({ page, frame, locator, refFilter, interactiveOnly, cdp, }: {
+    page: Page;
+    frame?: Frame | FrameLocator;
+    locator?: Locator;
+    refFilter?: (info: {
+        role: string;
+        name: string;
+    }) => boolean;
+    interactiveOnly?: boolean;
+    cdp?: ICDPSession;
+}): Promise<AriaSnapshotResult>;
+/**
+ * Show Vimium-style labels on interactive elements.
+ * Labels are colored badges positioned above each element showing the ref.
+ * Use with screenshots so agents can see which elements are interactive.
+ *
+ * Labels auto-hide after 30 seconds to prevent stale labels.
+ * Call this function again if the page HTML changes to get fresh labels.
+ *
+ * @param page - Playwright page
+ * @param locator - Optional locator to scope labels to a subtree
+ * @param interactiveOnly - Only show labels for interactive elements (default: true)
+ *
+ * @example
+ * ```ts
+ * const { snapshot, labelCount } = await showAriaRefLabels({ page })
+ * await page.screenshot({ path: '/tmp/screenshot.png' })
+ * // Agent sees [submit-btn] label on "Submit" button
+ * await page.locator('[data-testid="submit-btn"]').click()
+ * ```
+ */
+export declare function showAriaRefLabels({ page, locator, interactiveOnly, logger, }: {
+    page: Page;
+    locator?: Locator;
+    interactiveOnly?: boolean;
+    logger?: {
+        info?: (...args: unknown[]) => void;
+        error?: (...args: unknown[]) => void;
+    };
+}): Promise<{
+    snapshot: string;
+    labelCount: number;
+}>;
+/**
+ * Remove all aria ref labels from the page.
+ */
+export declare function hideAriaRefLabels({ page }: {
+    page: Page;
+}): Promise<void>;
+/**
+ * Take a screenshot with accessibility labels overlaid on interactive elements.
+ * Shows Vimium-style labels, captures the screenshot, then removes the labels.
+ * The screenshot is automatically included in the MCP response.
+ *
+ * @param page - Playwright page
+ * @param locator - Optional locator to scope labels to a subtree
+ * @param collector - Array to collect screenshots (passed by MCP execute tool)
+ *
+ * @example
+ * ```ts
+ * await screenshotWithAccessibilityLabels({ page })
+ * // Screenshot is automatically included in the MCP response
+ * // Use ref from the snapshot to interact with elements
+ * await page.locator('[data-testid="submit-btn"]').click()
+ * ```
+ */
+export declare function screenshotWithAccessibilityLabels({ page, locator, interactiveOnly, collector, logger, }: {
+    page: Page;
+    locator?: Locator;
+    interactiveOnly?: boolean;
+    collector: ScreenshotResult[];
+    logger?: {
+        info?: (...args: unknown[]) => void;
+        error?: (...args: unknown[]) => void;
+    };
+}): Promise<void>;
+export { getAriaSnapshot as getAriaSnapshotWithRefs };
+//# sourceMappingURL=aria-snapshot.d.ts.map

package/dist/aria-snapshot.d.ts.map

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