@a11y-pulse/tab-orchestrator 0.1.0

package/LICENSE.md

@@ -0,0 +1,166 @@
+Copyright (c) 2026-present, A11y Pulse Limited (https://www.a11ypulse.com/). All rights reserved.
+
+# PolyForm Shield License 1.0.0
+
+<https://polyformproject.org/licenses/shield/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose.  However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license
+to distribute copies of the software.  Your license
+to distribute covers distributing the software with
+changes and new works permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncompete
+
+Any purpose is a permitted purpose, except for providing any
+product that competes with the software or any product the
+licensor or any of its affiliates provides using the software.
+
+## Competition
+
+Goods and services compete even when they provide functionality
+through different kinds of interfaces or for different technical
+platforms.  Applications can compete with services, libraries
+with plugins, frameworks with development tools, and so on,
+even if they're written in different programming languages
+or for different computer architectures.  Goods and services
+compete even when provided free of charge.  If you market a
+product as a practical substitute for the software or another
+product, it definitely competes.
+
+## New Products
+
+If you are using the software to provide a product that does
+not compete, but the licensor or any of its affiliates brings
+your product into competition by providing a new version of
+the software or another product using the software, you may
+continue using versions of the software available under these
+terms beforehand to provide your competing product, but not
+any later versions.
+
+## Discontinued Products
+
+You may begin using the software to compete with a product
+or service that the licensor or any of its affiliates has
+stopped providing, unless the licensor includes a plain-text
+line beginning with `Licensor Line of Business:` with the
+software that mentions that line of business.  For example:
+
+> Licensor Line of Business: YoyodyneCMS Content Management
+System (http://example.com/cms)
+
+## Sales of Business
+
+If the licensor or any of its affiliates sells a line of
+business developing the software or using the software
+to provide a product, the buyer can also enforce
+[Noncompete](#noncompete) for that product.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else.  These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice.  Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+A **product** can be a good or service, or a combination
+of them.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+its affiliates.
+
+**Affiliates** means the other organizations than an
+organization has control over, is under the control of, or is
+under common control with.
+
+**Control** means ownership of substantially all the assets of
+an entity, or the power to direct its management and policies
+by vote, contract, or otherwise.  Control can be direct or
+indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.

package/README.md

@@ -0,0 +1,93 @@
+# @a11y-pulse/tab-orchestrator
+
+[![npm version](https://img.shields.io/npm/v/@a11y-pulse/tab-orchestrator)](https://www.npmjs.com/package/@a11y-pulse/tab-orchestrator)
+[![CI](https://github.com/A11y-Pulse/audits/actions/workflows/ci.yml/badge.svg)](https://github.com/A11y-Pulse/audits/actions/workflows/ci.yml)
+[![License: PolyForm Shield 1.0.0](https://img.shields.io/badge/license-PolyForm%20Shield%201.0.0-blue)](./LICENSE.md)
+
+A shared Tab-session runner for A11y Pulse's keyboard-driven accessibility audits. It drives a page through its focusable elements once — pressing Tab, tracking visited elements, capturing screenshots and styles on demand — while one or more **consumers** each score the tab stops for their own WCAG success criterion. This lets audits like [`@a11y-pulse/focus-appearance-audit`](../focus-appearance-audit) (WCAG 2.4.7) share a single tab loop with sibling audits instead of each re-tabbing the page from scratch.
+
+It is not an audit itself: it has no opinion on what "passing" means. It only owns the mechanics of moving focus, tracking cycle completion, and capturing the primitives (computed styles, clipped screenshots, unfocused/focused pairs) that consumers need.
+
+This package was developed by [A11y Pulse](https://www.a11ypulse.com/) for its accessibility monitoring service. It is released as source-available under the [PolyForm Shield License 1.0.0](#license).
+
+## Install
+
+```bash
+npm install @a11y-pulse/tab-orchestrator
+```
+
+Puppeteer is an optional peer dependency, needed only if you use the bundled [`PuppeteerAdaptor`](#puppeteeradaptor).
+
+## `createTabOrchestrator`
+
+```ts
+import { createTabOrchestrator } from "@a11y-pulse/tab-orchestrator";
+
+const orchestrator = createTabOrchestrator(adaptor, sessionOptions);
+
+orchestrator.attach(consumerA);
+orchestrator.attach(consumerB);
+
+await orchestrator.run();
+```
+
+- `createTabOrchestrator(adaptor: BrowserAdaptor, options?: TabSessionOptions)` builds a session against a single page, driven through the given [`BrowserAdaptor`](#browseradaptor). `TabSessionOptions` covers shared cost controls (`screenshotSettleDelay`, `screenshotClipBuffer`, `markerLimit`, `baselineElementLimit`), not any particular audit's policy.
+- `.attach(consumer)` registers a `TabConsumer`. Attaching after `run()` has started throws.
+- `.run()` presses Tab repeatedly, dispatching each `TabStopSnapshot` to every still-attached consumer, until either a full tab cycle completes, focus is lost, navigation happens, or every consumer has disconnected. Calling it twice throws; calling it with zero attached consumers returns immediately without tabbing.
+
+Each consumer declares the `capabilities` it needs (e.g. `baselineStyles`, `unfocusedPair`) and can disconnect independently once it has what it needs (say, after hitting its own element limit) — the orchestrator keeps driving the remaining consumers. Per-stop work like unfocused-pair screenshots is only captured if a still-attached consumer actually asks for it that stop.
+
+Most callers won't build a `TabConsumer` by hand — audit packages export a `createXAudit(options)` helper that returns one, plus a `runXAudit(adaptor, options)` convenience wrapper that builds a private single-consumer orchestrator for you. See [`@a11y-pulse/focus-appearance-audit`'s "Shared tab session"](../focus-appearance-audit#shared-tab-session) section for a worked example.
+
+## `BrowserAdaptor`
+
+The orchestrator drives a page through an **adaptor**: a small interface of primitives (evaluate JS in the page, press Tab, take a clipped screenshot, etc.) so it never needs to know which browser automation library is behind it.
+
+| Method                   | Description                                                                                                                                       |
+| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `evaluate(fn, ...args)`  | Runs `fn` in the page context, passing in any serialisable `args`, and returns its result.                                                          |
+| `evaluateHandle(fn)`     | Runs `fn` in the page context and returns an opaque `ElementRef` handle to the `Element` it returns, without serialising it.                        |
+| `disposeRef(ref)`        | Releases a handle previously returned by `evaluateHandle`.                                                                                           |
+| `pressTab()`             | Presses the Tab key, advancing focus to the next focusable element.                                                                                  |
+| `screenshotClip(clip)`   | Screenshots a clipped region of the page (`{ x, y, width, height }`) and returns PNG bytes.                                                          |
+| `ensureFocusReporting()` | Ensures the page reports focus for its lifetime — in particular that `document.hasFocus()` works and `:focus` styles apply, even when the page is not the foreground tab/window. Must not throw. |
+
+The orchestrator is the only thing that mutates the page through this adaptor during a session; consumers score snapshots, they don't call `pressTab`, take screenshots, or install observers themselves.
+
+### `PuppeteerAdaptor`
+
+```js
+import { createTabOrchestrator } from "@a11y-pulse/tab-orchestrator";
+import { PuppeteerAdaptor } from "@a11y-pulse/tab-orchestrator/puppeteer";
+
+const orchestrator = createTabOrchestrator(new PuppeteerAdaptor(page));
+```
+
+The package ships one implementation, `PuppeteerAdaptor`, backed by a Puppeteer `Page`, exported from the `./puppeteer` subpath so consumers that only need the type-level `BrowserAdaptor` interface aren't forced to import Puppeteer. Other environments (Playwright, Selenium, WebDriver) can be supported by implementing `BrowserAdaptor` against your automation library's page/session object; use [`src/adaptors/puppeteer.ts`](./src/adaptors/puppeteer.ts) as a reference implementation.
+
+## Releasing
+
+Releases are managed in the [A11y-Pulse/audits](https://github.com/A11y-Pulse/audits) monorepo with [Changesets](https://github.com/changesets/changesets). Publishing uses [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/) (OIDC). There is no long-lived `NPM_TOKEN`.
+
+### Ship a change
+
+1. Open a PR against `main` that includes a changeset (`npx changeset`) naming `@a11y-pulse/tab-orchestrator`.
+2. After merge, the Release workflow opens a Version PR. Merging that PR publishes this package to npm and tags `@a11y-pulse/tab-orchestrator@<version>`.
+
+Trusted Publisher on npm must stay configured for:
+
+| Field | Value |
+| --- | --- |
+| Organization or user | `A11y-Pulse` |
+| Repository | `audits` |
+| Workflow filename | `release.yml` |
+
+## License
+
+Released under the [PolyForm Shield License 1.0.0](./LICENSE.md), in plain language:
+
+- **Source-available.** The source is public and you can read, fork, and modify it.
+- **Permitted for non-competing use.** You can use this package freely in your own products and services, as long as they don't compete with A11y Pulse.
+- **Competing products are forbidden.** You may not use this software (or a modified version of it) to build a product or service that competes with A11y Pulse's accessibility monitoring offering.
+
+See [LICENSE.md](./LICENSE.md) for the full, binding terms.

package/dist/adaptor.d.ts

@@ -0,0 +1,47 @@
+export type Rect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/**
+ * An element handle in the page. This type is adaptor-specific and is opaque to the audit.
+ */
+export type ElementRef = unknown;
+/**
+ * A framework-specific adaptor that provides the primitives needed by the audit. An adaptor wraps
+ * a single page in a web browser.
+ */
+export interface BrowserAdaptor {
+    /**
+     * Run `fn` in the page context, passing in any serialisable `args`
+     */
+    evaluate<T>(fn: (...args: any[]) => T | Promise<T>, ...args: unknown[]): Promise<T>;
+    /**
+     * Return an opaque handle to an element in the page
+     */
+    evaluateHandle(fn: () => Element | null): Promise<ElementRef>;
+    /**
+     * Release a handle previously returned by evaluateHandle
+     */
+    disposeRef(ref: ElementRef): Promise<void>;
+    /**
+     * Press the tab key
+     */
+    pressTab(): Promise<void>;
+    /**
+     * Screenshot a clipped region of the page. `scale` is the device scale
+     * factor (bitmap pixels per CSS pixel).
+     */
+    screenshotClip(clip: Rect, scale?: number): Promise<Uint8Array>;
+    /** Device scale factor for evidence screenshots stored on failure. */
+    readonly screenshotClipScale?: number;
+    /**
+     * Ensure the page reports focus for its lifetime. In particular, `document.hasFocus()` must
+     * function correctly and :focus styles must be applied, even when the page is not the
+     * foreground.
+     *
+     * This function must not throw.
+     */
+    ensureFocusReporting(): Promise<void>;
+}

package/dist/adaptors/puppeteer.d.ts

@@ -0,0 +1,14 @@
+import type { Page } from "puppeteer";
+import type { BrowserAdaptor, ElementRef, Rect } from "../adaptor";
+/** A BrowserAdaptor backed by a Puppeteer Page. */
+export declare class PuppeteerAdaptor implements BrowserAdaptor {
+    private readonly page;
+    readonly screenshotClipScale = 2;
+    constructor(page: Page);
+    evaluate<T>(fn: (...args: any[]) => T | Promise<T>, ...args: unknown[]): Promise<T>;
+    evaluateHandle(fn: () => Element | null): Promise<ElementRef>;
+    disposeRef(ref: ElementRef): Promise<void>;
+    pressTab(): Promise<void>;
+    screenshotClip(clip: Rect, scale?: number): Promise<Uint8Array>;
+    ensureFocusReporting(): Promise<void>;
+}

package/dist/adaptors/puppeteer.js

@@ -0,0 +1,52 @@
+// src/adaptors/puppeteer.ts
+var focusEmulationEnabled = /* @__PURE__ */ new WeakSet();
+var PuppeteerAdaptor = class {
+  constructor(page) {
+    this.page = page;
+  }
+  page;
+  screenshotClipScale = 2;
+  evaluate(fn, ...args) {
+    return this.page.evaluate(fn, ...args);
+  }
+  evaluateHandle(fn) {
+    return this.page.evaluateHandle(fn);
+  }
+  async disposeRef(ref) {
+    await ref.dispose();
+  }
+  async pressTab() {
+    await this.page.keyboard.press("Tab");
+  }
+  async screenshotClip(clip, scale = 1) {
+    return await this.page.screenshot({
+      type: "png",
+      optimizeForSpeed: true,
+      clip: {
+        ...clip,
+        scale
+      }
+    });
+  }
+  async ensureFocusReporting() {
+    if (focusEmulationEnabled.has(this.page)) {
+      return;
+    }
+    try {
+      const client = await this.page.createCDPSession();
+      await client.send("Emulation.setFocusEmulationEnabled", {
+        enabled: true
+      });
+      focusEmulationEnabled.add(this.page);
+    } catch (error) {
+      console.warn(
+        "Could not enable focus emulation for the tab orchestrator",
+        { error }
+      );
+    }
+  }
+};
+export {
+  PuppeteerAdaptor
+};
+//# sourceMappingURL=puppeteer.js.map

package/dist/adaptors/puppeteer.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/adaptors/puppeteer.ts"],"sourcesContent":["import type { JSHandle, Page } from \"puppeteer\";\nimport type { BrowserAdaptor, ElementRef, Rect } from \"../adaptor\";\n\n// Pages that already have focus emulation enabled. A fresh adaptor is created per\n// audit run, but a page is often reused across runs (e.g. one page per snapshot,\n// many checks), so without this each run would open another CDP session that is\n// never detached. The emulation persists for the page's lifetime, so enabling it\n// once is enough. (Detaching the session instead is not an option — Chrome clears\n// the emulation when the CDP client disconnects.)\nconst focusEmulationEnabled = new WeakSet<Page>();\n\n/** A BrowserAdaptor backed by a Puppeteer Page. */\nexport class PuppeteerAdaptor implements BrowserAdaptor {\n\treadonly screenshotClipScale = 2;\n\n\tconstructor(private readonly page: Page) {}\n\n\tevaluate<T>(\n\t\t// biome-ignore lint/suspicious/noExplicitAny: the page-evaluated fn accepts arbitrary serialised args and element handles.\n\t\tfn: (...args: any[]) => T | Promise<T>,\n\t\t...args: unknown[]\n\t): Promise<T> {\n\t\t// Puppeteer resolves any JSHandle passed as an arg to the live element.\n\t\treturn this.page.evaluate(fn as never, ...(args as never[])) as Promise<T>;\n\t}\n\n\tevaluateHandle(fn: () => Element | null): Promise<ElementRef> {\n\t\treturn this.page.evaluateHandle(fn);\n\t}\n\n\tasync disposeRef(ref: ElementRef): Promise<void> {\n\t\tawait (ref as JSHandle).dispose();\n\t}\n\n\tasync pressTab(): Promise<void> {\n\t\tawait this.page.keyboard.press(\"Tab\");\n\t}\n\n\tasync screenshotClip(clip: Rect, scale = 1): Promise<Uint8Array> {\n\t\treturn (await this.page.screenshot({\n\t\t\ttype: \"png\",\n\t\t\toptimizeForSpeed: true,\n\t\t\tclip: {\n\t\t\t\t...clip,\n\t\t\t\tscale,\n\t\t\t},\n\t\t})) as Uint8Array;\n\t}\n\n\tasync ensureFocusReporting(): Promise<void> {\n\t\t// Pages only report focus while they are the foreground tab. Since this browser instance\n\t\t// is likely running in the background, we need to enable focus emulation to get accurate\n\t\t// results.\n\t\t//\n\t\t// Note this function does not throw if enabling emulation fails; it is a best-effort.\n\t\tif (focusEmulationEnabled.has(this.page)) {\n\t\t\treturn;\n\t\t}\n\n\t\ttry {\n\t\t\tconst client = await this.page.createCDPSession();\n\t\t\tawait client.send(\"Emulation.setFocusEmulationEnabled\", {\n\t\t\t\tenabled: true,\n\t\t\t});\n\t\t\tfocusEmulationEnabled.add(this.page);\n\t\t} catch (error) {\n\t\t\tconsole.warn(\n\t\t\t\t\"Could not enable focus emulation for the tab orchestrator\",\n\t\t\t\t{ error },\n\t\t\t);\n\t\t}\n\t}\n}\n"],"mappings":";AASA,IAAM,wBAAwB,oBAAI,QAAc;AAGzC,IAAM,mBAAN,MAAiD;AAAA,EAGvD,YAA6B,MAAY;AAAZ;AAAA,EAAa;AAAA,EAAb;AAAA,EAFpB,sBAAsB;AAAA,EAI/B,SAEC,OACG,MACU;AAEb,WAAO,KAAK,KAAK,SAAS,IAAa,GAAI,IAAgB;AAAA,EAC5D;AAAA,EAEA,eAAe,IAA+C;AAC7D,WAAO,KAAK,KAAK,eAAe,EAAE;AAAA,EACnC;AAAA,EAEA,MAAM,WAAW,KAAgC;AAChD,UAAO,IAAiB,QAAQ;AAAA,EACjC;AAAA,EAEA,MAAM,WAA0B;AAC/B,UAAM,KAAK,KAAK,SAAS,MAAM,KAAK;AAAA,EACrC;AAAA,EAEA,MAAM,eAAe,MAAY,QAAQ,GAAwB;AAChE,WAAQ,MAAM,KAAK,KAAK,WAAW;AAAA,MAClC,MAAM;AAAA,MACN,kBAAkB;AAAA,MAClB,MAAM;AAAA,QACL,GAAG;AAAA,QACH;AAAA,MACD;AAAA,IACD,CAAC;AAAA,EACF;AAAA,EAEA,MAAM,uBAAsC;AAM3C,QAAI,sBAAsB,IAAI,KAAK,IAAI,GAAG;AACzC;AAAA,IACD;AAEA,QAAI;AACH,YAAM,SAAS,MAAM,KAAK,KAAK,iBAAiB;AAChD,YAAM,OAAO,KAAK,sCAAsC;AAAA,QACvD,SAAS;AAAA,MACV,CAAC;AACD,4BAAsB,IAAI,KAAK,IAAI;AAAA,IACpC,SAAS,OAAO;AACf,cAAQ;AAAA,QACP;AAAA,QACA,EAAE,MAAM;AAAA,MACT;AAAA,IACD;AAAA,EACD;AACD;","names":[]}

package/dist/audit-scaffold.d.ts

@@ -0,0 +1,50 @@
+import type { SessionEndReason, TabSessionHandle } from "./types";
+export declare const DEFAULT_ELEMENT_LIMIT = 1024;
+export declare const DEFAULT_SCREENSHOT_SETTLE_DELAY = 33;
+export declare const DEFAULT_FAILED_ELEMENT_LIMIT = 0;
+export declare const DEFAULT_TIMEOUT = 0;
+export type BaseAuditOptions = {
+    /** Max focusable elements to tab through. */
+    elementLimit?: number;
+    /** How long to wait (ms) after each Tab for the page to settle. */
+    screenshotSettleDelay?: number;
+    /** Disconnect early after this many elements fail (0 = never). */
+    failedElementLimit?: number;
+    /** Return whatever's gathered so far after this many ms (0 = no timeout). */
+    timeout?: number;
+};
+export type BaseAuditSummary = {
+    checked: number;
+    passed: number;
+    failed: number;
+    /** True if the element limit was hit before tabbing finished. */
+    reachedLimit: boolean;
+    /** True if the audit stopped early after hitting `failedElementLimit`. */
+    reachedFailedElementLimit: boolean;
+    /**
+     * True if the audit returned early because `timeout` elapsed. The results
+     * are whatever had been gathered when the deadline hit.
+     */
+    timedOut: boolean;
+    /**
+     * Why the tab session ended, or `null` when this consumer disconnected
+     * itself (element limit, failed-element limit, or timeout).
+     */
+    sessionEnd: SessionEndReason | null;
+};
+export type AuditSelfDisconnect = {
+    /** True once this consumer has disconnected itself from the session. */
+    readonly disconnectedSelf: boolean;
+    /** Arm a timeout that calls `onTimeout` then disconnects, if `timeout` is greater than 0. */
+    armTimeout(timeout: number, session: TabSessionHandle, onTimeout: () => void): void;
+    /** Disconnect the session and record that this consumer initiated it. */
+    disconnect(session: TabSessionHandle): void;
+    /** Clear any pending timeout without disconnecting. */
+    clear(): void;
+};
+/**
+ * Arms an optional self-disconnecting timeout and tracks whether this
+ * consumer initiated its own disconnect, so `onSessionEnd` can tell that
+ * apart from an external end.
+ */
+export declare function createAuditSelfDisconnect(): AuditSelfDisconnect;

package/dist/browser-scripts.d.ts

@@ -0,0 +1,148 @@
+/**
+ * IMPORTANT: Functions in this file are serialized and injected into the audited page, so they
+ * must not reference any symbols outside their own scope. This also means they cannot share code,
+ * so any common logic (like descending into shadow roots) must be duplicated.
+ */
+import type { Rect } from "./adaptor";
+import type { StyleSnapshot } from "./types";
+type BaselineElementEntry = {
+    index: number;
+    /** Position of this element's snapshot in the payload's `styles` table. */
+    styleIndex: number;
+    /** The element's page-relative rect in its unfocused (baseline) state. */
+    rect: Rect;
+};
+/**
+ * The baseline as a table of unique style snapshots plus per-element entries referencing them.
+ * Elements overwhelmingly share identical snapshots (same classes), so interning keeps the
+ * serialised payload O(unique styles) instead of O(elements × style size).
+ */
+export type BaselinePayload = {
+    styles: StyleSnapshot[];
+    entries: BaselineElementEntry[];
+};
+/**
+ * Find up to `limit` focusable elements and mark them with `markerAttr` and a unique index. Then
+ * return a snapshot of their styles to use as a baseline.
+ */
+export declare function baselineScript(props: string[], markerAttr: string, limit: number): BaselinePayload;
+export type ActiveElementBase = {
+    index: number | null;
+    isBody: boolean;
+    /**
+     * The focused element is an <iframe>. Tabbing into a frame passes focus into
+     * its embedded document, but the parent's document.activeElement is the frame
+     * element itself, so the loop uses this to skip the frame as a tab stop.
+     */
+    isIframe: boolean;
+    html: string;
+    styles: StyleSnapshot;
+    rect: Rect;
+};
+/**
+ * Read the currently focused element (descending open shadow roots), returning
+ * its marker index, opening-tag HTML (marker attribute stripped), focus-relevant
+ * styles, and page-relative rect.
+ */
+export declare function probeActiveElementScript(props: string[], markerAttr: string): ActiveElementBase;
+export declare function activeElementHandleScript(): Element | null;
+export declare function pageDimensionsScript(): {
+    width: number;
+    height: number;
+};
+export declare function elementRectScript(el: Element | null): Rect;
+/**
+ * Whether something unrelated (e.g. a fixed cookie banner) covers the element's centre point, so
+ * a screenshot of the element's box would show the covering element instead.
+ */
+export declare function isCenterObscuredScript(el: Element | null): boolean;
+/**
+ * Scroll the element to the centre of the viewport, instantly so a screenshot taken immediately
+ * afterwards isn't captured mid-animation.
+ */
+export declare function scrollToCenterScript(el: Element | null): void;
+/**
+ * Blur (unfocus) an element
+ */
+export declare function blurScript(el: Element | null): void;
+/**
+ * Focus an element
+ */
+export declare function focusScript(el: Element | null): void;
+/**
+ * Read focus-relevant computed styles from a given element. Unlike
+ * `probeActiveElementScript`, this does not use `document.activeElement`, so it
+ * still works after the node has been blurred.
+ */
+export declare function elementStylesScript(el: Element | null, props: string[]): StyleSnapshot;
+/**
+ * Remove the marker attribute from all elements and blur the active element. This is a best-effort
+ * attempt to reset state between audits.
+ */
+export declare function clearMarkersScript(markerAttr: string): void;
+export type MeasureObscuringResult = {
+    coveredFraction: number;
+    fullyObscured: boolean;
+    offscreen: boolean;
+    opacity: "opaque" | "semi-transparent" | "unknown";
+    obscuredByHtml: string | null;
+    /** True when a covering element was marked for selector resolution. */
+    hasObscurer: boolean;
+};
+/**
+ * Hit-test whether author-created content entirely hides the focused element.
+ * Marks a single covering element with `obscurerAttr` when containment confirms
+ * a full cover, so the host can resolve its selector via getSelector.
+ */
+export declare function measureObscuringScript(el: Element | null, obscurerAttr: string): MeasureObscuringResult;
+/** Return the element marked as the obscurer, if any. */
+export declare function obscurerHandleScript(): Element | null;
+export declare function clearObscurerScript(obscurerAttr: string): void;
+type ContextObserverState = {
+    baselineHref: string;
+    openedWindow: boolean;
+    submittedForm: boolean;
+    /** Elements that received focusin since the last drain. */
+    focusIns: Element[];
+    softUrlChange: boolean;
+    installed: boolean;
+};
+declare global {
+    interface Window {
+        __a11yContextObserver?: ContextObserverState;
+    }
+}
+/**
+ * Install once: wrap window.open (record + inert stub), capture-phase submit
+ * (record + preventDefault), track focusin and soft URL changes.
+ */
+export declare function installContextObserverScript(): void;
+export type DrainContextObserverResult = {
+    openedWindow: boolean;
+    submittedForm: boolean;
+    focusRemoved: boolean;
+    redirect: "outside" | "same-subtree" | null;
+    softUrlChange: boolean;
+    navigation: boolean;
+    attributedHtml: string | null;
+    /** True when an attributed element was marked for selector resolution. */
+    hasAttributed: boolean;
+};
+/**
+ * Drain observer signals for the current tab stop and reset per-stop flags.
+ * Classification of focus removal / redirection uses the post-Tab settle
+ * activeElement and the focusin history from this stop only.
+ */
+export declare function drainContextObserverScript(markerAttr: string): DrainContextObserverResult;
+/** Return the element marked as attributed by drainContextObserverScript (the
+ * element that received a focus event this stop and then lost it), if any. */
+export declare function attributedHandleScript(): Element | null;
+export declare function clearAttributedScript(): void;
+/**
+ * Drop focusin history accumulated after drain (e.g. pixel-diff blur/refocus)
+ * so the next tab stop does not mis-attribute F55 or redirects.
+ */
+export declare function clearContextFocusInsScript(): void;
+/** Current location.href for navigation comparison in the host. */
+export declare function locationHrefScript(): string;
+export {};

package/dist/clip.d.ts

@@ -0,0 +1,7 @@
+import type { Rect } from "./adaptor";
+/**
+ * A screenshot clip framing `rect` with up to `buffer` pixels of padding on each side, shrunk
+ * where the page edges leave less room. The padding allows for indicators drawn just outside
+ * the element box (outlines, shadows) and for anti-aliasing.
+ */
+export declare function bufferedClip(rect: Rect, pageWidth: number, pageHeight: number, buffer: number): Rect;

package/dist/context-signals.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Whether focus destination Y is inside the subtree of intended focus X
+ * (descendant or ancestor), which is legitimate delegation rather than theft.
+ * Walks across open shadow roots so focusing into a host's shadow content is
+ * same-subtree, not theft.
+ */
+export declare function isSameFocusSubtree(intended: Element, settled: Element): boolean;

package/dist/focus-style.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Computed-style properties that are likely to draw a visible focus indicator. Layout properties
+ * like margin and padding are deliberately excluded.
+ */
+export declare const FOCUS_STYLE_PROPERTIES: readonly ["background-color", "background-image", "border-bottom-color", "border-bottom-style", "border-bottom-width", "border-left-color", "border-left-style", "border-left-width", "border-right-color", "border-right-style", "border-right-width", "border-top-color", "border-top-style", "border-top-width", "box-shadow", "color", "font-weight", "outline-color", "outline-style", "outline-width", "text-decoration"];

package/dist/get-selector.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Build a compact, hopefully-unique selector for any given element on the page. This function is
+ * serialized and run in the page context, so it must not reference any symbols outside its own
+ * scope.
+ *
+ * Mirrors axe-core's approach: each level contributes the fewest features that discriminate the
+ * element (a unique id, the rarest single class, or an :nth-of-type position), and the walk stops
+ * as soon as the joined selector matches exactly one element. Selectors stay short because of
+ * that early stop, not because of truncation; the length budget is only a backstop.
+ */
+export declare function getSelector(root: Node | null): string;

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export type { BrowserAdaptor, ElementRef, Rect } from "./adaptor";
+export type { AuditSelfDisconnect, BaseAuditOptions, BaseAuditSummary, } from "./audit-scaffold";
+export { createAuditSelfDisconnect, DEFAULT_ELEMENT_LIMIT, DEFAULT_FAILED_ELEMENT_LIMIT, DEFAULT_SCREENSHOT_SETTLE_DELAY, DEFAULT_TIMEOUT, } from "./audit-scaffold";
+export type { ActiveElementBase, BaselinePayload } from "./browser-scripts";
+export { activeElementHandleScript, baselineScript, blurScript, clearMarkersScript, elementRectScript, elementStylesScript, focusScript, isCenterObscuredScript, pageDimensionsScript, probeActiveElementScript, scrollToCenterScript, } from "./browser-scripts";
+export { bufferedClip } from "./clip";
+export { FOCUS_STYLE_PROPERTIES } from "./focus-style";
+export { getSelector } from "./get-selector";
+export type { TabSessionOptions } from "./orchestrator";
+export { createTabOrchestrator } from "./orchestrator";
+export type { TruncateHtmlOptions } from "./truncate-html";
+export { truncateHtml } from "./truncate-html";
+export type { ActiveElementInfo, Capability, ContextChangeDrain, ContextChangeSignals, ObscuredMeasurement, SessionEndReason, StyleSnapshot, TabConsumer, TabSessionHandle, TabStopSnapshot, UnfocusedPair, } from "./types";