Skip to content

feat(a11y): meta.source + opt-in --native platform accessibility tree - #183

Merged
ractive merged 2 commits into
mainfrom
iter-143/native-a11y-tree
Aug 12, 2026
Merged

feat(a11y): meta.source + opt-in --native platform accessibility tree#183
ractive merged 2 commits into
mainfrom
iter-143/native-a11y-tree

Conversation

@ractive

@ractive ractive commented Aug 12, 2026

Copy link
Copy Markdown
Owner

Summary

  • ff-rdp a11y (and a11y --critical, a11y contrast) now always reports meta.source ("native" | "js-fallback", plus meta.source_reason) so a caller can tell the real Firefox platform accessibility tree apart from the DOM-derived JS approximation without a separate --verbose round-trip.
  • Adds an opt-in --native flag (commands::a11y::run_native_opt_in) that enables Firefox's platform accessibility service via parentAccessibilityActor.enable() when it's off, walks the native tree, and restores the prior state afterward — but only when this call is what turned it on. Never the default (per DEC-027: enable() is browser-global/process-wide and its disable() can be blocked by an active Windows screen reader). Any failure (enable failing, bootstrap() still reporting disabled, a stalled walker request) surfaces as an explicit error, never a silent fallback.
  • Bounds accessibility walker requests (getWalker/root accessor/children) to a 3s read timeout (with_walker_timeout), so a stalled platform service (iter-136: the walker never replies while the service is off) costs a few seconds instead of the full configured --timeout.
  • New core primitives: AccessibilityActor::enable_service/disable_service (ff-rdp-core) and connection_meta::merge_source (ff-rdp-cli), following the same unconditional-merge pattern iter-134 established for meta.route.

Spec drift

No local Firefox checkout (FF_RDP_FIREFOX_PATH) was available in this environment to run the static rdp-spec-reviewer diff-vs-source comparison, so this section is filled in manually per its fallback rule ("if the Firefox checkout is not available, say so and list the actors that could not be reviewed").

  • Actor touched: crates/ff-rdp-core/src/actors/accessibility.rs — could not be statically diffed against devtools/shared/specs/accessibility.js in this run.
  • No new protocol surface is introduced: enable()/disable() on parentAccessibilityActor were already documented as existing lifecycle methods in kb/rdp/actors/accessibility.md (iter-136, from prior source verification) — this PR is the first call site, not new spec research.
  • Live-Firefox evidence in place of the static check: live_143_native_a11y_tree.rs's three tests (live_a11y_source_meta, live_a11y_native_opt_in, live_a11y_service_restored) were run in this session against real headless Firefox (FF_RDP_LIVE_TESTS=1) and passed, exercising enable/disable end-to-end. The manual dogfood run (ff-rdp a11y --native) also succeeded, returning {"source":"native","role":"document"}.
  • No oneway/release/bulk markers are involved — both methods are plain request/reply, matching the existing bootstrap() call already in this actor.

Test plan

  • cargo fmt --all -- --check

  • cargo clippy --workspace --all-targets -- -D warnings

  • cargo test --workspace -q (full workspace, all green)

  • FF_RDP_LIVE_TESTS=1 live tests: live_143_native_a11y_tree::{live_a11y_source_meta,live_a11y_native_opt_in,live_a11y_service_restored} and live_a11y_critical::a11y_critical_filters_to_violations — all pass against real headless Firefox

  • Manual dogfood run of the plan's dogfood_path against real Firefox — meta.source correctly reports "js-fallback" by default and "native"/"document" under --native

  • cargo run -p xtask -- check-iteration-ready --plan kb/iterations/iteration-143-native-a11y-tree.md --base origin/main — 10/10 PASS## Claims vs code
    <generated 2026-08-12T06:00:11Z by ralph-loop>

  • an → ✅ matched in diff

ractive and others added 2 commits August 12, 2026 07:55
Iteration 143: ff-rdp a11y now always reports meta.source
("native"/"js-fallback", plus a reason) so callers can tell the real
platform accessibility tree apart from the DOM-derived JS fallback.
Adds an opt-in --native flag that enables Firefox's accessibility
service via parentAccessibilityActor.enable() when it is off, walks
the native tree, and restores the prior state afterward — never the
default (DEC-027). Also bounds walker requests to a 3s read timeout so
a stalled service costs seconds, not the full configured --timeout.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…dent

iter-143 established two reusable patterns (DEC-027 restore-only-what-
you-changed, and bounded RDP read-timeouts around calls that stall
instead of erroring) directly applicable to iter-144's Theme C field-
honesty redesign and any stalling calls Theme D/F turn up.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@ractive
ractive merged commit aeca4d0 into main Aug 12, 2026
10 checks passed
@ractive
ractive deleted the iter-143/native-a11y-tree branch August 12, 2026 06:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant