@twip/web 0.0.0-canary-f16fa12

package/dist/host/pointer.d.ts

@@ -0,0 +1,4 @@
+import type { Session } from '../editor.js';
+import type { Dom, Ledger } from './dom.js';
+import type { Scroll } from './scroll.js';
+export declare function startPointer(s: Session, dom: Dom, ledger: Ledger, scroll: Scroll, report: (e: unknown) => void, focus: () => void, ignore: (target: EventTarget | null) => boolean): void;

package/dist/host/pointer.js

@@ -0,0 +1,196 @@
+import { Kind } from '../transport/protocol.js';
+import { CELL_SELECT, COLUMN_SELECT, ROW_SELECT } from './cursors.js';
+import { modsOf } from './keys.js';
+const PointerKind = { down: 0, move: 1, up: 2, cancel: 3, leave: 4 };
+/** DOM `PointerEvent.button` to the engine's: primary 0, secondary 1, middle 2. */
+const buttons = { 0: 0, 2: 1, 1: 2 };
+/** A `.cur` cursor, over the browser's own `fallback` where it can't show one. */
+const cur = (c, fallback) => `url("${c.url}") ${c.x} ${c.y}, ${fallback}`;
+/** The browser's cursors, and the selection arrows it has none of (`cursors.ts`, the WinForms host's `.cur` files). */
+const cursors = {
+    default: 'default',
+    text: 'text',
+    pointer: 'pointer',
+    move: 'move',
+    resizeHorizontal: 'col-resize',
+    resizeVertical: 'row-resize',
+    resizeNorthWestSouthEast: 'nwse-resize',
+    resizeNorthEastSouthWest: 'nesw-resize',
+    crosshair: 'crosshair',
+    notAllowed: 'not-allowed',
+    copy: 'copy',
+    cellSelect: cur(CELL_SELECT, 'cell'),
+    columnSelect: cur(COLUMN_SELECT, 'default'),
+    rowSelect: cur(ROW_SELECT, 'default'),
+};
+/** Presses closer than this in time (ms) and distance (CSS px) count as one multi-click. */
+const CLICK_TIME = 500;
+const CLICK_SLOP = 4;
+export function startPointer(s, dom, ledger, scroll, report, focus, ignore) {
+    const { scroller } = dom;
+    const point = (e) => {
+        const r = dom.canvas.getBoundingClientRect();
+        return { x: e.clientX - r.left, y: e.clientY - r.top };
+    };
+    const send = (kind, e, button, mods) => s.input({ type: 'pointer', kind, ...point(e), button, clicks, mods }).catch(report);
+    let clicks = 0;
+    let last = { time: -Infinity, x: 0, y: 0, button: -1 };
+    /** The pointer of the press being dragged. */
+    let pressed;
+    /** Where a mouse or pen last moved over the document, until it leaves. */
+    let over;
+    /** Touches down, for pinch and pan. */
+    const touches = new Map();
+    let pinch;
+    let stopAutoscroll;
+    const twoTouches = () => {
+        const [a, b] = [...touches.values()];
+        return { distance: Math.hypot(a.x - b.x, a.y - b.y), x: (a.x + b.x) / 2, y: (a.y + b.y) / 2 };
+    };
+    ledger.listen(scroller, 'pointerdown', (e) => {
+        if (ignore(e.target))
+            return;
+        const at = point(e);
+        // A press on a scrollbar scrolls.
+        if (at.x >= scroller.clientWidth || at.y >= scroller.clientHeight)
+            return;
+        const button = buttons[e.button];
+        if (button === undefined)
+            return;
+        if (e.pointerType === 'touch') {
+            touches.set(e.pointerId, { x: e.clientX, y: e.clientY });
+            if (touches.size === 2) {
+                // A second finger: the first one's press is withdrawn, and the two pinch and pan.
+                if (pressed)
+                    send(PointerKind.cancel, pressed.at, 0, 0);
+                pressed = undefined;
+                pinch = twoTouches();
+                return;
+            }
+            if (touches.size > 2)
+                return;
+        }
+        // A press takes the focus (the browser would give it to no element: the canvas takes none).
+        if (button !== 2) {
+            e.preventDefault();
+            focus();
+        }
+        const near = Math.hypot(e.clientX - last.x, e.clientY - last.y) <= CLICK_SLOP;
+        clicks = button === last.button && near && e.timeStamp - last.time <= CLICK_TIME ? clicks + 1 : 1;
+        last = { time: e.timeStamp, x: e.clientX, y: e.clientY, button };
+        if (button === 0) {
+            pressed = { id: e.pointerId, at: e };
+            scroller.setPointerCapture(e.pointerId);
+        }
+        send(PointerKind.down, e, button, modsOf(e));
+    });
+    ledger.listen(scroller, 'pointermove', (e) => {
+        if (touches.has(e.pointerId)) {
+            touches.set(e.pointerId, { x: e.clientX, y: e.clientY });
+            if (pinch && touches.size === 2) {
+                const now = twoTouches();
+                if (pinch.distance > 0 && Math.abs(now.distance / pinch.distance - 1) > 0.02) {
+                    scroll.zoomBy(now.distance / pinch.distance);
+                    pinch.distance = now.distance;
+                }
+                scroller.scrollBy(pinch.x - now.x, pinch.y - now.y);
+                pinch = { ...pinch, x: now.x, y: now.y };
+                return;
+            }
+            if (pinch)
+                return;
+        }
+        if (pressed && pressed.id !== e.pointerId)
+            return;
+        if (!pressed && ignore(e.target))
+            return;
+        if (pressed) {
+            pressed.at = e;
+            autoscroll(e);
+        }
+        send(PointerKind.move, e, 0, modsOf(e));
+    });
+    const end = (kind) => (e) => {
+        touches.delete(e.pointerId);
+        if (pinch) {
+            if (touches.size === 0)
+                pinch = undefined;
+            return;
+        }
+        if (pressed?.id === e.pointerId) {
+            pressed = undefined;
+            stopAutoscroll?.();
+            if (scroller.hasPointerCapture(e.pointerId))
+                scroller.releasePointerCapture(e.pointerId);
+        }
+        else if (ignore(e.target))
+            return;
+        const button = buttons[e.button] ?? 0;
+        send(kind, e, button, modsOf(e));
+    };
+    ledger.listen(scroller, 'pointerup', end(PointerKind.up));
+    ledger.listen(scroller, 'pointercancel', end(PointerKind.cancel));
+    ledger.listen(scroller, 'pointerleave', (e) => {
+        if (!pressed && e.pointerType !== 'touch')
+            send(PointerKind.leave, e, 0, modsOf(e));
+        over = undefined;
+    });
+    // Ctrl, Shift or Meta pressed or released with the pointer still: the same move again with the new modifiers, so
+    // the shape follows what a press would now do (the hand over a link with Ctrl, copy while dragging).
+    ledger.listen(scroller, 'pointermove', (e) => {
+        if (e.pointerType !== 'touch')
+            over = { clientX: e.clientX, clientY: e.clientY };
+    });
+    const modifier = (event) => {
+        const e = event;
+        if (!over || e.repeat || !['Control', 'Shift', 'Meta'].includes(e.key))
+            return;
+        send(PointerKind.move, pressed?.at ?? over, 0, modsOf(e));
+    };
+    const doc = scroller.ownerDocument;
+    ledger.listen(doc, 'keydown', modifier, { capture: true });
+    ledger.listen(doc, 'keyup', modifier, { capture: true });
+    // Autoscroll: a drag past the viewport's edge scrolls each frame, faster further out, and extends the drag.
+    const autoscroll = (e) => {
+        const step = () => {
+            if (!pressed)
+                return;
+            const at = point(pressed.at);
+            const out = (v, size) => (v < 0 ? v : v > size ? v - size : 0);
+            const dx = out(at.x, scroller.clientWidth);
+            const dy = out(at.y, scroller.clientHeight);
+            if (!dx && !dy) {
+                stopAutoscroll = undefined;
+                return;
+            }
+            const speed = (d) => Math.sign(d) * Math.min(40, Math.ceil(Math.abs(d) / 4));
+            scroller.scrollBy(speed(dx), speed(dy));
+            send(PointerKind.move, pressed.at, 0, modsOf(pressed.at));
+            stopAutoscroll = ledger.frame(step);
+        };
+        const at = point(e);
+        const inside = at.x >= 0 && at.y >= 0 && at.x <= scroller.clientWidth && at.y <= scroller.clientHeight;
+        if (!inside && !stopAutoscroll)
+            stopAutoscroll = ledger.frame(step);
+    };
+    // The engine's requests: the cursor, and capture for its own drags.
+    const onMessage = (m) => {
+        if (m.kind !== Kind.HostRequest)
+            return;
+        const r = m.payload;
+        if (r.type === 'cursor')
+            scroller.style.cursor = cursors[r.cursor] ?? 'default';
+        else if (r.type === 'capture' && pressed && !scroller.hasPointerCapture(pressed.id))
+            scroller.setPointerCapture(pressed.id);
+        else if (r.type === 'release' && pressed && scroller.hasPointerCapture(pressed.id))
+            scroller.releasePointerCapture(pressed.id);
+    };
+    s.hostListeners.add(onMessage);
+    s.disposers.push(() => s.hostListeners.delete(onMessage));
+    // The engine opens its menu on a secondary press (and the menu keys): the browser's stays shut while the
+    // application listens for it.
+    ledger.listen(scroller, 'contextmenu', (e) => {
+        if (!ignore(e.target) && s.listening('contextMenu'))
+            e.preventDefault();
+    });
+}

package/dist/host/scroll.d.ts

@@ -0,0 +1,14 @@
+import type { Session } from '../editor.js';
+import { type FrameInfo } from '../transport/protocol.js';
+import type { Dom, Ledger } from './dom.js';
+import type { Frames } from './frames.js';
+/** The scrolling of a mounted editor. */
+export interface Scroll {
+    /** Where content x 0 is in the scroller's scrolled box: the centring offset. */
+    readonly offset: number;
+    /** Sizes the content after a frame. */
+    layout(info: FrameInfo): void;
+    /** Zooms by a factor of the current zoom. */
+    zoomBy(factor: number): void;
+}
+export declare function startScroll(s: Session, dom: Dom, ledger: Ledger, frames: Frames, report: (e: unknown) => void): Scroll;

package/dist/host/scroll.js

@@ -0,0 +1,95 @@
+import { Kind } from '../transport/protocol.js';
+export function startScroll(s, dom, ledger, frames, report) {
+    const { scroller, content } = dom;
+    let offset = 0;
+    let sent = { x: NaN, y: NaN };
+    let size = { width: 0, height: 0 };
+    // A `scroll` request (a zoom), applied once the next frame has sized the content for it.
+    let pending;
+    const send = () => {
+        const at = { x: scroller.scrollLeft - offset, y: scroller.scrollTop };
+        if (at.x === sent.x && at.y === sent.y)
+            return;
+        sent = at;
+        s.input({ type: 'scroll', ...at }).catch(report);
+    };
+    const layout = (info) => {
+        if (info.contentWidth !== size.width || info.contentHeight !== size.height) {
+            size = { width: info.contentWidth, height: info.contentHeight };
+            content.style.width = `${size.width}px`;
+            content.style.height = `${size.height}px`;
+        }
+        const centred = Math.max(0, Math.floor((scroller.clientWidth - size.width) / 2));
+        if (centred !== offset) {
+            offset = centred;
+            content.style.marginLeft = `${offset}px`;
+        }
+        if (pending) {
+            // The engine drew this frame from there already: report only where the scroller couldn't go.
+            scroller.scrollLeft = pending.x + offset;
+            scroller.scrollTop = pending.y;
+            sent = pending;
+            pending = undefined;
+        }
+        send();
+    };
+    ledger.listen(scroller, 'scroll', send, { passive: true });
+    // `scroll_to`: the least scrolling that shows the rectangle (content px).
+    const scrollTo = (r) => {
+        const left = r.x + offset;
+        const { clientWidth: w, clientHeight: h } = scroller;
+        if (r.y < scroller.scrollTop)
+            scroller.scrollTop = r.y;
+        else if (r.y + r.height > scroller.scrollTop + h)
+            scroller.scrollTop = r.y + r.height - h;
+        if (left < scroller.scrollLeft)
+            scroller.scrollLeft = left;
+        else if (left + r.width > scroller.scrollLeft + w)
+            scroller.scrollLeft = left + r.width - w;
+        send();
+    };
+    const onMessage = (m) => {
+        const r = m.payload;
+        if (m.kind !== Kind.HostRequest)
+            return;
+        if (r.type === 'scroll_to')
+            scrollTo(r);
+        else if (r.type === 'scroll')
+            pending = { x: r.x, y: r.y };
+    };
+    s.hostListeners.add(onMessage);
+    s.disposers.push(() => s.hostListeners.delete(onMessage));
+    // Zoom: factors gather while a zoom is running, then apply at once.
+    let factor = 1;
+    let zooming = false;
+    const zoomBy = (f) => {
+        factor *= f;
+        if (zooming)
+            return;
+        zooming = true;
+        const zoom = Math.min(500, Math.max(10, Math.round(s.state.view.zoom * factor)));
+        factor = 1;
+        s.run({ type: 'setZoom', value: zoom })
+            .catch(report)
+            .finally(() => {
+            zooming = false;
+            frames.request();
+            if (factor !== 1)
+                zoomBy(1);
+        });
+    };
+    ledger.listen(scroller, 'wheel', (e) => {
+        if (!e.ctrlKey)
+            return;
+        e.preventDefault();
+        // 10% a wheel notch (100 px, or 3 lines); a pinch sends small deltas.
+        zoomBy(1.1 ** (-e.deltaY / (e.deltaMode === 0 ? 100 : 3)));
+    }, { passive: false });
+    return {
+        get offset() {
+            return offset;
+        },
+        layout,
+        zoomBy,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The Twip DOCX editor for the browser and Node: a managed, framework-independent editor. Mount it in a sized
+ * container with {@link Editor.mount}, or create a session with no DOM with {@link HeadlessEditor.create}.
+ *
+ * @packageDocumentation
+ */
+export { Editor, HeadlessEditor } from './editor.js';
+export type { ExportResult, MountOptions, SessionOptions } from './editor.js';
+export type { CommandEntry, CommandId, CommandInfo, Commands, FieldTargets, NoArgumentCommandId, Op, OpArgs, PlaceholderLook, } from './commands.js';
+export type { CharacterFormatting, CommandState, CommandValues, EditorState, ElementContext, HighlightColor, LineSpacing, MarkupView, Mixed, ObjectSelection, ObjectWrap, PageFormatting, ParagraphFormatting, ReviewState, RowHeight, SelectionSummary, TableSelection, TableStyleOptions, TableWidth, Tri, UnderlineStyle, ViewState, } from './state.js';
+export type { HostCommand, Tooltip, TransactionRecord, TwipEvents } from './events.js';
+export { EditorError } from './errors.js';
+export type { ErrorCode } from './errors.js';
+export { FontLibrary } from './fonts/library.js';
+export type { FaceInfo, FontRequest, SubstitutionRule } from './fonts/library.js';
+export type { BalloonPlacement, Comment, CommentAnchor, CommentThread, MountedReview, Person, Review, RevisionInfo, RichRun, RichText, } from './review.js';
+export type { ContextMenu, ContextMenuEvent, MenuAction, MenuItem, MenuTarget, Menus } from './services/menus.js';
+export type { AccessibilityDialogSession, DialogKind, DialogSession, DialogSessionOf, DialogValues, Dialogs, FieldInfo, } from './services/dialogs.js';
+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, } from './services/elements.js';
+export type { Accessibility, AccessibleNode, 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 { GestureAction, GestureBinding, GestureEvent, GestureId, Gestures, View } from './services/view.js';
+export { cm, inches, mm, pt } from './types.js';
+export type { Author, ClientPoint, ClientRect, Color, CommentId, ContentPoint, ElementId, FrameStats, HeadingId, OverlayColors, MatchId, Points, RevisionId, StyleId, Warning, WordCount, } from './types.js';

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * The Twip DOCX editor for the browser and Node: a managed, framework-independent editor. Mount it in a sized
+ * container with {@link Editor.mount}, or create a session with no DOM with {@link HeadlessEditor.create}.
+ *
+ * @packageDocumentation
+ */
+export { Editor, HeadlessEditor } from './editor.js';
+export { EditorError } from './errors.js';
+export { FontLibrary } from './fonts/library.js';
+export { cm, inches, mm, pt } from './types.js';

package/dist/review.d.ts

@@ -0,0 +1,156 @@
+import type { Session } from './editor.js';
+import type { SelectionSummary } from './state.js';
+import type { Color, CommentId, ContentPoint, RevisionId } from './types.js';
+/** Reading tracked changes and comments. Changing them is done with the review commands. */
+export interface Review {
+    /** Every tracked revision, in document order. */
+    revisions(): Promise<RevisionInfo[]>;
+    /** Every comment thread, in document order. */
+    comments(): Promise<CommentThread[]>;
+    /** Everyone who made a revision or a comment. */
+    people(): Promise<Person[]>;
+    /** Card tops that don't overlap: `heights[i]` is the card height for `anchors[i]`. Pure and synchronous. */
+    stackBalloons(anchors: readonly CommentAnchor[], heights: readonly number[], options?: {
+        gap?: number;
+    }): number[];
+}
+/** {@link Review} on a mounted editor: adds the markup pane and balloons. */
+export interface MountedReview extends Review {
+    /** Room beside the pages for balloons, CSS px. 0 (the default) removes it. */
+    setMarkupPaneWidth(width: number): Promise<void>;
+    /**
+     * An SDK-owned element inside the scrolling content, in ContentPoint coordinates. Put cards and leader lines here.
+     * It has `pointer-events: none`: a card placed here needs `pointer-events: auto` to be clickable.
+     */
+    readonly balloonLayer: HTMLElement;
+    /** Places `card` beside its thread, stacked with the others, and keeps it there through scroll, zoom and edits. */
+    attachBalloon(thread: CommentId, card: HTMLElement): () => void;
+    /** The current anchors, also delivered by the `commentAnchors` event. */
+    anchors(): CommentAnchor[];
+}
+/** A tracked revision. */
+export interface RevisionInfo {
+    /** The revision. */
+    id: RevisionId;
+    /** What changed. */
+    kind: 'insertion' | 'deletion' | 'moveFrom' | 'moveTo' | 'formatting' | 'paragraphProperties' | 'sectionProperties' | 'tableProperties' | 'rowInsertion' | 'rowDeletion' | 'cellInsertion' | 'cellDeletion' | 'cellMerge';
+    /** Who made it. */
+    author: Person;
+    /** When, ISO 8601 UTC, if the document says. */
+    time: string | null;
+    /** The inserted, deleted or moved text, when there is some. */
+    text: string;
+    /** For example `'Formatted: Bold, Italic'` for formatting changes. */
+    description: string;
+    /** The page it starts on. */
+    page: number;
+    /** The story it is in. */
+    story: SelectionSummary['story'];
+    /** A move's other half. */
+    pair?: RevisionId;
+}
+/** A comment and its replies. */
+export interface CommentThread {
+    /** The first comment's id. */
+    id: CommentId;
+    /** Resolved. */
+    done: boolean;
+    /** The commented text. */
+    anchorText: string;
+    /** The page it starts on. */
+    page: number;
+    /** The first comment, then its replies. */
+    comments: Comment[];
+}
+/** One comment. */
+export interface Comment {
+    /** The comment. */
+    id: CommentId;
+    /** Who wrote it. */
+    author: Person;
+    /** When, ISO 8601 UTC, if the document says. */
+    time: string | null;
+    /** The body. */
+    body: RichText;
+    /** The body as plain text. */
+    plainText: string;
+}
+/** Someone who made a revision or a comment. */
+export interface Person {
+    /** The display name. */
+    name: string;
+    /** The initials. */
+    initials?: string;
+    /** The identity in a directory. */
+    identity?: {
+        provider: string;
+        userId: string;
+    };
+    /** The colour the editor marks their changes with. */
+    color: Color;
+}
+/** Formatted text: paragraphs of runs. */
+export interface RichText {
+    /** The paragraphs. */
+    paragraphs: {
+        runs: RichRun[];
+    }[];
+}
+/** A run of {@link RichText}. */
+export interface RichRun {
+    /** The text. */
+    text: string;
+    /** Bold. */
+    bold?: boolean;
+    /** Italic. */
+    italic?: boolean;
+    /** Underlined. */
+    underline?: boolean;
+    /** Struck through. */
+    strikethrough?: boolean;
+    /** A link address. */
+    link?: string;
+}
+/** Where a visible comment's range is, for placing its card. */
+export interface CommentAnchor {
+    /** The thread. */
+    thread: CommentId;
+    /** The page. */
+    page: number;
+    /** The active thread. */
+    active: boolean;
+    /** Resolved. */
+    done: boolean;
+    /** The range's first character, at its baseline. */
+    start: ContentPoint;
+    /** The range's last character, at its baseline. */
+    end: ContentPoint;
+    /** The first line's top, for a card level with it. */
+    lineTop: number;
+    /** The first line's bottom. */
+    lineBottom: number;
+    /** The x where a leader line leaves the page. */
+    pageEdge: number;
+}
+/** Where the SDK placed an attached balloon. */
+export interface BalloonPlacement {
+    /** The thread. */
+    thread: CommentId;
+    /** The card's top. */
+    top: number;
+    /** The card's left. */
+    left: number;
+    /** The leader line, a polyline. */
+    leader: ContentPoint[];
+}
+/**
+ * Card tops that don't overlap, `gap` apart: card `i` (`heights[i]` tall) is for `anchors[i]`. The first active card
+ * sits level with its line; the cards before it rise above it only as far as they must, and the cards after it fall
+ * below it. No card goes above 0. With no active card, each card is level with its line or just below the card before
+ * it. The engine's `stack_balloons`, the same algorithm.
+ */
+export declare function stackBalloons(anchors: readonly CommentAnchor[], heights: readonly number[], gap?: number): number[];
+/** Review over a session. */
+export declare function createReview(s: Session): Review;
+/** The mounted editor's review members this layer provides: the markup pane, and the anchors last sent. */
+export declare function createMountedReview(s: Session): Pick<MountedReview, 'setMarkupPaneWidth' | 'anchors'>;

package/dist/review.js

@@ -0,0 +1,38 @@
+import { Method } from './transport/protocol.js';
+/**
+ * Card tops that don't overlap, `gap` apart: card `i` (`heights[i]` tall) is for `anchors[i]`. The first active card
+ * sits level with its line; the cards before it rise above it only as far as they must, and the cards after it fall
+ * below it. No card goes above 0. With no active card, each card is level with its line or just below the card before
+ * it. The engine's `stack_balloons`, the same algorithm.
+ */
+export function stackBalloons(anchors, heights, gap = 8) {
+    const n = Math.min(anchors.length, heights.length);
+    const tops = anchors.slice(0, n).map((a) => a.lineTop);
+    const active = Math.max(0, anchors.slice(0, n).findIndex((a) => a.active));
+    for (let i = active - 1; i >= 0; i--)
+        tops[i] = Math.min(tops[i], tops[i + 1] - gap - heights[i]);
+    let bottom = -Infinity;
+    for (let i = 0; i < n; i++) {
+        tops[i] = Math.max(tops[i], 0, bottom + gap);
+        bottom = tops[i] + heights[i];
+    }
+    return tops;
+}
+/** Review over a session. */
+export function createReview(s) {
+    return {
+        revisions: () => s.call(Method.Revisions),
+        comments: () => s.call(Method.Comments),
+        people: () => s.call(Method.People),
+        stackBalloons: (anchors, heights, options) => stackBalloons(anchors, heights, options?.gap),
+    };
+}
+/** The mounted editor's review members this layer provides: the markup pane, and the anchors last sent. */
+export function createMountedReview(s) {
+    let anchors = [];
+    s.on('commentAnchors', (a) => (anchors = a));
+    return {
+        setMarkupPaneWidth: (width) => s.call(Method.HostSetMarkupPaneWidth, width),
+        anchors: () => anchors,
+    };
+}

package/dist/services/accessibility.d.ts

@@ -0,0 +1,52 @@
+import type { CommandId } from '../commands.js';
+import type { Session } from '../editor.js';
+import type { HostCommand } from '../events.js';
+/** The document as an accessibility tree. The mounted editor manages its own accessibility DOM. */
+export interface Accessibility {
+    /** The tree. */
+    tree(): Promise<AccessibleNode>;
+}
+/** 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 accessible name. */
+    name?: string;
+    /** Its text. */
+    text?: string;
+    /** A heading's or list item's level. */
+    level?: number;
+    /** Review and spelling marks on it. */
+    marks?: ('insertion' | 'deletion' | 'comment' | 'misspelling')[];
+    /** Its children. */
+    children: AccessibleNode[];
+}
+/** 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. */
+    register(shortcut: {
+        id: string;
+        keys: string | {
+            windows: string;
+            mac: string;
+        };
+    }): () => void;
+    /** What a key does now: a command, an application shortcut, a host command, or nothing. */
+    lookup(keys: string): {
+        kind: 'command';
+        id: CommandId;
+    } | {
+        kind: 'shortcut';
+        id: string;
+    } | {
+        kind: 'host';
+        command: HostCommand;
+    } | null;
+}
+/** The accessibility tree over a session. */
+export declare function createAccessibility(s: Session): Accessibility;
+/**
+ * Shortcuts over a session. Lookups are answered here, from the catalog, the host keys and the registrations, so
+ * they can be synchronous; registrations also go to the engine, which presses them.
+ */
+export declare function createShortcuts(s: Session): Shortcuts;

package/dist/services/accessibility.js

@@ -0,0 +1,71 @@
+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) };
+}
+/** The keys the application owns (the engine's host keys), by their Windows shortcut. */
+const hostKeys = {
+    'Ctrl+S': 'save',
+    F12: 'saveAs',
+    'Ctrl+P': 'print',
+    'Ctrl+O': 'open',
+    'Ctrl+N': 'new',
+    'Ctrl+F': 'find',
+    'Ctrl+H': 'replace',
+    'Ctrl+G': 'goTo',
+    'Ctrl+K': 'insertHyperlink',
+    F7: 'nextMisspelling',
+    'Ctrl+Shift+F': 'focusFont',
+    'Ctrl+Shift+P': 'focusFontSize',
+    F1: 'help',
+};
+/** A shortcut in one spelling: modifiers sorted, case ignored. `'Ctrl+Alt+S'`, `'⌥⌘S'`. */
+function normalize(keys) {
+    const glyphs = /^[⌘⌥⇧⌃]*/u.exec(keys)[0];
+    const parts = glyphs ? [...glyphs, keys.slice(glyphs.length)] : keys.split(/\+(?=.)/);
+    const key = parts.pop().toLowerCase();
+    return [...parts.map((p) => p.toLowerCase()).sort(), key].join('+');
+}
+/**
+ * Shortcuts over a session. Lookups are answered here, from the catalog, the host keys and the registrations, so
+ * they can be synchronous; registrations also go to the engine, which presses them.
+ */
+export function createShortcuts(s) {
+    const registered = new Map();
+    const lookup = (keys) => {
+        const key = normalize(keys);
+        const matches = (k) => normalize(k) === key;
+        for (const [id, k] of registered)
+            if (matches(k.windows) || matches(k.mac))
+                return { kind: 'shortcut', id };
+        for (const c of s.catalog)
+            if ([...c.shortcuts.windows, ...c.shortcuts.mac].some(matches))
+                return { kind: 'command', id: c.id };
+        const host = Object.entries(hostKeys).find(([k]) => matches(k));
+        return host ? { kind: 'host', command: host[1] } : null;
+    };
+    const report = (call) => call.catch((e) => s.emit('error', e instanceof EditorError ? e : new EditorError('internal', String(e), { cause: e })));
+    return {
+        register: ({ id, keys }) => {
+            const both = typeof keys === 'string' ? { windows: keys, mac: keys } : keys;
+            if (s.destroyed)
+                throw new EditorError('destroyed', 'the editor was destroyed');
+            for (const k of new Set([both.windows, both.mac])) {
+                const taken = lookup(k);
+                if (taken)
+                    throw new EditorError('unavailable', `${k} is already ${taken.kind === 'host' ? `the ${taken.command} key` : `bound to ${taken.id}`}`);
+            }
+            registered.set(id, both);
+            report(s.call(Method.ShortcutsRegister, { id, keys }));
+            return () => {
+                if (registered.get(id) !== both)
+                    return;
+                registered.delete(id);
+                if (!s.destroyed)
+                    report(s.call(Method.ShortcutsUnregister, id));
+            };
+        },
+        lookup,
+    };
+}