@twip/web 0.0.0-canary-4d6177a → 0.0.0-canary-abcb2d5

package/dist/commands.d.ts

@@ -680,6 +680,8 @@ export interface Commands {
     showAutoCorrectOptions(): Promise<void>;
     /** Dismisses the popover asked for (`popoverClosed`), for an application that closes its own on Esc or a press elsewhere; with none open, nothing. View. */
     closePopover(): Promise<void>;
+    /** Says the formatting at the caret to screen readers (an `announcement` of kind `formatting`). Shift+F1. */
+    describeFormatting(): Promise<void>;
 }
 /** A command id: the method name, the batch op's `type`, the catalog id and the key in `state.commands`. */
 export type CommandId = keyof Commands;

package/dist/commands.js

@@ -191,6 +191,7 @@ const encodings = {
     neverAutoCorrect: 'none',
     showAutoCorrectOptions: 'none',
     closePopover: 'none',
+    describeFormatting: 'none',
 };
 /** Builds a command's op from its method arguments. */
 export function toOp(id, arg) {

package/dist/editor.d.ts

@@ -74,6 +74,8 @@ export interface MountOptions extends SessionOptions {
      * `leaders` colour, so the application draws only the cards. Default false: the application draws them.
      */
     drawLeaders?: boolean;
+    /** The editor's accessible name, which screen readers say when it gets the focus. Default `'Document'`. */
+    label?: string;
     /** Aborts the mount; everything it created is released. */
     signal?: AbortSignal;
 }

package/dist/events.d.ts

@@ -1,5 +1,6 @@
 import type { EditorError } from './errors.js';
 import type { BalloonPlacement, CommentAnchor } from './review.js';
+import type { AnnouncementKind } from './services/accessibility.js';
 import type { DialogKind } from './services/dialogs.js';
 import type { ElementInfo } from './services/elements.js';
 import type { ContextMenuEvent } from './services/menus.js';
@@ -101,9 +102,10 @@ export interface TwipEvents {
     rulerChanged: RulerView;
     /** Mounted only: hover over a link, element mark, revision or comment, or `null` when it ends. */
     tooltip: Tooltip | null;
-    /** What the editor said to screen readers. */
+    /** What the editor said to screen readers, and what it is about (when one change says several things, the first). */
     announcement: {
         text: string;
+        kind: AnnouncementKind;
     };
     /** A fidelity warning outside an operation. */
     warning: Warning;

package/dist/host/a11y.d.ts

@@ -1,3 +1,9 @@
 import type { Session } from '../editor.js';
 import type { Dom, Ledger } from './dom.js';
-export declare function startA11y(s: Session, dom: Dom, ledger: Ledger): void;
+/** The mirror's part in pointer input. */
+export interface A11y {
+    /** Whether a mirror node was just activated: a press now is the screen reader's click, and places no caret. */
+    activating(): boolean;
+}
+/** Mirrors the tree and speaks announcements. `label` is the editor's accessible name; `focus` focuses the editing element. */
+export declare function startA11y(s: Session, dom: Dom, ledger: Ledger, label: string, focus: () => void, report: (e: unknown) => void): A11y;

package/dist/host/a11y.js

@@ -1,42 +1,156 @@
-import { Kind } from '../transport/protocol.js';
-const roles = {
-    document: 'document',
-    page: 'region',
-    paragraph: 'paragraph',
-    heading: 'heading',
-    list: 'list',
-    listItem: 'listitem',
-    table: 'table',
-    row: 'row',
-    cell: 'cell',
-    image: 'img',
-    link: 'link',
-    textBox: 'group',
-    note: 'note',
-    header: 'region',
-    footer: 'region',
+import { Kind, Method } from '../transport/protocol.js';
+/** Each role's element and ARIA role. Inline nodes are spans; the rest are divs. */
+const elements = {
+    document: { tag: 'div', role: 'document' },
+    paragraph: { tag: 'div', role: 'paragraph' },
+    heading: { tag: 'div', role: 'heading' },
+    list: { tag: 'div', role: 'list' },
+    listItem: { tag: 'div', role: 'listitem' },
+    table: { tag: 'div', role: 'table' },
+    row: { tag: 'div', role: 'row' },
+    cell: { tag: 'div', role: 'cell' },
+    columnHeader: { tag: 'div', role: 'columnheader' },
+    rowHeader: { tag: 'div', role: 'rowheader' },
+    image: { tag: 'span', role: 'img' },
+    link: { tag: 'span', role: 'link' },
+    textBox: { tag: 'div', role: 'group' },
+    note: { tag: 'div', role: 'note' },
+    noteRef: { tag: 'span', role: 'link' },
+    comment: { tag: 'div', role: 'comment' },
+    // Named groups inside the headers and footers region: the landmark key goes from region to region, not into each.
+    header: { tag: 'div', role: 'group' },
+    footer: { tag: 'div', role: 'group' },
+    region: { tag: 'div', role: 'region' },
+    text: { tag: 'span' },
 };
-const hidden = 'position:absolute;left:0;top:0;width:1px;height:1px;overflow:hidden;clip-path:inset(50%);white-space:nowrap;';
-function build(node) {
-    const e = document.createElement('div');
-    e.setAttribute('role', roles[node.role] ?? 'group');
-    if (node.name)
-        e.setAttribute('aria-label', node.name);
-    if (node.level !== undefined)
-        e.setAttribute('aria-level', String(node.level));
-    const marks = node.marks ?? [];
-    if (marks.includes('misspelling'))
-        e.setAttribute('aria-invalid', 'spelling');
-    const review = marks.filter((m) => m !== 'misspelling');
-    if (review.length)
-        e.setAttribute('aria-description', review.join(' '));
-    if (node.text)
-        e.append(node.text);
-    for (const child of node.children)
-        e.append(build(child));
-    return e;
+/** Nodes that hold no caret position of their own: the rest take the focus, and focusing one starts editing there. */
+const unfocused = new Set(['document', 'region', 'header', 'footer', 'list', 'table', 'row', 'text']);
+// Out of sight, one line per block: wrapped at 1px, a screen reader using the screen's layout reads a word a line.
+const hidden = 'position:absolute;left:0;top:0;width:1px;height:1px;overflow:hidden;clip-path:inset(50%);white-space:pre;';
+/** Mounts on one page get distinct element ids: `aria-details` refers to them. */
+let mounts = 0;
+/** The mirror of one mount's tree. */
+class Mirror {
+    #byId = new Map();
+    #prefix = `twip-${++mounts}-`;
+    root;
+    label;
+    constructor(root, label) {
+        this.root = root;
+        this.label = label;
+    }
+    /** The element id of node `id`, for `aria-details`. */
+    #elementId(id) {
+        return this.#prefix + id;
+    }
+    #build(node) {
+        const { tag, role } = elements[node.role] ?? elements.paragraph;
+        // Insertions and deletions are ins and del, which screen readers report as such.
+        const marks = node.marks ?? [];
+        const e = document.createElement(marks.includes('insertion') ? 'ins' : marks.includes('deletion') ? 'del' : tag);
+        e.dataset.twipId = String(node.id);
+        e.id = this.#elementId(node.id);
+        if (role)
+            e.setAttribute('role', role);
+        const name = node.role === 'document' ? this.label : node.name;
+        // A note reference holds no text of its own: its name is its text (a name alone, Chrome's NVDA reads as a letter).
+        if (name && node.role === 'noteRef' && !node.text && !node.children.length)
+            e.append(name);
+        else if (name && node.role !== 'text')
+            e.setAttribute('aria-label', name);
+        if (node.level !== undefined && (node.role === 'heading' || node.role === 'listItem'))
+            e.setAttribute('aria-level', String(node.level));
+        if (node.position) {
+            e.setAttribute('aria-posinset', String(node.position.index));
+            e.setAttribute('aria-setsize', String(node.position.count));
+        }
+        if (node.cell) {
+            e.setAttribute('aria-colindex', String(node.cell.col));
+            if (node.cell.colSpan > 1)
+                e.setAttribute('aria-colspan', String(node.cell.colSpan));
+            if (node.cell.rowSpan > 1)
+                e.setAttribute('aria-rowspan', String(node.cell.rowSpan));
+        }
+        if (marks.includes('misspelling'))
+            e.setAttribute('aria-invalid', 'spelling');
+        if (node.author && (marks.includes('insertion') || marks.includes('deletion')))
+            e.setAttribute('aria-description', `by ${node.author}`);
+        if (node.lang)
+            e.lang = node.lang;
+        if (node.details !== undefined)
+            e.setAttribute('aria-details', this.#elementId(node.details));
+        // Focusable, as a screen reader's activation (browse mode Enter) focuses the element before it clicks.
+        if (!unfocused.has(node.role))
+            e.tabIndex = -1;
+        if (node.label)
+            e.append(Object.assign(document.createElement('span'), { textContent: `${node.label} ` }));
+        if (node.text)
+            e.append(node.text);
+        for (const child of node.children)
+            e.append(this.#build(child));
+        // A row's index: its cells'.
+        if (node.role === 'row') {
+            const row = node.children.find((c) => c.cell)?.cell?.row;
+            if (row !== undefined)
+                e.setAttribute('aria-rowindex', String(row));
+        }
+        this.#byId.set(node.id, e);
+        return e;
+    }
+    #forget(e) {
+        for (const x of [e, ...e.querySelectorAll('[data-twip-id]')]) {
+            const id = Number(x.dataset.twipId);
+            if (this.#byId.get(id) === x)
+                this.#byId.delete(id);
+        }
+    }
+    update(update) {
+        if ('full' in update) {
+            this.#byId.clear();
+            this.root.replaceChildren(this.#build(update.full));
+            return;
+        }
+        // Replaced nodes not in the tree yet wait for the `children` change that places them.
+        const detached = new Map();
+        for (const change of update.patch) {
+            if (change.type === 'replace') {
+                const old = this.#byId.get(change.node.id);
+                if (old)
+                    this.#forget(old);
+                const e = this.#build(change.node);
+                if (old)
+                    old.replaceWith(e);
+                else
+                    detached.set(change.node.id, e);
+                continue;
+            }
+            const parent = this.#byId.get(change.parent);
+            if (!parent)
+                continue;
+            const wanted = change.ids.map((id) => detached.get(id) ?? this.#byId.get(id)).filter((e) => !!e);
+            const keep = new Set(wanted);
+            for (const child of [...parent.children]) {
+                if (!keep.has(child)) {
+                    this.#forget(child);
+                    child.remove();
+                }
+            }
+            // Only elements out of place move: the others stay where the screen reader may be reading.
+            wanted.forEach((e, i) => {
+                if (parent.children[i] !== e)
+                    parent.insertBefore(e, parent.children[i] ?? null);
+            });
+        }
+    }
 }
-export function startA11y(s, dom, ledger) {
+/** How long an announcement waits after emptying the live region. */
+const LIVE_MS = 50;
+/** How long after the focus comes into the editing element an announcement waits: past the focus's own speech. */
+const AFTER_FOCUS_MS = 600;
+/** How long after a mirror node's activation a press on the editor is the activation's own mouse click. */
+const ACTIVATION_MS = 500;
+/** Mirrors the tree and speaks announcements. `label` is the editor's accessible name; `focus` focuses the editing element. */
+export function startA11y(s, dom, ledger, label, focus, report) {
     const tree = ledger.node(dom.layer, document.createElement('div'));
     tree.dataset.twip = 'a11y';
     tree.style.cssText = hidden;
@@ -45,18 +159,42 @@ export function startA11y(s, dom, ledger) {
     live.setAttribute('aria-live', 'polite');
     live.setAttribute('role', 'status');
     live.style.cssText = hidden;
+    const mirror = new Mirror(tree, label);
     const onMessage = (m) => {
         const r = m.payload;
         if (m.kind === Kind.HostRequest && r.type === 'a11y')
-            tree.replaceChildren(build(r.tree));
+            mirror.update(r.update);
     };
     s.hostListeners.add(onMessage);
     s.disposers.push(() => s.hostListeners.delete(onMessage));
-    // A repeated announcement is read again: the region empties first.
+    // Activating a node starts editing there. A screen reader's activation focuses the node, then clicks it, or clicks
+    // with the mouse where it is: that lands on the canvas, and is the activation's, not a click to place the caret.
+    let activated = -Infinity;
+    const activate = (e) => {
+        // Regions and the document hold no caret position: the nearest node inside one that does.
+        const at = e.target?.closest('[data-twip-id][tabindex]');
+        if (!at || s.destroyed)
+            return;
+        e.preventDefault();
+        activated = performance.now();
+        s.call(Method.AccessibleGo, Number(at.dataset.twipId)).then(focus, report);
+    };
+    ledger.listen(tree, 'click', activate);
+    ledger.listen(tree, 'focusin', activate);
+    // A repeated announcement is read again: the region empties first. One made as the focus comes into the editing
+    // element waits for the screen reader to start saying the focus (NVDA does about 150 ms later, and cancels what it
+    // was saying): it is then said after it, not cut off by it ("Editing sub-template Violation" from a button).
     let cancel;
+    let focusedAt = -Infinity;
+    ledger.listen(dom.layer, 'focusin', (e) => {
+        if (e.target.matches('[data-twip="input"]'))
+            focusedAt = performance.now();
+    });
     s.disposers.push(s.on('announcement', ({ text }) => {
         live.textContent = '';
         cancel?.();
-        cancel = ledger.timeout(() => (live.textContent = text), 50);
+        const wait = Math.max(LIVE_MS, focusedAt + AFTER_FOCUS_MS - performance.now());
+        cancel = ledger.timeout(() => (live.textContent = text), wait);
     }));
+    return { activating: () => performance.now() - activated < ACTIVATION_MS };
 }

package/dist/host/clipboard.d.ts

@@ -7,7 +7,7 @@ export interface Clipboard {
         as?: 'formatted' | 'text';
     }): Promise<void>;
 }
-export declare function startClipboard(s: Session, dom: Dom, input: HTMLTextAreaElement, ledger: Ledger, report: (e: unknown) => void, toViewport: (e: {
+export declare function startClipboard(s: Session, dom: Dom, input: HTMLElement, ledger: Ledger, report: (e: unknown) => void, toViewport: (e: {
     clientX: number;
     clientY: number;
 }) => {

package/dist/host/clipboard.js

@@ -1,5 +1,6 @@
 import { EditorError } from '../errors.js';
 import { Kind, Method } from '../transport/protocol.js';
+import { codeOf } from './keys.js';
 /** The last copy on the page: the system clipboard has no place for its token, so a paste brings it back (the engine
  * pastes the copy it names only while the text is still that copy's). */
 let lastCopy;
@@ -71,7 +72,7 @@ export function startClipboard(s, dom, input, ledger, report, toViewport) {
     // Ctrl+Shift+V pastes as text.
     let plain = false;
     ledger.listen(input, 'keydown', (e) => {
-        plain = (e.ctrlKey || e.metaKey) && e.shiftKey && e.code === 'KeyV';
+        plain = (e.ctrlKey || e.metaKey) && e.shiftKey && codeOf(e) === 'KeyV';
     });
     ledger.listen(input, 'paste', (e) => {
         e.preventDefault();

package/dist/host/dom.js

@@ -113,6 +113,8 @@ export function createDom(container, ledger) {
     // extent, in both directions.
     const scroller = element('div', 'editor', 'position:relative;width:100%;height:100%;overflow:auto;display:grid;outline:none;');
     const canvas = element('canvas', 'canvas', 'grid-area:1/1;position:sticky;left:0;top:0;align-self:start;justify-self:start;display:block;touch-action:none;');
+    // The pixels say nothing to assistive technology: the editing element and the accessibility DOM do.
+    canvas.setAttribute('aria-hidden', 'true');
     const content = element('div', 'content', 'grid-area:1/1;position:relative;pointer-events:none;');
     const layer = element('div', 'layer', 'position:absolute;inset:0;overflow:hidden;');
     content.append(layer);

package/dist/host/ime.d.ts

@@ -1,3 +1,3 @@
 import type { Session } from '../editor.js';
 import type { Ledger } from './dom.js';
-export declare function startIme(s: Session, input: HTMLTextAreaElement, ledger: Ledger, report: (e: unknown) => void): void;
+export declare function startIme(s: Session, input: HTMLElement, ledger: Ledger, report: (e: unknown) => void): void;

package/dist/host/ime.js

@@ -3,9 +3,6 @@ export function startIme(s, input, ledger, report) {
     const compose = (phase, text) => s.input({ type: 'composition', phase, text }).catch(report);
     ledger.listen(input, 'compositionstart', () => compose(Phase.start, ''));
     ledger.listen(input, 'compositionupdate', (e) => compose(Phase.update, e.data));
-    ledger.listen(input, 'compositionend', (e) => {
-        compose(Phase.end, e.data);
-        // The element only ever holds the composition.
-        input.value = '';
-    });
+    // The editing element puts its text back after the composition (host/input.ts).
+    ledger.listen(input, 'compositionend', (e) => compose(Phase.end, e.data));
 }

package/dist/host/input.d.ts

@@ -1,12 +1,15 @@
 import type { Session } from '../editor.js';
 import type { Dom, Ledger } from './dom.js';
+/** What the editing element tells screen readers about leaving it. */
+export declare const LEAVE_HINT = "Press F6, or Escape then Tab, to leave the editor";
 /** The input element of a mounted editor. */
 export interface Input {
-    readonly element: HTMLTextAreaElement;
+    readonly element: HTMLElement;
     focus(): void;
 }
 /**
  * Starts keyboard and text input. `claims` says whether a chord is a command's, an application shortcut or a host
  * key (`shortcuts.lookup`): those keys are the editor's, and their browser defaults (Save, Print, Find) don't run.
+ * `label` is the editor's accessible name.
  */
-export declare function startInput(s: Session, dom: Dom, ledger: Ledger, report: (e: unknown) => void, claims: (chord: string) => boolean): Input;
+export declare function startInput(s: Session, dom: Dom, ledger: Ledger, report: (e: unknown) => void, claims: (chord: string) => boolean, label: string): Input;

package/dist/host/input.js

@@ -1,5 +1,5 @@
-import { Kind } from '../transport/protocol.js';
-import { keyNumber, modsOf } from './keys.js';
+import { Kind, Method } from '../transport/protocol.js';
+import { codeOf, keyNumber, modsOf } from './keys.js';
 /** Keys that edit or move, with Ctrl or Shift or neither (not Alt, which the browser keeps): the engine's. */
 const editingKeys = new Set([
     'Backspace', 'Delete', 'Enter', 'NumpadEnter', 'Tab', 'ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight', 'Home', 'End',
@@ -18,30 +18,189 @@ const names = {
     NumpadEnter: 'Enter',
 };
 /** A keydown as the shortcut strings spell it: `'Ctrl+Shift+>'`, by the key's code and by the character it made. */
-function chords(e) {
+function chords(e, code) {
     // shortcut: Cmd is read as Ctrl, so the Windows shortcut strings serve the Mac too.
     const mods = `${e.ctrlKey || e.metaKey ? 'Ctrl+' : ''}${e.altKey ? 'Alt+' : ''}${e.shiftKey ? 'Shift+' : ''}`;
-    const keys = new Set([names[e.code] ?? e.code.replace(/^Key|^Digit/, ''), e.code]);
+    const keys = new Set([names[code] ?? code.replace(/^Key|^Digit/, ''), code]);
     if (e.key.length === 1)
         keys.add(e.key.toUpperCase());
     return [...keys].map((k) => mods + k);
 }
+/** What the editing element tells screen readers about leaving it. */
+export const LEAVE_HINT = 'Press F6, or Escape then Tab, to leave the editor';
+/** Elements that can be Tab stops. */
+const STOPS = 'a[href],area[href],button,input,select,textarea,iframe,summary,[tabindex],[contenteditable=""],[contenteditable="true"]';
+/**
+ * F6 and Shift+F6, as in Word (the next pane): the focus goes to the next or previous Tab stop outside `editor`. Screen
+ * readers keep the first Escape for themselves (NVDA's leaves focus mode), so Escape then Tab doesn't get out with one.
+ */
+// ponytail: document order and tabIndex >= 0, not positive tabindex order; follow it if a page relies on that.
+function leave(from, editor, back) {
+    const stops = [...document.querySelectorAll(STOPS)].filter((e) => !editor.contains(e) && e.tabIndex >= 0 && !e.disabled && e.getClientRects().length > 0);
+    const after = (e) => (from.compareDocumentPosition(e) & Node.DOCUMENT_POSITION_FOLLOWING) !== 0;
+    (back ? stops.filter((e) => !after(e)).at(-1) : stops.find(after))?.focus();
+}
+/** A segment's element: plain text, or an element carrying its marks and language. */
+function segment(s) {
+    const marks = s.marks ?? [];
+    if (!marks.length && !s.lang)
+        return document.createTextNode(s.text);
+    const e = document.createElement(marks.includes('insertion') ? 'ins' : marks.includes('deletion') ? 'del' : 'span');
+    if (marks.includes('misspelling'))
+        e.setAttribute('aria-invalid', 'spelling');
+    if (s.author && (marks.includes('insertion') || marks.includes('deletion')))
+        e.setAttribute('aria-description', `by ${s.author}`);
+    if (s.lang)
+        e.lang = s.lang;
+    e.textContent = s.text;
+    return e;
+}
+/**
+ * A window paragraph's element: one block, so a screen reader's paragraph is the paragraph, with its lines where the
+ * canvas has them. Each line is a span that doesn't wrap, with a break point (`<wbr>`) after it; the element is 1 px
+ * wide, so the browser breaks at every break point and nowhere else: its lines are the canvas's. A `<br>` would end a
+ * paragraph for the screen reader too. A list item's label comes first.
+ */
+function paragraph(p) {
+    const e = document.createElement('div');
+    e.dataset.twipId = String(p.id);
+    if (p.role === 'heading') {
+        e.setAttribute('role', 'heading');
+        e.setAttribute('aria-level', String(p.level ?? 1));
+    }
+    if (p.label) {
+        const label = document.createElement('span');
+        label.dataset.twipLabel = '';
+        label.style.whiteSpace = 'pre';
+        label.textContent = `${p.label} `;
+        e.append(label);
+    }
+    p.lines.forEach((line, i) => {
+        if (i > 0)
+            e.append(document.createElement('wbr'));
+        const l = document.createElement('span');
+        l.dataset.twipLine = '';
+        l.style.whiteSpace = 'pre';
+        for (const s of line.segments)
+            l.append(segment(s));
+        e.append(l);
+    });
+    // An empty paragraph still has a line to put the caret on.
+    if (!e.textContent || e.textContent === (p.label ? `${p.label} ` : ''))
+        e.append(document.createElement('br'));
+    return e;
+}
+/** The text nodes of a paragraph's element that count for offsets: not its label's. */
+function texts(e) {
+    const out = [];
+    const walker = document.createTreeWalker(e, NodeFilter.SHOW_TEXT, {
+        acceptNode: (n) => ((n.parentElement?.closest('[data-twip-label]') ? NodeFilter.FILTER_REJECT : NodeFilter.FILTER_ACCEPT)),
+    });
+    for (let n = walker.nextNode(); n; n = walker.nextNode())
+        out.push(n);
+    return out;
+}
+/** The DOM place of a window place. */
+function domPoint(paragraphs, p) {
+    const e = paragraphs[p.paragraph];
+    if (!e)
+        return undefined;
+    let left = p.offset;
+    const nodes = texts(e);
+    for (const t of nodes) {
+        if (left <= t.length)
+            return { node: t, offset: left };
+        left -= t.length;
+    }
+    const last = nodes.at(-1);
+    // An empty paragraph: before its `<br>`, after its label.
+    return last ? { node: last, offset: last.length } : { node: e, offset: e.querySelector('[data-twip-label]') ? 1 : 0 };
+}
+/** The window place of a DOM place, or none outside the element's paragraphs. */
+function windowPoint(paragraphs, node, offset) {
+    const k = paragraphs.findIndex((e) => e.contains(node));
+    const e = paragraphs[k];
+    if (!e)
+        return undefined;
+    // The text from the paragraph's start to the place, without the label (always first).
+    const r = document.createRange();
+    r.setStart(e, 0);
+    r.setEnd(node, offset);
+    const label = e.querySelector('[data-twip-label]')?.textContent?.length ?? 0;
+    return { paragraph: k, offset: Math.max(0, r.toString().length - label) };
+}
+const same = (a, b) => a?.paragraph === b?.paragraph && a?.offset === b?.offset;
 /**
  * Starts keyboard and text input. `claims` says whether a chord is a command's, an application shortcut or a host
  * key (`shortcuts.lookup`): those keys are the editor's, and their browser defaults (Save, Print, Find) don't run.
+ * `label` is the editor's accessible name.
  */
-export function startInput(s, dom, ledger, report, claims) {
-    const input = ledger.node(dom.layer, document.createElement('textarea'));
+export function startInput(s, dom, ledger, report, claims, label) {
+    const input = ledger.node(dom.layer, document.createElement('div'));
     input.dataset.twip = 'input';
-    input.setAttribute('aria-label', 'Document');
+    input.contentEditable = 'true';
+    input.setAttribute('role', 'textbox');
     input.setAttribute('aria-multiline', 'true');
+    input.setAttribute('aria-label', label);
+    // What is edited is in the name, so the screen reader says it with the focus: "Document, sub-template Violation".
+    // (The switch's announcement can be lost while the screen reader reloads the page's content.)
+    s.disposers.push(s.on('editingTargetChanged', (t) => input.setAttribute('aria-label', t.kind === 'subTemplate' ? `${label}, sub-template ${t.name}` : label)));
+    input.setAttribute('aria-description', LEAVE_HINT);
     input.setAttribute('autocomplete', 'off');
     input.setAttribute('autocorrect', 'off');
     input.setAttribute('autocapitalize', 'off');
     input.spellcheck = false;
     input.style.cssText =
-        'position:absolute;left:0;top:0;width:1px;height:1em;opacity:0;border:0;padding:0;margin:0;resize:none;overflow:hidden;' +
-            'white-space:pre;outline:none;caret-color:transparent;pointer-events:none;';
+        'position:absolute;left:0;top:0;width:1px;height:1em;opacity:0;border:0;padding:0;margin:0;overflow:hidden;' +
+            'white-space:normal;overflow-wrap:normal;outline:none;caret-color:transparent;pointer-events:none;';
+    // The window: paragraphs by id, with what they were built from, so only changed ones are replaced.
+    const built = new Map();
+    let shown = [];
+    let latest;
+    let composing = false;
+    // The selection the host last set, so the selectionchange it causes isn't taken for the screen reader's.
+    let set;
+    const render = (w) => {
+        input.lang = w.lang;
+        if (w.readOnly)
+            input.setAttribute('aria-readonly', 'true');
+        else
+            input.removeAttribute('aria-readonly');
+        // The text is there only while the element has the focus: in browse mode a screen reader then finds the document
+        // once, in the structure mirror, and not again (the caret's paragraphs) in the editing element.
+        if (document.activeElement !== input)
+            return;
+        const next = w.paragraphs.map((p) => {
+            const from = JSON.stringify(p);
+            const old = built.get(p.id);
+            if (old?.from === from)
+                return old.e;
+            const e = paragraph(p);
+            built.set(p.id, { e, from });
+            return e;
+        });
+        const keep = new Set(next);
+        for (const child of [...input.children])
+            if (!keep.has(child))
+                child.remove();
+        for (const [id, b] of built)
+            if (!keep.has(b.e))
+                built.delete(id);
+        // Only elements out of place move: the others stay where the screen reader is reading.
+        next.forEach((e, i) => {
+            if (input.children[i] !== e)
+                input.insertBefore(e, input.children[i] ?? null);
+        });
+        shown = next;
+        const a = domPoint(shown, w.anchor);
+        const f = domPoint(shown, w.focus);
+        if (!a || !f)
+            return;
+        set = { anchor: w.anchor, focus: w.focus };
+        getSelection()?.setBaseAndExtent(a.node, a.offset, f.node, f.offset);
+    };
+    // Escape, then Tab or Shift+Tab: the browser moves the focus out; Escape still goes to the engine.
+    let escaped = false;
     // A modifier pressed or let go alone (Alt mid-drag): the engine runs the drag or hover again with it.
     const modifier = (e) => {
         if (!modifierKeys.has(e.key) || e.repeat)
@@ -53,42 +212,95 @@ export function startInput(s, dom, ledger, report, claims) {
     ledger.listen(input, 'keydown', (e) => {
         if (e.isComposing || e.keyCode === 229 || modifier(e))
             return;
-        const key = keyNumber(e.code);
+        const code = codeOf(e);
+        if (code === 'F6' && !e.ctrlKey && !e.altKey && !e.metaKey) {
+            e.preventDefault();
+            escaped = false;
+            leave(input, dom.scroller, e.shiftKey);
+            return;
+        }
+        const leaving = escaped && code === 'Tab' && !e.ctrlKey && !e.altKey && !e.metaKey;
+        escaped = code === 'Escape' && !e.shiftKey && !e.ctrlKey && !e.altKey && !e.metaKey;
+        if (leaving)
+            return;
+        const key = keyNumber(code);
         if (!key)
             return;
-        const all = chords(e);
+        const all = chords(e, code);
         if (all.some((c) => clipboardKeys.has(c.toLowerCase())))
             return;
         // The menu keys open the application's menu only when it listens; otherwise the browser's opens.
-        const menu = e.code === 'ContextMenu' || all.includes('Shift+F10');
+        const menu = code === 'ContextMenu' || all.includes('Shift+F10');
         if (menu && !s.listening('contextMenu'))
             return;
         const claimed = all.some((c) => claims(c) || dialogKeys.has(c.toLowerCase()));
-        if (!menu && !(!e.altKey && editingKeys.has(e.code)) && !claimed)
+        if (!menu && !(!e.altKey && editingKeys.has(code)) && !claimed)
             return;
         e.preventDefault();
         s.input({ type: 'key', key, mods: modsOf(e) }).catch(report);
     });
+    // Nothing edits the element itself: typed text goes to the engine, and the engine's window comes back. Composition
+    // can't be cancelled; the window is put back after it ends.
     ledger.listen(input, 'beforeinput', (e) => {
-        if (e.inputType !== 'insertText' && e.inputType !== 'insertReplacementText')
+        if (e.inputType === 'insertCompositionText')
             return;
         e.preventDefault();
+        if (e.inputType !== 'insertText' && e.inputType !== 'insertReplacementText')
+            return;
         const text = e.data ?? e.dataTransfer?.getData('text/plain');
         if (text)
             s.input({ type: 'text', text }).catch(report);
     });
-    const focused = (focused) => () => s.input({ type: 'focus', focused }).catch(report);
+    ledger.listen(input, 'compositionstart', () => (composing = true));
+    ledger.listen(input, 'compositionend', () => {
+        composing = false;
+        // The browser put the composition in the paragraphs: build them again.
+        built.clear();
+        if (latest)
+            render(latest);
+    });
+    const focused = (focused) => () => {
+        if (focused && latest)
+            render(latest);
+        if (!focused) {
+            input.replaceChildren();
+            built.clear();
+            shown = [];
+        }
+        s.input({ type: 'focus', focused }).catch(report);
+    };
     ledger.listen(input, 'focus', focused(true));
     ledger.listen(input, 'blur', focused(false));
-    // The caret request: the input element follows the caret, so the IME's window opens beside it.
+    // A selection the host didn't set: the screen reader moved the caret (reading continuously). The engine follows.
+    ledger.listen(document, 'selectionchange', () => {
+        if (document.activeElement !== input || composing || s.destroyed)
+            return;
+        const sel = getSelection();
+        if (!sel?.anchorNode || !sel.focusNode)
+            return;
+        const anchor = windowPoint(shown, sel.anchorNode, sel.anchorOffset);
+        const focus = windowPoint(shown, sel.focusNode, sel.focusOffset);
+        if (!anchor || !focus || (same(anchor, set?.anchor) && same(focus, set?.focus)))
+            return;
+        set = { anchor, focus };
+        s.call(Method.HostCaretWindowSelect, { anchor, focus }).catch(report);
+    });
     const onMessage = (m) => {
-        const r = m.payload;
-        if (m.kind !== Kind.HostRequest || r.type !== 'caret')
+        if (m.kind !== Kind.HostRequest)
             return;
-        input.style.left = `${r.x}px`;
-        input.style.top = `${r.y}px`;
-        input.style.height = `${Math.max(1, r.height)}px`;
-        input.style.fontSize = `${Math.max(1, r.height * 0.8)}px`;
+        const r = m.payload;
+        // The caret request: the element follows the caret, so the IME's window opens beside it.
+        if (r.type === 'caret') {
+            input.style.left = `${r.x}px`;
+            input.style.top = `${r.y}px`;
+            input.style.height = `${Math.max(1, r.height)}px`;
+            input.style.fontSize = `${Math.max(1, r.height * 0.8)}px`;
+        }
+        else if (r.type === 'caret_text') {
+            latest = r.window;
+            if (!composing)
+                render(r.window);
+        }
     };
     s.hostListeners.add(onMessage);
     s.disposers.push(() => s.hostListeners.delete(onMessage));

package/dist/host/keys.d.ts

@@ -1,5 +1,15 @@
 /** A key's number for the engine, or 0 when the engine doesn't know it. */
 export declare function keyNumber(code: string): number;
+/**
+ * The key's code: `KeyboardEvent.code`, or, when it is empty (keys sent without a scan code, as screen readers, on-screen
+ * keyboards and automation do), the code `key` implies on a US layout: `ArrowDown`, `KeyA`, `Digit1`, `Space`. A keypad
+ * key that navigates (NumLock off, or a key sent without its extended flag) is the key it acts as: `Numpad2` is
+ * `ArrowDown`.
+ */
+export declare function codeOf(e: {
+    code: string;
+    key: string;
+}): string;
 /** Modifier bits of the C ABI. */
 export declare const Mods: {
     readonly ctrl: 1;

package/dist/host/keys.js

@@ -19,6 +19,29 @@ const numbers = {
 export function keyNumber(code) {
     return Object.hasOwn(numbers, code) ? numbers[code] : 0;
 }
+/** Keys whose `KeyboardEvent.key` is their code's name. */
+const named = new Set(Object.keys(numbers).filter((c) => !/^(Key|Digit|Numpad|Intl)/.test(c) && c.length > 1));
+/**
+ * The key's code: `KeyboardEvent.code`, or, when it is empty (keys sent without a scan code, as screen readers, on-screen
+ * keyboards and automation do), the code `key` implies on a US layout: `ArrowDown`, `KeyA`, `Digit1`, `Space`. A keypad
+ * key that navigates (NumLock off, or a key sent without its extended flag) is the key it acts as: `Numpad2` is
+ * `ArrowDown`.
+ */
+export function codeOf(e) {
+    if (/^Numpad(\d|Decimal)$/.test(e.code) && named.has(e.key))
+        return e.key;
+    if (e.code && e.code !== 'Unidentified')
+        return e.code;
+    if (named.has(e.key))
+        return e.key;
+    if (e.key === ' ')
+        return 'Space';
+    if (/^[a-z]$/i.test(e.key))
+        return `Key${e.key.toUpperCase()}`;
+    if (/^[0-9]$/.test(e.key))
+        return `Digit${e.key}`;
+    return e.code;
+}
 /** Modifier bits of the C ABI. */
 export const Mods = { ctrl: 1, shift: 2, alt: 4, meta: 8 };
 /** A keyboard event's modifier bits. */

package/dist/host/mount.js

@@ -51,12 +51,17 @@ export async function mountHost(container, s, options, claims) {
     });
     const scroll = startScroll(s, dom, ledger, frames, report);
     chrome = startChrome(s, dom, ledger, frames, report, toViewport);
-    const input = startInput(s, dom, ledger, report, claims);
+    const label = options.label ?? 'Document';
+    const input = startInput(s, dom, ledger, report, claims, label);
     startIme(s, input.element, ledger, report);
     const clipboard = startClipboard(s, dom, input.element, ledger, report, toViewport);
     const balloons = chrome.balloonLayer;
-    startPointer(s, dom, ledger, scroll, report, input.focus, (t) => t instanceof Node && balloons.contains(t) && t !== balloons);
-    startA11y(s, dom, ledger);
+    const a11y = startA11y(s, dom, ledger, label, input.focus, report);
+    startPointer(s, dom, ledger, scroll, report, input.focus, (t) => (t instanceof Node && balloons.contains(t) && t !== balloons) || a11y.activating());
+    // Firefox makes a scrolling element a Tab stop, where a screen reader reads the whole mirror: the editor has one
+    // stop, the editing element, and focus given to the scroller goes on to it.
+    dom.scroller.tabIndex = -1;
+    ledger.listen(dom.scroller, 'focus', input.focus);
     if (options.background)
         await chrome.view.setBackground(options.background);
     if (options.overlayColors)

package/dist/index.d.ts

@@ -19,7 +19,7 @@ export type { AccessibilityDialogSession, DialogKind, DialogSession, DialogSessi
 export type { Find, FindMatch, FindQuery, FindResult } from './services/find.js';
 export type { Dictionary, Spelling } from './services/spelling.js';
 export type { Block, ControlKind, ControlOptions, DataBinding, DataParts, ElementDetail, ElementInfo, Elements, MountedElements, PlaceholderInfo, ReferenceResolution, ReferenceRule, SubTemplateInfo, SubTemplateReference, SubTemplates, } from './services/elements.js';
-export type { Accessibility, AccessibleNode, Shortcuts } from './services/accessibility.js';
+export type { Accessibility, AccessibleId, AccessibleNode, AnnouncementKind, CellPlace, ListPosition, Shortcuts } from './services/accessibility.js';
 export type { Heading, Navigation, StyleInfo, Styles } from './services/navigation.js';
 export type { Ruler, RulerModel, RulerModelSource, RulerUnit, RulerView, TabAlignment, TabLeader, TabSelector, } from './services/ruler.js';
 export type { ChromeColors, ChromeTheme, DocumentAppearance, GestureAction, GestureBinding, GestureEvent, GestureId, Gestures, MeasureDetail, ObjectGrid, Popover, SystemColors, TabTypeChoice, ThemeColors, View, ViewOptions, } from './services/view.js';

package/dist/services/accessibility.d.ts

@@ -5,22 +5,71 @@ import type { HostCommand } from '../events.js';
 export interface Accessibility {
     /** The tree. */
     tree(): Promise<AccessibleNode>;
+    /**
+     * Puts the caret at the start of a node's content and scrolls it into view: a note reference's note, a comment's
+     * commented text. Rejects with `'invalid-argument'` when no node has the id, and `'unavailable'` when the node holds
+     * no caret position (a region).
+     */
+    go(id: AccessibleId): Promise<void>;
+    /** The kinds of announcements the editor makes; the others are neither said nor emitted. Default: all. */
+    setAnnouncements(kinds: AnnouncementKind[]): Promise<void>;
 }
+/**
+ * A node's identity: the same across edits while the thing it names exists (a paragraph, table, note, comment or
+ * story keeps its id when other content changes).
+ */
+export type AccessibleId = number;
 /** A node of the accessibility tree. */
 export interface AccessibleNode {
-    /** Its role. */
-    role: 'document' | 'page' | 'paragraph' | 'heading' | 'list' | 'listItem' | 'table' | 'row' | 'cell' | 'image' | 'link' | 'textBox' | 'note' | 'header' | 'footer';
+    /** Its identity. */
+    id: AccessibleId;
+    /** Its role. `region`: a named group after the body (headers and footers, footnotes, endnotes, comments). */
+    role: 'document' | 'paragraph' | 'heading' | 'list' | 'listItem' | 'table' | 'row' | 'cell' | 'columnHeader' | 'rowHeader' | 'image' | 'link' | 'textBox' | 'note' | 'noteRef' | 'comment' | 'header' | 'footer' | 'region' | 'text';
     /** Its accessible name. */
     name?: string;
-    /** Its text. */
+    /** A text node's text. */
     text?: string;
-    /** A heading's or list item's level. */
+    /** A heading's level, a list item's nesting level, or a table's nesting level, from 1. */
     level?: number;
-    /** Review and spelling marks on it. */
-    marks?: ('insertion' | 'deletion' | 'comment' | 'misspelling')[];
+    /** A numbered list item's number as shown (`3.`, `a)`). */
+    label?: string;
+    /** A list item's position in its list. */
+    position?: ListPosition;
+    /** A cell's place in its table. */
+    cell?: CellPlace;
+    /** Review and spelling marks on a text node. */
+    marks?: ('insertion' | 'deletion' | 'misspelling')[];
+    /** Whose marks or comment it is. */
+    author?: string;
+    /** Its language (BCP 47), where it differs from its parent's. */
+    lang?: string;
+    /** The comment the text is in the range of. */
+    details?: AccessibleId;
+    /** The note a note reference points to; for a sub-template body shown in place, its reference's paragraph. */
+    target?: AccessibleId;
     /** Its children. */
     children: AccessibleNode[];
 }
+/** Where a list item is in its list: its index (from 1) among the items at its level, and how many there are. */
+export interface ListPosition {
+    /** Its index, from 1. */
+    index: number;
+    /** The number of items. */
+    count: number;
+}
+/** Where a cell is in its table's grid: its row and column (from 1) and how many it spans. */
+export interface CellPlace {
+    /** Its row, from 1. */
+    row: number;
+    /** Its first grid column, from 1. */
+    col: number;
+    /** How many rows it spans. */
+    rowSpan: number;
+    /** How many grid columns it spans. */
+    colSpan: number;
+}
+/** What an announcement is about. */
+export type AnnouncementKind = 'table' | 'list' | 'page' | 'review' | 'comment' | 'spelling' | 'formatting' | 'mode' | 'readOnly' | 'command' | 'selection';
 /** Keyboard shortcuts: the application's own, and what a key does now. */
 export interface Shortcuts {
     /** Claims a key for the application: pressing it emits `shortcut`. Throws 'unavailable' on a collision, naming it. */

package/dist/services/accessibility.js

@@ -2,7 +2,9 @@ import { EditorError } from '../errors.js';
 import { Method } from '../transport/protocol.js';
 /** The accessibility tree over a session. */
 export function createAccessibility(s) {
-    return { tree: () => s.call(Method.AccessibleTree) };
+    return { tree: () => s.call(Method.AccessibleTree), go: (id) => s.call(Method.AccessibleGo, id),
+        setAnnouncements: (kinds) => s.call(Method.AnnouncementsSet, kinds),
+    };
 }
 /** The keys the application owns (the engine's host keys), by their Windows shortcut. */
 const hostKeys = {

package/dist/transport/protocol.d.ts

@@ -1,7 +1,7 @@
 import { EditorError, type ErrorCode } from '../errors.js';
 import type { TwipEvents } from '../events.js';
 import type { FaceInfo } from '../fonts/library.js';
-import type { AccessibleNode } from '../services/accessibility.js';
+import type { AccessibleId, AccessibleNode } from '../services/accessibility.js';
 import type { Warning } from '../types.js';
 /** Structured call numbers: `TwipMethod` in `twip.h`, the C ABI's `Method`. The two lists must match exactly. */
 export declare const Method: {
@@ -82,6 +82,9 @@ export declare const Method: {
     readonly HostSetLeaders: 75;
     readonly ShapeGallery: 76;
     readonly SubTemplates: 77;
+    readonly AccessibleGo: 78;
+    readonly HostCaretWindowSelect: 79;
+    readonly AnnouncementsSet: 80;
 };
 /** A structured call number. */
 export type Method = (typeof Method)[keyof typeof Method];
@@ -141,10 +144,59 @@ export type HostRequest = {
     width: number;
     height: number;
 }
-/** The accessibility tree changed: mirror it. */
+/** The text around the caret and the selection in it changed: for the focused editing element. */
+ | {
+    type: 'caret_text';
+    window: CaretWindow;
+}
+/** The accessibility tree changed: the whole tree, or the changes since the last one. */
  | {
     type: 'a11y';
-    tree: AccessibleNode;
+    update: A11yUpdate;
+};
+/** The text around the caret: the caret's paragraph and its neighbours in its container, in laid-out lines. */
+export interface CaretWindow {
+    paragraphs: {
+        id: AccessibleId;
+        role: 'paragraph' | 'heading' | 'listItem';
+        level?: number;
+        /** A numbered item's number: not part of the text or its offsets. */
+        label?: string;
+        lines: {
+            segments: WindowSegment[];
+        }[];
+    }[];
+    anchor: WindowPoint;
+    focus: WindowPoint;
+    /** The selection is all of its story. */
+    all: boolean;
+    lang: string;
+    readOnly: boolean;
+}
+/** Text of a line with the same marks, author and language. */
+export interface WindowSegment {
+    text: string;
+    marks?: ('insertion' | 'deletion' | 'misspelling')[];
+    author?: string;
+    lang?: string;
+}
+/** A place in a caret window: a paragraph's index and an offset in its text (characters, without the label). */
+export interface WindowPoint {
+    paragraph: number;
+    offset: number;
+}
+/** The accessibility tree, or what changed in it: a node and its subtree replaced, or a node's children reordered. */
+export type A11yUpdate = {
+    full: AccessibleNode;
+} | {
+    patch: ({
+        type: 'replace';
+        node: AccessibleNode;
+    } | {
+        type: 'children';
+        parent: AccessibleId;
+        ids: AccessibleId[];
+    })[];
 };
 /** One engine-to-SDK message. `payload` is the decoded JSON, or undefined for kinds without one. */
 export interface Message {

package/dist/transport/protocol.js

@@ -81,6 +81,9 @@ export const Method = {
     HostSetLeaders: 75,
     ShapeGallery: 76,
     SubTemplates: 77,
+    AccessibleGo: 78,
+    HostCaretWindowSelect: 79,
+    AnnouncementsSet: 80,
 };
 /** What the engine sends: callback kinds of the C ABI. */
 export const Kind = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twip/web",
-  "version": "0.0.0-canary-4d6177a",
+  "version": "0.0.0-canary-abcb2d5",
   "description": "The Twip DOCX editor for the browser and Node: a managed, framework-independent editor over the WebAssembly engine.",
   "type": "module",
   "license": "Apache-2.0",