@twip/web 0.1.0-alpha.1 → 0.1.0-pre.1

package/dist/transport/protocol.d.ts

@@ -0,0 +1,265 @@
+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 { 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: {
+    readonly Run: 1;
+    readonly Batch: 2;
+    readonly State: 3;
+    readonly Catalog: 4;
+    readonly NewDocument: 5;
+    readonly SetReadOnly: 6;
+    readonly SetMode: 7;
+    readonly SetAuthor: 8;
+    readonly ContextMenu: 9;
+    readonly Invoke: 10;
+    readonly DialogOpen: 11;
+    readonly DialogUpdate: 12;
+    readonly DialogApply: 13;
+    readonly Find: 14;
+    readonly FindAll: 15;
+    readonly SelectMatch: 16;
+    readonly Replace: 17;
+    readonly ReplaceAll: 18;
+    readonly SpellingAddDictionary: 19;
+    readonly SpellingSetEnabled: 20;
+    readonly SpellingSetLanguage: 21;
+    readonly SpellingIgnore: 22;
+    readonly SpellingAdd: 23;
+    readonly SpellingLoadUserWords: 24;
+    readonly SpellingSuggestions: 25;
+    readonly SpellingNext: 26;
+    readonly Headings: 27;
+    readonly SelectHeading: 28;
+    readonly Styles: 29;
+    readonly Revisions: 30;
+    readonly Comments: 31;
+    readonly People: 32;
+    readonly Elements: 33;
+    readonly Element: 34;
+    readonly Structure: 35;
+    readonly SelectElement: 36;
+    readonly DataParts: 37;
+    readonly AccessibleTree: 38;
+    readonly ShortcutsRegister: 39;
+    readonly ShortcutsUnregister: 40;
+    readonly ShortcutsLookup: 41;
+    readonly GesturesBindings: 42;
+    readonly GesturesSet: 43;
+    readonly GesturesReset: 44;
+    readonly WordCount: 45;
+    readonly Copy: 46;
+    readonly Paste: 47;
+    readonly FontFamilies: 48;
+    readonly FontSetSubstitutions: 49;
+    readonly FontSetDefault: 50;
+    readonly FontMarkUnresolved: 51;
+    readonly HostSetBackground: 52;
+    readonly HostSetMarkupPaneWidth: 53;
+    readonly HostSetRulers: 54;
+    readonly HostSetRulerUnit: 55;
+    readonly HostSetTabSelector: 56;
+    readonly HostRulerView: 57;
+    readonly HostCommentAnchors: 58;
+    readonly HostHitTest: 59;
+    readonly HostDragOver: 60;
+    readonly HostDragLeave: 61;
+    readonly HostDrop: 62;
+    readonly HostRevealSelection: 63;
+    readonly HostVisiblePages: 64;
+    readonly StackBalloons: 65;
+    readonly OpenCommit: 66;
+    readonly OpenDiscard: 67;
+    readonly DialogSelectIssue: 68;
+    readonly FontSetResolver: 69;
+    readonly Placeholders: 70;
+    readonly HostSetCaretBlink: 71;
+    readonly HostFrameStats: 72;
+    readonly HostSetOverlayPalette: 73;
+    readonly HostSetPaintBudget: 74;
+    readonly HostSetLeaders: 75;
+};
+/** A structured call number. */
+export type Method = (typeof Method)[keyof typeof Method];
+/** What the engine sends: callback kinds of the C ABI. */
+export declare const Kind: {
+    readonly Event: 1;
+    readonly State: 2;
+    readonly RequestFrame: 3;
+    readonly SetTimer: 4;
+    readonly FontRequest: 5;
+    readonly HostRequest: 6;
+};
+/** A pointer shape over the document: the engine's `Cursor`. */
+export type Cursor = 'default' | 'text' | 'pointer' | 'move' | 'resizeHorizontal' | 'resizeVertical' | 'resizeNorthWestSouthEast' | 'resizeNorthEastSouthWest' | 'crosshair' | 'notAllowed' | 'copy';
+/** What a copy puts on the clipboard: the engine's `ClipboardData`. */
+export interface ClipboardData {
+    text: string;
+    html?: string;
+    /** The engine's own copy, for a paste back into it. */
+    internal?: string;
+}
+/** Something only the view showing a session can do: the {@link Kind.HostRequest} payload. Content CSS px. */
+export type HostRequest = {
+    type: 'cursor';
+    cursor: Cursor;
+}
+/** Send every pointer event to the view until `release`. */
+ | {
+    type: 'capture';
+} | {
+    type: 'release';
+}
+/** A cut or copy from the keyboard, for the system clipboard. */
+ | {
+    type: 'clipboard';
+    data: ClipboardData;
+}
+/** The caret moved: for the IME and the system caret. */
+ | {
+    type: 'caret';
+    x: number;
+    y: number;
+    height: number;
+    visible: boolean;
+}
+/** Scroll the viewport's top-left to this point, after the next frame sizes the content (a zoom). */
+ | {
+    type: 'scroll';
+    x: number;
+    y: number;
+}
+/** Scroll so this rectangle shows. */
+ | {
+    type: 'scroll_to';
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** The accessibility tree changed: mirror it. */
+ | {
+    type: 'a11y';
+    tree: AccessibleNode;
+};
+/** One engine-to-SDK message. `payload` is the decoded JSON, or undefined for kinds without one. */
+export interface Message {
+    kind: number;
+    sessionId: number;
+    payload: unknown;
+}
+/** Raw input, forwarded to the engine as typed calls (no JSON). */
+export type Input = {
+    type: 'key';
+    key: number;
+    mods: number;
+} | {
+    type: 'text';
+    text: string;
+} | {
+    type: 'composition';
+    phase: number;
+    text: string;
+} | {
+    type: 'focus';
+    focused: boolean;
+} | {
+    type: 'surface';
+    width: number;
+    height: number;
+    dpr: number;
+} | {
+    type: 'scroll';
+    x: number;
+    y: number;
+} | {
+    type: 'wheel';
+    dx: number;
+    dy: number;
+    mods: number;
+} | {
+    type: 'pointer';
+    kind: number;
+    x: number;
+    y: number;
+    button: number;
+    clicks: number;
+    mods: number;
+};
+/** What a frame reports: the content's size, CSS px, and the pages laid out so far. */
+export interface FrameInfo {
+    contentWidth: number;
+    contentHeight: number;
+    pages: number;
+}
+/** How a canvas gets its frames: the best of the page's WebGPU, WebGL 2 and CPU pixels. */
+export type Backend = 'webgpu' | 'webgl' | 'cpu';
+/** The engine, behind one ordered queue. Every method runs after every earlier call on the same transport. */
+export interface Transport {
+    /** Creates a session over the shared engine. */
+    createSession(options: object): Promise<number>;
+    /** Closes a session; later calls with its id fail `destroyed`. */
+    closeSession(session: number): Promise<void>;
+    /** A structured call: request and response are the engine's JSON shapes. */
+    call(session: number, method: Method, request?: unknown): Promise<unknown>;
+    /** Opens a document; resolves with the read's warnings. */
+    open(session: number, bytes: Uint8Array, signal?: AbortSignal): Promise<Warning[]>;
+    /**
+     * Reads a document without replacing the open one, for an open that may still be aborted: resolves with a token
+     * for {@link Transport.openCommit} or {@link Transport.openDiscard}.
+     */
+    openPrepare(session: number, bytes: Uint8Array): Promise<number>;
+    /** Replaces the open document with a prepared one; resolves with the read's warnings. */
+    openCommit(session: number, token: number): Promise<Warning[]>;
+    /** Drops a prepared document: the open one stays. */
+    openDiscard(session: number, token: number): Promise<void>;
+    /** Exports the document. */
+    export(session: number, options: {
+        format: 'docx' | 'pdf';
+    }, signal?: AbortSignal): Promise<{
+        bytes: Uint8Array;
+        revision: number;
+        warnings: Warning[];
+    }>;
+    /** Adds a font to the shared library. */
+    addFont(bytes: Uint8Array): Promise<FaceInfo[]>;
+    /** Forwards input; a key resolves with its outcome (0 unhandled, 1 handled, 2 and up a host key). */
+    input(session: number, input: Input): Promise<number>;
+    /**
+     * Gives a session the canvas its frames go to, on the best backend the page has. Rejects `unsupported` when the
+     * canvas can't be drawn at all.
+     */
+    attachCanvas(session: number, canvas: HTMLCanvasElement): Promise<Backend>;
+    /**
+     * Draws a frame of `width` x `height` device pixels into the session's canvas (sizing it), or resolves null when
+     * there is no canvas or nothing to draw.
+     */
+    frame(session: number, width: number, height: number): Promise<FrameInfo | null>;
+    /** Receives a session's messages, after the operation that caused them and before its promise settles. */
+    listen(session: number, listener: (message: Message) => void): () => void;
+}
+/** The engine's error shape. */
+interface WireError {
+    code: ErrorCode;
+    message: string;
+    details?: unknown;
+}
+/** Turns a response envelope (`{ ok }` or `{ error }`) into its value, or throws its error. */
+export declare function unwrap(response: unknown): unknown;
+/** The engine's error shape as an {@link EditorError}. */
+export declare function toError(error: WireError): EditorError;
+/** An {@link EditorError} in the engine's error shape. */
+export declare function fromError(error: EditorError): WireError;
+/**
+ * An engine event as its public type and payload. Events travel as `{ type, ...fields }`; an event whose payload
+ * isn't an object carries it as `value`, and `error` carries the error shape plus `fatal`.
+ */
+export declare function decodeEvent(wire: unknown): {
+    type: keyof TwipEvents;
+    event: unknown;
+};
+/** The inverse of {@link decodeEvent}. */
+export declare function encodeEvent(type: keyof TwipEvents, event: unknown): unknown;
+export {};

package/dist/transport/protocol.js

@@ -0,0 +1,132 @@
+// The private boundary between the public classes and the engine. The engine may run on this thread
+// (DirectTransport) or in the page's engine worker; both deliver the same message stream and run operations in one
+// ordered queue, so the public classes don't know which one they talk to.
+import { EditorError } from '../errors.js';
+/** Structured call numbers: `TwipMethod` in `twip.h`, the C ABI's `Method`. The two lists must match exactly. */
+export const Method = {
+    Run: 1,
+    Batch: 2,
+    State: 3,
+    Catalog: 4,
+    NewDocument: 5,
+    SetReadOnly: 6,
+    SetMode: 7,
+    SetAuthor: 8,
+    ContextMenu: 9,
+    Invoke: 10,
+    DialogOpen: 11,
+    DialogUpdate: 12,
+    DialogApply: 13,
+    Find: 14,
+    FindAll: 15,
+    SelectMatch: 16,
+    Replace: 17,
+    ReplaceAll: 18,
+    SpellingAddDictionary: 19,
+    SpellingSetEnabled: 20,
+    SpellingSetLanguage: 21,
+    SpellingIgnore: 22,
+    SpellingAdd: 23,
+    SpellingLoadUserWords: 24,
+    SpellingSuggestions: 25,
+    SpellingNext: 26,
+    Headings: 27,
+    SelectHeading: 28,
+    Styles: 29,
+    Revisions: 30,
+    Comments: 31,
+    People: 32,
+    Elements: 33,
+    Element: 34,
+    Structure: 35,
+    SelectElement: 36,
+    DataParts: 37,
+    AccessibleTree: 38,
+    ShortcutsRegister: 39,
+    ShortcutsUnregister: 40,
+    ShortcutsLookup: 41,
+    GesturesBindings: 42,
+    GesturesSet: 43,
+    GesturesReset: 44,
+    WordCount: 45,
+    Copy: 46,
+    Paste: 47,
+    FontFamilies: 48,
+    FontSetSubstitutions: 49,
+    FontSetDefault: 50,
+    FontMarkUnresolved: 51,
+    HostSetBackground: 52,
+    HostSetMarkupPaneWidth: 53,
+    HostSetRulers: 54,
+    HostSetRulerUnit: 55,
+    HostSetTabSelector: 56,
+    HostRulerView: 57,
+    HostCommentAnchors: 58,
+    HostHitTest: 59,
+    HostDragOver: 60,
+    HostDragLeave: 61,
+    HostDrop: 62,
+    HostRevealSelection: 63,
+    HostVisiblePages: 64,
+    StackBalloons: 65,
+    OpenCommit: 66,
+    OpenDiscard: 67,
+    DialogSelectIssue: 68,
+    FontSetResolver: 69,
+    Placeholders: 70,
+    HostSetCaretBlink: 71,
+    HostFrameStats: 72,
+    HostSetOverlayPalette: 73,
+    HostSetPaintBudget: 74,
+    HostSetLeaders: 75,
+};
+/** What the engine sends: callback kinds of the C ABI. */
+export const Kind = {
+    Event: 1,
+    State: 2,
+    RequestFrame: 3,
+    SetTimer: 4,
+    FontRequest: 5,
+    HostRequest: 6,
+};
+/** Turns a response envelope (`{ ok }` or `{ error }`) into its value, or throws its error. */
+export function unwrap(response) {
+    const envelope = response;
+    if (envelope && typeof envelope === 'object' && 'error' in envelope && envelope.error)
+        throw toError(envelope.error);
+    if (envelope && typeof envelope === 'object' && 'ok' in envelope)
+        return envelope.ok;
+    throw new EditorError('internal', `malformed engine response: ${JSON.stringify(response)}`);
+}
+/** The engine's error shape as an {@link EditorError}. */
+export function toError(error) {
+    return new EditorError(error.code, error.message, error.details == null ? undefined : { details: error.details });
+}
+/** An {@link EditorError} in the engine's error shape. */
+export function fromError(error) {
+    return error.details === undefined
+        ? { code: error.code, message: error.message }
+        : { code: error.code, message: error.message, details: error.details };
+}
+/**
+ * An engine event as its public type and payload. Events travel as `{ type, ...fields }`; an event whose payload
+ * isn't an object carries it as `value`, and `error` carries the error shape plus `fatal`.
+ */
+export function decodeEvent(wire) {
+    const { type, ...fields } = wire;
+    if (type === 'error') {
+        const { fatal, ...error } = fields;
+        const e = toError(error);
+        return { type, event: fatal ? new EditorError(e.code, e.message, { details: e.details, fatal }) : e };
+    }
+    return { type, event: 'value' in fields ? fields.value : fields };
+}
+/** The events whose payload always travels as `value`, an object or not: the engine's optional payloads. */
+const valueEvents = new Set(['tooltip']);
+/** The inverse of {@link decodeEvent}. */
+export function encodeEvent(type, event) {
+    if (event instanceof EditorError)
+        return { type, ...fromError(event), fatal: event.fatal };
+    const spread = event !== null && typeof event === 'object' && !Array.isArray(event) && !valueEvents.has(type);
+    return spread ? { type, ...event } : { type, value: event };
+}

package/dist/transport/worker.d.ts

@@ -0,0 +1,54 @@
+import { EditorError } from '../errors.js';
+import type { FaceInfo } from '../fonts/library.js';
+import type { Warning } from '../types.js';
+import { type Backend, type FrameInfo, type Input, type Message, Method, type Transport } from './protocol.js';
+/** A call to the worker: a {@link Transport} method and its arguments (without the signal), or an abort. */
+export interface Request {
+    id: number;
+    op: keyof Transport | 'abort';
+    args: unknown[];
+}
+/** The worker's answer to a request. */
+export type Reply = {
+    id: number;
+    ok: unknown;
+} | {
+    id: number;
+    error: {
+        code: EditorError['code'];
+        message: string;
+        details?: unknown;
+    };
+    fatal: boolean;
+};
+/**
+ * The mode `execution` asks for. `'auto'` is the worker where the page supports it, and the main thread otherwise;
+ * `'worker'` where it doesn't is `unsupported`.
+ */
+export declare function chooseExecution(execution?: 'auto' | 'main' | 'worker'): 'main' | 'worker';
+/** The page's one worker transport. */
+export declare function workerTransport(): WorkerTransport;
+/** The {@link Transport} that posts every call to the page's engine worker. */
+export declare class WorkerTransport implements Transport {
+    #private;
+    createSession(options: object): Promise<number>;
+    closeSession(session: number): Promise<void>;
+    call(session: number, method: Method, request?: unknown): Promise<unknown>;
+    open(session: number, bytes: Uint8Array, signal?: AbortSignal): Promise<Warning[]>;
+    openPrepare(session: number, bytes: Uint8Array): Promise<number>;
+    openCommit(session: number, token: number): Promise<Warning[]>;
+    openDiscard(session: number, token: number): Promise<void>;
+    export(session: number, options: {
+        format: 'docx' | 'pdf';
+    }, signal?: AbortSignal): Promise<{
+        bytes: Uint8Array;
+        revision: number;
+        warnings: Warning[];
+    }>;
+    addFont(bytes: Uint8Array): Promise<FaceInfo[]>;
+    input(session: number, input: Input): Promise<number>;
+    /** Moves the canvas to the worker, which draws the session's frames into it from then on. */
+    attachCanvas(session: number, canvas: HTMLCanvasElement): Promise<Backend>;
+    frame(session: number, width: number, height: number): Promise<FrameInfo | null>;
+    listen(session: number, listener: (message: Message) => void): () => void;
+}

package/dist/transport/worker.js

@@ -0,0 +1,203 @@
+// The engine in the page's engine worker (src/worker/entry.ts). One worker per page hosts every editor's session, so
+// fonts, dictionaries and the internal clipboard are shared. Calls are posted in submission order and the worker runs
+// them through one queue (a DirectTransport there), so the ordering is the direct transport's. Each operation's
+// messages arrive before its reply and are dispatched in arrival order, so a state message reaches the session's
+// cache before any event of the same drain.
+import { EditorError, unsupported } from '../errors.js';
+import { live } from '../host/dom.js';
+import { Method, toError } from './protocol.js';
+let modules;
+/** Whether this page can run the engine in a worker: module workers and `transferControlToOffscreen`. */
+function workerSupported() {
+    if (typeof Worker === 'undefined' || typeof HTMLCanvasElement === 'undefined')
+        return false;
+    if (typeof HTMLCanvasElement.prototype.transferControlToOffscreen !== 'function')
+        return false;
+    if (modules === undefined) {
+        // A browser with module workers reads `type`; the URL doesn't parse, so no worker starts.
+        modules = false;
+        try {
+            new Worker('http://[', {
+                get type() {
+                    modules = true;
+                    return 'module';
+                },
+            });
+        }
+        catch {
+            // Expected: the URL.
+        }
+    }
+    return modules;
+}
+/**
+ * The mode `execution` asks for. `'auto'` is the worker where the page supports it, and the main thread otherwise;
+ * `'worker'` where it doesn't is `unsupported`.
+ */
+export function chooseExecution(execution = 'auto') {
+    if (execution === 'main')
+        return 'main';
+    if (workerSupported())
+        return 'worker';
+    if (execution === 'worker')
+        throw unsupported("execution: 'worker' on this browser");
+    return 'main';
+}
+let shared;
+/** The page's one worker transport. */
+export function workerTransport() {
+    return (shared ??= new WorkerTransport());
+}
+/** The {@link Transport} that posts every call to the page's engine worker. */
+export class WorkerTransport {
+    #worker;
+    #next = 1;
+    #calls = new Map();
+    #listeners = new Map();
+    /** Open sessions: the worker stops when the last one closes and no call is in flight. */
+    #sessions = new Set();
+    /** The font library's changes, replayed into a restarted worker so the page's fonts survive it. */
+    #library = [];
+    /** Set when the worker failed: it can't be trusted again. */
+    #fault;
+    createSession(options) {
+        return this.#request('createSession', [options]).then((id) => (this.#sessions.add(id), id));
+    }
+    closeSession(session) {
+        return this.#request('closeSession', [session]).finally(() => {
+            this.#listeners.delete(session);
+            this.#sessions.delete(session);
+            this.#stopWhenIdle();
+        });
+    }
+    call(session, method, request) {
+        return this.#request('call', [session, method, request], { library: session === 0 && method !== Method.FontFamilies });
+    }
+    open(session, bytes, signal) {
+        return this.#request('open', [session, bytes], { signal });
+    }
+    openPrepare(session, bytes) {
+        return this.#request('openPrepare', [session, bytes]);
+    }
+    openCommit(session, token) {
+        return this.#request('openCommit', [session, token]);
+    }
+    openDiscard(session, token) {
+        return this.#request('openDiscard', [session, token]);
+    }
+    export(session, options, signal) {
+        return this.#request('export', [session, options], { signal });
+    }
+    addFont(bytes) {
+        return this.#request('addFont', [bytes], { library: true });
+    }
+    input(session, input) {
+        return this.#request('input', [session, input]);
+    }
+    /** Moves the canvas to the worker, which draws the session's frames into it from then on. */
+    attachCanvas(session, canvas) {
+        const offscreen = canvas.transferControlToOffscreen();
+        return this.#request('attachCanvas', [session, offscreen], { transfer: [offscreen] });
+    }
+    frame(session, width, height) {
+        return this.#request('frame', [session, width, height]);
+    }
+    listen(session, listener) {
+        let set = this.#listeners.get(session);
+        if (!set)
+            this.#listeners.set(session, (set = new Set()));
+        set.add(listener);
+        return () => set.delete(listener);
+    }
+    #request(op, args, how = {}) {
+        if (this.#fault)
+            return Promise.reject(this.#fault);
+        const { signal } = how;
+        if (signal?.aborted)
+            return Promise.reject(new EditorError('aborted', 'the operation was aborted'));
+        let worker;
+        try {
+            worker = this.#start();
+        }
+        catch (cause) {
+            return Promise.reject(this.#failed(cause));
+        }
+        const request = { id: this.#next++, op, args };
+        // Replayed with no reply to wait for (id 0).
+        if (how.library)
+            this.#library.push({ ...request, id: 0 });
+        return new Promise((resolve, reject) => {
+            const abort = () => worker.postMessage({ id: request.id, op: 'abort', args: [] });
+            signal?.addEventListener('abort', abort, { once: true });
+            this.#calls.set(request.id, {
+                resolve: (value) => (signal?.removeEventListener('abort', abort), resolve(value)),
+                reject: (error) => (signal?.removeEventListener('abort', abort), reject(error)),
+            });
+            worker.postMessage(request, { transfer: how.transfer ?? [] });
+        });
+    }
+    #start() {
+        if (this.#worker)
+            return this.#worker;
+        // The worker is beside this file's directory, in dist/. Written out in one expression, as bundlers recognise
+        // it: they build the worker and its imports into the application.
+        const worker = new Worker(new URL('../worker.js', import.meta.url), { type: 'module', name: 'twip-engine' });
+        live.workers++;
+        worker.onmessage = ({ data }) => this.#receive(data);
+        worker.onerror = (e) => {
+            e.preventDefault();
+            this.#failed(e.message || 'the engine worker failed to start');
+        };
+        for (const request of this.#library)
+            worker.postMessage(request);
+        return (this.#worker = worker);
+    }
+    #receive(data) {
+        if ('kind' in data) {
+            for (const listener of [...(this.#listeners.get(data.sessionId) ?? [])]) {
+                try {
+                    listener(data);
+                }
+                catch (e) {
+                    globalThis.reportError?.(e);
+                }
+            }
+            return;
+        }
+        const call = this.#calls.get(data.id);
+        if (!call)
+            return;
+        this.#calls.delete(data.id);
+        if ('error' in data) {
+            const e = toError(data.error);
+            call.reject(data.fatal ? new EditorError(e.code, e.message, { details: e.details, fatal: true }) : e);
+        }
+        else
+            call.resolve(data.ok);
+        // After the caller's reaction, which counts a session just created.
+        queueMicrotask(() => this.#stopWhenIdle());
+    }
+    /** No editor left: the worker goes, and the next call starts a new one. */
+    #stopWhenIdle() {
+        if (this.#sessions.size || this.#calls.size || !this.#worker)
+            return;
+        this.#stop();
+    }
+    #stop() {
+        this.#worker?.terminate();
+        if (this.#worker)
+            live.workers--;
+        this.#worker = undefined;
+    }
+    /** The worker failed: every call in flight and every later one rejects, and the next editor gets a new worker. */
+    #failed(cause) {
+        this.#fault ??= new EditorError('internal', `the engine worker stopped: ${String(cause)}`, { fatal: true, cause });
+        if (shared === this)
+            shared = undefined;
+        for (const call of this.#calls.values())
+            call.reject(this.#fault);
+        this.#calls.clear();
+        this.#stop();
+        return this.#fault;
+    }
+}