Release Tactual v0.5.0

[bmatar]

Summary

Prepares Tactual v0.5.0 for public release from the current public baseline, v0.4.1 / public/main.

This release expands Tactual from a navigation-cost analyzer with runtime probes into a more reliable SPA and embedded-frame analyzer with deeper AT-tree modeling and a repeatable calibration workflow. The PR branch has been rewritten as one public release commit so the public history shows the shipped delta, not internal iteration.

User-facing delta

• SPA capture reliability: framework-aware settling, convergence polling, route-change tracking, lazy-content auto-scroll, banner dismissal, hover-content probing, tab-order walking, viewport diffing, and same-origin iframe descent.
• Cross-origin iframe coverage: Chromium CDP fallback recovers many OOPIF accessibility trees that Playwright frame-scoped ariaSnapshot cannot access.
• AT-tree modeling: richer navigation strategies for rotor/element-list jumps, forms mode, touch exploration, relationship jumps, active descendants, and composite-widget arrow traversal.
• Diagnostics: broader always-on structural, ARIA, visual, media, metadata, language, repeated-navigation, and viewport diagnostics, with README coverage for emitted codes.
• Calibration: observed/tested announcement fields, calibration_report, NVDA VM observation tooling, imported calibration corpus evidence, and matrix/audit scripts for reachability tuning.
• Release evidence tooling: benchmark:known-pages runs the built CLI against complex SPA/component-library documentation pages with the 0.5 capture helpers enabled and writes ignored category-rollup reports under build/.
• Public surfaces: package metadata, GitHub Action, MCP server metadata, CLI/MCP docs, release matrix, limitations docs, and security notes updated for 0.5.0, with contract tests keeping CLI/MCP/Action parameters aligned.
• CLI presentation: long console diagnostics wrap under their severity labels instead of emitting unreadable single-line paragraphs.

Corpus and package boundary

• The versioned calibration corpus is intentionally committed as portable release evidence, but it is excluded from the npm package by package.json files.
• The corpus now keeps only durable evidence: datasets, manifests, shared analysis snapshots, and sequence plans.
• Generated review/debug artifacts stay out of git: batch reports, review queues, speech alignment dumps, host summaries, generated audit output, generated matrix output, and live known-pages benchmark output.
• Final committed calibration corpus footprint: 65 files / 34,948 added lines, down from the earlier 169-file generated-artifact shape.

Compatibility notes

Scores, diagnostics, JSON baselines, SARIF findings, and CI thresholds can change on unchanged pages because 0.5.0 captures more evidence by default. Consumers should regenerate 0.4.x baselines before using 0.5.0 as a regression gate.

Branch states discovered by --explore no longer promote isolated possibly-degraded-content warnings when the primary scripted capture contains substantial content. Bot-block, empty-page, and other hard reliability diagnostics are still reported.

MCP URL-taking tools now reject file: URLs; CLI and library workflows still accept file: URLs for local fixture/offline workflows.

commander@15 is intentionally not included because it raises the runtime floor to Node >=22.12.0; Tactual still supports Node >=20.0.0.

Verification

Verification for the clean release branch:

• npm run test:release passed
• npm audit --omit=dev passed with 0 vulnerabilities
• Release gate coverage included typecheck, lint, all Vitest release shards, build, ARIA-AT calibration, calibration corpus audit, calibration matrix, package smoke, and release smoke
• Focused parity/presentation verification passed after the final polish: npx vitest run src/pipeline/surface-parity.test.ts src/cli/cli.test.ts src/mcp/tool-handlers.test.ts src/reporters, npm run typecheck, npm run lint, and npm run build
• Focused fixture verification passed: npx vitest run src/benchmark
• node scripts/known-pages-corpus.mjs --build --limit 1 passed against React Aria ComboBox and produced an ignored report with 8 states, 2,765 targets, 520 findings, route tracking, and category rollups
• npm pack --dry-run --json is covered by the pack smoke and confirms the npm package excludes calibration/corpus/ and ships only the configured package files

Public CI is green on 5c4a79e across Node 20 and Node 22.