@okent/accessibility-scanner-keyboard-plugin 0.0.0-stage → 0.1.1

package/LICENSE

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

package/README.md

@@ -1,3 +1,123 @@
-# Temporary Holding Version
+# Keyboard probe plugin for github/accessibility-scanner
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A plugin for [GitHub's accessibility scanner](https://github.com/github/accessibility-scanner)
+that walks the real Tab order of each page and reports the keyboard failures a
+rule engine inspecting the DOM at rest cannot see. It is a TypeScript port of
+the keyboard probe in accessibility-tooling, an ACR toolkit, with the same rules, the
+same thresholds, and the same refusal to treat a clean walk as a pass.
+
+| Rule | Criterion | Asserts |
+|---|---|---|
+| `keyboard-trap` | 2.1.2 No Keyboard Trap | failure: Tab cycles inside a subset of the page and Escape does not release it |
+| `keyboard-unreachable` | 2.1.1 Keyboard | failure: a visible interactive element never receives focus during a complete walk |
+| `focus-not-visible` | 2.4.7 Focus Visible | failure: screenshots of an element focused and unfocused are pixel-identical (text-entry elements are flagged for review instead, since the caret may be the only indicator and screenshots do not capture it) |
+| `focus-order-vs-dom` | 2.4.3 Focus Order | review only: the Tab order jumps backwards through the DOM, usually a positive `tabindex` |
+
+Review-only findings carry a `needs review:` prefix in the issue title, the
+convention the scanner's own reflow plugin uses.
+
+## What a finding does and does not mean
+
+A detected failure is real evidence: the trap was walked into and Escape was
+pressed, the control was never focused across a complete walk, the pixels did
+not change. A clean walk proves nothing. The page may trap focus under a key
+the probe never presses, a control may be reachable only through a shortcut
+the probe does not know, and an indicator that is present may still be too
+faint to see. Treat silence from this plugin as "not detected", never as
+"conforms".
+
+Two limits are logged rather than reported, because the scanner has no
+info-level finding:
+
+- **Iframes are not entered.** Their contents are not walked. The log line
+  says how many frames were skipped.
+- **Closed shadow roots are invisible.** Open shadow roots are walked through
+  the composed tree and their controls are named with `>>>` selectors.
+
+## Use
+
+### As an npm plugin
+
+Once the package is on the scanner's npm allowlist:
+
+```yaml
+- uses: github/accessibility-scanner@v3
+  with:
+    scans: |
+      ["axe", {"name": "keyboard-scan", "package": "@okent/accessibility-scanner-keyboard-plugin", "version": "0.1.0"}]
+```
+
+### As a local plugin
+
+Copy this folder to `.github/scanner-plugins/keyboard-scan/` in the repository
+that runs the workflow, check the repository out before the scanner step, and
+list the plugin by name. The scanner bundles `index.ts` with esbuild at run
+time. There are no runtime dependencies to install; Playwright comes from the
+scanner.
+
+```yaml
+steps:
+  - uses: actions/checkout@v6
+  - uses: github/accessibility-scanner@v3
+    with:
+      scans: '["axe", "keyboard-scan"]'
+```
+
+### Configuration
+
+Optional, at `.github/scanner-plugins/keyboard-scan/config.json`:
+
+```json
+{
+  "stepDelayMs": 60,
+  "maxShots": 40,
+  "maxUnreachable": 8
+}
+```
+
+`stepDelayMs` is the wait after each Tab press before focus is read; raise it
+for pages with slow focus handlers. `maxShots` caps the per-page focus
+screenshots, which bound the run time of the visibility check. `maxUnreachable`
+caps individual unreachable-element findings per page; the rest are folded
+into one summary finding.
+
+## How it works
+
+1. Enumerate candidate controls in the composed tree, scoped to the open modal
+   if one is visible, skipping anything hidden, inert, disabled or
+   `aria-hidden`.
+2. Blur, then press Tab repeatedly, recording which candidate holds focus after
+   each press and screenshotting each newly focused element with a 12px
+   margin.
+3. When the sequence repeats with a full period twice, press Escape. If focus
+   leaves the cycle the container was dismissible and the walk continues. If
+   Escape closed the container, the page has changed under the walk and it
+   stops. Otherwise it is a trap, reported once by its common ancestor, and
+   the walk continues from the next focusable element with that jump marked
+   so it is not counted as an order divergence.
+4. After a complete walk, report candidates that were never focused, except
+   those reachable through a focused ancestor or descendant, radio-group
+   members whose group was reached, and roving-tabindex composite members whose
+   composite was reached. Nothing past a trap is judged.
+5. Report backwards jumps in the first-visit order, excluding jumps the probe
+   made itself.
+6. Blur and re-screenshot each captured element unfocused. Identical bytes mean
+   focus produced no visible change.
+
+## Development
+
+```
+npm install
+npx playwright install chromium
+npm test          # unit tests for the walk analysis, plus an end-to-end run
+                  # against test/fixtures/demo.html
+npm run build
+```
+
+The end-to-end test asserts that every keyboard defect planted in the
+fixture is found and that its control cases stay silent. The
+fixture's header comment lists what is planted.
+
+## License
+
+MIT.

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+import type { Page } from 'playwright';
+import { type ProbeFinding } from './src/probe.js';
+export declare const name = "keyboard-scan";
+/** The scanner's Finding input, as its plugin docs define it. */
+export type FindingInput = {
+    scannerType: string;
+    category?: 'wcag' | 'best-practice' | 'experimental';
+    ruleId?: string;
+    url: string;
+    html?: string;
+    problemShort: string;
+    problemUrl: string;
+    solutionShort: string;
+    solutionLong?: string;
+};
+export type PluginParams = {
+    page: Page;
+    addFinding: (finding: FindingInput) => Promise<void>;
+};
+/** Shape one probe result into the scanner's Finding. Exported for tests. */
+export declare function toFinding(f: ProbeFinding, url: string): FindingInput;
+export default function keyboardScan({ page, addFinding }: PluginParams): Promise<void>;

package/dist/index.js

@@ -0,0 +1,71 @@
+// Keyboard probe plugin for github/accessibility-scanner.
+//
+// The scanner's engines inspect the DOM at rest. The failures that lock
+// keyboard users out are behavioural: focus enters a widget and never leaves,
+// a click-only control never receives focus at all, the focus indicator was
+// styled away. This plugin drives the keyboard for real and reports exactly
+// those, as a port of the keyboard probe in owenpkent/accessibility-tooling.
+//
+//   keyboard-trap        Tab cycles inside a subset of the page and Escape
+//                        does not release it                     -> 2.1.2
+//   keyboard-unreachable a visible interactive element is never focusable
+//                                                                -> 2.1.1
+//   focus-not-visible    focused and unfocused screenshots of an element are
+//                        pixel-identical                          -> 2.4.7
+//                        (text-entry elements are flagged for review instead)
+//   focus-order-vs-dom   the Tab order jumps backwards through the DOM
+//                                                                -> 2.4.3, review
+//
+// A detected failure is real evidence. A clean walk proves nothing: the page
+// may still trap focus under a key the probe never pressed, and a present
+// indicator may still be too faint to see.
+import { loadConfig } from './src/config.js';
+import { probePage } from './src/probe.js';
+import { RULES } from './src/rules.js';
+export const name = 'keyboard-scan';
+/** Shape one probe result into the scanner's Finding. Exported for tests. */
+export function toFinding(f, url) {
+    const rule = RULES[f.ruleId];
+    // The scanner has no confidence field. Its own reflow plugin marks a
+    // review-only finding with this prefix, so the issue title says so too.
+    const prefix = f.confidence === 'review' ? 'needs review: ' : '';
+    const occurrences = f.occurrences > 1 ? ` (${f.occurrences} occurrences)` : '';
+    return {
+        scannerType: name,
+        category: 'wcag',
+        ruleId: f.ruleId,
+        url,
+        html: f.html,
+        problemShort: `${prefix}${rule.problemShort}${occurrences}`,
+        problemUrl: rule.problemUrl,
+        solutionShort: rule.solutionShort,
+        solutionLong: `WCAG 2.2 ${rule.wcagSc}. Selector: \`${f.selector}\`\n\n${f.detail}`,
+    };
+}
+export default async function keyboardScan({ page, addFinding }) {
+    const cfg = loadConfig();
+    const url = page.url();
+    const { findings, notes } = await probePage(page, cfg);
+    if (notes.shadowRootsTraversed) {
+        console.info(`[keyboard-scan] ${url}: ${notes.shadowRootsTraversed} open shadow root(s) traversed`);
+    }
+    if (notes.framesNotWalked) {
+        // Silence about a page says nothing about its frames; say so where the
+        // run log is read, since the scanner has no info-level finding.
+        console.warn(`[keyboard-scan] ${url}: ${notes.framesNotWalked} iframe(s) NOT walked; ` +
+            `Tab order, traps and focus indicators inside them were not checked`);
+    }
+    if (notes.dismissed) {
+        console.warn(`[keyboard-scan] ${url}: Escape closed a container mid-walk, so the walk stopped there; ` +
+            `reachability and focus visibility were not judged on this page`);
+    }
+    else if (!notes.walkComplete && !notes.trapsFound) {
+        console.warn(`[keyboard-scan] ${url}: the walk did not complete; reachability was not judged`);
+    }
+    for (const f of findings) {
+        await addFinding(toFinding(f, url));
+    }
+    console.info(`[keyboard-scan] ${url}: ${notes.candidates} candidate(s), ` +
+        `${findings.filter(f => f.confidence === 'violation').length} violation(s), ` +
+        `${findings.filter(f => f.confidence === 'review').length} flagged for review`);
+}

package/dist/src/config.d.ts

@@ -0,0 +1,16 @@
+export type ProbeConfig = {
+    /** ms to wait after each Tab press before reading focus. */
+    stepDelayMs: number;
+    /** Cap on per-element focus screenshots per page. */
+    maxShots: number;
+    /** Cap on individual unreachable-element findings per page. */
+    maxUnreachable: number;
+};
+export declare const DEFAULTS: ProbeConfig;
+/**
+ * Optional overrides from `.github/scanner-plugins/keyboard-scan/config.json`
+ * in the repository the workflow runs from, which is where the scanner's own
+ * plugins read theirs. A missing or malformed file falls back to the defaults;
+ * unknown keys and non-numeric values are ignored and logged.
+ */
+export declare function loadConfig(cwd?: string): ProbeConfig;

package/dist/src/config.js

@@ -0,0 +1,41 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+export const DEFAULTS = {
+    stepDelayMs: 60,
+    maxShots: 40,
+    maxUnreachable: 8,
+};
+/**
+ * Optional overrides from `.github/scanner-plugins/keyboard-scan/config.json`
+ * in the repository the workflow runs from, which is where the scanner's own
+ * plugins read theirs. A missing or malformed file falls back to the defaults;
+ * unknown keys and non-numeric values are ignored and logged.
+ */
+export function loadConfig(cwd = process.cwd()) {
+    const file = path.join(cwd, '.github', 'scanner-plugins', 'keyboard-scan', 'config.json');
+    const out = { ...DEFAULTS };
+    if (!fs.existsSync(file))
+        return out;
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch (e) {
+        console.warn(`[keyboard-scan] ignoring malformed ${file}: ${e}`);
+        return out;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return out;
+    for (const [key, value] of Object.entries(parsed)) {
+        if (!(key in DEFAULTS)) {
+            console.warn(`[keyboard-scan] ignoring unknown config key ${key}`);
+            continue;
+        }
+        if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+            console.warn(`[keyboard-scan] ignoring non-numeric config value for ${key}`);
+            continue;
+        }
+        out[key] = value;
+    }
+    return out;
+}

package/dist/src/probe.d.ts

@@ -0,0 +1,33 @@
+import type { Page } from 'playwright';
+import { type RuleId } from './rules.js';
+import type { ProbeConfig } from './config.js';
+/** One probe result before it is shaped into the scanner's Finding. */
+export type ProbeFinding = {
+    ruleId: RuleId;
+    confidence: 'violation' | 'review';
+    selector: string;
+    html: string;
+    detail: string;
+    occurrences: number;
+};
+/** Facts about the walk that are not findings but that a reader must know. */
+export type ProbeNotes = {
+    shadowRootsTraversed: number;
+    framesNotWalked: number;
+    candidates: number;
+    walkComplete: boolean;
+    trapsFound: number;
+    dismissed: boolean;
+};
+/**
+ * Walk the real Tab order of the page as it currently stands and report what
+ * a rule engine inspecting the DOM at rest cannot see. The page is left with
+ * focus wherever the walk ended; callers that run other scans afterwards
+ * should not depend on focus position.
+ */
+export declare function probePage(page: Page, cfg: ProbeConfig): Promise<{
+    findings: ProbeFinding[];
+    notes: ProbeNotes;
+}>;
+/** The criterion a rule supplies evidence for, for callers shaping output. */
+export declare function criterionFor(ruleId: RuleId): string;

package/dist/src/probe.js

@@ -0,0 +1,299 @@
+import { RULES } from './rules.js';
+import { detectCycle, isPositiveTabindex, nextFocusableAfter, orderDivergences, unreachableCandidates, } from './walk.js';
+import * as S from './scripts.js';
+// Padding around an element's box when screenshotting it, so outlines and
+// shadows drawn outside the border box are inside the frame. An indicator
+// offset further out than this is invisible to the comparison, which errs
+// toward missing a defect rather than inventing one.
+const SHOT_PAD = 12;
+// Node Playwright evaluates a string as an expression and does not call it
+// with an argument, so wrap the arrow-function source in a call with the
+// argument inlined. Arguments here are small: indices and index lists.
+function evalScript(page, script, arg) {
+    const call = arg === undefined ? `(${script})()` : `(${script})(${JSON.stringify(arg)})`;
+    return page.evaluate(call);
+}
+/**
+ * Screenshot the focused element's neighbourhood, viewport-relative.
+ *
+ * Returns null when the element is offscreen: comparing frames that show
+ * other content would manufacture false verdicts, and a missed comparison
+ * only costs a detection, never invents one.
+ */
+async function captureFocused(page, idx) {
+    const r = await evalScript(page, S.RECT, idx);
+    const x = Math.max(r.x - SHOT_PAD, 0);
+    const y = Math.max(r.y - SHOT_PAD, 0);
+    const w = Math.min(r.x + r.w + SHOT_PAD, r.vw) - x;
+    const h = Math.min(r.y + r.h + SHOT_PAD, r.vh) - y;
+    if (w < 4 || h < 4)
+        return null;
+    const clip = { x, y, width: w, height: h };
+    try {
+        const png = await page.screenshot({ clip, animations: 'disabled' });
+        return { clip, sx: r.sx, sy: r.sy, png };
+    }
+    catch {
+        return null;
+    }
+}
+function sameMembers(a, b) {
+    if (a.length !== b.length)
+        return false;
+    const sa = new Set(a);
+    return b.every(v => sa.has(v));
+}
+/**
+ * Walk the real Tab order of the page as it currently stands and report what
+ * a rule engine inspecting the DOM at rest cannot see. The page is left with
+ * focus wherever the walk ended; callers that run other scans afterwards
+ * should not depend on focus position.
+ */
+export async function probePage(page, cfg) {
+    const findings = [];
+    const cands = await evalScript(page, S.ENUMERATE);
+    const shadowRootsTraversed = await evalScript(page, S.SHADOW_COUNT);
+    const framesNotWalked = await evalScript(page, S.FRAME_COUNT);
+    const notes = {
+        shadowRootsTraversed,
+        framesNotWalked,
+        candidates: cands.length,
+        walkComplete: false,
+        trapsFound: 0,
+        dismissed: false,
+    };
+    if (!cands.length)
+        return { findings, notes };
+    const n = cands.length;
+    await evalScript(page, S.BLUR);
+    const visited = new Set();
+    const firstVisit = [];
+    const barriers = new Set();
+    let seq = [];
+    const shots = new Map();
+    const traps = [];
+    const escapedCycles = [];
+    let dismissed = false;
+    let walkComplete = false;
+    let stray = 0;
+    let wraps = 0;
+    const maxSteps = 2 * n + 15;
+    let step = 0;
+    const noteVisit = async (idx) => {
+        if (idx >= 0 && !visited.has(idx)) {
+            visited.add(idx);
+            firstVisit.push(idx);
+            if (shots.size < cfg.maxShots) {
+                const shot = await captureFocused(page, idx);
+                if (shot)
+                    shots.set(idx, shot);
+            }
+        }
+    };
+    while (step < maxSteps) {
+        step++;
+        await page.keyboard.press('Tab');
+        await page.waitForTimeout(cfg.stepDelayMs);
+        const info = await evalScript(page, S.ACTIVE);
+        if (info.wrapped) {
+            // The walk does not necessarily start at the top of the page. One more
+            // pass picks up whatever came before the starting point; a second wrap
+            // means everything reachable has been seen.
+            wraps++;
+            const unvisitedFocusable = cands.some(c => c.focusable && !visited.has(c.i));
+            if (wraps >= 2 || !unvisitedFocusable) {
+                walkComplete = true;
+                break;
+            }
+            barriers.add(firstVisit.length);
+            seq = [];
+            continue;
+        }
+        const idx = info.idx;
+        seq.push(idx);
+        if (idx < 0) {
+            // Focus is somewhere the enumeration cannot see. Tolerate a stretch of
+            // it; give up honestly rather than loop forever.
+            stray++;
+            if (stray > 25)
+                break;
+            continue;
+        }
+        stray = 0;
+        await noteVisit(idx);
+        const cyc = detectCycle(seq);
+        if (!cyc || escapedCycles.some(e => sameMembers(e, cyc)))
+            continue;
+        if (new Set(cyc).size >= n) {
+            // The whole page cycling is wrap behaviour, not a trap.
+            walkComplete = true;
+            break;
+        }
+        if (cyc.every(i => cands[i].tag === 'iframe' || cands[i].tag === 'frame')) {
+            // Focus is progressing inside an embedded document; from out here it
+            // looks stationary. Step past it and keep walking.
+            const nxt = nextFocusableAfter(cands, Math.max(...cyc), visited);
+            if (nxt === null) {
+                walkComplete = true;
+                break;
+            }
+            await evalScript(page, S.FOCUS, nxt);
+            barriers.add(firstVisit.length);
+            seq = [];
+            continue;
+        }
+        // Candidate trap. The one exit a probe can honestly press is Escape: if
+        // that releases focus, this is a dismissible container behaving itself.
+        await page.keyboard.press('Escape');
+        await page.waitForTimeout(120);
+        await page.keyboard.press('Tab');
+        await page.waitForTimeout(cfg.stepDelayMs);
+        const info2 = await evalScript(page, S.ACTIVE);
+        if (info2.wrapped || !cyc.includes(info2.idx)) {
+            const stillVisible = await evalScript(page, S.ALL_VISIBLE, cyc);
+            if (!stillVisible) {
+                // Escape closed the container. The page has mutated under the walk,
+                // so stop here; stale geometry is not evidence.
+                dismissed = true;
+                break;
+            }
+            escapedCycles.push(cyc);
+            seq = [];
+            if (!info2.wrapped) {
+                barriers.add(firstVisit.length);
+                await noteVisit(info2.idx);
+            }
+            continue;
+        }
+        traps.push(cyc);
+        const anc = await evalScript(page, S.COMMON_ANCESTOR, cyc);
+        const members = cyc.map(i => `\`${cands[i].selector}\``).join(', ');
+        findings.push({
+            ruleId: 'keyboard-trap',
+            confidence: 'violation',
+            selector: anc.selector,
+            html: anc.html,
+            detail: `Tab cycles between ${members} and never leaves. Escape was pressed and did not ` +
+                `release focus. Keyboard and switch users cannot reach anything after this point; ` +
+                `the rest of this walk was continued by moving focus programmatically, which a user cannot do.`,
+            occurrences: 1,
+        });
+        const nxt = nextFocusableAfter(cands, Math.max(...cyc), visited);
+        if (nxt === null)
+            break;
+        await evalScript(page, S.FOCUS, nxt);
+        barriers.add(firstVisit.length);
+        seq = [];
+    }
+    notes.walkComplete = walkComplete;
+    notes.trapsFound = traps.length;
+    notes.dismissed = dismissed;
+    // -- reachability ----------------------------------------------------------
+    if ((walkComplete || traps.length) && !dismissed) {
+        const before = traps.length ? Math.min(...traps.map(t => Math.min(...t))) : null;
+        const unvisited = cands.filter(c => !visited.has(c.i)).map(c => c.i);
+        const contained = new Set(unvisited.length
+            ? await evalScript(page, S.CONTAINED, [unvisited, [...visited].sort((a, b) => a - b)])
+            : []);
+        const missed = unreachableCandidates(cands, visited, contained, before);
+        for (const c of missed.slice(0, cfg.maxUnreachable)) {
+            const why = c.tabindex === '-1'
+                ? 'it has tabindex="-1" and no focusable alternative'
+                : !c.focusable
+                    ? 'it is not focusable at all'
+                    : 'the browser never moved focus to it during a complete walk';
+            findings.push({
+                ruleId: 'keyboard-unreachable',
+                confidence: 'violation',
+                selector: c.selector,
+                html: c.html,
+                detail: `This <${c.tag}> looks interactive but never received focus while tabbing through ` +
+                    `the page: ${why}. Its function is unavailable to keyboard and switch users.`,
+                occurrences: 1,
+            });
+        }
+        if (missed.length > cfg.maxUnreachable) {
+            const rest = missed.slice(cfg.maxUnreachable);
+            findings.push({
+                ruleId: 'keyboard-unreachable',
+                confidence: 'violation',
+                selector: rest[0].selector,
+                html: rest[0].html,
+                detail: `${rest.length} further element(s) were never reachable by keyboard on this page. ` +
+                    `First few: ${rest
+                        .slice(0, 5)
+                        .map(c => `\`${c.selector}\``)
+                        .join('; ')}`,
+                occurrences: rest.length,
+            });
+        }
+    }
+    // -- focus order -----------------------------------------------------------
+    const jumps = orderDivergences(firstVisit, barriers);
+    if (jumps.length) {
+        const positive = cands.filter(c => isPositiveTabindex(c.tabindex));
+        const lines = jumps
+            .slice(0, 8)
+            .map(([a, b]) => `- focus moved to \`${cands[b].selector}\` (DOM position ${b}) after ` +
+            `\`${cands[a].selector}\` (DOM position ${a})`);
+        if (positive.length) {
+            lines.push('Elements with a positive tabindex, the usual cause: ' +
+                positive
+                    .slice(0, 5)
+                    .map(c => `\`${c.selector}\``)
+                    .join(', '));
+        }
+        const first = jumps[0][1];
+        findings.push({
+            ruleId: 'focus-order-vs-dom',
+            confidence: 'review',
+            selector: cands[first].selector,
+            html: cands[first].html,
+            detail: 'The Tab order jumps backwards through the document:\n' +
+                lines.join('\n') +
+                '\nWhether this order still preserves meaning and operability is a human judgement; ' +
+                'review it against the visual layout.',
+            occurrences: jumps.length,
+        });
+    }
+    // -- focus visibility ------------------------------------------------------
+    if (shots.size && !dismissed) {
+        await evalScript(page, S.BLUR);
+        await page.waitForTimeout(150);
+        for (const idx of [...shots.keys()].sort((a, b) => a - b)) {
+            const shot = shots.get(idx);
+            await evalScript(page, S.SCROLL_TO, [shot.sx, shot.sy]);
+            await page.waitForTimeout(30);
+            let after;
+            try {
+                after = await page.screenshot({ clip: shot.clip, animations: 'disabled' });
+            }
+            catch {
+                continue;
+            }
+            if (!after.equals(shot.png))
+                continue;
+            const c = cands[idx];
+            findings.push({
+                ruleId: 'focus-not-visible',
+                // The caret, which screenshots do not capture, may be a text field's
+                // only indicator; ask rather than assert.
+                confidence: c.editable ? 'review' : 'violation',
+                selector: c.selector,
+                html: c.html,
+                detail: 'Screenshots of this element focused and unfocused are pixel-identical (including a ' +
+                    'margin around it), so keyboard focus produces no visible change at all.' +
+                    (c.editable
+                        ? ' This is a text-entry element, so the caret, which screenshots do not capture, ' +
+                            'may be its only indicator; review by hand.'
+                        : ' A sighted keyboard user has no way to tell where they are on the page.'),
+                occurrences: 1,
+            });
+        }
+    }
+    return { findings, notes };
+}
+/** The criterion a rule supplies evidence for, for callers shaping output. */
+export function criterionFor(ruleId) {
+    return RULES[ruleId].wcagSc;
+}

package/dist/src/rules.d.ts

@@ -0,0 +1,14 @@
+export type RuleId = 'keyboard-trap' | 'keyboard-unreachable' | 'focus-not-visible' | 'focus-order-vs-dom';
+export type Rule = {
+    /** WCAG 2.2 success criterion the rule supplies evidence for. */
+    wcagSc: string;
+    /** Lower-case fragment that completes "An accessibility scan flagged ... because ...". */
+    problemShort: string;
+    /** The W3C Understanding page. */
+    problemUrl: string;
+    /** Lower-case fragment that completes "To fix this, ...". */
+    solutionShort: string;
+    /** Whether a finding under this rule asserts a failure or only asks for a look. */
+    asserts: 'violation' | 'review';
+};
+export declare const RULES: Record<RuleId, Rule>;

package/dist/src/rules.js

@@ -0,0 +1,43 @@
+// The four rules, and what each one asserts. These mirror lib/probe_rules.py
+// in the parent repository; the reason text is the same so a finding reads
+// the same whichever harness produced it.
+//
+// The asymmetry is the whole design: a detected failure is real evidence of
+// non-conformance, a clean walk is NOT evidence of conformance. Every one of
+// these checks observes a mechanical fragment of a criterion whose full
+// meaning needs a human.
+const UNDERSTANDING = 'https://www.w3.org/WAI/WCAG22/Understanding/';
+export const RULES = {
+    'keyboard-trap': {
+        wcagSc: '2.1.2',
+        problemShort: 'sequential focus enters a set of elements it cannot leave, and Escape does not release it',
+        problemUrl: `${UNDERSTANDING}no-keyboard-trap`,
+        solutionShort: 'make sure focus can always be moved away with Tab or Shift+Tab, or document the exit; ' +
+            'if a widget repurposes Tab, Escape should leave it',
+        asserts: 'violation',
+    },
+    'keyboard-unreachable': {
+        wcagSc: '2.1.1',
+        problemShort: 'a visible interactive element can never receive keyboard focus',
+        problemUrl: `${UNDERSTANDING}keyboard`,
+        solutionShort: 'make every control reachable with the keyboard: use a native button or link, or add ' +
+            'tabindex="0" and key handling to the custom element',
+        asserts: 'violation',
+    },
+    'focus-not-visible': {
+        wcagSc: '2.4.7',
+        problemShort: 'an element shows no visible change at all when it receives keyboard focus',
+        problemUrl: `${UNDERSTANDING}focus-visible`,
+        solutionShort: 'restore a focus indicator (usually the removed outline) or provide a replacement with ' +
+            'sufficient contrast',
+        asserts: 'violation',
+    },
+    'focus-order-vs-dom': {
+        wcagSc: '2.4.3',
+        problemShort: 'the sequential focus order diverges from the DOM order',
+        problemUrl: `${UNDERSTANDING}focus-order`,
+        solutionShort: 'review the Tab order against the visual layout; remove positive tabindex values and ' +
+            'reorder the DOM instead if the order does not preserve meaning',
+        asserts: 'review',
+    },
+};

package/dist/src/scripts.d.ts

@@ -0,0 +1,11 @@
+export declare const ENUMERATE: string;
+export declare const SHADOW_COUNT = "() => {\n\n  const queryAllComposed = (root, selector) => {\n    const out = [];\n    const visit = (node) => {\n      if (node.nodeType !== 1) return;\n      if (node.matches(selector)) out.push(node);\n      if (node.shadowRoot) {\n        for (const child of node.shadowRoot.children) visit(child);\n      }\n      for (const child of node.children) visit(child);\n    };\n    for (const child of root.children) visit(child);\n    if (root.shadowRoot) {\n      for (const child of root.shadowRoot.children) visit(child);\n    }\n    return out;\n  };\n\n  const countShadowRoots = (root) =>\n    queryAllComposed(root, '*').filter((el) => !!el.shadowRoot).length\n    + (root.shadowRoot ? 1 : 0);\n\n  return countShadowRoots(document.body);\n}";
+export declare const FRAME_COUNT = "() => {\n\n  const queryAllComposed = (root, selector) => {\n    const out = [];\n    const visit = (node) => {\n      if (node.nodeType !== 1) return;\n      if (node.matches(selector)) out.push(node);\n      if (node.shadowRoot) {\n        for (const child of node.shadowRoot.children) visit(child);\n      }\n      for (const child of node.children) visit(child);\n    };\n    for (const child of root.children) visit(child);\n    if (root.shadowRoot) {\n      for (const child of root.shadowRoot.children) visit(child);\n    }\n    return out;\n  };\n\n  const countFrames = (root) => queryAllComposed(root, 'iframe,frame').length;\n\n  return countFrames(document.body);\n}";
+export declare const ACTIVE = "() => {\n\n  const deepActiveElement = (doc) => {\n    let el = doc.activeElement;\n    while (el && el.shadowRoot && el.shadowRoot.activeElement) {\n      el = el.shadowRoot.activeElement;\n    }\n    return el;\n  };\n\n  const p = window.__kbProbe || { els: [] };\n  const ae = deepActiveElement(document);\n  const wrapped = !ae || ae === document.body || ae === document.documentElement;\n  return { idx: wrapped ? -1 : p.els.indexOf(ae), wrapped: wrapped };\n}";
+export declare const RECT = "(i) => {\n  const el = window.__kbProbe.els[i];\n  const r = el.getBoundingClientRect();\n  return { x: r.x, y: r.y, w: r.width, h: r.height,\n           sx: window.scrollX, sy: window.scrollY,\n           vw: window.innerWidth, vh: window.innerHeight };\n}";
+export declare const ALL_VISIBLE = "(idxs) => {\n  const p = window.__kbProbe || { els: [] };\n  return idxs.every(i => {\n    const el = p.els[i];\n    if (!el || !el.isConnected) return false;\n    const cs = getComputedStyle(el);\n    if (cs.display === 'none' || cs.visibility !== 'visible') return false;\n    const r = el.getBoundingClientRect();\n    return r.width >= 2 && r.height >= 2;\n  });\n}";
+export declare const CONTAINED = "([unvisited, visited]) => {\n\n  const composedParent = (node) => {\n    if (!node) return null;\n    if (node.assignedSlot) return node.assignedSlot;\n    const p = node.parentNode;\n    if (!p) return null;\n    if (p.nodeType === 11) return p.host || null;\n    return p;\n  };\n  const composedContains = (ancestor, node) => {\n    for (let n = node; n; n = composedParent(n)) {\n      if (n === ancestor) return true;\n    }\n    return false;\n  };\n  const composedClosest = (node, selector) => {\n    for (let n = node; n; n = composedParent(n)) {\n      if (n.nodeType === 1 && n.matches(selector)) return n;\n    }\n    return null;\n  };\n\n  const els = (window.__kbProbe || { els: [] }).els;\n  const vis = visited.map(i => els[i]).filter(Boolean);\n  return unvisited.filter(u => {\n    const el = els[u];\n    return el && vis.some(v => composedContains(el, v) || composedContains(v, el));\n  });\n}";
+export declare const FOCUS = "(i) => { const el = window.__kbProbe.els[i]; if (el) el.focus(); }";
+export declare const BLUR = "() => {\n\n  const deepActiveElement = (doc) => {\n    let el = doc.activeElement;\n    while (el && el.shadowRoot && el.shadowRoot.activeElement) {\n      el = el.shadowRoot.activeElement;\n    }\n    return el;\n  };\n\n  const a = deepActiveElement(document); if (a && a.blur) a.blur();\n}";
+export declare const SCROLL_TO = "([x, y]) => window.scrollTo(x, y)";
+export declare const COMMON_ANCESTOR = "(idxs) => {\n\n  const composedParent = (node) => {\n    if (!node) return null;\n    if (node.assignedSlot) return node.assignedSlot;\n    const p = node.parentNode;\n    if (!p) return null;\n    if (p.nodeType === 11) return p.host || null;\n    return p;\n  };\n  const composedContains = (ancestor, node) => {\n    for (let n = node; n; n = composedParent(n)) {\n      if (n === ancestor) return true;\n    }\n    return false;\n  };\n  const composedClosest = (node, selector) => {\n    for (let n = node; n; n = composedParent(n)) {\n      if (n.nodeType === 1 && n.matches(selector)) return n;\n    }\n    return null;\n  };\n\n  const p = window.__kbProbe;\n  let anc = p.els[idxs[0]];\n  for (const i of idxs.slice(1)) {\n    while (anc && !composedContains(anc, p.els[i])) anc = composedParent(anc);\n  }\n  if (!anc) anc = document.body;\n  return { selector: p.path(anc), html: (anc.outerHTML || '').slice(0, 400) };\n}";

package/dist/src/scripts.js

@@ -0,0 +1,228 @@
+// In-page scripts, as source strings. Each is an arrow function; `evalScript`
+// in probe.ts wraps one in a call expression with its argument inlined, so the
+// same text runs under Node Playwright that keyboard_scan.py runs under
+// Python Playwright. The element list lives on window.__kbProbe so every later
+// query resolves the same nodes the enumeration saw.
+//
+// All of it walks the composed (flat) tree, so controls inside open shadow
+// roots are enumerated, focused, and named. Closed roots are invisible by
+// construction, and iframes are counted but not entered.
+const QUERY_ALL = `
+  const queryAllComposed = (root, selector) => {
+    const out = [];
+    const visit = (node) => {
+      if (node.nodeType !== 1) return;
+      if (node.matches(selector)) out.push(node);
+      if (node.shadowRoot) {
+        for (const child of node.shadowRoot.children) visit(child);
+      }
+      for (const child of node.children) visit(child);
+    };
+    for (const child of root.children) visit(child);
+    if (root.shadowRoot) {
+      for (const child of root.shadowRoot.children) visit(child);
+    }
+    return out;
+  };
+`;
+// document.activeElement stops at the shadow host; follow each root's own
+// activeElement down until the chain stops moving.
+const DEEP_ACTIVE_ELEMENT = `
+  const deepActiveElement = (doc) => {
+    let el = doc.activeElement;
+    while (el && el.shadowRoot && el.shadowRoot.activeElement) {
+      el = el.shadowRoot.activeElement;
+    }
+    return el;
+  };
+`;
+// Ancestry across shadow boundaries. closest() and contains() stop at a
+// ShadowRoot; this climbs the flat tree the way an event does.
+const COMPOSED_ANCESTRY = `
+  const composedParent = (node) => {
+    if (!node) return null;
+    if (node.assignedSlot) return node.assignedSlot;
+    const p = node.parentNode;
+    if (!p) return null;
+    if (p.nodeType === 11) return p.host || null;
+    return p;
+  };
+  const composedContains = (ancestor, node) => {
+    for (let n = node; n; n = composedParent(n)) {
+      if (n === ancestor) return true;
+    }
+    return false;
+  };
+  const composedClosest = (node, selector) => {
+    for (let n = node; n; n = composedParent(n)) {
+      if (n.nodeType === 1 && n.matches(selector)) return n;
+    }
+    return null;
+  };
+`;
+// A selector a person can paste into devtools, one segment per shadow
+// boundary joined with axe's `>>>` notation. String.raw keeps the regex
+// backslash intact.
+const COMPOSED_SELECTOR = String.raw `
+  const composedSelectorPath = (el) => {
+    const segmentFor = (node, stopAt) => {
+      const bits = [];
+      let n = node;
+      while (n && n.nodeType === 1 && n !== stopAt) {
+        let bit = n.localName;
+        if (n.id) { bits.unshift(bit + '#' + CSS.escape(n.id)); break; }
+        const cls = (typeof n.className === 'string')
+          ? n.className.trim().split(/\s+/).filter(Boolean).slice(0, 2) : [];
+        if (cls.length) bit += '.' + cls.map((c) => CSS.escape(c)).join('.');
+        const parent = n.parentNode;
+        if (parent && parent.children) {
+          const same = Array.from(parent.children).filter((ch) => ch.localName === n.localName);
+          if (same.length > 1) bit += ':nth-of-type(' + (same.indexOf(n) + 1) + ')';
+        }
+        bits.unshift(bit);
+        n = n.parentElement;
+      }
+      return bits.join(' > ');
+    };
+    const segments = [];
+    let node = el;
+    while (node) {
+      const treeRoot = node.getRootNode();
+      const inShadow = treeRoot instanceof ShadowRoot;
+      const stopAt = inShadow ? null : (node.ownerDocument ? node.ownerDocument.body : null);
+      segments.unshift(segmentFor(node, stopAt));
+      if (!inShadow) break;
+      node = treeRoot.host;
+    }
+    return segments.join(' >>> ');
+  };
+`;
+const SHADOW_ROOT_COUNT = `
+  const countShadowRoots = (root) =>
+    queryAllComposed(root, '*').filter((el) => !!el.shadowRoot).length
+    + (root.shadowRoot ? 1 : 0);
+`;
+const IFRAME_COUNT = `
+  const countFrames = (root) => queryAllComposed(root, 'iframe,frame').length;
+`;
+export const ENUMERATE = `() => {
+${QUERY_ALL}${COMPOSED_ANCESTRY}${COMPOSED_SELECTOR}${SHADOW_ROOT_COUNT}
+  // dialog:modal is the well-behaved case; role alone is not proof of
+  // modality, but it is what a hand-rolled widget tends to expose instead of
+  // a real <dialog>. The first visible match wins.
+  const MODAL_SEL = 'dialog:modal, [role="dialog"], [role="alertdialog"], [aria-modal="true"]';
+  let modal = null;
+  for (const el of queryAllComposed(document.body, MODAL_SEL)) {
+    const mcs = getComputedStyle(el);
+    if (mcs.display === 'none' || mcs.visibility !== 'visible') continue;
+    const mr = el.getBoundingClientRect();
+    if (mr.width < 2 || mr.height < 2) continue;
+    modal = el;
+    break;
+  }
+  const root = modal || document.body;
+  const SEL = [
+    'a[href]', 'area[href]', 'button', 'input', 'select', 'textarea', 'summary',
+    'iframe', 'audio[controls]', 'video[controls]',
+    '[contenteditable="true"]', '[contenteditable=""]', '[tabindex]', '[onclick]',
+    '[role="button"]', '[role="link"]', '[role="checkbox"]', '[role="radio"]',
+    '[role="tab"]', '[role="menuitem"]', '[role="menuitemcheckbox"]',
+    '[role="menuitemradio"]', '[role="option"]', '[role="switch"]',
+    '[role="textbox"]', '[role="combobox"]', '[role="slider"]',
+    '[role="spinbutton"]', '[role="searchbox"]'
+  ].join(',');
+  const COMPOSITE = ['[role="radiogroup"]', '[role="toolbar"]', '[role="menu"]',
+    '[role="menubar"]', '[role="listbox"]', '[role="tablist"]', '[role="tree"]',
+    '[role="grid"]'].join(',');
+  const els = [];
+  for (const el of queryAllComposed(root, SEL)) {
+    if (el === document.body || el === document.documentElement) continue;
+    const cs = getComputedStyle(el);
+    if (cs.display === 'none' || cs.visibility !== 'visible') continue;
+    const r = el.getBoundingClientRect();
+    if (r.width < 2 || r.height < 2) continue;
+    if (el.disabled) continue;
+    if (composedClosest(el, '[aria-hidden="true"]')) continue;
+    if (composedClosest(el, '[inert]')) continue;
+    els.push(el);
+  }
+  window.__kbProbe = { els: els, path: composedSelectorPath };
+  const TEXTLIKE = ['button', 'submit', 'reset', 'checkbox', 'radio', 'range',
+                    'color', 'file', 'image'];
+  return els.map((el, i) => {
+    const comp = composedClosest(el, COMPOSITE);
+    return {
+      i: i,
+      tag: el.localName,
+      selector: composedSelectorPath(el),
+      tabindex: el.getAttribute('tabindex'),
+      focusable: el.tabIndex >= 0,
+      type: (el.getAttribute('type') || '').toLowerCase(),
+      name: el.getAttribute('name') || '',
+      role: el.getAttribute('role') || '',
+      editable: el.localName === 'textarea' || el.isContentEditable ||
+        (el.localName === 'input' &&
+         !TEXTLIKE.includes((el.getAttribute('type') || 'text').toLowerCase())),
+      composite: comp ? composedSelectorPath(comp) : '',
+      html: (el.outerHTML || '').slice(0, 400),
+    };
+  });
+}`;
+export const SHADOW_COUNT = `() => {
+${QUERY_ALL}${SHADOW_ROOT_COUNT}
+  return countShadowRoots(document.body);
+}`;
+export const FRAME_COUNT = `() => {
+${QUERY_ALL}${IFRAME_COUNT}
+  return countFrames(document.body);
+}`;
+export const ACTIVE = `() => {
+${DEEP_ACTIVE_ELEMENT}
+  const p = window.__kbProbe || { els: [] };
+  const ae = deepActiveElement(document);
+  const wrapped = !ae || ae === document.body || ae === document.documentElement;
+  return { idx: wrapped ? -1 : p.els.indexOf(ae), wrapped: wrapped };
+}`;
+export const RECT = `(i) => {
+  const el = window.__kbProbe.els[i];
+  const r = el.getBoundingClientRect();
+  return { x: r.x, y: r.y, w: r.width, h: r.height,
+           sx: window.scrollX, sy: window.scrollY,
+           vw: window.innerWidth, vh: window.innerHeight };
+}`;
+export const ALL_VISIBLE = `(idxs) => {
+  const p = window.__kbProbe || { els: [] };
+  return idxs.every(i => {
+    const el = p.els[i];
+    if (!el || !el.isConnected) return false;
+    const cs = getComputedStyle(el);
+    if (cs.display === 'none' || cs.visibility !== 'visible') return false;
+    const r = el.getBoundingClientRect();
+    return r.width >= 2 && r.height >= 2;
+  });
+}`;
+export const CONTAINED = `([unvisited, visited]) => {
+${COMPOSED_ANCESTRY}
+  const els = (window.__kbProbe || { els: [] }).els;
+  const vis = visited.map(i => els[i]).filter(Boolean);
+  return unvisited.filter(u => {
+    const el = els[u];
+    return el && vis.some(v => composedContains(el, v) || composedContains(v, el));
+  });
+}`;
+export const FOCUS = `(i) => { const el = window.__kbProbe.els[i]; if (el) el.focus(); }`;
+export const BLUR = `() => {
+${DEEP_ACTIVE_ELEMENT}
+  const a = deepActiveElement(document); if (a && a.blur) a.blur();
+}`;
+export const SCROLL_TO = `([x, y]) => window.scrollTo(x, y)`;
+export const COMMON_ANCESTOR = `(idxs) => {
+${COMPOSED_ANCESTRY}
+  const p = window.__kbProbe;
+  let anc = p.els[idxs[0]];
+  for (const i of idxs.slice(1)) {
+    while (anc && !composedContains(anc, p.els[i])) anc = composedParent(anc);
+  }
+  if (!anc) anc = document.body;
+  return { selector: p.path(anc), html: (anc.outerHTML || '').slice(0, 400) };
+}`;

package/dist/src/walk.d.ts

@@ -0,0 +1,45 @@
+export type Candidate = {
+    i: number;
+    tag: string;
+    selector: string;
+    tabindex: string | null;
+    focusable: boolean;
+    type: string;
+    name: string;
+    role: string;
+    editable: boolean;
+    composite: string;
+    html: string;
+};
+/**
+ * Return the member indices of a focus cycle at the tail of `seq`, or null.
+ *
+ * A Tab walk never legitimately revisits an element (revisiting means focus
+ * looped), but a single revisit can also be a probe artifact, so this demands
+ * two full periods: the last 2p entries repeat with period p. Unknown elements
+ * (-1) never form a cycle; focus we cannot identify is not evidence.
+ */
+export declare function detectCycle(seq: number[], maxPeriod?: number): number[] | null;
+/**
+ * (from, to) pairs where the first-visit order jumps backwards in the DOM.
+ *
+ * `barriers` holds positions in `firstVisit` where the probe moved focus
+ * programmatically (past an iframe or a trap); the jump across a barrier is
+ * the probe's doing, not the page's, so it is not a divergence.
+ */
+export declare function orderDivergences(firstVisit: number[], barriers?: Set<number>): Array<[number, number]>;
+/**
+ * Candidates that never received focus and have no keyboard-reachable proxy.
+ *
+ * `contained` holds indices that wrap or sit inside a visited element (a card
+ * div with an onclick around a real link: the function is reachable through
+ * the link). Roving-tabindex composites and radio groups keep one tab stop by
+ * design, so an unvisited member whose group was reached is not a defect.
+ * `beforeIndex` limits reporting to elements before a detected trap: past the
+ * trap, "unreachable" and "blocked by the trap" cannot be told apart, and the
+ * trap finding already owns that blockage.
+ */
+export declare function unreachableCandidates(cands: Candidate[], visited: Set<number>, contained: Set<number>, beforeIndex?: number | null): Candidate[];
+export declare function nextFocusableAfter(cands: Candidate[], after: number, visited: Set<number>): number | null;
+/** True for a tabindex attribute that is a positive integer. */
+export declare function isPositiveTabindex(value: string | null): boolean;

package/dist/src/walk.js

@@ -0,0 +1,93 @@
+// Pure walk analysis. No browser here, so test/walk.test.ts can exercise every
+// branch without Playwright. A port of the same functions in keyboard_scan.py;
+// if one changes, change the other.
+/**
+ * Return the member indices of a focus cycle at the tail of `seq`, or null.
+ *
+ * A Tab walk never legitimately revisits an element (revisiting means focus
+ * looped), but a single revisit can also be a probe artifact, so this demands
+ * two full periods: the last 2p entries repeat with period p. Unknown elements
+ * (-1) never form a cycle; focus we cannot identify is not evidence.
+ */
+export function detectCycle(seq, maxPeriod = 12) {
+    const limit = Math.min(maxPeriod, Math.floor(seq.length / 2));
+    for (let p = 1; p <= limit; p++) {
+        const window = seq.slice(-2 * p);
+        const first = window.slice(0, p);
+        const second = window.slice(p);
+        const repeats = first.every((v, k) => v === second[k]);
+        const known = window.every(v => v >= 0);
+        const distinct = new Set(first).size === p;
+        if (repeats && known && distinct)
+            return Array.from(new Set(first));
+    }
+    return null;
+}
+/**
+ * (from, to) pairs where the first-visit order jumps backwards in the DOM.
+ *
+ * `barriers` holds positions in `firstVisit` where the probe moved focus
+ * programmatically (past an iframe or a trap); the jump across a barrier is
+ * the probe's doing, not the page's, so it is not a divergence.
+ */
+export function orderDivergences(firstVisit, barriers = new Set()) {
+    const out = [];
+    for (let pos = 1; pos < firstVisit.length; pos++) {
+        const prev = firstVisit[pos - 1];
+        const cur = firstVisit[pos];
+        if (cur < prev && !barriers.has(pos))
+            out.push([prev, cur]);
+    }
+    return out;
+}
+/**
+ * Candidates that never received focus and have no keyboard-reachable proxy.
+ *
+ * `contained` holds indices that wrap or sit inside a visited element (a card
+ * div with an onclick around a real link: the function is reachable through
+ * the link). Roving-tabindex composites and radio groups keep one tab stop by
+ * design, so an unvisited member whose group was reached is not a defect.
+ * `beforeIndex` limits reporting to elements before a detected trap: past the
+ * trap, "unreachable" and "blocked by the trap" cannot be told apart, and the
+ * trap finding already owns that blockage.
+ */
+export function unreachableCandidates(cands, visited, contained, beforeIndex = null) {
+    const reachedComposites = new Set();
+    const reachedRadioGroups = new Set();
+    for (const i of visited) {
+        const c = cands[i];
+        if (!c)
+            continue;
+        if (c.composite)
+            reachedComposites.add(c.composite);
+        if (c.type === 'radio' && c.name)
+            reachedRadioGroups.add(c.name);
+    }
+    const out = [];
+    for (const c of cands) {
+        if (visited.has(c.i) || contained.has(c.i))
+            continue;
+        if (beforeIndex !== null && c.i >= beforeIndex)
+            continue;
+        if (c.type === 'radio' && reachedRadioGroups.has(c.name))
+            continue;
+        if (c.composite && reachedComposites.has(c.composite))
+            continue;
+        out.push(c);
+    }
+    return out;
+}
+export function nextFocusableAfter(cands, after, visited) {
+    for (const c of cands) {
+        if (c.i > after && c.focusable && !visited.has(c.i))
+            return c.i;
+    }
+    return null;
+}
+/** True for a tabindex attribute that is a positive integer. */
+export function isPositiveTabindex(value) {
+    if (!value)
+        return false;
+    const trimmed = value.trim().replace(/^\+/, '');
+    return /^\d+$/.test(trimmed) && Number(trimmed) > 0;
+}

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@okent/accessibility-scanner-keyboard-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Keyboard probe plugin for github/accessibility-scanner: focus traps, unreachable controls, removed focus indicators, and focus-order divergence, found by walking the real Tab order.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/owenpkent/accessibility-scanner-keyboard-plugin.git"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:unit": "vitest run test/walk.test.ts",
+    "test:e2e": "vitest run test/fixture.e2e.test.ts"
+  },
+  "keywords": [
+    "accessibility",
+    "a11y",
+    "keyboard",
+    "wcag",
+    "playwright",
+    "accessibility-scanner"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "playwright": ">=1.40"
+  },
+  "peerDependenciesMeta": {
+    "playwright": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "playwright": "^1.50.0",
+    "typescript": "^5.5.0",
+    "vitest": "^3.0.0"
+  },
+  "homepage": "https://github.com/owenpkent/accessibility-scanner-keyboard-plugin#readme",
+  "bugs": {
+    "url": "https://github.com/owenpkent/accessibility-scanner-keyboard-plugin/issues"
+  }
+}