@flighthq/accessibility 0.1.0

package/dist/accessibility.d.ts

@@ -0,0 +1,10 @@
+import type { AccessibilityBackend, AccessibilityLiveness, AccessibilityNode } from '@flighthq/types';
+export declare function announceAccessibility(message: string, liveness?: AccessibilityLiveness): void;
+export declare function clearAccessibilityTree(): void;
+export declare function createWebAccessibilityBackend(container?: HTMLElement): AccessibilityBackend;
+export declare function getAccessibilityBackend(): AccessibilityBackend;
+export declare function removeAccessibilityNode(id: string): void;
+export declare function setAccessibilityBackend(backend: AccessibilityBackend | null): void;
+export declare function setAccessibilityFocus(id: string): boolean;
+export declare function setAccessibilityNode(node: Readonly<AccessibilityNode>): void;
+//# sourceMappingURL=accessibility.d.ts.map

package/dist/accessibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accessibility.d.ts","sourceRoot":"","sources":["../src/accessibility.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EAElB,MAAM,iBAAiB,CAAC;AAKzB,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,GAAE,qBAAgC,GAAG,IAAI,CAEvG;AAID,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C;AAQD,wBAAgB,6BAA6B,CAAC,SAAS,CAAC,EAAE,WAAW,GAAG,oBAAoB,CAgE3F;AAID,wBAAgB,uBAAuB,IAAI,oBAAoB,CAG9D;AAGD,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAExD;AAGD,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI,GAAG,IAAI,CAElF;AAID,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAEzD;AAID,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,QAAQ,CAAC,iBAAiB,CAAC,GAAG,IAAI,CAE5E"}

package/dist/accessibility.js

@@ -0,0 +1,234 @@
+// Speaks a transient message through the platform's live region. `liveness` picks urgency: 'polite'
+// waits for current speech, 'assertive' interrupts. Defaults to 'polite'. No-op when no backend can
+// speak.
+export function announceAccessibility(message, liveness = 'polite') {
+    getAccessibilityBackend().announce(message, liveness);
+}
+// Empties the mirrored accessibility tree, removing every published node. Announcement live regions
+// are recreated lazily on the next announce.
+export function clearAccessibilityTree() {
+    getAccessibilityBackend().clear();
+}
+// Builds the default web backend: a visually-hidden ARIA DOM overlay. Created lazily by
+// getAccessibilityBackend — nothing touches the DOM at import time, so importing the package has no
+// side effect. Each published node becomes an element carrying `role` + `aria-*` attributes, nested
+// under its `parentId`'s element (or the container root). By default a hidden container is appended
+// to document.body on first use; pass `container` to host the overlay elsewhere. With no DOM present
+// every method is a sentinel no-op (setFocus returns false) rather than throwing.
+export function createWebAccessibilityBackend(container) {
+    const elements = new Map();
+    const liveRegions = new Map();
+    let root = container ?? null;
+    let rootResolved = container !== undefined;
+    // Resolves the overlay root, lazily creating and appending a hidden container on first use. Returns
+    // null when no DOM is available, which flips every method into a no-op.
+    function getRoot() {
+        if (rootResolved)
+            return root;
+        rootResolved = true;
+        if (typeof document === 'undefined' || document.body === null) {
+            root = null;
+            return null;
+        }
+        root = _createHiddenAccessibilityContainer(document);
+        document.body.appendChild(root);
+        return root;
+    }
+    return {
+        setNode(node) {
+            const overlayRoot = getRoot();
+            if (overlayRoot === null)
+                return;
+            let element = elements.get(node.id);
+            if (element === undefined) {
+                element = overlayRoot.ownerDocument.createElement('div');
+                element.setAttribute('data-flight-accessibility-id', node.id);
+                elements.set(node.id, element);
+            }
+            _applyAccessibilityElementAttributes(element, node);
+            _reparentAccessibilityElement(element, node.parentId, elements, overlayRoot);
+        },
+        removeNode(id) {
+            const element = elements.get(id);
+            if (element === undefined)
+                return;
+            // Drop the node and its entire descendant subtree (Node.contains is true for the element
+            // itself and every DOM descendant, matching the nested overlay layout).
+            for (const [key, other] of elements) {
+                if (element.contains(other))
+                    elements.delete(key);
+            }
+            if (element.parentNode !== null)
+                element.parentNode.removeChild(element);
+        },
+        clear() {
+            const overlayRoot = getRoot();
+            elements.clear();
+            liveRegions.clear();
+            if (overlayRoot !== null)
+                overlayRoot.replaceChildren();
+        },
+        setFocus(id) {
+            const overlayRoot = getRoot();
+            if (overlayRoot === null)
+                return false;
+            const element = elements.get(id);
+            if (element === undefined)
+                return false;
+            element.focus();
+            return overlayRoot.ownerDocument.activeElement === element;
+        },
+        announce(message, liveness) {
+            const overlayRoot = getRoot();
+            if (overlayRoot === null)
+                return;
+            const region = _getAccessibilityLiveRegion(overlayRoot, liveRegions, liveness);
+            region.textContent = message;
+        },
+    };
+}
+// The active accessibility backend, lazily defaulting to the web ARIA overlay. There is always a
+// backend.
+export function getAccessibilityBackend() {
+    if (_backend === null)
+        _backend = createWebAccessibilityBackend();
+    return _backend;
+}
+// Removes a node and its entire descendant subtree from the mirrored tree.
+export function removeAccessibilityNode(id) {
+    getAccessibilityBackend().removeNode(id);
+}
+// Installs a native host accessibility backend; pass null to fall back to a fresh lazy web default.
+export function setAccessibilityBackend(backend) {
+    _backend = backend;
+}
+// Moves platform focus to the published node. Returns false when the node is missing or the platform
+// could not focus it — a sentinel, never a throw.
+export function setAccessibilityFocus(id) {
+    return getAccessibilityBackend().setFocus(id);
+}
+// Registers or updates a node in the mirrored tree, keyed by `node.id` and parented by
+// `node.parentId`. Re-issuing with the same id updates the existing node in place.
+export function setAccessibilityNode(node) {
+    getAccessibilityBackend().setNode(node);
+}
+let _backend = null;
+const _TEXT_NODE = 3;
+// Reflects a node's semantics onto its overlay element: role, the label/description/value text and
+// their ARIA attributes, focusability, and the mapped state attributes. Attributes are cleared when
+// their source field is absent, so an update that drops a field clears the stale attribute.
+function _applyAccessibilityElementAttributes(element, node) {
+    element.setAttribute('role', node.role);
+    _reflectAccessibilityAttribute(element, 'aria-label', node.label);
+    _reflectAccessibilityAttribute(element, 'aria-description', node.description);
+    _reflectAccessibilityAttribute(element, 'title', node.description);
+    _reflectAccessibilityAttribute(element, 'aria-valuetext', node.value);
+    _setAccessibilityElementValueText(element, node.value);
+    // Every node element is focusable so setFocus can move platform focus to it, including
+    // non-interactive roles (heading/region) a caller may want to move a screen reader to.
+    element.setAttribute('tabindex', '-1');
+    _applyAccessibilityStateAttributes(element, node.states ?? _EMPTY_STATE);
+}
+// Maps each AccessibilityState field to its ARIA attribute. Absent fields clear the attribute so a
+// state that was set then dropped does not linger.
+function _applyAccessibilityStateAttributes(element, state) {
+    _reflectAccessibilityBoolean(element, 'aria-disabled', state.disabled);
+    _reflectAccessibilityBoolean(element, 'aria-checked', state.checked);
+    _reflectAccessibilityBoolean(element, 'aria-expanded', state.expanded);
+    _reflectAccessibilityBoolean(element, 'aria-selected', state.selected);
+    _reflectAccessibilityBoolean(element, 'aria-pressed', state.pressed);
+    _reflectAccessibilityBoolean(element, 'aria-busy', state.busy);
+    _reflectAccessibilityBoolean(element, 'aria-hidden', state.hidden);
+    _reflectAccessibilityBoolean(element, 'aria-readonly', state.readonly);
+    _reflectAccessibilityBoolean(element, 'aria-required', state.required);
+    _reflectAccessibilityNumber(element, 'aria-level', state.level);
+    _reflectAccessibilityNumber(element, 'aria-valuemin', state.valueMin);
+    _reflectAccessibilityNumber(element, 'aria-valuemax', state.valueMax);
+    _reflectAccessibilityNumber(element, 'aria-valuenow', state.valueNow);
+}
+// Builds the visually-hidden overlay container. Uses the standard clip-rect "sr-only" inline styles
+// so the elements stay in the accessibility tree while drawing nothing on screen.
+function _createHiddenAccessibilityContainer(doc) {
+    const container = doc.createElement('div');
+    container.setAttribute('data-flight-accessibility', 'true');
+    const style = container.style;
+    style.position = 'absolute';
+    style.width = '1px';
+    style.height = '1px';
+    style.margin = '-1px';
+    style.padding = '0';
+    style.border = '0';
+    style.overflow = 'hidden';
+    style.clip = 'rect(0 0 0 0)';
+    style.clipPath = 'inset(50%)';
+    style.whiteSpace = 'nowrap';
+    return container;
+}
+// Resolves the persistent aria-live region for the given urgency, creating and appending it under
+// the container on first use (or when a prior clear removed it).
+function _getAccessibilityLiveRegion(root, liveRegions, liveness) {
+    let region = liveRegions.get(liveness);
+    if (region === undefined || region.parentNode === null) {
+        region = root.ownerDocument.createElement('div');
+        region.setAttribute('aria-live', liveness);
+        region.setAttribute('aria-atomic', 'true');
+        region.setAttribute('data-flight-accessibility-live', liveness);
+        liveRegions.set(liveness, region);
+        root.appendChild(region);
+    }
+    return region;
+}
+// Sets a string attribute, or removes it when the value is absent.
+function _reflectAccessibilityAttribute(element, attribute, value) {
+    if (value === undefined) {
+        element.removeAttribute(attribute);
+        return;
+    }
+    element.setAttribute(attribute, value);
+}
+// Sets a boolean attribute as 'true'/'false', or removes it when the value is absent.
+function _reflectAccessibilityBoolean(element, attribute, value) {
+    if (value === undefined) {
+        element.removeAttribute(attribute);
+        return;
+    }
+    element.setAttribute(attribute, value ? 'true' : 'false');
+}
+// Sets a numeric attribute as its decimal string, or removes it when the value is absent.
+function _reflectAccessibilityNumber(element, attribute, value) {
+    if (value === undefined) {
+        element.removeAttribute(attribute);
+        return;
+    }
+    element.setAttribute(attribute, String(value));
+}
+// Moves the element under the element of `parentId` (or the container root when the parent is unknown
+// or unset). Only touches the DOM when the parent actually changes, so re-issuing an unchanged node
+// causes no reparenting churn.
+function _reparentAccessibilityElement(element, parentId, elements, root) {
+    let parent = root;
+    if (parentId !== undefined) {
+        const found = elements.get(parentId);
+        if (found !== undefined)
+            parent = found;
+    }
+    if (element.parentNode !== parent)
+        parent.appendChild(element);
+}
+// Maintains the node's value as a leading text node so nested child elements survive value updates
+// (setting element.textContent would wipe the appended child nodes).
+function _setAccessibilityElementValueText(element, value) {
+    const first = element.firstChild;
+    if (value === undefined) {
+        if (first !== null && first.nodeType === _TEXT_NODE)
+            element.removeChild(first);
+        return;
+    }
+    if (first !== null && first.nodeType === _TEXT_NODE) {
+        first.nodeValue = value;
+        return;
+    }
+    element.insertBefore(element.ownerDocument.createTextNode(value), first);
+}
+const _EMPTY_STATE = {};
+//# sourceMappingURL=accessibility.js.map

package/dist/accessibility.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"accessibility.js","sourceRoot":"","sources":["../src/accessibility.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './accessibility';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './accessibility';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC"}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@flighthq/accessibility",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.test.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts",
+    "prepack": "npm run clean && npm run clean:dist && npm run build",
+    "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
+  },
+  "dependencies": {
+    "@flighthq/types": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "Assistive-technology (ARIA) bridge over a swappable web/native backend (a visually-hidden ARIA DOM overlay by default)",
+  "sideEffects": false
+}

package/src/accessibility.test.ts

@@ -0,0 +1,285 @@
+import type { AccessibilityBackend, AccessibilityLiveness, AccessibilityNode } from '@flighthq/types';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  announceAccessibility,
+  clearAccessibilityTree,
+  createWebAccessibilityBackend,
+  getAccessibilityBackend,
+  removeAccessibilityNode,
+  setAccessibilityBackend,
+  setAccessibilityFocus,
+  setAccessibilityNode,
+} from './accessibility';
+
+afterEach(() => {
+  setAccessibilityBackend(null);
+  vi.unstubAllGlobals();
+  document.body.replaceChildren();
+});
+
+describe('announceAccessibility', () => {
+  it('dispatches the message and liveness to the backend', () => {
+    const mock = createMockAccessibilityBackend();
+    setAccessibilityBackend(mock.backend);
+    announceAccessibility('saved', 'assertive');
+    expect(mock.calls.announce).toEqual([['saved', 'assertive']]);
+  });
+
+  it('defaults liveness to polite', () => {
+    const mock = createMockAccessibilityBackend();
+    setAccessibilityBackend(mock.backend);
+    announceAccessibility('loading');
+    expect(mock.calls.announce).toEqual([['loading', 'polite']]);
+  });
+});
+
+describe('clearAccessibilityTree', () => {
+  it('dispatches a clear to the backend', () => {
+    const mock = createMockAccessibilityBackend();
+    setAccessibilityBackend(mock.backend);
+    clearAccessibilityTree();
+    expect(mock.calls.clear).toBe(1);
+  });
+});
+
+describe('createWebAccessibilityBackend', () => {
+  it('creates an element carrying role, aria-label, and mapped state attributes', () => {
+    const container = document.createElement('div');
+    const backend = createWebAccessibilityBackend(container);
+    backend.setNode(node('play', 'button', { label: 'Play', states: { disabled: true, pressed: false } }));
+    const element = container.querySelector('[data-flight-accessibility-id="play"]');
+    expect(element).not.toBeNull();
+    expect(element?.getAttribute('role')).toBe('button');
+    expect(element?.getAttribute('aria-label')).toBe('Play');
+    expect(element?.getAttribute('aria-disabled')).toBe('true');
+    expect(element?.getAttribute('aria-pressed')).toBe('false');
+  });
+
+  it('maps description to aria-description and title, and value to text and aria-valuetext', () => {
+    const container = document.createElement('div');
+    const backend = createWebAccessibilityBackend(container);
+    backend.setNode(node('vol', 'slider', { description: 'Volume level', value: '70%' }));
+    const element = container.querySelector('[data-flight-accessibility-id="vol"]');
+    expect(element?.getAttribute('aria-description')).toBe('Volume level');
+    expect(element?.getAttribute('title')).toBe('Volume level');
+    expect(element?.getAttribute('aria-valuetext')).toBe('70%');
+    expect(element?.textContent).toBe('70%');
+  });
+
+  it('maps range and level numerics to their aria attributes', () => {
+    const container = document.createElement('div');
+    const backend = createWebAccessibilityBackend(container);
+    backend.setNode(node('bar', 'progressbar', { states: { valueMin: 0, valueMax: 100, valueNow: 42, level: 2 } }));
+    const element = container.querySelector('[data-flight-accessibility-id="bar"]');
+    expect(element?.getAttribute('aria-valuemin')).toBe('0');
+    expect(element?.getAttribute('aria-valuemax')).toBe('100');
+    expect(element?.getAttribute('aria-valuenow')).toBe('42');
+    expect(element?.getAttribute('aria-level')).toBe('2');
+  });
+
+  it('updates an existing node in place without duplicating the element', () => {
+    const container = document.createElement('div');
+    const backend = createWebAccessibilityBackend(container);
+    backend.setNode(node('cb', 'checkbox', { label: 'Mute', states: { checked: false } }));
+    backend.setNode(node('cb', 'checkbox', { label: 'Muted', states: { checked: true } }));
+    const matches = container.querySelectorAll('[data-flight-accessibility-id="cb"]');
+    expect(matches.length).toBe(1);
+    expect(matches[0].getAttribute('aria-label')).toBe('Muted');
+    expect(matches[0].getAttribute('aria-checked')).toBe('true');
+  });
+
+  it('clears an attribute when an updated node drops the field', () => {
+    const container = document.createElement('div');
+    const backend = createWebAccessibilityBackend(container);
+    backend.setNode(node('cb', 'checkbox', { label: 'Mute', states: { checked: true } }));
+    backend.setNode(node('cb', 'checkbox', {}));
+    const element = container.querySelector('[data-flight-accessibility-id="cb"]');
+    expect(element?.hasAttribute('aria-label')).toBe(false);
+    expect(element?.hasAttribute('aria-checked')).toBe(false);
+    expect(element?.textContent).toBe('');
+  });
+
+  it('nests a child element under its parentId element', () => {
+    const container = document.createElement('div');
+    const backend = createWebAccessibilityBackend(container);
+    backend.setNode(node('menu', 'menu', { label: 'File' }));
+    backend.setNode(node('item', 'menuitem', { label: 'Open', parentId: 'menu' }));
+    const parent = container.querySelector('[data-flight-accessibility-id="menu"]');
+    const child = container.querySelector('[data-flight-accessibility-id="item"]');
+    expect(child?.parentElement).toBe(parent);
+  });
+
+  it('re-parents an element when parentId changes', () => {
+    const container = document.createElement('div');
+    const backend = createWebAccessibilityBackend(container);
+    backend.setNode(node('a', 'group', {}));
+    backend.setNode(node('b', 'group', {}));
+    backend.setNode(node('leaf', 'button', { parentId: 'a' }));
+    const child = () => container.querySelector('[data-flight-accessibility-id="leaf"]');
+    expect(child()?.parentElement?.getAttribute('data-flight-accessibility-id')).toBe('a');
+    backend.setNode(node('leaf', 'button', { parentId: 'b' }));
+    expect(child()?.parentElement?.getAttribute('data-flight-accessibility-id')).toBe('b');
+  });
+
+  it('removes a node and its descendant subtree', () => {
+    const container = document.createElement('div');
+    const backend = createWebAccessibilityBackend(container);
+    backend.setNode(node('menu', 'menu', {}));
+    backend.setNode(node('item', 'menuitem', { parentId: 'menu' }));
+    backend.removeNode('menu');
+    expect(container.querySelector('[data-flight-accessibility-id="menu"]')).toBeNull();
+    expect(container.querySelector('[data-flight-accessibility-id="item"]')).toBeNull();
+    // The descendant id is dropped from tracking too, so re-adding it lands at the root.
+    backend.setNode(node('item', 'menuitem', { parentId: 'menu' }));
+    expect(container.querySelector('[data-flight-accessibility-id="item"]')?.parentElement).toBe(container);
+  });
+
+  it('focuses a node element and reports missing ids as false', () => {
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    const backend = createWebAccessibilityBackend(container);
+    backend.setNode(node('field', 'textbox', { label: 'Name' }));
+    expect(backend.setFocus('field')).toBe(true);
+    const element = container.querySelector('[data-flight-accessibility-id="field"]');
+    expect(document.activeElement).toBe(element);
+    expect(backend.setFocus('missing')).toBe(false);
+  });
+
+  it('writes announcements into the polite and assertive live regions', () => {
+    const container = document.createElement('div');
+    const backend = createWebAccessibilityBackend(container);
+    backend.announce('level complete', 'polite');
+    backend.announce('warning', 'assertive');
+    const polite = container.querySelector('[data-flight-accessibility-live="polite"]');
+    const assertive = container.querySelector('[data-flight-accessibility-live="assertive"]');
+    expect(polite?.getAttribute('aria-live')).toBe('polite');
+    expect(polite?.textContent).toBe('level complete');
+    expect(assertive?.getAttribute('aria-live')).toBe('assertive');
+    expect(assertive?.textContent).toBe('warning');
+  });
+
+  it('empties the container on clear', () => {
+    const container = document.createElement('div');
+    const backend = createWebAccessibilityBackend(container);
+    backend.setNode(node('a', 'button', {}));
+    backend.announce('hi', 'polite');
+    expect(container.childElementCount).toBeGreaterThan(0);
+    backend.clear();
+    expect(container.childElementCount).toBe(0);
+  });
+
+  it('defaults its container into document.body', () => {
+    const backend = createWebAccessibilityBackend();
+    backend.setNode(node('a', 'button', {}));
+    expect(document.querySelector('[data-flight-accessibility-id="a"]')).not.toBeNull();
+    expect(document.body.querySelector('[data-flight-accessibility]')).not.toBeNull();
+  });
+
+  it('is a sentinel no-op when no DOM is available', () => {
+    vi.stubGlobal('document', undefined);
+    const backend = createWebAccessibilityBackend();
+    expect(() => backend.setNode(node('a', 'button', {}))).not.toThrow();
+    expect(() => backend.removeNode('a')).not.toThrow();
+    expect(() => backend.announce('hi', 'polite')).not.toThrow();
+    expect(() => backend.clear()).not.toThrow();
+    expect(backend.setFocus('a')).toBe(false);
+  });
+});
+
+describe('getAccessibilityBackend', () => {
+  it('lazily returns a stable web default', () => {
+    const first = getAccessibilityBackend();
+    expect(first).toBe(getAccessibilityBackend());
+  });
+
+  it('returns the installed backend', () => {
+    const mock = createMockAccessibilityBackend();
+    setAccessibilityBackend(mock.backend);
+    expect(getAccessibilityBackend()).toBe(mock.backend);
+  });
+});
+
+describe('removeAccessibilityNode', () => {
+  it('dispatches the id to the backend', () => {
+    const mock = createMockAccessibilityBackend();
+    setAccessibilityBackend(mock.backend);
+    removeAccessibilityNode('gone');
+    expect(mock.calls.removeNode).toEqual(['gone']);
+  });
+});
+
+describe('setAccessibilityBackend', () => {
+  it('installs a backend that later commands dispatch through', () => {
+    const mock = createMockAccessibilityBackend();
+    setAccessibilityBackend(mock.backend);
+    setAccessibilityNode(node('a', 'button', {}));
+    expect(mock.calls.setNode.length).toBe(1);
+  });
+
+  it('restores a fresh, distinct web default when passed null', () => {
+    const original = getAccessibilityBackend();
+    setAccessibilityBackend(null);
+    const restored = getAccessibilityBackend();
+    expect(restored).not.toBe(original);
+  });
+});
+
+describe('setAccessibilityFocus', () => {
+  it('dispatches the id and returns the backend result', () => {
+    const mock = createMockAccessibilityBackend();
+    setAccessibilityBackend(mock.backend);
+    expect(setAccessibilityFocus('ok')).toBe(true);
+    expect(setAccessibilityFocus('nope')).toBe(false);
+    expect(mock.calls.setFocus).toEqual(['ok', 'nope']);
+  });
+});
+
+describe('setAccessibilityNode', () => {
+  it('dispatches the node to the backend', () => {
+    const mock = createMockAccessibilityBackend();
+    setAccessibilityBackend(mock.backend);
+    const target = node('a', 'button', { label: 'Go' });
+    setAccessibilityNode(target);
+    expect(mock.calls.setNode).toEqual([target]);
+  });
+});
+
+function node(
+  id: string,
+  role: AccessibilityNode['role'],
+  rest: Readonly<Omit<AccessibilityNode, 'id' | 'role'>>,
+): AccessibilityNode {
+  return { id, role, ...rest };
+}
+
+interface MockAccessibilityCalls {
+  setNode: AccessibilityNode[];
+  removeNode: string[];
+  clear: number;
+  setFocus: string[];
+  announce: (readonly [string, AccessibilityLiveness])[];
+}
+
+function createMockAccessibilityBackend(): { backend: AccessibilityBackend; calls: MockAccessibilityCalls } {
+  const calls: MockAccessibilityCalls = { setNode: [], removeNode: [], clear: 0, setFocus: [], announce: [] };
+  const backend: AccessibilityBackend = {
+    setNode(target) {
+      calls.setNode.push(target as AccessibilityNode);
+    },
+    removeNode(id) {
+      calls.removeNode.push(id);
+    },
+    clear() {
+      calls.clear += 1;
+    },
+    setFocus(id) {
+      calls.setFocus.push(id);
+      return id === 'ok';
+    },
+    announce(message, liveness) {
+      calls.announce.push([message, liveness]);
+    },
+  };
+  return { backend, calls };
+}