Tactual

Tactual

Screen-reader navigation cost analyzer. Measures how many keystrokes a screen-reader user needs to discover, reach, and operate every interactive target on your page — under a specific AT profile (NVDA, JAWS, VoiceOver).

What it does

Existing accessibility tools check conformance — is the ARIA correct? Is the contrast ratio sufficient?

Tactual measures navigation cost — how many actions does it take a screen-reader user to reach the checkout button? What happens if they overshoot? Can they even discover it exists? Does the menu actually open on Enter, or only on click? Does focus land on the first menuitem or stay stuck on the trigger?

How it works:

• Captures Playwright accessibility snapshots + screen-reader announcement simulation
• Optionally explores hidden branches (menus, dialogs, tabs, disclosures) and probes them with real keyboard events, including APG-style widget contracts and form-error flows
• Builds a navigation graph with entry points (landmarks, headings, linear Tab) and scores every target
• Optionally validates predicted paths against @guidepup/virtual-screen-reader for calibration

Tactual is a developer tool for analyzing your own sites and staging environments. Run it locally, in CI, or via the MCP server in your editor. It is not a public scanning service.

How it fits

Tactual complements conformance scanners such as axe-core, Lighthouse, and Pa11y. Those tools are still the right first pass for broad WCAG and ARIA rule coverage. Tactual is aimed at the next question: after a page has valid markup, how expensive is it for an AT user to discover, reach, and operate the important targets?

Use Tactual for screen-reader navigation-cost triage, path tracing, measured keyboard/widget evidence, before/after diffs, CI prioritization, and MCP workflows where an agent needs compact findings with source selectors and remediation candidates. Use real screen readers and manual testing for final validation of critical journeys, timing-sensitive flows, browser/AT settings, and implementation patterns that intentionally differ from a common APG example.

Agent quick path: this README is a product overview plus reference. Agents should start with docs/AGENT-RECIPES.md for task patterns and docs/MCP-TOOLS.md for full MCP schemas, then come back here only for product context, install notes, and release-surface examples.

Install

Requires Node.js 20 or later.

npm install tactual

Tactual installs Playwright as a runtime dependency so one-off npx tactual@latest ... commands work without separately installing Playwright into the npx cache. The MCP SDK also ships as a runtime dependency, so tactual-mcp works from an installed tactual package without a separate SDK install.

Quick start

CLI

# Analyze a URL (default profile: generic-mobile-web-sr-v0)

npx tactual analyze-url https://example.com

Analyze with a specific AT profile

npx tactual analyze-url https://example.com --profile voiceover-ios-v0

Explore hidden UI (menus, tabs, dialogs, disclosures)

npx tactual analyze-url https://example.com --explore

Use a scoring preset for your use case

npx tactual analyze-url https://shop.com --preset ecommerce-checkout npx tactual analyze-url https://docs.example.com --preset docs-site

Output as JSON, Markdown, or SARIF

npx tactual analyze-url https://example.com --format json --output report.json npx tactual analyze-url https://example.com --format sarif --output report.sarif

Compare two analysis runs

npx tactual diff-results baseline.json candidate.json npx tactual diff-results baseline.json candidate.json --format json

Print what NVDA would say as you Tab through the page

npx tactual transcript https://example.com npx tactual transcript https://example.com --at voiceover

List available AT profiles and scoring presets

npx tactual profiles npx tactual presets

Run benchmark suites

npx tactual benchmark npx tactual benchmark --suite all

Benchmark fixtures ship with the npm package, so the benchmark command works from a fresh install and does not require cloning the repository fixtures into your current directory.

Validate predicted paths against a virtual screen reader (reachability + step count)

Requires optional deps, installed by default with tactual

npx tactual validate-url https://example.com --max-targets 10 --strategy semantic

Initialize a tactual.json config file

npx tactual init

Analyze a bot-protected site with stealth + real Chrome

npx tactual analyze-url https://www.npmjs.com/ --stealth --channel chrome

Deep keyboard probing including revealed widgets and form-error flows

npx tactual analyze-url https://docs.example.com --probe --explore --probe-mode deep

Focus probing on one opened branch, such as a dialog trigger

npx tactual analyze-url https://app.example.com/settings \ --probe \ --entry-selector "[aria-controls='profile-dialog']" \ --probe-strategy modal-return-focus

Analyze + inline virtual-SR validation in one command (predicted vs validated steps)

npx tactual analyze-url https://example.com --validate --validate-max-targets 10

Console output includes a compacted path line for each finding showing how a screen-reader user reaches it:

  ██████░░ 70  link:reference structural

D:47 R:71 O:100 Rec:100 getByRole('link', { name: 'Reference' }) ↪ Tab ×2 "v19.2" → K "Learn" → Tab "Reference" → Target is not efficiently reachable via heading or landmark navigation

Where Tab = nextItem, H = nextHeading, ; = nextLandmark, K = nextLink, B = nextButton, Enter = activate. Consecutive same-action steps collapse (Tab ×2).

From Audit to Fix

For accessibility work in a local app or preview environment, Tactual supplies evidence for small, reviewable changes:

• selector, penalties, suggestedFixes, and evidence summaries on each finding
• grouped issueGroups and remediation candidates in summarized output
• analyze_pages.site.repeatedNavigation for repeated navigation cost across routes
• diff-results / diff_results for before-and-after verification

Start with broad triage, then deepen one route before changing code:

# Site-level triage. Redirect JSON for tool consumption.

npx tactual analyze-pages \ https://app.example.com/ \ https://app.example.com/docs \ https://app.example.com/settings \ --profile nvda-desktop-v0 \ --format json > tactual-site.json

Deepen one route and produce a reviewable markdown report.

npx tactual analyze-url https://app.example.com/docs \ --profile nvda-desktop-v0 \ --explore --probe --probe-mode standard \ --format markdown --output tactual-report.md

When one branch is the target, open it first and spend probe budget there.

npx tactual analyze-url https://app.example.com/docs \ --profile nvda-desktop-v0 \ --probe \ --entry-selector "[aria-controls='search-panel']" \ --probe-selector "#search-panel" \ --probe-strategy composite-widget \ --format markdown --output tactual-search-panel.md

Save a baseline before editing, then verify the patch.

npx tactual analyze-url https://app.example.com/docs --explore --probe --format json --output baseline.json

Edit one root cause in the local repo, rebuild/restart the preview, then re-run:

npx tactual analyze-url https://app.example.com/docs --explore --probe --format json --output candidate.json npx tactual diff-results baseline.json candidate.json

Use the candidate section as a starting point for repeated root causes such as a shared component, navigation pattern, or widget contract. Confirm the source component and include the route, command, finding evidence, user impact, code change, and verification in whatever issue or PR format the project expects. Score movement is useful supporting evidence, but the change should lead with the accessibility behavior that changed.

MCP clients can consume the same compact output and keep the review loop grounded in routes, selectors, evidence, source changes, and before/after verification.

Library API

import { analyze, getProfile } from "tactual";

import { captureState } from "tactual/playwright"; import { chromium } from "playwright";

const browser = await chromium.launch(); const page = await browser.newPage(); await page.goto("https://example.com");

const state = await captureState(page); await browser.close();

const profile = getProfile("generic-mobile-web-sr-v0"); const result = analyze([state], profile);

for (const finding of result.findings) { console.log(finding.targetId, finding.scores.overall, finding.severity); }

Screen-reader announcement simulator — predict what NVDA, JAWS, or VoiceOver would announce for every target, with state info (checked, expanded, selected, modal, value, required, invalid, etc.):

import {

simulateScreenReader, buildAnnouncement, buildMultiATAnnouncement, buildTranscript, } from "tactual/playwright";

const report = await simulateScreenReader(page, state.targets);

for (const a of report.formFields) { console.log(a.announcement); // → "Subscribe, check box, checked" // → "Country, combo box, collapsed" // → "Email, edit, invalid entry, required, you must use a work address" }

// Compare across screen readers const tx = state.targets[5]; buildAnnouncement(tx, "nvda"); // → "Country, combo box, collapsed" buildAnnouncement(tx, "voiceover"); // → "Country, popup button"

// All three at once buildMultiATAnnouncement(tx); // → { nvda: "...", jaws: "...", voiceover: "..." }

// Linear navigation transcript — what an SR user hears Tabbing through const transcript = buildTranscript(state.targets, "nvda"); // → [{ step: 1, kind: "landmark", announcement: "Main, main landmark" }, ...]

// Multi-target navigation modes (linear, by-heading, by-landmark, by-form-control) import { buildNavigationTranscript } from "tactual/playwright";

// Heading-only navigation (NVDA: H key) const headings = buildNavigationTranscript(state.targets, { mode: "by-heading" });

// Navigate from one element to another const path = buildNavigationTranscript(state.targets, { from: "link:before-main", to: "heading:welcome", mode: "linear", });

// Demoted landmarks (in DOM but stripped by HTML rules, e.g. in ) for (const d of report.demotedLandmarks) { console.warn(d.demotionReason); }

Validation and calibration APIs — compare model output against virtual-SR validation runs or human-observation datasets:

import { validateFindingsInJsdom } from "tactual/validation";

import { runCalibration, formatCalibrationReport } from "tactual/calibration";

// Given a JSDOM instance, PageState, AnalysisResult, and calibration dataset: const validation = await validateFindingsInJsdom(dom, state, result.findings, { maxTargets: 10, strategy: "semantic", });

const calibration = runCalibration(dataset, new Map([[state.url, result]])); console.log(validation, formatCalibrationReport(calibration));

Or from the CLI:

npx tactual transcript https://example.com --at voiceover

npx tactual calibration-report my-calibration.json --analysis example-nvda.json

The simulator is heuristic prediction, not real screen-reader output. The simulator itself is fast (pure JavaScript over captured targets — sub-second once targets are in memory), but a full analyze-url run includes browser launch + page capture + scoring and takes seconds on small pages, longer with --probe (~30s+) and --explore (~1–5 min on complex SPAs). Analysis runs in a headless browser by default, so nothing pops up while you work. (Use --no-headless or --channel chrome --stealth for visible/bot-protected sites.)

Data quality. Calibrated against token-l