@a11y-pulse/tab-orchestrator

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 (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 for its accessibility monitoring service. It is released under the MIT License.

Install

npm install @a11y-pulse/tab-orchestrator

This package drives the page through a BrowserAdaptor you supply. It has no peer dependencies: install @a11y-pulse/browser-adaptor alongside it for the bundled Puppeteer and Playwright implementations.

createTabOrchestrator

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. 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" 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. The BrowserAdaptor interface and its method-by-method reference live in @a11y-pulse/browser-adaptor; this package does not re-export them.

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.

Supplying an adaptor

import { createTabOrchestrator } from "@a11y-pulse/tab-orchestrator";
import { PuppeteerAdaptor } from "@a11y-pulse/browser-adaptor/puppeteer";

const orchestrator = createTabOrchestrator(new PuppeteerAdaptor(page));

This package ships no adaptor of its own. @a11y-pulse/browser-adaptor provides BrowserAdaptor along with two implementations, PuppeteerAdaptor and PlaywrightAdaptor, so consumers that only need the type-level interface aren't forced to install either automation library. Other environments (Selenium, WebDriver) can be supported by implementing BrowserAdaptor against your automation library's page/session object; use @a11y-pulse/browser-adaptor's src/adaptors/puppeteer.ts as a reference implementation.

Releasing

Releases are managed in the A11y-Pulse/audits monorepo with Changesets. Publishing uses npm trusted publishing (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

MIT. Use it however you like, including in commercial and competing products.

The audit packages in this repository are licensed separately, under the PolyForm Shield License 1.0.0.