@a11ign/screenreader-worker

Drives a real NVDA screen reader through real navigation on Windows and returns what it announced.

Windows only, with an interactive desktop session. Not a limitation to be worked around: NVDA is a real Windows application, and guidepup needs a logged-on desktop to drive it. A service, an SSH session or utmctl exec all land in session 0, where NVDA reports its own absence as nvda.start failed: NVDA is not supported — which reads like a broken install and is not one.

npm install @a11ign/screenreader-worker
npx a11ign-nvda-worker            # serves on :8765

The HTTP contract is the API

Almost nobody should import this package. A capture needs Windows, NVDA and a desktop, so the normal shape is a small Windows worker serving HTTP to a controller running anywhere:

POST /capture      { url, task?, probeForms?, probeFocus?, probeTables? }  → the capture
GET  /health       readiness, vitals, environment, code hash
GET  /diagnostics  Edge profile sizes, orphan processes, NVDA config + logs   (on demand — it walks disks)

Dispatch on ready, not on ok. ok only ever meant "the HTTP server is answering", and a worker answered it while NVDA could not start — which is how this pool's dominant failure hid for a day. ready is about the environment: Edge is resolvable, ForegroundLockTimeout is 0, the worker is free. ready: false right after a boot is normal and self-correcting.

Watch vitals.recoveries. It counts faults the worker papered over. The worst fault this pool has had produced zero failures — one guest's NVDA went mute on 4 of 4 captures, the retry absorbed every one, and the only symptom was 122.9 s per capture against a healthy peer's 40.6 s.

CAPTURE_PROTOCOL_VERSION is not the package version

It versions the wire contract and the meaning of the evidence, independently of semver, and conflating the two would be expensive in both directions: a package major must not invalidate cached captures, and a protocol bump must not wait for a major.

Bump it when a change alters what the evidence means — a new field a signal reads, a probe that announces differently. It is a cache key, so a bump forces a full recapture. That is the point, and it is why a refactor must not touch it.

guidepup is pinned exactly, and that is deliberate

"@guidepup/guidepup": "0.31.0" — no caret. guidepup parses NVDA's speech before this package ever sees it, so its version is evidence. Upgrading 0.29.2 → 0.31.0 fixed an intermittent OBJECT REPLACEMENT CHARACTER (U+FFFC) appended to form-field announcements: 1 in 15 captures before, 0 in 15 after. A caret range would let npm update silently change what a capture says.

What the programmatic surface is for

import { captureWithNvda, CAPTURE_PROTOCOL_VERSION, codeVersion } from "@a11ign/screenreader-worker";

captureWithNvda(url, options) is the one-shot path, for a controller that already runs on the Windows box. codeVersion() hashes the worker's own files so a deploy can be verified over the channel the worker serves on — which matters because push-then-restart can fail silently in both halves, and a check that goes through the same channel as the action verifies nothing.

Everything else — capture-core internals, the speech-socket shim, browser-session, the diagnostics payload shapes — is not public and will change without a major.

One behaviour worth knowing before you read a transcript

NVDA has two modes, and in focus mode single letters are typed into the page instead of navigating. A control activation is a focus change, which switches focus mode on and it sticks — so a naive sweep after activating a form types its own quick-nav keys into whatever has focus. This ran here for 2,122 captures with every check green, and one site search-as-you-typed them and rendered 1 result for FFffGGggKKkkLLll, which was read as a page defect. The sweep now detects the echo and escalates out of focus mode, and reports focusModeStuck rather than "this page has no links" when it cannot recover — because "nothing was found" and "we could not ask" must never be the same evidence.