Repository navigation
Live mode works on macOS 27; release 0.12.0 - #47
Merged
Merged
Conversation
macOS 27 removed VoiceOverStarter, the program Guidepup launched VoiceOver through. Guidepup 0.36 opens VoiceOver.app there instead (guidepup#151), so move to it. The live-mode pre-check looked for VoiceOverStarter as well, so it refused every macOS 27 machine even with the new driver. It now checks the launcher Guidepup will use, chosen by Guidepup's own rule. Remove --start-timeout: it was passed to Guidepup as a setting Guidepup never read, in either version. Guidepup 0.36 retries the start itself (2 x 30s), which covers the cold start the flag was meant for. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Without the subcommand, @guidepup/setup prints its help and changes nothing. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Starting VoiceOver through VoiceOver.app brings it to the front and takes focus from the browser, so every live read came back empty. Bring the browser back once the reader is running. Verified on macOS 27: live read of test/fixtures/basic.html reads all 20 items. The README now lists every setup step a current Mac needs: Full Disk Access for the terminal, `npx @guidepup/setup install voiceover`, and allowing each control prompt on the first run. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
11 tasks done
Elizabeth1979
added a commit
to Elizabeth1979/accessibility-evidence-engine
that referenced
this pull request
Oct 17, 2026
…os sorted (#121) ## Summary Finishes master-plan step 10.8, the last open product step, and moves AEE to one tool for screen readers. - **One tool.** `npm run readers:compare` used to put *screen-reader-cli's* virtual reader next to VoiceOver, so it measured a reader AEE does not ship. It now reads the page with AEE's own virtual reader, and drives VoiceOver, NVDA or Orca through Guidepup's Playwright integration (`@guidepup/playwright`), which starts and stops the real reader and steps it into the page. screen-reader-cli is no longer a dependency. The decisions log records why this reverses 2026-09-26's "no second bridge". - **10.8 done.** On the owner's Mac (macOS 27), VoiceOver read the demo page next to AEE's virtual reader: 47 and 35 announcements, in the same order, kept in [`docs/examples/reader-comparison-voiceover.md`](https://github.com/Elizabeth1979/accessibility-evidence-engine/blob/finish-10-8/docs/examples/reader-comparison-voiceover.md). Both announce the page's deliberate faults the same way. The virtual reader leaves out loose text in cards, "current page", list positions and the end of lists and regions; the decisions log records these as its next improvements. - **The virtual reader reads loose text.** The first VoiceOver run showed it passed over text no announced item says (a card's bold title, a field's visible label, a box styled as a button), though that text is in the accessibility tree. It now reads each piece as plain text, as VoiceOver does, without repeating text a link, heading or paragraph already says; the screen-reader judge cross-checks these items against the tree's StaticText. The rerun comparison shows every phrase it used to miss. - **The repo review list is carried out (8.1)**, under the owner's new rule: a repo someone would use on its own is kept as a product. With 8.1 ticked the plan is complete, and the roadmap now says so. - **`npm run reader:record`** records AEE's virtual reader reading a page on video, with its transcript. The homepage's screen-reader video now comes from the same recorder, and CLAUDE.md uses it for our own pages' virtual screen-reader pass. - **Setup.** The README lists every step a current Mac needs before the real reader runs (Accessibility and Full Disk Access for the terminal, `npx @guidepup/setup install voiceover`, allowing each control prompt). ## Related issue Master plan step 10.8 (implementation roadmap Milestone 4). The matching screen-reader-cli fix for its own users is Elizabeth1979/screen-reader-cli#47; this PR does not depend on it. ## Behavior and contracts - `@aee/playwright`: the virtual reader adds items of role `text` for loose text. `@aee/judges`: the screen-reader judge matches them to `StaticText`. Schemas and reports are unchanged. - `readers:compare` fails with Guidepup's reason when the real reader cannot start, instead of writing a one-sided comparison. - With M10 finished, the homepage's "Coming to AEE" section has no product milestone left, so the generator drops it (M8 is internal and never shown). - `.impeccable/hook.cache.json`, a design plugin's local cache, is gitignored; it was failing `format:check`. ## Verification - [x] `npm audit --audit-level=high` (0 vulnerabilities) - [x] `npm run check` - [x] `npm run test:unit` (222 pass, 1 skipped as before) - [x] `npm run test:playwright` (99 pass) - [x] `npm run format:check`, `npm run site:check`, `npm run lint` - [x] `npm run site:shots` regenerates every shot, the screen-reader video from AEE's reader - [x] `npm run readers:compare` on macOS 27 with VoiceOver: passed, transcript above ## Privacy and accessibility claims - [x] I reviewed fixtures, logs, screenshots, reports, and test artifacts for credentials, personal data, and proprietary content. The saved transcript is of the fictional demo page. - [x] New network fields are sanitized before persistence. (None added.) - [x] New or changed judgments remain traceable to evidence identifiers. (None changed.) - [x] Documentation does not present an AEE pass as WCAG certification. ## Notes for reviewers - NVDA and Orca take the same Guidepup path but were not run here; only VoiceOver was. - Follow-up: the reader's remaining gaps from the comparison: `aria-current` inside a list item, list positions, and the end of lists and regions. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this fixes
Live mode could not run on macOS 27. Three things stood in the way, and this release (0.12.0) fixes each:
VoiceOverStarter, the program the screen-reader driver (Guidepup) used to launch it. Guidepup 0.36 opensVoiceOver.appinstead (guidepup#151), so this moves from 0.24 to 0.36.3.VoiceOverStartertoo. It now checks the launcher Guidepup will actually use, chosen by Guidepup's own rule.VoiceOver.appbrings VoiceOver to the front and takes focus from the browser, so every read returned 0 announcements. The browser is brought back to the front once the reader is running.Also:
--start-timeout. It never did anything: Guidepup never read the value, in either version. Guidepup 0.36 retries the start itself (2 × 30 s). A command still passing the flag gets "unknown option".npx @guidepup/setuponly prints help; it needssetupafter it. The README now lists every step a current Mac needs: Accessibility and Full Disk Access for the terminal,npx @guidepup/setup install voiceover, and allowing each control prompt on the first run.Verified
screenreader live read test/fixtures/basic.htmlreads all 20 items in order, from the navigation's links to the footer. Before this change it either refused to start or read 0 items.npm test: 163 of 163 pass.npm audit --omit=dev: 0 vulnerabilities.node bin/cli.js scan docs/index.html --fail-on minorpasses.Merging publishes 0.12.0 to npm.
🤖 Generated with Claude Code