craftdriver 0.1.0 → 0.2.0

package/dist/lib/tracing.js

@@ -0,0 +1,272 @@
+/**
+ * Tracer — append-only, crash-resilient session recorder for bug
+ * investigation.
+ *
+ * Streams events to `<outDir>/trace.ndjson` synchronously, one line per
+ * event. Screenshots are written to `<outDir>/screenshots/NNNN.png` as
+ * their captures resolve. There is **no finalisation step** — if the
+ * test throws (or the process is killed) every event up to that point is
+ * already on disk and the partial file is still valid NDJSON.
+ *
+ * **BiDi-only.** Tracing relies on the same subscriptions that power
+ * `browser.logs` and `browser.network` and is unavailable in Classic mode.
+ */
+import { mkdirSync, writeFileSync, openSync, writeSync, closeSync } from 'node:fs';
+import { join } from 'node:path';
+export class Tracer {
+    browser;
+    conn;
+    startedAtMs = 0;
+    startedAtIso = '';
+    outDir = '';
+    fd = null;
+    unsubs = [];
+    screenshotIndex = 0;
+    screenshotDirEnsured = false;
+    running = false;
+    actionsEnabled = true;
+    screenshotMode = 'auto';
+    actionIndex = 0;
+    /** Tracks in-flight screenshot captures so `stop()` can drain them. */
+    pendingCaptures = [];
+    constructor(browser, conn) {
+        this.browser = browser;
+        this.conn = conn;
+    }
+    get isRunning() {
+        return this.running;
+    }
+    async start(opts) {
+        if (this.running) {
+            throw new Error('Tracer is already running. Call stopTrace() first.');
+        }
+        if (!opts || typeof opts.outDir !== 'string' || opts.outDir.length === 0) {
+            throw new Error('startTrace() requires { outDir: string }.');
+        }
+        this.running = true;
+        this.startedAtMs = Date.now();
+        this.startedAtIso = new Date(this.startedAtMs).toISOString();
+        this.outDir = opts.outDir;
+        this.screenshotIndex = 0;
+        this.screenshotDirEnsured = false;
+        this.actionIndex = 0;
+        this.pendingCaptures = [];
+        this.actionsEnabled = opts.actions ?? true;
+        const networkOn = opts.network ?? true;
+        const consoleOn = opts.console ?? true;
+        this.screenshotMode = normalizeScreenshotMode(opts.screenshots);
+        mkdirSync(this.outDir, { recursive: true });
+        this.fd = openSync(join(this.outDir, 'trace.ndjson'), 'w');
+        // First line: start meta. Readers can match `type === 'meta'` to find
+        // start/end markers and ignore the rest of the schema.
+        this.writeLine({
+            t: 0,
+            type: 'meta',
+            startedAt: this.startedAtIso,
+            opts: {
+                actions: this.actionsEnabled,
+                network: networkOn,
+                console: consoleOn,
+                screenshots: this.screenshotMode,
+            },
+        });
+        const wantedSubs = ['browsingContext.navigationStarted'];
+        if (consoleOn)
+            wantedSubs.push('log.entryAdded');
+        if (networkOn)
+            wantedSubs.push('network.beforeRequestSent', 'network.responseCompleted');
+        // BiDi accepts duplicate subscribes (LogMonitor / NetworkInterceptor may already be subscribed).
+        await this.conn.subscribe(wantedSubs).catch(() => { });
+        if (consoleOn) {
+            this.unsubs.push(this.conn.on('log.entryAdded', (params) => {
+                const p = params;
+                const text = String(p.text ?? '');
+                if (p.type === 'console') {
+                    this.push({ type: 'console', level: String(p.level ?? 'info'), text });
+                }
+                else {
+                    this.push({ type: 'error', text });
+                    if (this.screenshotMode === 'auto')
+                        this.scheduleScreenshot('error');
+                }
+            }));
+        }
+        if (networkOn) {
+            this.unsubs.push(this.conn.on('network.beforeRequestSent', (params) => {
+                const p = params;
+                const req = (p.request ?? {});
+                this.push({
+                    type: 'request',
+                    url: String(req.url ?? ''),
+                    method: String(req.method ?? ''),
+                    requestId: req.request,
+                });
+            }));
+            this.unsubs.push(this.conn.on('network.responseCompleted', (params) => {
+                const p = params;
+                const req = (p.request ?? {});
+                const res = (p.response ?? {});
+                const ev = {
+                    type: 'response',
+                    url: String(req.url ?? res.url ?? ''),
+                    status: Number(res.status ?? 0),
+                    requestId: req.request,
+                };
+                const mime = res.mimeType;
+                if (typeof mime === 'string' && mime.length > 0)
+                    ev.mimeType = mime;
+                if (res.fromCache === true)
+                    ev.fromCache = true;
+                this.push(ev);
+            }));
+        }
+        this.unsubs.push(this.conn.on('browsingContext.navigationStarted', (params) => {
+            const p = params;
+            this.push({
+                type: 'navigation',
+                url: String(p.url ?? ''),
+                context: p.context,
+            });
+        }));
+    }
+    /**
+     * Record a public-API action. Fire-and-forget — the event is written
+     * **synchronously** to `trace.ndjson` before returning, so a thrown
+     * `expect` on the next line cannot lose it. When `screenshots: 'auto'`
+     * is on, also enqueues a pre-action screenshot capture (async; doesn't
+     * block the caller).
+     *
+     * Zero-cost when no tracer is running or `actions: false`.
+     */
+    recordAction(name, args, selector) {
+        if (!this.running || !this.actionsEnabled)
+            return;
+        const idx = ++this.actionIndex;
+        this.writeLine({
+            t: Date.now() - this.startedAtMs,
+            type: 'action',
+            name,
+            args: args && args.length ? args.map(safeArg) : undefined,
+            selector,
+        });
+        if (this.screenshotMode === 'auto')
+            this.scheduleScreenshot('action', idx);
+    }
+    scheduleScreenshot(reason, actionIndex) {
+        const startedAtMs = Date.now();
+        const p = this.browser.screenshot().then((buf) => {
+            if (!this.running)
+                return;
+            const idx = ++this.screenshotIndex;
+            const rel = `screenshots/${String(idx).padStart(4, '0')}.png`;
+            if (!this.screenshotDirEnsured) {
+                mkdirSync(join(this.outDir, 'screenshots'), { recursive: true });
+                this.screenshotDirEnsured = true;
+            }
+            try {
+                writeFileSync(join(this.outDir, rel), buf);
+            }
+            catch {
+                return; // disk error; skip this frame
+            }
+            const ev = {
+                t: startedAtMs - this.startedAtMs,
+                type: 'screenshot',
+                file: rel,
+                reason,
+            };
+            if (actionIndex !== undefined)
+                ev.actionIndex = actionIndex;
+            this.writeLine(ev);
+        }, () => { });
+        this.pendingCaptures.push(p);
+    }
+    /**
+     * Stop tracing cleanly: drain in-flight screenshots, write the closing
+     * `meta` line, and close the file. If the test throws and `stop()` is
+     * never called, the file is still a valid NDJSON trace — just without
+     * the closing marker.
+     */
+    async stop() {
+        if (!this.running) {
+            throw new Error('stopTrace(): no trace is running. Call startTrace() first.');
+        }
+        for (const un of this.unsubs)
+            un();
+        this.unsubs = [];
+        if (this.pendingCaptures.length > 0) {
+            await Promise.allSettled(this.pendingCaptures);
+            this.pendingCaptures = [];
+        }
+        this.writeLine({
+            t: Date.now() - this.startedAtMs,
+            type: 'meta',
+            endedAt: new Date().toISOString(),
+        });
+        if (this.fd !== null) {
+            try {
+                closeSync(this.fd);
+            }
+            catch { /* ignore */ }
+            this.fd = null;
+        }
+        this.running = false;
+    }
+    /** Close the file without writing an end marker. Used by `Browser.quit()`. */
+    abort() {
+        for (const un of this.unsubs)
+            un();
+        this.unsubs = [];
+        if (this.fd !== null) {
+            try {
+                closeSync(this.fd);
+            }
+            catch { /* ignore */ }
+            this.fd = null;
+        }
+        this.running = false;
+        this.pendingCaptures = [];
+    }
+    push(ev) {
+        if (!this.running)
+            return;
+        this.writeLine({ t: Date.now() - this.startedAtMs, ...ev });
+    }
+    writeLine(ev) {
+        if (this.fd === null)
+            return;
+        try {
+            writeSync(this.fd, JSON.stringify(ev) + '\n');
+        }
+        catch {
+            // Disk full / fd closed unexpectedly. Stop trying so we don't
+            // throw from inside a hot action method.
+        }
+    }
+}
+function normalizeScreenshotMode(v) {
+    if (v === undefined || v === 'auto' || v === true)
+        return 'auto';
+    return 'off';
+}
+function safeArg(v) {
+    if (v === null || v === undefined)
+        return v;
+    const t = typeof v;
+    if (t === 'string' || t === 'number' || t === 'boolean')
+        return v;
+    if (t === 'function')
+        return '[Function]';
+    if (Array.isArray(v))
+        return v.slice(0, 8).map(safeArg);
+    try {
+        const s = JSON.stringify(v);
+        if (s && s.length < 200)
+            return JSON.parse(s);
+        return '[Object]';
+    }
+    catch {
+        return '[Object]';
+    }
+}
+//# sourceMappingURL=tracing.js.map

package/dist/lib/tracing.js.map

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

package/dist/lib/wait.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wait.d.ts","sourceRoot":"","sources":["../../src/lib/wait.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAC7B,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,MAAM,MAAM,SAAS,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;AAEhE,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,aAAa;IAMtB,OAAO,CAAC,MAAM;IALhB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,UAAU,CAAC,CAAS;gBAGlB,MAAM,EAAE,MAAM,EACtB,gBAAgB,CAAC,EAAE,MAAM,GAAG,WAAW,EACvC,UAAU,CAAC,EAAE,MAAM;IAYf,KAAK,CAAC,CAAC,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;CAoBtE;AAOD,eAAO,MAAM,KAAK;8BACU,EAAE,MAAY,QAAQ,MAAM;6BAI7B,EAAE,MAAY,QAAQ,MAAM;gCASzB,EAAE,MAAY,QAAQ,MAAM;+BAS7B,EAAE,GAAG,UAAU,MAAY,QAAQ,MAAM;kCAUtC,EAAE,GAAG,UAAU,MAAY,QAAQ,MAAM;CAaxE,CAAC"}
+{"version":3,"file":"wait.d.ts","sourceRoot":"","sources":["../../src/lib/wait.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAC7B,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAG7C,MAAM,MAAM,SAAS,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;AAEhE,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,aAAa;IAMtB,OAAO,CAAC,MAAM;IALhB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,UAAU,CAAC,CAAS;gBAGlB,MAAM,EAAE,MAAM,EACtB,gBAAgB,CAAC,EAAE,MAAM,GAAG,WAAW,EACvC,UAAU,CAAC,EAAE,MAAM;IAYf,KAAK,CAAC,CAAC,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;CA8BtE;AAOD,eAAO,MAAM,KAAK;8BACU,EAAE,MAAY,QAAQ,MAAM;6BAI7B,EAAE,MAAY,QAAQ,MAAM;gCASzB,EAAE,MAAY,QAAQ,MAAM;+BAS7B,EAAE,GAAG,UAAU,MAAY,QAAQ,MAAM;kCAUtC,EAAE,GAAG,UAAU,MAAY,QAAQ,MAAM;CAaxE,CAAC"}

package/dist/lib/wait.js

@@ -1,4 +1,5 @@
 import { WebElement } from './webelement.js';
+import { CraftdriverError, ErrorCode } from './errors.js';
 export class WebDriverWait {
     driver;
     timeoutMs;
@@ -33,7 +34,19 @@ export class WebDriverWait {
             await new Promise((r) => setTimeout(r, this.intervalMs));
         }
         const errMsg = message ?? this.timeoutMsg ?? `Wait timed out after ${this.timeoutMs}ms`;
-        throw new Error(lastErr ? `${errMsg}: ${String(lastErr?.message ?? lastErr)}` : errMsg);
+        const full = lastErr ? `${errMsg}: ${String(lastErr?.message ?? lastErr)}` : errMsg;
+        // Preserve a more specific code when the inner condition already raised one.
+        if (CraftdriverError.is(lastErr)) {
+            throw new CraftdriverError(lastErr.code, full, {
+                detail: { ...(lastErr.detail ?? {}), timeout: this.timeoutMs },
+                cause: lastErr,
+                hint: lastErr.hint,
+            });
+        }
+        throw new CraftdriverError(ErrorCode.TIMEOUT, full, {
+            detail: { timeout: this.timeoutMs },
+            cause: lastErr,
+        });
     }
 }
 async function resolveElement(driver, target) {

package/dist/lib/wait.js.map

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

package/dist/lib/webelement.d.ts

@@ -1,4 +1,5 @@
 import type { WebDriverEndpoint } from './types.js';
+import { By } from './by.js';
 export declare const W3C_ELEMENT_KEY = "element-6066-11e4-a52e-4f735466cecf";
 export declare const LEGACY_ELEMENT_KEY = "ELEMENT";
 export declare class WebElement {
@@ -28,5 +29,6 @@ export declare class WebElement {
         width: number;
         height: number;
     }>;
+    findElements(locator: By): Promise<WebElement[]>;
 }
 //# sourceMappingURL=webelement.d.ts.map

package/dist/lib/webelement.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"webelement.d.ts","sourceRoot":"","sources":["../../src/lib/webelement.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAmB,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAErE,eAAO,MAAM,eAAe,wCAAwC,CAAC;AACrE,eAAO,MAAM,kBAAkB,YAAY,CAAC;AAE5C,qBAAa,UAAU;IAEnB,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,SAAS;IACjB,OAAO,CAAC,SAAS;gBAFT,QAAQ,EAAE,iBAAiB,EAC3B,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM;IAG3B,KAAK,IAAI,MAAM;IAIT,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAStB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUrC,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC;IAUhC,MAAM;;;;IAIA,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAU/B,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC;IAUnC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAStB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAUlD,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAU3C,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;IAU7B,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC;IAU9B,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;IAU7B,OAAO,IAAI,OAAO,CAAC;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CASlF"}
+{"version":3,"file":"webelement.d.ts","sourceRoot":"","sources":["../../src/lib/webelement.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAmB,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACrE,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAE7B,eAAO,MAAM,eAAe,wCAAwC,CAAC;AACrE,eAAO,MAAM,kBAAkB,YAAY,CAAC;AAE5C,qBAAa,UAAU;IAEnB,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,SAAS;IACjB,OAAO,CAAC,SAAS;gBAFT,QAAQ,EAAE,iBAAiB,EAC3B,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM;IAG3B,KAAK,IAAI,MAAM;IAIT,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAStB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUrC,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC;IAUhC,MAAM;;;;IAIA,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAU/B,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC;IAUnC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAStB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAUlD,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAU3C,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;IAU7B,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC;IAU9B,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;IAU7B,OAAO,IAAI,OAAO,CAAC;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAU3E,YAAY,CAAC,OAAO,EAAE,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;CAiBvD"}

package/dist/lib/webelement.js

@@ -122,5 +122,23 @@ export class WebElement {
         const value = res?.value ?? res;
         return value;
     }
+    async findElements(locator) {
+        const client = new HttpClient(this.endpoint);
+        const res = await client.send({
+            method: 'POST',
+            path: `/session/${this.sessionId}/element/${this.elementId}/elements`,
+            body: { using: locator.using, value: locator.value },
+        });
+        const arr = (res?.value ??
+            res);
+        return (arr || [])
+            .map((v) => {
+            const elId = v?.[W3C_ELEMENT_KEY] || v?.[LEGACY_ELEMENT_KEY];
+            if (!elId)
+                return undefined;
+            return new WebElement(this.endpoint, this.sessionId, elId);
+        })
+            .filter(Boolean);
+    }
 }
 //# sourceMappingURL=webelement.js.map

package/dist/lib/webelement.js.map

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

package/docs/accessibility.md

@@ -0,0 +1,177 @@
+# Accessibility audits
+
+`craftdriver` wraps [axe-core](https://github.com/dequelabs/axe-core) so
+you can assert WCAG compliance with the same fluency as any other
+action — at the page, element, or locator level.
+
+axe-core ships with craftdriver — no extra install. Works out of the box.
+
+```ts
+import { Browser } from 'craftdriver';
+
+const browser = await Browser.launch({ browserName: 'chrome' });
+await browser.navigateTo('https://example.com');
+
+await browser.a11y.check();         // throws on any serious+ violation
+const report = await browser.a11y.audit(); // returns the raw report
+console.log(report.violations);
+await browser.quit();
+```
+
+Check a page is clean except for known colour-contrast issues:
+
+```ts
+await browser.a11y.check({ disableRules: ['color-contrast'] });
+```
+
+## Finding rule IDs
+
+Rule IDs like `color-contrast`, `image-alt`, `button-name` come from
+axe-core. Look them up here:
+
+- [Deque — full rule catalogue](https://dequeuniversity.com/rules/axe/) — the
+  authoritative list, with WCAG mapping and remediation guidance per rule.
+- [axe-core rule descriptions](https://github.com/dequelabs/axe-core/blob/develop/doc/rule-descriptions.md) —
+  one-line summary per rule, grouped by WCAG level.
+- Every `A11yViolation` returned by `audit()` carries a `helpUrl` pointing
+  straight at the relevant Deque page — copy the rule ID from there.
+
+## Ignoring rules (you will have violations — this is how you manage them)
+
+Most production pages have known, deliberate axe-core violations:
+third-party widgets with poor contrast, brand colours that miss AAA,
+decorative images without alt. Three escalating shapes are supported,
+in order of how often you'll reach for them.
+
+### 1. The common case — a project-wide constant
+
+```ts
+// a11y-config.ts
+export const PROJECT_A11Y = {
+  disableRules: ['color-contrast', 'region', 'landmark-one-main'],
+};
+
+// in your test
+import { PROJECT_A11Y } from './a11y-config';
+await browser.a11y.check(PROJECT_A11Y);
+```
+
+A flat `string[]` of rule IDs is what teams actually maintain in
+version control.
+
+### 2. Per-test override — extend the constant ad-hoc
+
+```ts
+await browser.a11y.check({
+  ...PROJECT_A11Y,
+  disableRules: [...PROJECT_A11Y.disableRules, 'aria-allowed-attr'],
+});
+```
+
+Plain object spread — no hidden state, no setter.
+
+### 3. Escape hatch — raw axe-core options
+
+```ts
+await browser.a11y.check({
+  axeOptions: { rules: { 'color-contrast': { enabled: false } } },
+});
+```
+
+`axeOptions` is merged last and wins over anything else. Use it when
+you need exotic axe configuration (custom rule sets, locale, etc.).
+
+## Filtering by impact
+
+Default reports only include `serious` and `critical` violations.
+Tune the threshold per call:
+
+```ts
+// CI gate: only fail PRs on critical issues
+await browser.a11y.check({ minImpact: 'critical' });
+
+// Debug everything
+const report = await browser.a11y.audit({ minImpact: 'minor' });
+```
+
+## Scoping to an element
+
+Both `ElementHandle` and `Locator` expose `.a11y`. The audit context
+is restricted to the resolved element and its descendants — perfect
+for asserting that *the modal you just opened* is clean even if the
+rest of the page has known issues.
+
+```ts
+await browser.click('#open-settings');
+await browser.find('#settings-modal').a11y.check({
+  disableRules: ['color-contrast'], // brand teal misses AA, known
+});
+
+// Locator form — re-resolves on every call
+const dialog = browser.locator('[role="dialog"]');
+const report = await dialog.a11y.audit();
+expect(report.violations).toHaveLength(0);
+```
+
+## Inspecting violations programmatically
+
+`audit()` returns:
+
+```ts
+interface A11yResult {
+  violations: A11yViolation[];
+  passes: number;        // count, not the full list
+  incomplete: number;
+  inapplicable: number;
+}
+
+interface A11yViolation {
+  id: string;            // e.g. 'color-contrast'
+  impact: 'minor' | 'moderate' | 'serious' | 'critical';
+  description: string;
+  helpUrl: string;
+  nodes: Array<{ target: string[]; html: string; failureSummary: string }>;
+}
+```
+
+`check()` throws an `A11yError` whose `.violations` and `.result`
+fields carry the full report:
+
+```ts
+import { A11yError } from 'craftdriver';
+
+try {
+  await browser.a11y.check();
+} catch (e) {
+  if (e instanceof A11yError) {
+    for (const v of e.violations) {
+      console.error(`${v.id} (${v.impact}) — ${v.helpUrl}`);
+    }
+  }
+  throw e;
+}
+```
+
+## CI patterns
+
+Save the full report as a build artefact and gate PRs on
+critical/serious only:
+
+```ts
+import { writeFileSync } from 'node:fs';
+
+const report = await browser.a11y.audit({ minImpact: 'minor' });
+writeFileSync('a11y-report.json', JSON.stringify(report, null, 2));
+
+// Gate the run on the serious+ subset
+await browser.a11y.check({ minImpact: 'serious', ...PROJECT_A11Y });
+```
+
+## How it works (one paragraph)
+
+On the first audit, `axe-core` is lazily imported from your
+`node_modules` and its `.source` is injected into the page (guarded by
+a `window` flag so subsequent audits in the same document skip the
+inject step). The audit itself uses Classic WebDriver
+`execute/async` so the underlying `axe.run()` promise is awaited
+before the result is shipped back — works with or without BiDi.

package/docs/api-reference.md

@@ -0,0 +1,71 @@
+# API reference
+
+Every symbol re-exported from [`src/index.ts`](../src/index.ts). One row per export.
+Generated by `scripts/gen-api-reference.mjs` — do not edit by hand.
+
+Run `npm run docs:api` to regenerate. CI fails when this file is out of date.
+
+| Symbol | Kind | Summary | Docs |
+|---|---|---|---|
+| `A11y` | class | Ergonomic wrapper around axe-core. Obtain instances via the `.a11y` accessor on `Browser`, `ElementHandle`, or `Locator` — never construct directly. | [accessibility](accessibility.md) |
+| `A11yError` | class | Thrown by `A11y.check()` when violations are found. | [accessibility](accessibility.md) |
+| `A11yImpact` | type | Severity buckets reported by axe-core. | [accessibility](accessibility.md) |
+| `A11yOptions` | type | — | [accessibility](accessibility.md) |
+| `A11yResult` | type | — | [accessibility](accessibility.md) |
+| `A11yViolation` | type | — | [accessibility](accessibility.md) |
+| `A11yViolationNode` | type | — | [accessibility](accessibility.md) |
+| `Browser` | class | — | [browser-api](browser-api.md) |
+| `BrowserContext` | class | — | [browser-context](browser-context.md) |
+| `BrowserContextConfig` | type | Per-context options stored at creation time. | [browser-context](browser-context.md) |
+| `BrowserContextHooks` | type | Internal hooks the owning {@link Browser } passes to a new context. | [browser-context](browser-context.md) |
+| `By` | class | — | [selectors](selectors.md) |
+| `ChromeService` | class | — | [getting-started](getting-started.md) |
+| `ChromeServiceOptions` | type | — | [getting-started](getting-started.md) |
+| `ClearCookiesFilter` | type | Filter applied to {@link BrowserContext.clearCookies}. | [browser-context](browser-context.md) |
+| `Clock` | class | Controls the virtual clock inside the browser page. | [clock](clock.md) |
+| `ClockInstallOptions` | type | Options for {@link Clock.install}. | [clock](clock.md) |
+| `ClockTime` | type | Accepted forms for a point in time. | [clock](clock.md) |
+| `ConsoleMessage` | type | — | [bidi-features](bidi-features.md) |
+| `ContextStorageStateOptions` | type | Options for {@link BrowserContext.storageState}. | [browser-context](browser-context.md) |
+| `Cookie` | type | — | [bidi-features](bidi-features.md) |
+| `CookieInput` | type | — | [bidi-features](bidi-features.md) |
+| `CraftdriverError` | class | Base class for every error thrown from the public API. | [error-codes](error-codes.md) |
+| `CraftdriverErrorOptions` | type | — | [error-codes](error-codes.md) |
+| `DeviceMetrics` | type | Device metrics for custom mobile emulation | [browser-api](browser-api.md) |
+| `DeviceName` | type | — | [browser-api](browser-api.md) |
+| `devices` | const | Common mobile device presets | [browser-api](browser-api.md) |
+| `Dialog` | type | Represents an open browser dialog (alert / confirm / prompt). Passed to handlers registered with `browser.onDialog()`. | [browser-api](browser-api.md) |
+| `DialogType` | type | The type of a browser dialog. | [browser-api](browser-api.md) |
+| `Download` | type | A file downloaded during a `waitForDownload()` call. | [browser-api](browser-api.md) |
+| `EmulateOptions` | type | Options for {@link Browser.emulate}. Every field is independent; only the keys you pass are applied, others stay at their previous value. Passing `null` for a field clears the override for that field. | [browser-api](browser-api.md) |
+| `ErrorCode` | const | Stable, machine-readable error codes for the public craftdriver API. | [error-codes](error-codes.md) |
+| `ErrorCodeName` | type | — | [error-codes](error-codes.md) |
+| `ErrorCodeValue` | type | — | [error-codes](error-codes.md) |
+| `FirefoxService` | class | — | [getting-started](getting-started.md) |
+| `FirefoxServiceOptions` | type | — | [getting-started](getting-started.md) |
+| `Frame` | class | — | [browser-api](browser-api.md) |
+| `InitScriptHandle` | type | A handle returned by {@link BrowserContext.addInitScript}. | [browser-context](browser-context.md) |
+| `InterceptedRequest` | type | — | [bidi-features](bidi-features.md) |
+| `InterceptedResponse` | type | — | [bidi-features](bidi-features.md) |
+| `JavaScriptError` | type | — | [bidi-features](bidi-features.md) |
+| `Key` | const | — | [keyboard-mouse](keyboard-mouse.md) |
+| `Keyboard` | class | — | [keyboard-mouse](keyboard-mouse.md) |
+| `LaunchOptions` | type | — | [browser-api](browser-api.md) |
+| `LoadState` | type | When to consider a navigation complete. - `'load'` — page `load` event has fired (default) - `'domcontentloaded'` — `DOMContentLoaded` has fired (faster, no waiting for images/fonts) - `'networkidle'` — `load` + no in-flight requests for 500 ms - `'none'` — do not wait; return as soon as the navigation is initiated | [browser-api](browser-api.md) |
+| `Locator` | class | — | [selectors](selectors.md) |
+| `LogMessage` | type | — | [bidi-features](bidi-features.md) |
+| `LogMonitor` | class | — | [bidi-features](bidi-features.md) |
+| `MobileEmulation` | type | Mobile emulation configuration | [browser-api](browser-api.md) |
+| `MockResponse` | type | — | [bidi-features](bidi-features.md) |
+| `Mouse` | class | — | [keyboard-mouse](keyboard-mouse.md) |
+| `NetworkInterceptor` | class | — | [bidi-features](bidi-features.md) |
+| `Page` | class | — | [browser-api](browser-api.md) |
+| `RoutePattern` | type | Pattern accepted by {@link BrowserContext.route}. Same shape as the browser-level interceptor. | [browser-context](browser-context.md) |
+| `SessionState` | type | — | [bidi-features](bidi-features.md) |
+| `SessionStateManager` | class | — | [bidi-features](bidi-features.md) |
+| `StorageStateOptions` | type | — | [bidi-features](bidi-features.md) |
+| `TraceEvent` | type | — | [tracing](tracing.md) |
+| `TraceScreenshotMode` | type | Screenshot mode for tracing. | [tracing](tracing.md) |
+| `TraceStartOptions` | type | — | [tracing](tracing.md) |
+
+Total exports: **60**.