AutomationShim Spec (a11y phase 1, U1 deliverable)
Authoritative contract for replatforming ChromeVox’s live-region brain onto standard-extension inputs. Derived from the vendored fork at third_party/chromevox (chromium/src @ 7df028f9, chromevox + accessibility/common subtrees). Plan: docs/plans/2026-07-06-accessibility-primitive-layer-brainstorm.md.
Method: import-closure walk from mv3/background/live_regions.ts + mv3/background/output/*.ts (425 edges); AutomationNode member enumeration over identifiers TypeScript-typed as AutomationNode plus conventional node locals; chrome.automation.* symbol grep; line-verified read of live_regions.ts. Grep-based member enumeration is a superset guide — U3 finalizes per-member semantics against recorded AX-tree fixtures.
1. The TreeChange observer contract (verified line-by-line)
The only web-content entry point into LiveRegions (mv3/background/live_regions.ts):
- Constructor (L64–68):
chrome.automation.addTreeChangeObserver(TreeChangeObserverFilter.LIVE_REGION_TREE_CHANGES, treeChange => this.onTreeChange(treeChange)). The shim implementsaddTreeChangeObserverfor this filter. TreeChange = {type, target}wheretargetis an AutomationNode andtype ∈ {NODE_CREATED, SUBTREE_CREATED, TEXT_CHANGED, NODE_REMOVED, SUBTREE_UPDATE_END}.onTreeChange(L117–151): early-returns unlesstarget.containerLiveStatusis set and ≠'off'— exceptSUBTREE_UPDATE_END, which must always be delivered (it flushes the queued batch, L148–150). Relevance parsing (additions/text/removals/allfromcontainerLiveRelevant) happens in the fork (L129–146) — the observer must NOT pre-filter by relevance, only supply the attributes.- Emission rule for the U4 observer: per changed descendant node (not region root), typed records, each burst terminated by one
SUBTREE_UPDATE_END. - Timing/dedupe the fork already owns (don’t duplicate): 5000ms
LIVE_REGION_QUEUE_TIME_MSwindow (L53), 20ms same-node throttle (L58),liveRegionNodeSet_WeakSet recursive dedupe (L243–253),containerLiveBusyskip (L179),liveAtomicwalk-up (L183–185),@live_regions_removedfor removals (L145).
2. Suppression & flush topology (the anti-“delivered but silent” contract)
shouldIgnoreLiveRegion_ (L255–281), in order:
- static
announceLiveRegionsFromBackgroundTabs_flag (false; private — not a seam). ChromeVoxRange.current.start.node.root === node.root→ NOT ignored (L260–263). MaintainingChromeVoxRange.currentinside the active tab’s tree is sufficient to defeat suppression for that tab. The announcer owns this.- Fallback:
hostView = getTopLevelRoot(node).parent— null on a bare per-tab tree → ignored. The synthetic ancestor (below) rescues non-current tabs.
Flush semantics (outputLiveRegionChangeForNode_, L200–224): forceQueue = !hostView || !hostView.state['focused'] || currentRange.root !== node.root || status==='polite' — without a focused synthetic ancestor everything is QueueMode.QUEUE, never CATEGORY_FLUSH. QueueMode is additionally time-multiplexed by the 5s window, so politeness is NOT recoverable from QueueMode (plan KTD4): politeness rides the observer metadata; QueueMode only informs the interrupt hint.
Synthetic topology the shim presents: a synthetic desktop root (also serves chrome.automation.getDesktop) → per-tab synthetic window node (role: window, state.focused true for the active tab, not INVISIBLE) → the tab’s real AX page root. getTopLevelRoot(node).parent then resolves to the synthetic window.
3. Module closure: 89 modules → bundle vs stub
Closure: 69 chromevox/mv3 + 20 common/ modules. Full lists reproducible via the walk in this spec’s Method. Cut set:
Tier A — bundle unmodified (the brain): background/live_regions.ts; background/output/ (all 11: output, output_rules, output_formatter, output_format_parser, output_format_tree, output_ancestry_info, output_role_info, output_interface, output_logger, output_types, braille_output — braille_output stays, its braille deps are stubbed below it); background/chromevox_range.ts, background/chromevox_state.ts, background/chromevox.ts (the static tts/braille/earcons holder — our injection point), background/focus_bounds.ts; background/editing/editable_line.ts (+ its editing chain if the build pulls it cleanly); mv3/common/: tts_types, msgs, locale_output_helper, spannable, role_type, log_types, custom_automation_event, earcon_id, command, event_source_type, internal_key_event, tree_dumper; common/ (vendored): automation_predicate, automation_util, tree_walker, constants, cursors/{cursor,range,recovery_strategy}, string_util, word_utils, paragraph_utils, async_util, settings, event_generator, key_code, extension_util, testing/test_import_manager.
Tier B — stub by esbuild alias (the platform leaves):
| Seam | Modules aliased | Stub behavior |
|---|---|---|
| TTS → sink | abstract_tts, primary_tts, tts_background, console_tts, composite_tts, tts_interface | our tts_sink implements the TtsInterface speak(text, queueMode, properties); emits announcement records |
| Braille | braille/{braille_command_handler, braille_interface, braille_translator, liblouis, spans}, braille_command_data, braille_key_types, nav_braille | no-op |
| Panel/offscreen | panel_bridge, panel_command, panel_menu_data, offscreen_bridge(+constants) | no-op |
| Bridge plumbing | bridge_helper, bridge_callback_manager, bridge_constants | no-op |
| Settings/storage | settings_manager, local_storage, prefs | static normal-profile object |
| Logging | logging/{event_stream_logger, log_store, log_url_watcher} | no-op |
| Msgs formatter | /chromevox/mv3/third_party/messageformat/messageformat.rollup.js (a Chromium build artifact, absent from every source subtree) | thin adapter over npm @messageformat/core (MIT — the same library Chromium rolls up) |
| Phonetics | phonetic_data.js (+ its generated ../phonetic_dictionaries.js), tamachiyomi/ja_phonetic_data | empty dictionaries |
| Misc | math_handler, abstract_earcons/earcons, event/{base_automation_handler, desktop_automation_interface}, input/command_handler_interface, event_source | no-op / inert holders |
Resolution rule for U2: bundle Tier A; alias Tier B; any remaining unresolved import gets case-by-case triage within these seams. Stop condition (plan Goal Capsule): a module that requires a NEW privileged surface not covered by this table.
4. chrome.automation API surface the shim provides
Runtime functions (4): addTreeChangeObserver(filter, cb) (§1); getFocus(cb) → focused node in active tab; getDesktop(cb) → synthetic desktop root (§2); setDocumentSelection(...) (from cursors/range select paths) → no-op with debug log in phase 1. Runtime enum-value objects (used as values, not just types): EventType, RoleType, StateType, TreeChangeType, TreeChangeObserverFilter, ActionType, NameFromType, Restriction, DefaultActionVerb, HasPopup, InvalidState, MarkerType, SortDirectionType, AriaCurrentState — provided as a chrome.automation value shim module (values mirror Chromium’s string enums).
5. AutomationNode member surface
100 distinct members accessed across the closure (grep enumeration; counts = file spread). Core set (accessed in ≥3 files or by Tier-A hot paths): role, parent, root, state, children, firstChild, lastChild, nextSibling, previousSibling, value, location, checked, description, restriction, display, docUrl, url, nextOnLine, wordStarts/wordEnds, textSelStart/textSelEnd (dark on canvas — known), unclippedLocation, indexInParent, nameFrom, roleDescription, inputType, detectedLanguage, activeDescendant(For), containerLive{Status,Relevant,Busy,Atomic}, liveAtomic, tableCell{Row,Column}Index, tableCell{Row,Column}Headers, ariaCell{Row,Column}IndexText, posInSet, setSize, selected, hasPopup, modal, hierarchicalLevel, invalidState, placeholder, tooltip, autoComplete, accessKey, customActions, standardActions, defaultActionVerb, doDefaultLabel, longClickLabel, clickable, htmlTag, language, markers, matches, addEventListener/removeEventListener (event subscription on nodes — no-op acceptable phase 1), querySelectorAll (no-op/queryAXTree bridge), boundsForRange (editing; may no-op), font/style members (bold, italic, underline, fontSize, fontFamily, color, lineThrough, sub/superscript — editing/rich-text paths; low priority), selectionStart/EndObject+Offset, nextWindowFocus/previousWindowFocus (synthetic-topology aware), sortDirection, mathContent (stubbed with math_handler), isButton/isComboBox/isCheckBox/isImage (predicate helpers on the node in newer API — implement from role). CDP mapping: role/name/value/description/states/properties from AXNode; location/unclippedLocation via backendDOMNodeId box model; tree links from childIds/parentId wrappers; live-region attrs from AXNode properties (live, atomic, relevant, busy → containerLive* per ancestor walk); textSel* undefined on canvas (per plan).
6. Announcement record shape (sink output → bridge)
{text, politeness, category, interrupt, tab, region, ts} — politeness correlated from U4 observer metadata (NOT QueueMode); interrupt = QueueMode==CATEGORY_FLUSH hint; tab = source tabId; region = stable region identity for coalescing (additive roles exempt per R5).
7. Stop-condition assessment
None triggered. Every closure module lands in a Tier; every external touchpoint has a seam; the two non-source imports (messageformat rollup, phonetic dictionaries) are build artifacts with clean replacements. The heaviest residual risk is Tier-A drag from editing/* via chromevox_range/editable_line — bounded by the Tier-B event/ + input/ stubs and triaged mechanically in U2.