@real-a11y-dev/mcp 0.1.0-beta.0

package/dist/chunk-EXVRX5JP.js

@@ -0,0 +1,401 @@
+import { readFileSync } from 'fs';
+import { createRequire } from 'module';
+import { join, dirname } from 'path';
+
+// src/browser.ts
+function bundlePath() {
+  const require2 = createRequire(import.meta.url);
+  const testingEntry = require2.resolve("@real-a11y-dev/testing");
+  return join(dirname(testingEntry), "page-bundle.iife.global.js");
+}
+var cachedBundle;
+function readBundle() {
+  if (!cachedBundle) {
+    try {
+      cachedBundle = readFileSync(bundlePath(), "utf8");
+    } catch {
+      throw new Error(
+        "Real A11y extraction bundle is missing \u2014 reinstall dependencies (is @real-a11y-dev/testing installed?)."
+      );
+    }
+  }
+  return cachedBundle;
+}
+function assertOpenableUrl(url) {
+  let scheme;
+  try {
+    scheme = new URL(url).protocol.replace(/:$/, "").toLowerCase();
+  } catch {
+    throw new Error(`Not a valid absolute URL: ${JSON.stringify(url)}`);
+  }
+  if (scheme === "http" || scheme === "https" || scheme === "data") return;
+  if (scheme === "file" && process.env.REAL_A11Y_MCP_ALLOW_FILE === "1") return;
+  throw new Error(
+    `Refusing to open a ${scheme}: URL \u2014 only http(s) (and data:) are allowed` + (scheme === "file" ? " (set REAL_A11Y_MCP_ALLOW_FILE=1 to permit file://)." : ".")
+  );
+}
+var NATIVE_DROP = /* @__PURE__ */ new Set([
+  "StaticText",
+  "InlineTextBox",
+  "LineBreak",
+  "LabelText",
+  "generic",
+  "none",
+  "presentation",
+  "RootWebArea"
+]);
+var NATIVE_ROLE_MAP = { image: "img" };
+function serializeNativeAX(nodes) {
+  const byId = new Map(nodes.map((n) => [n.nodeId, n]));
+  const roots = nodes.filter((n) => !n.parentId);
+  const treeLines = [];
+  const pairs = [];
+  const walk = (node, depth) => {
+    const role = node.role?.value ?? "";
+    const drop = node.ignored || NATIVE_DROP.has(role);
+    let childDepth = depth;
+    if (!drop && role) {
+      const mapped = NATIVE_ROLE_MAP[role] ?? role;
+      const name = (node.name?.value ?? "").replace(/\s+/g, " ").trim();
+      const pair = name ? `${mapped} "${name}"` : mapped;
+      treeLines.push(`${"  ".repeat(depth)}${pair}`);
+      pairs.push(pair);
+      childDepth = depth + 1;
+    }
+    for (const cid of node.childIds ?? []) {
+      const child = byId.get(cid);
+      if (child) walk(child, childDepth);
+    }
+  };
+  for (const root of roots) walk(root, 0);
+  return { tree: treeLines.join("\n"), pairs };
+}
+var cachedExpr;
+function bundleExpression() {
+  if (!cachedExpr) {
+    cachedExpr = `(function(){
+${readBundle()}
+;globalThis.__realA11y__=__realA11y__;})()`;
+  }
+  return cachedExpr;
+}
+var BrowserSession = class {
+  constructor(opts = {}) {
+    this.opts = opts;
+    if (opts.storageState && opts.cdpEndpoint) {
+      throw new Error(
+        "storageState is for launched browsers \u2014 a CDP connection reuses the running browser's own session, so the two can't be combined."
+      );
+    }
+  }
+  opts;
+  browser;
+  context;
+  page;
+  /** Signature of the current context's emulation, to detect device changes. */
+  emulationKey = "";
+  /** Over CDP: whether we created `page` (so `close()` only closes our tab). */
+  ownsPage = false;
+  /** Serializes every operation so concurrent tool calls can't race the page. */
+  queue = Promise.resolve();
+  /** Origins allowed for extraction, or null when unrestricted. */
+  get allowedOrigins() {
+    const list = this.opts.allowedOrigins;
+    return list && list.length ? new Set(list) : null;
+  }
+  /**
+   * Run `fn` after any in-flight operation. MCP clients dispatch tool calls
+   * concurrently, but all tools share one mutable `page`, so we single-flight.
+   */
+  run(fn) {
+    const result = this.queue.then(fn, fn);
+    this.queue = result.then(
+      () => void 0,
+      () => void 0
+    );
+    return result;
+  }
+  /** Navigate to `url`, settle, then confirm the bundle initialized. */
+  async open(url, options = {}) {
+    return this.run(async () => {
+      assertOpenableUrl(url);
+      const {
+        waitUntil = "load",
+        settleMs = 0,
+        device,
+        viewport,
+        timeoutMs
+      } = options;
+      const page = await this.ensurePage({ device, viewport });
+      try {
+        await page.goto(url, {
+          waitUntil,
+          ...timeoutMs != null ? { timeout: timeoutMs } : {}
+        });
+      } catch (err) {
+        const isTimeout = err instanceof Error && err.name === "TimeoutError";
+        if (!(isTimeout && waitUntil === "networkidle")) throw err;
+      }
+      if (settleMs > 0) await page.waitForTimeout(settleMs);
+      if (page.url() === "about:blank") {
+        throw new Error(
+          `Navigation to ${url} did not complete (still on about:blank). Try waitUntil:"load" or a larger timeoutMs.`
+        );
+      }
+      this.assertAllowedOrigin(page.url());
+      await this.injectBundle(page);
+      await this.verifyReady(page);
+      return { title: await page.title(), url: page.url() };
+    });
+  }
+  /**
+   * Run a named export from the injected bundle against a root selector.
+   * Re-injects first if a navigation wiped the global.
+   */
+  async call(fn, rootSelector, args = []) {
+    return this.run(async () => {
+      const page = this.requirePage();
+      await this.ensureInjected(page);
+      return page.evaluate(
+        ({ fn: fn2, selector, args: args2 }) => {
+          const ra = globalThis.__realA11y__;
+          if (!ra) throw new Error("__realA11y__ is not present on the page.");
+          if (typeof ra[fn2] !== "function") {
+            throw new Error(
+              `Real A11y bundle has no "${fn2}" \u2014 the installed @real-a11y-dev/testing is too old for this MCP server; upgrade it.`
+            );
+          }
+          let root;
+          try {
+            root = document.querySelector(selector);
+          } catch {
+            throw new Error(`Invalid rootSelector: "${selector}".`);
+          }
+          if (!root) {
+            if (selector === "body" && document.body) root = document.body;
+            else {
+              throw new Error(
+                `rootSelector "${selector}" matched no element on the page.`
+              );
+            }
+          }
+          return ra[fn2](root, ...args2);
+        },
+        { fn, selector: rootSelector, args }
+      );
+    });
+  }
+  /**
+   * Extract the a11y tree **once** and derive all four views from it inside a
+   * single `page.evaluate`, so findings / tree / outline / tab order always
+   * describe the same instant — no cross-call drift on a moving page.
+   */
+  async snapshot(rootSelector, options = {}) {
+    return this.run(async () => {
+      const page = this.requirePage();
+      await this.ensureInjected(page);
+      return page.evaluate(
+        ({ selector, rules, includeGeneric }) => {
+          const ra = globalThis.__realA11y__;
+          if (!ra || typeof ra.extractA11yTree !== "function") {
+            throw new Error(
+              "Real A11y bundle missing/too old \u2014 upgrade @real-a11y-dev/testing."
+            );
+          }
+          let el;
+          try {
+            el = document.querySelector(selector);
+          } catch {
+            throw new Error(`Invalid rootSelector: "${selector}".`);
+          }
+          if (!el) {
+            if (selector === "body" && document.body) el = document.body;
+            else {
+              throw new Error(
+                `rootSelector "${selector}" matched no element on the page.`
+              );
+            }
+          }
+          const tree = ra.extractA11yTree(el);
+          return {
+            findings: ra.collectFindings(
+              tree,
+              rules && rules.length ? rules : void 0
+            ),
+            tree: ra.auditSnapshot(tree, { includeGeneric }),
+            outline: ra.outlineSnapshot(tree),
+            tabOrder: ra.tabSequenceSnapshot(tree)
+          };
+        },
+        {
+          selector: rootSelector,
+          rules: options.rules ?? null,
+          includeGeneric: options.includeGeneric ?? false
+        }
+      );
+    });
+  }
+  /**
+   * Chromium's own accessibility tree, straight from Blink via the CDP
+   * `Accessibility` domain — the authoritative computation, not our
+   * reimplementation. Used to cross-check custom-engine fidelity.
+   */
+  async nativeAX() {
+    return this.run(async () => {
+      const page = this.requirePage();
+      const client = await page.context().newCDPSession(page);
+      try {
+        await client.send("Accessibility.enable");
+        const { nodes } = await client.send(
+          "Accessibility.getFullAXTree"
+        );
+        return serializeNativeAX(nodes);
+      } finally {
+        await client.detach().catch(() => {
+        });
+      }
+    });
+  }
+  /**
+   * Capture the current context's storage state (cookies + origin storage) —
+   * the "save" step behind the CLI's `login` helper. Returns the plain object;
+   * the caller owns serialization + file writing (permissions, atomicity).
+   * `indexedDB` is caller-gated: it's a no-op on Playwright < 1.51, so the CLI
+   * passes it only when the resolved version supports it.
+   */
+  async captureStorageState(options = {}) {
+    return this.run(async () => {
+      const context = this.context;
+      if (!context) {
+        throw new Error("No browser context is open \u2014 call open() first.");
+      }
+      return context.storageState(options.indexedDB ? { indexedDB: true } : {});
+    });
+  }
+  async close() {
+    return this.run(async () => {
+      if (this.opts.cdpEndpoint) {
+        if (this.ownsPage) await this.page?.close().catch(() => {
+        });
+        await this.browser?.close().catch(() => {
+        });
+      } else {
+        await this.context?.close().catch(() => {
+        });
+        await this.browser?.close().catch(() => {
+        });
+      }
+      this.browser = void 0;
+      this.context = void 0;
+      this.page = void 0;
+      this.ownsPage = false;
+      this.emulationKey = "";
+    });
+  }
+  hasPage() {
+    return this.page !== void 0;
+  }
+  // ── internals ────────────────────────────────────────────────────────────
+  requirePage() {
+    if (!this.page) {
+      throw new Error("No page is open. Call the open_page tool first.");
+    }
+    return this.page;
+  }
+  /** Refuse extraction when the final URL's origin isn't allowlisted. */
+  assertAllowedOrigin(finalUrl) {
+    const allowed = this.allowedOrigins;
+    if (!allowed) return;
+    let origin;
+    try {
+      origin = new URL(finalUrl).origin;
+    } catch {
+      throw new Error(`Refusing to audit an unparseable URL: ${finalUrl}`);
+    }
+    if (!allowed.has(origin)) {
+      throw new Error(
+        `Refusing to audit ${origin}: not an allowed audit origin under an authenticated session (a redirect may have left the intended site).`
+      );
+    }
+  }
+  async ensurePage(emu = {}) {
+    const { chromium, devices } = await import('playwright');
+    if (this.opts.cdpEndpoint) {
+      if (emu.device || emu.viewport) {
+        throw new Error(
+          "Device / viewport emulation is not supported over a CDP connection \u2014 it reuses the running browser's own context."
+        );
+      }
+      if (this.page && !this.page.isClosed()) return this.page;
+      if (!this.browser || !this.browser.isConnected()) {
+        this.browser = await chromium.connectOverCDP(this.opts.cdpEndpoint);
+      }
+      this.context = this.browser.contexts()[0] ?? await this.browser.newContext();
+      this.page = await this.context.newPage();
+      this.ownsPage = true;
+      return this.page;
+    }
+    const key = JSON.stringify({
+      device: emu.device ?? null,
+      viewport: emu.viewport ?? null
+    });
+    if (this.page && !this.page.isClosed() && key === this.emulationKey) {
+      return this.page;
+    }
+    if (!this.browser || !this.browser.isConnected()) {
+      this.browser = await chromium.launch({
+        headless: this.opts.headless ?? true,
+        ...this.opts.proxy ? { proxy: this.opts.proxy } : {}
+      });
+    }
+    let ctxOpts = {};
+    if (emu.device) {
+      const descriptor = devices[emu.device];
+      if (!descriptor) {
+        throw new Error(
+          `Unknown device "${emu.device}". Use a Playwright device name such as "iPhone 13", "Pixel 7", or "iPad Pro 11".`
+        );
+      }
+      ctxOpts = descriptor;
+    }
+    if (emu.viewport) ctxOpts = { ...ctxOpts, viewport: emu.viewport };
+    if (this.opts.storageState) {
+      ctxOpts = { ...ctxOpts, storageState: this.opts.storageState };
+    }
+    if (this.context) {
+      await this.context.close().catch(() => {
+      });
+      this.context = void 0;
+      this.page = void 0;
+    }
+    this.context = await this.browser.newContext(ctxOpts);
+    this.page = await this.context.newPage();
+    this.emulationKey = key;
+    return this.page;
+  }
+  /** Evaluate the bundle in the page (CSP / Trusted-Types-safe via CDP). */
+  async injectBundle(page) {
+    await page.evaluate(bundleExpression());
+  }
+  /** (Re)inject the bundle if a navigation wiped the global. */
+  async ensureInjected(page) {
+    if (!await this.isReady(page)) await this.injectBundle(page);
+  }
+  /** Confirm the bundle initialized; throw a clear error if not. */
+  async verifyReady(page) {
+    if (!await this.isReady(page)) {
+      throw new Error(
+        "Real A11y extraction bundle did not initialize on this page \u2014 a strict Content-Security-Policy may be blocking script evaluation here."
+      );
+    }
+  }
+  isReady(page) {
+    return page.evaluate(
+      () => typeof globalThis.__realA11y__ === "object"
+    );
+  }
+};
+
+export { BrowserSession, assertOpenableUrl };
+//# sourceMappingURL=chunk-EXVRX5JP.js.map
+//# sourceMappingURL=chunk-EXVRX5JP.js.map

package/dist/chunk-EXVRX5JP.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/browser.ts"],"names":["require","fn","args"],"mappings":"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","file":"chunk-EXVRX5JP.js","sourcesContent":["/**\n * Browser session for the MCP server.\n *\n * Mirrors the architecture of `@real-a11y-dev/testing/playwright`: drive a real\n * browser with Playwright, inject the pre-built IIFE page-bundle (which sets\n * `window.__realA11y__`), and route each a11y query through `page.evaluate()`.\n *\n * A real browser is required — the extraction engine depends on\n * `getComputedStyle`/layout to decide what is exposed to assistive tech, which\n * a serverside jsdom cannot faithfully reproduce.\n */\n\nimport { readFileSync } from \"node:fs\";\nimport { createRequire } from \"node:module\";\nimport { dirname, join } from \"node:path\";\n\nimport type { Finding } from \"@real-a11y-dev/testing\";\nimport type {\n  Browser,\n  BrowserContext,\n  BrowserContextOptions,\n  Page,\n} from \"playwright\";\n\n/** Resolve the testing package's injected page-bundle from node_modules. */\nfunction bundlePath(): string {\n  const require = createRequire(import.meta.url);\n  // Resolves to @real-a11y-dev/testing/dist/index.* — the bundle sits beside it.\n  const testingEntry = require.resolve(\"@real-a11y-dev/testing\");\n  return join(dirname(testingEntry), \"page-bundle.iife.global.js\");\n}\n\nlet cachedBundle: string | undefined;\nfunction readBundle(): string {\n  if (!cachedBundle) {\n    try {\n      cachedBundle = readFileSync(bundlePath(), \"utf8\");\n    } catch {\n      // Don't leak the absolute local path into tool output.\n      throw new Error(\n        \"Real A11y extraction bundle is missing — reinstall dependencies (is @real-a11y-dev/testing installed?).\",\n      );\n    }\n  }\n  return cachedBundle;\n}\n\n/**\n * Reject non-web URLs before navigating. `file://` is a local-file exfiltration\n * primitive for an LLM-driven server (open `file:///…/.env`, then read the DOM\n * back), so it's blocked unless `REAL_A11Y_MCP_ALLOW_FILE=1`. `data:` is allowed\n * (it's caller-supplied inline content, not a filesystem read).\n */\nexport function assertOpenableUrl(url: string): void {\n  let scheme: string;\n  try {\n    scheme = new URL(url).protocol.replace(/:$/, \"\").toLowerCase();\n  } catch {\n    throw new Error(`Not a valid absolute URL: ${JSON.stringify(url)}`);\n  }\n  if (scheme === \"http\" || scheme === \"https\" || scheme === \"data\") return;\n  if (scheme === \"file\" && process.env.REAL_A11Y_MCP_ALLOW_FILE === \"1\") return;\n  throw new Error(\n    `Refusing to open a ${scheme}: URL — only http(s) (and data:) are allowed` +\n      (scheme === \"file\"\n        ? \" (set REAL_A11Y_MCP_ALLOW_FILE=1 to permit file://).\"\n        : \".\"),\n  );\n}\n\n/** A subset of a Chromium CDP `Accessibility.AXNode`. */\ninterface AXNode {\n  nodeId: string;\n  parentId?: string;\n  childIds?: string[];\n  role?: { value?: string };\n  name?: { value?: string };\n  ignored?: boolean;\n}\n\n// Native roles that are structural noise vs. our custom tree: text runs and\n// generic wrappers the custom serializer collapses into names / drops.\nconst NATIVE_DROP = new Set([\n  \"StaticText\",\n  \"InlineTextBox\",\n  \"LineBreak\",\n  \"LabelText\",\n  \"generic\",\n  \"none\",\n  \"presentation\",\n  \"RootWebArea\",\n]);\n// Blink AX role → the ARIA role our custom tree uses, where they differ.\nconst NATIVE_ROLE_MAP: Record<string, string> = { image: \"img\" };\n\n/**\n * Reconstruct Chromium's native accessibility tree from a flat `getFullAXTree`\n * node list and serialize it in the same `role \"name\"` shape our custom tree\n * uses — so the two are comparable. Returns the indented tree plus a flat list\n * of role+name pairs (for order/indent-insensitive diffing).\n */\nfunction serializeNativeAX(nodes: AXNode[]): { tree: string; pairs: string[] } {\n  const byId = new Map(nodes.map((n) => [n.nodeId, n]));\n  const roots = nodes.filter((n) => !n.parentId);\n  const treeLines: string[] = [];\n  const pairs: string[] = [];\n\n  const walk = (node: AXNode, depth: number): void => {\n    const role = node.role?.value ?? \"\";\n    const drop = node.ignored || NATIVE_DROP.has(role);\n    let childDepth = depth;\n    if (!drop && role) {\n      const mapped = NATIVE_ROLE_MAP[role] ?? role;\n      const name = (node.name?.value ?? \"\").replace(/\\s+/g, \" \").trim();\n      const pair = name ? `${mapped} \"${name}\"` : mapped;\n      treeLines.push(`${\"  \".repeat(depth)}${pair}`);\n      pairs.push(pair);\n      childDepth = depth + 1;\n    }\n    for (const cid of node.childIds ?? []) {\n      const child = byId.get(cid);\n      if (child) walk(child, childDepth);\n    }\n  };\n\n  for (const root of roots) walk(root, 0);\n  return { tree: treeLines.join(\"\\n\"), pairs };\n}\n\nlet cachedExpr: string | undefined;\n/**\n * The IIFE bundle wrapped as a single self-executing expression that hoists its\n * global (`var __realA11y__ = …`) onto `globalThis`.\n *\n * We inject this via `page.evaluate`, which runs through the CDP runtime and is\n * **not** subject to the page's CSP or Trusted Types. `addScriptTag` (sets\n * `<script>.text`) is blocked by `require-trusted-types-for 'script'`, and\n * `addInitScript` is CSP-gated too — both fail on YouTube, Google, GitHub, and\n * many enterprise apps. Evaluating the source directly is the robust path.\n */\nfunction bundleExpression(): string {\n  if (!cachedExpr) {\n    cachedExpr = `(function(){\\n${readBundle()}\\n;globalThis.__realA11y__=__realA11y__;})()`;\n  }\n  return cachedExpr;\n}\n\nexport interface BrowserSessionOptions {\n  /** Launch headless (default true). Ignored when `cdpEndpoint` is set. */\n  headless?: boolean;\n  /**\n   * Attach to a user's already-running Chrome over the DevTools protocol\n   * instead of launching a fresh browser (e.g. \"http://localhost:9222\").\n   */\n  cdpEndpoint?: string;\n  /**\n   * Network proxy for the launched browser. Chromium does not honor\n   * `HTTP_PROXY`/`HTTPS_PROXY` env vars on its own, so callers on corporate\n   * networks must pass one explicitly. Ignored when `cdpEndpoint` is set (the\n   * running browser already has its own network config).\n   */\n  proxy?: {\n    server: string;\n    bypass?: string;\n    username?: string;\n    password?: string;\n  };\n  /**\n   * Path to a Playwright storage-state JSON (cookies + origin storage), loaded\n   * into every **launched** context so pages open already authenticated. The\n   * user creates it out-of-band (e.g. the CLI's `login` helper); this is never\n   * an agent-supplied parameter. Applied at the single `newContext()` site, so\n   * it survives device-emulation context rebuilds. Rejected together with\n   * `cdpEndpoint` (a CDP connection reuses the running browser's own session).\n   */\n  storageState?: string;\n  /**\n   * When set (non-empty), extraction is refused unless the page's **final**\n   * origin (after redirects) is in this allowlist. This is the control that\n   * stops a redirect from an intended target to a different origin from\n   * silently auditing an authenticated page the operator never asked for.\n   * Empty/absent ⇒ no origin restriction (anonymous audits follow redirects\n   * freely — logged-out content isn't sensitive). Origins are compared as\n   * `new URL(...).origin` strings.\n   */\n  allowedOrigins?: string[];\n}\n\n/** Navigation / settle options for {@link A11ySession.open}. */\nexport interface OpenOptions {\n  /**\n   * Playwright navigation wait state. `\"networkidle\"` waits until the network\n   * has been quiet for 500ms — the most reliable \"the SPA finished rendering\"\n   * signal, at the cost of latency. Default `\"load\"`.\n   */\n  waitUntil?: \"load\" | \"domcontentloaded\" | \"networkidle\" | \"commit\";\n  /**\n   * Extra fixed settle time (ms) after the wait state, to let late-firing JS\n   * (async content, consent dialogs) reach a stable state before extraction.\n   * Default 0.\n   */\n  settleMs?: number;\n  /**\n   * Emulate a device by Playwright device name — e.g. `\"iPhone 13\"`,\n   * `\"Pixel 7\"`, `\"iPad Pro 11\"`. Sets viewport, user-agent, touch, and device\n   * scale so the extracted tree reflects the **mobile/tablet** layout, not\n   * desktop. Changing device between calls rebuilds the browser context.\n   * Not supported over a `cdpEndpoint` (reuses the running browser's context).\n   */\n  device?: string;\n  /**\n   * Explicit viewport override, e.g. `{ width: 375, height: 812 }`. Layered on\n   * top of `device` when both are given.\n   */\n  viewport?: { width: number; height: number };\n  /** Navigation timeout in ms. Default is Playwright's 30s. */\n  timeoutMs?: number;\n}\n\n/** Options for a single-extraction {@link A11ySession.snapshot}. */\nexport interface SnapshotOptions {\n  /** Rules to run for `findings`. Omit to run all. */\n  rules?: string[];\n  /** Include generic container nodes in `tree`. Default false. */\n  includeGeneric?: boolean;\n}\n\n/**\n * All four views derived from **one** extraction — so they can never disagree.\n * The fix for cross-call drift: `findings`, `tree`, `outline`, and `tabOrder`\n * are computed from a single a11y tree snapshot, not four separate extractions.\n */\nexport interface PageSnapshot {\n  findings: Finding[];\n  tree: string;\n  outline: string;\n  tabOrder: string;\n}\n\n/**\n * The session surface the MCP server depends on. Implemented by\n * {@link BrowserSession} in production and faked in unit tests, so the server\n * wiring can be exercised without launching a browser.\n */\nexport interface A11ySession {\n  open(\n    url: string,\n    options?: OpenOptions,\n  ): Promise<{ title: string; url: string }>;\n  call<T>(fn: string, rootSelector: string, args?: unknown[]): Promise<T>;\n  snapshot(\n    rootSelector: string,\n    options?: SnapshotOptions,\n  ): Promise<PageSnapshot>;\n  /** The browser's own (native) accessibility tree via CDP — Chromium only. */\n  nativeAX(): Promise<{ tree: string; pairs: string[] }>;\n  close(): Promise<void>;\n}\n\nexport class BrowserSession implements A11ySession {\n  private browser?: Browser;\n  private context?: BrowserContext;\n  private page?: Page;\n  /** Signature of the current context's emulation, to detect device changes. */\n  private emulationKey = \"\";\n  /** Over CDP: whether we created `page` (so `close()` only closes our tab). */\n  private ownsPage = false;\n  /** Serializes every operation so concurrent tool calls can't race the page. */\n  private queue: Promise<unknown> = Promise.resolve();\n\n  constructor(private readonly opts: BrowserSessionOptions = {}) {\n    if (opts.storageState && opts.cdpEndpoint) {\n      throw new Error(\n        \"storageState is for launched browsers — a CDP connection reuses the running browser's own session, so the two can't be combined.\",\n      );\n    }\n  }\n\n  /** Origins allowed for extraction, or null when unrestricted. */\n  private get allowedOrigins(): Set<string> | null {\n    const list = this.opts.allowedOrigins;\n    return list && list.length ? new Set(list) : null;\n  }\n\n  /**\n   * Run `fn` after any in-flight operation. MCP clients dispatch tool calls\n   * concurrently, but all tools share one mutable `page`, so we single-flight.\n   */\n  private run<T>(fn: () => Promise<T>): Promise<T> {\n    const result = this.queue.then(fn, fn);\n    // Keep the chain alive even if this op rejects.\n    this.queue = result.then(\n      () => undefined,\n      () => undefined,\n    );\n    return result;\n  }\n\n  /** Navigate to `url`, settle, then confirm the bundle initialized. */\n  async open(\n    url: string,\n    options: OpenOptions = {},\n  ): Promise<{ title: string; url: string }> {\n    return this.run(async () => {\n      assertOpenableUrl(url);\n      const {\n        waitUntil = \"load\",\n        settleMs = 0,\n        device,\n        viewport,\n        timeoutMs,\n      } = options;\n      const page = await this.ensurePage({ device, viewport });\n      try {\n        await page.goto(url, {\n          waitUntil,\n          ...(timeoutMs != null ? { timeout: timeoutMs } : {}),\n        });\n      } catch (err) {\n        // Only tolerate a timeout for `networkidle` — chatty sites (analytics,\n        // sockets) never fully idle. For other wait states a timeout means the\n        // navigation didn't happen, so surface it.\n        const isTimeout = err instanceof Error && err.name === \"TimeoutError\";\n        if (!(isTimeout && waitUntil === \"networkidle\")) throw err;\n      }\n      if (settleMs > 0) await page.waitForTimeout(settleMs);\n      // A tolerated timeout can leave us on about:blank (nav never committed) —\n      // don't silently audit an empty tab as if it were the requested URL.\n      if (page.url() === \"about:blank\") {\n        throw new Error(\n          `Navigation to ${url} did not complete (still on about:blank). Try waitUntil:\"load\" or a larger timeoutMs.`,\n        );\n      }\n      // Origin pinning: with a session loaded, a redirect to a recorded cookie\n      // domain would render an authenticated page we never intended to audit.\n      // Enforce the allowlist on the FINAL url, before injecting or extracting.\n      this.assertAllowedOrigin(page.url());\n      await this.injectBundle(page);\n      await this.verifyReady(page);\n      return { title: await page.title(), url: page.url() };\n    });\n  }\n\n  /**\n   * Run a named export from the injected bundle against a root selector.\n   * Re-injects first if a navigation wiped the global.\n   */\n  async call<T>(\n    fn: string,\n    rootSelector: string,\n    args: unknown[] = [],\n  ): Promise<T> {\n    return this.run(async () => {\n      const page = this.requirePage();\n      await this.ensureInjected(page);\n      return page.evaluate(\n        ({ fn, selector, args }) => {\n          const ra = (globalThis as Record<string, unknown>).__realA11y__ as\n            | Record<string, (root: Element, ...rest: unknown[]) => unknown>\n            | undefined;\n          if (!ra) throw new Error(\"__realA11y__ is not present on the page.\");\n          if (typeof ra[fn] !== \"function\") {\n            throw new Error(\n              `Real A11y bundle has no \"${fn}\" — the installed @real-a11y-dev/testing is too old for this MCP server; upgrade it.`,\n            );\n          }\n          let root: Element | null;\n          try {\n            root = document.querySelector(selector);\n          } catch {\n            throw new Error(`Invalid rootSelector: \"${selector}\".`);\n          }\n          if (!root) {\n            if (selector === \"body\" && document.body) root = document.body;\n            else {\n              throw new Error(\n                `rootSelector \"${selector}\" matched no element on the page.`,\n              );\n            }\n          }\n          return ra[fn](root, ...args) as unknown;\n        },\n        { fn, selector: rootSelector, args },\n      ) as Promise<T>;\n    });\n  }\n\n  /**\n   * Extract the a11y tree **once** and derive all four views from it inside a\n   * single `page.evaluate`, so findings / tree / outline / tab order always\n   * describe the same instant — no cross-call drift on a moving page.\n   */\n  async snapshot(\n    rootSelector: string,\n    options: SnapshotOptions = {},\n  ): Promise<PageSnapshot> {\n    return this.run(async () => {\n      const page = this.requirePage();\n      await this.ensureInjected(page);\n      return page.evaluate(\n        ({ selector, rules, includeGeneric }) => {\n          const ra = (globalThis as Record<string, unknown>).__realA11y__ as\n            | Record<string, (...a: unknown[]) => unknown>\n            | undefined;\n          if (!ra || typeof ra.extractA11yTree !== \"function\") {\n            throw new Error(\n              \"Real A11y bundle missing/too old — upgrade @real-a11y-dev/testing.\",\n            );\n          }\n          let el: Element | null;\n          try {\n            el = document.querySelector(selector);\n          } catch {\n            throw new Error(`Invalid rootSelector: \"${selector}\".`);\n          }\n          if (!el) {\n            if (selector === \"body\" && document.body) el = document.body;\n            else {\n              throw new Error(\n                `rootSelector \"${selector}\" matched no element on the page.`,\n              );\n            }\n          }\n          const tree = ra.extractA11yTree(el); // ← the single extraction\n          return {\n            findings: ra.collectFindings(\n              tree,\n              rules && rules.length ? rules : undefined,\n            ),\n            tree: ra.auditSnapshot(tree, { includeGeneric }),\n            outline: ra.outlineSnapshot(tree),\n            tabOrder: ra.tabSequenceSnapshot(tree),\n          };\n        },\n        {\n          selector: rootSelector,\n          rules: options.rules ?? null,\n          includeGeneric: options.includeGeneric ?? false,\n        },\n      ) as Promise<PageSnapshot>;\n    });\n  }\n\n  /**\n   * Chromium's own accessibility tree, straight from Blink via the CDP\n   * `Accessibility` domain — the authoritative computation, not our\n   * reimplementation. Used to cross-check custom-engine fidelity.\n   */\n  async nativeAX(): Promise<{ tree: string; pairs: string[] }> {\n    return this.run(async () => {\n      const page = this.requirePage();\n      const client = await page.context().newCDPSession(page);\n      try {\n        await client.send(\"Accessibility.enable\");\n        const { nodes } = (await client.send(\n          \"Accessibility.getFullAXTree\",\n        )) as { nodes: AXNode[] };\n        return serializeNativeAX(nodes);\n      } finally {\n        await client.detach().catch(() => {});\n      }\n    });\n  }\n\n  /**\n   * Capture the current context's storage state (cookies + origin storage) —\n   * the \"save\" step behind the CLI's `login` helper. Returns the plain object;\n   * the caller owns serialization + file writing (permissions, atomicity).\n   * `indexedDB` is caller-gated: it's a no-op on Playwright < 1.51, so the CLI\n   * passes it only when the resolved version supports it.\n   */\n  async captureStorageState(\n    options: { indexedDB?: boolean } = {},\n  ): Promise<unknown> {\n    return this.run(async () => {\n      const context = this.context;\n      if (!context) {\n        throw new Error(\"No browser context is open — call open() first.\");\n      }\n      return context.storageState(options.indexedDB ? { indexedDB: true } : {});\n    });\n  }\n\n  async close(): Promise<void> {\n    return this.run(async () => {\n      if (this.opts.cdpEndpoint) {\n        // Attached to the user's own browser: close only the tab we created and\n        // disconnect — never close their Chrome or their other tabs.\n        if (this.ownsPage) await this.page?.close().catch(() => {});\n        await this.browser?.close().catch(() => {});\n      } else {\n        await this.context?.close().catch(() => {});\n        await this.browser?.close().catch(() => {});\n      }\n      this.browser = undefined;\n      this.context = undefined;\n      this.page = undefined;\n      this.ownsPage = false;\n      this.emulationKey = \"\";\n    });\n  }\n\n  hasPage(): boolean {\n    return this.page !== undefined;\n  }\n\n  // ── internals ────────────────────────────────────────────────────────────\n\n  private requirePage(): Page {\n    if (!this.page) {\n      throw new Error(\"No page is open. Call the open_page tool first.\");\n    }\n    return this.page;\n  }\n\n  /** Refuse extraction when the final URL's origin isn't allowlisted. */\n  private assertAllowedOrigin(finalUrl: string): void {\n    const allowed = this.allowedOrigins;\n    if (!allowed) return;\n    let origin: string;\n    try {\n      origin = new URL(finalUrl).origin;\n    } catch {\n      throw new Error(`Refusing to audit an unparseable URL: ${finalUrl}`);\n    }\n    if (!allowed.has(origin)) {\n      throw new Error(\n        `Refusing to audit ${origin}: not an allowed audit origin under an authenticated session (a redirect may have left the intended site).`,\n      );\n    }\n  }\n\n  private async ensurePage(\n    emu: { device?: string; viewport?: { width: number; height: number } } = {},\n  ): Promise<Page> {\n    // playwright is a peer dep; import lazily so importing the server API\n    // (types, buildServer) never requires playwright to be installed.\n    const { chromium, devices } = await import(\"playwright\");\n\n    // CDP: attach to the running browser's context. Device emulation can't be\n    // applied to an already-open browser, so reject it explicitly.\n    if (this.opts.cdpEndpoint) {\n      if (emu.device || emu.viewport) {\n        throw new Error(\n          \"Device / viewport emulation is not supported over a CDP connection — it reuses the running browser's own context.\",\n        );\n      }\n      if (this.page && !this.page.isClosed()) return this.page;\n      if (!this.browser || !this.browser.isConnected()) {\n        this.browser = await chromium.connectOverCDP(this.opts.cdpEndpoint);\n      }\n      this.context =\n        this.browser.contexts()[0] ?? (await this.browser.newContext());\n      // Create our OWN tab rather than hijacking the user's oldest one.\n      this.page = await this.context.newPage();\n      this.ownsPage = true;\n      return this.page;\n    }\n\n    // Reuse the current page only when it's live and the emulation is unchanged.\n    const key = JSON.stringify({\n      device: emu.device ?? null,\n      viewport: emu.viewport ?? null,\n    });\n    if (this.page && !this.page.isClosed() && key === this.emulationKey) {\n      return this.page;\n    }\n\n    if (!this.browser || !this.browser.isConnected()) {\n      this.browser = await chromium.launch({\n        headless: this.opts.headless ?? true,\n        ...(this.opts.proxy ? { proxy: this.opts.proxy } : {}),\n      });\n    }\n\n    // Resolve the device descriptor BEFORE tearing down the old context, so a\n    // mistyped device name doesn't destroy the current session.\n    let ctxOpts: BrowserContextOptions = {};\n    if (emu.device) {\n      const descriptor = devices[emu.device];\n      if (!descriptor) {\n        throw new Error(\n          `Unknown device \"${emu.device}\". Use a Playwright device name such as \"iPhone 13\", \"Pixel 7\", or \"iPad Pro 11\".`,\n        );\n      }\n      ctxOpts = descriptor;\n    }\n    if (emu.viewport) ctxOpts = { ...ctxOpts, viewport: emu.viewport };\n    // Load the session into every launched context — including this one when a\n    // device change rebuilds it, so auth is never silently dropped by emulation.\n    if (this.opts.storageState) {\n      ctxOpts = { ...ctxOpts, storageState: this.opts.storageState };\n    }\n\n    // Emulation changed (or first open) → rebuild the context with it.\n    if (this.context) {\n      await this.context.close().catch(() => {});\n      this.context = undefined;\n      this.page = undefined;\n    }\n    this.context = await this.browser.newContext(ctxOpts);\n    this.page = await this.context.newPage();\n    this.emulationKey = key;\n    return this.page;\n  }\n\n  /** Evaluate the bundle in the page (CSP / Trusted-Types-safe via CDP). */\n  private async injectBundle(page: Page): Promise<void> {\n    await page.evaluate(bundleExpression());\n  }\n\n  /** (Re)inject the bundle if a navigation wiped the global. */\n  private async ensureInjected(page: Page): Promise<void> {\n    if (!(await this.isReady(page))) await this.injectBundle(page);\n  }\n\n  /** Confirm the bundle initialized; throw a clear error if not. */\n  private async verifyReady(page: Page): Promise<void> {\n    if (!(await this.isReady(page))) {\n      throw new Error(\n        \"Real A11y extraction bundle did not initialize on this page — a strict Content-Security-Policy may be blocking script evaluation here.\",\n      );\n    }\n  }\n\n  private isReady(page: Page): Promise<boolean> {\n    return page.evaluate(\n      () =>\n        typeof (globalThis as Record<string, unknown>).__realA11y__ ===\n        \"object\",\n    );\n  }\n}\n"]}