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

package/dist/types.d.ts

@@ -0,0 +1,134 @@
+/** A length in points (1/72 inch). Every length in the API is in points. */
+export type Points = number;
+/** A colour as `#RRGGBB`. */
+export type Color = `#${string}`;
+/** Converts inches to points. */
+export declare function inches(n: number): Points;
+/** Converts centimetres to points. */
+export declare function cm(n: number): Points;
+/** Converts millimetres to points. */
+export declare function mm(n: number): Points;
+/** Returns `n` points: for call sites that state their unit. */
+export declare function pt(n: number): Points;
+declare const brand: unique symbol;
+/** A merge-designer element (a field or a content control). Stable while the document is open. */
+export type ElementId = string & {
+    readonly [brand]: 'element';
+};
+/** A comment. Stable while the document is open. */
+export type CommentId = string & {
+    readonly [brand]: 'comment';
+};
+/** A tracked revision. Stable while the document is open. */
+export type RevisionId = string & {
+    readonly [brand]: 'revision';
+};
+/** A heading in the navigation list. */
+export type HeadingId = string & {
+    readonly [brand]: 'heading';
+};
+/** A find match. */
+export type MatchId = string & {
+    readonly [brand]: 'match';
+};
+/** A style. */
+export type StyleId = string & {
+    readonly [brand]: 'style';
+};
+/** A point relative to the browser viewport, in CSS pixels, like `MouseEvent.clientX`. */
+export interface ClientPoint {
+    /** CSS pixels from the viewport's left edge. */
+    clientX: number;
+    /** CSS pixels from the viewport's top edge. */
+    clientY: number;
+}
+/** The colours of what the editor draws over the document (`view.setOverlayColors`). */
+export interface OverlayColors {
+    /** The caret. Default black. */
+    caret: Color;
+    /** The selection, blended under the text (multiply), so black text stays black. Default `'#4A90D9'`. */
+    selection: Color;
+    /** A selected object's outline and handles. Default `'#606060'`. */
+    object: Color;
+    /** The drop caret of a drag. Default `'#404040'`. */
+    drop: Color;
+    /** Formatting marks and text boundaries. Default `'#2F6FB5'`. */
+    marks: Color;
+    /** The markup pane's leader lines. Default `'#767676'`. */
+    leaders: Color;
+}
+/** What a mounted editor's frames have cost so far (`view.frameStats()`): for benchmarks and tests. */
+export interface FrameStats {
+    /** Frames drawn. */
+    frames: number;
+    /** Page recordings made: an unchanged page is recorded once. */
+    pagesRecorded: number;
+    /** Pages drawn again from their recordings. */
+    pagesReused: number;
+    /** The page recordings kept now, bytes. */
+    recordingBytes: number;
+    /** The last frame's time, ms. */
+    lastFrameMs: number;
+    /** The 95th percentile of the last 120 frames' times, ms. */
+    p95FrameMs: number;
+}
+/** A rectangle relative to the browser viewport, in CSS pixels. */
+export interface ClientRect {
+    /** The left edge. */
+    left: number;
+    /** The top edge. */
+    top: number;
+    /** The width. */
+    width: number;
+    /** The height. */
+    height: number;
+}
+/** A point relative to the editor's balloon layer, in CSS pixels: it scrolls and zooms with the document. */
+export interface ContentPoint {
+    /** CSS pixels from the layer's left edge. */
+    x: number;
+    /** CSS pixels from the layer's top edge. */
+    y: number;
+}
+/** Who makes changes: recorded on transactions, revisions and comments. */
+export interface Author {
+    /** The display name. */
+    name: string;
+    /** The initials shown on comments. */
+    initials?: string;
+    /** The identity in a directory, written to the document with the author. */
+    identity?: {
+        provider: string;
+        userId: string;
+    };
+}
+/** A recoverable fidelity issue found while reading or writing a document. Aggregated per code and part. */
+export interface Warning {
+    /** What kind of issue it is. */
+    code: 'unsupported-element' | 'image-undecodable' | 'font-unresolved' | 'font-substituted' | 'rewritten-content' | 'pdf-font-fallback' | 'revision-id-missing' | 'range-unpaired' | 'author-missing' | 'comment-unanchored' | 'comment-reference-orphan';
+    /** A readable description. */
+    message: string;
+    /** How many times it occurred. */
+    count: number;
+    /** Where it occurred, when known. */
+    location?: {
+        part: string;
+        paragraph?: number;
+    };
+}
+/** Word, character, paragraph, line and page counts, computed on request. */
+export interface WordCount {
+    /** Words. */
+    words: number;
+    /** Characters, without spaces. */
+    characters: number;
+    /** Characters, with spaces. */
+    charactersWithSpaces: number;
+    /** Paragraphs. */
+    paragraphs: number;
+    /** Lines. */
+    lines: number;
+    /** Pages. */
+    pages: number;
+}
+export {};

package/dist/types.js

@@ -0,0 +1,16 @@
+/** Converts inches to points. */
+export function inches(n) {
+    return n * 72;
+}
+/** Converts centimetres to points. */
+export function cm(n) {
+    return (n * 72) / 2.54;
+}
+/** Converts millimetres to points. */
+export function mm(n) {
+    return (n * 72) / 25.4;
+}
+/** Returns `n` points: for call sites that state their unit. */
+export function pt(n) {
+    return n;
+}

package/dist/worker/entry.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/worker/entry.js

@@ -0,0 +1,53 @@
+// The page's engine worker: one per page hosts every editor's session in one module instance, so fonts, dictionaries
+// and the internal clipboard are shared. It runs each posted call through a DirectTransport, whose queue keeps them in
+// arrival order, and relays the sessions' { kind, sessionId, payload } messages ahead of each reply. A session's canvas
+// moves here, and its frames are drawn here when the page's frame loop asks (host/frames.ts); the engine's timers run
+// on this thread.
+import { EditorError } from '../errors.js';
+import { directTransport } from '../transport/direct.js';
+import { fromError } from '../transport/protocol.js';
+const engine = directTransport();
+const signals = new Map();
+/** Posts to the page, moving the buffer of exported bytes instead of copying it. */
+function post(message) {
+    const bytes = 'ok' in message ? message.ok?.bytes : undefined;
+    postMessage(message, { transfer: bytes instanceof Uint8Array && bytes.buffer instanceof ArrayBuffer ? [bytes.buffer] : [] });
+}
+/** Runs one request on the engine. */
+function run(t, { id, op, args }) {
+    switch (op) {
+        case 'createSession':
+            return t.createSession(args[0]).then((session) => {
+                t.listen(session, post);
+                return session;
+            });
+        case 'attachCanvas':
+            // An OffscreenCanvas: the GPU and CPU paths take either kind of canvas.
+            return t.attachCanvas(args[0], args[1]);
+        case 'open':
+        case 'export': {
+            const controller = new AbortController();
+            signals.set(id, controller);
+            const call = t[op];
+            return call.call(t, ...args, controller.signal).finally(() => signals.delete(id));
+        }
+        default:
+            return t[op].apply(t, args);
+    }
+}
+// Session 0 is the engine's own: font requests.
+engine.then((t) => t.listen(0, post), () => { });
+onmessage = ({ data }) => {
+    if (data.op === 'abort') {
+        signals.get(data.id)?.abort();
+        return;
+    }
+    // Every request waits on the same promise, so they reach the engine's queue in arrival order. Id 0 is a replayed
+    // library change: nothing waits for its reply.
+    engine.then((t) => run(t, data)).then((ok) => data.id && post({ id: data.id, ok }), (e) => {
+        if (!data.id)
+            return console.error(e);
+        const error = e instanceof EditorError ? e : new EditorError('internal', String(e), { cause: e });
+        post({ id: data.id, error: fromError(error), fatal: error.fatal });
+    });
+};

package/dist/worker.d.ts

@@ -0,0 +1 @@
+import './worker/entry.js';

package/dist/worker.js

@@ -0,0 +1,2 @@
+// The page's engine worker entry (`@twip/web/worker.js`). The SDK starts it itself; applications never load it.
+import './worker/entry.js';

package/package.json

@@ -1,20 +1,25 @@
 {
   "name": "@twip/web",
-  "version": "0.1.0-alpha.1",
-  "description": "TypeScript SDK for the twip DOCX engine (WebAssembly). Generated from crates/twip-ffi.",
+  "version": "0.1.0-pre.1",
+  "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",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "default": "./dist/index.mjs"
-    }
+      "node": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./worker.js": "./dist/worker.js"
   },
+  "types": "./dist/index.d.ts",
   "files": [
     "dist"
   ],
   "devDependencies": {
-    "@playwright/test": "1.64.1"
-  },
-  "scripts": {}
+    "@microsoft/api-extractor": "7.60.0",
+    "@playwright/test": "1.64.1",
+    "@types/node": "26.6.5",
+    "typescript": "7.0.2"
+  }
 }

package/dist/AccessibleNode.d.ts

@@ -1,51 +0,0 @@
-// generated by diplomat-tool
-import type { Rect } from "./Rect"
-import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
-
-
-
-/**
- * A node of the document's reading structure (headings, paragraphs, lists, tables, rows, cells), for screen
- * readers and other assistive technology.
- */
-export class AccessibleNode {
-    /** @internal */
-    get ffiValue(): pointer;
-    /** @internal */
-    constructor();
-
-
-    /**
-     * The role: `document`, `heading`, `paragraph`, `list`, `listitem`, `table`, `row`, `cell`, ...
-     */
-    role(): string;
-
-    /**
-     * The heading level (0 when not a heading).
-     */
-    get level(): number;
-
-    /**
-     * The accessible name (a list item's label, a cell's position, ...), empty if none.
-     */
-    label(): string;
-
-    /**
-     * How many drawn lines the node's own text has.
-     */
-    get lineCount(): number;
-
-    /**
-     * A line's text.
-     */
-    lineText(index: number): string;
-
-    /**
-     * A line's box, content pixels.
-     */
-    lineRect(index: number): Rect;
-
-    get childCount(): number;
-
-    child(index: number): AccessibleNode | null;
-}

package/dist/AccessibleNode.mjs

@@ -1,177 +0,0 @@
-// generated by diplomat-tool
-import { Rect } from "./Rect.mjs"
-import wasm from "./diplomat-wasm.mjs";
-import * as diplomatRuntime from "./diplomat-runtime.mjs";
-
-const AccessibleNode_box_destroy_registry = new FinalizationRegistry((ptr) => {
-    wasm.AccessibleNode_destroy(ptr);
-});
-
-/**
- * A node of the document's reading structure (headings, paragraphs, lists, tables, rows, cells), for screen
- * readers and other assistive technology.
- */
-export class AccessibleNode {
-    // Internal ptr reference:
-    #ptr = null;
-
-    // Lifetimes are only to keep dependencies alive.
-    // Since JS won't garbage collect until there are no incoming edges.
-    #selfEdge = [];
-
-    #internalConstructor(symbol, ptr, selfEdge) {
-        if (symbol !== diplomatRuntime.internalConstructor) {
-            console.error("AccessibleNode is an Opaque type. You cannot call its constructor.");
-            return;
-        }
-        this.#ptr = ptr;
-        this.#selfEdge = selfEdge;
-
-        // Are we being borrowed? If not, we can register.
-        if (this.#selfEdge.length === 0) {
-            AccessibleNode_box_destroy_registry.register(this, this.#ptr);
-        }
-
-        return this;
-    }
-    /** @internal */
-    get ffiValue() {
-        return this.#ptr;
-    }
-
-
-    /**
-     * The role: `document`, `heading`, `paragraph`, `list`, `listitem`, `table`, `row`, `cell`, ...
-     */
-    role() {
-        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
-
-    wasm.AccessibleNode_role(this.ffiValue, write.buffer);
-
-        try {
-            return write.readString8();
-        }
-
-        finally {
-            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
-            write.free();
-        }
-    }
-
-    /**
-     * The heading level (0 when not a heading).
-     */
-    get level() {
-
-        const result = wasm.AccessibleNode_level(this.ffiValue);
-
-        try {
-            return result;
-        }
-
-        finally {
-            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
-        }
-    }
-
-    /**
-     * The accessible name (a list item's label, a cell's position, ...), empty if none.
-     */
-    label() {
-        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
-
-    wasm.AccessibleNode_label(this.ffiValue, write.buffer);
-
-        try {
-            return write.readString8();
-        }
-
-        finally {
-            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
-            write.free();
-        }
-    }
-
-    /**
-     * How many drawn lines the node's own text has.
-     */
-    get lineCount() {
-
-        const result = wasm.AccessibleNode_line_count(this.ffiValue);
-
-        try {
-            return result;
-        }
-
-        finally {
-            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
-        }
-    }
-
-    /**
-     * A line's text.
-     */
-    lineText(index) {
-        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
-
-    wasm.AccessibleNode_line_text(this.ffiValue, index, write.buffer);
-
-        try {
-            return write.readString8();
-        }
-
-        finally {
-            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
-            write.free();
-        }
-    }
-
-    /**
-     * A line's box, content pixels.
-     */
-    lineRect(index) {
-        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 32, 8, false);
-
-
-        const result = wasm.AccessibleNode_line_rect(diplomatReceive.buffer, this.ffiValue, index);
-
-        try {
-            return Rect._fromFFI(diplomatRuntime.internalConstructor, diplomatReceive.buffer);
-        }
-
-        finally {
-            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
-            diplomatReceive.free();
-        }
-    }
-
-    get childCount() {
-
-        const result = wasm.AccessibleNode_child_count(this.ffiValue);
-
-        try {
-            return result;
-        }
-
-        finally {
-            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
-        }
-    }
-
-    child(index) {
-
-        const result = wasm.AccessibleNode_child(this.ffiValue, index);
-
-        try {
-            return result === 0 ? null : new AccessibleNode(diplomatRuntime.internalConstructor, result, []);
-        }
-
-        finally {
-            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
-        }
-    }
-
-    constructor(symbol, ptr, selfEdge) {
-        return this.#internalConstructor(...arguments)
-    }
-}

package/dist/Alignment.d.ts

@@ -1,38 +0,0 @@
-// generated by diplomat-tool
-import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
-
-
-
-/**
- * Paragraph alignment.
- */
-export class Alignment {
-
-    /** @internal */
-    static fromValue(value: Alignment | string): Alignment;
-
-    get value(): string;
-
-    /** @internal */
-    get ffiValue(): number;
-
-    /**
-     * Lines start at the left margin.
-     */
-    static Left : Alignment;
-    /**
-     * Lines are centred.
-     */
-    static Center : Alignment;
-    /**
-     * Lines end at the right margin.
-     */
-    static Right : Alignment;
-    /**
-     * Lines fill the width, except a paragraph's last.
-     */
-    static Justify : Alignment;
-
-
-    constructor(value: Alignment | string );
-}

package/dist/Alignment.mjs

@@ -1,90 +0,0 @@
-// generated by diplomat-tool
-import wasm from "./diplomat-wasm.mjs";
-import * as diplomatRuntime from "./diplomat-runtime.mjs";
-
-
-
-/**
- * Paragraph alignment.
- */
-export class Alignment {
-    #value = undefined;
-
-    static #values = new Map([
-        ["Left", 0],
-        ["Center", 1],
-        ["Right", 2],
-        ["Justify", 3]
-    ]);
-
-    static getAllEntries() {
-        return Alignment.#values.entries();
-    }
-
-    #internalConstructor(value) {
-        if (arguments.length > 1 && arguments[0] === diplomatRuntime.internalConstructor) {
-            // We pass in two internalConstructor arguments to create *new*
-            // instances of this type, otherwise the enums are treated as singletons.
-            if (arguments[1] === diplomatRuntime.internalConstructor ) {
-                this.#value = arguments[2];
-                return this;
-            }
-            return Alignment.#objectValues[arguments[1]];
-        }
-
-        if (value instanceof Alignment) {
-            return value;
-        }
-
-        let intVal = Alignment.#values.get(value);
-
-        // Nullish check, checks for null or undefined
-        if (intVal != null) {
-            return Alignment.#objectValues[intVal];
-        }
-
-        throw TypeError(value + " is not a Alignment and does not correspond to any of its enumerator values.");
-    }
-
-    /** @internal */
-    static fromValue(value) {
-        return new Alignment(value);
-    }
-
-    get value(){
-        return [...Alignment.#values.keys()][this.#value];
-    }
-
-    /** @internal */
-    get ffiValue(){
-        return this.#value;
-    }
-    static #objectValues = [
-        new Alignment(diplomatRuntime.internalConstructor, diplomatRuntime.internalConstructor, 0),
-        new Alignment(diplomatRuntime.internalConstructor, diplomatRuntime.internalConstructor, 1),
-        new Alignment(diplomatRuntime.internalConstructor, diplomatRuntime.internalConstructor, 2),
-        new Alignment(diplomatRuntime.internalConstructor, diplomatRuntime.internalConstructor, 3),
-    ];
-
-    /**
-     * Lines start at the left margin.
-     */
-    static Left = Alignment.#objectValues[0];
-    /**
-     * Lines are centred.
-     */
-    static Center = Alignment.#objectValues[1];
-    /**
-     * Lines end at the right margin.
-     */
-    static Right = Alignment.#objectValues[2];
-    /**
-     * Lines fill the width, except a paragraph's last.
-     */
-    static Justify = Alignment.#objectValues[3];
-
-
-    constructor(value) {
-        return this.#internalConstructor(...arguments)
-    }
-}

package/dist/BorderEdges.d.ts

@@ -1,50 +0,0 @@
-// generated by diplomat-tool
-import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
-
-
-
-/**
- * Which cell edges a border applies to.
- */
-export class BorderEdges {
-
-    /** @internal */
-    static fromValue(value: BorderEdges | string): BorderEdges;
-
-    get value(): string;
-
-    /** @internal */
-    get ffiValue(): number;
-
-    /**
-     * Every edge.
-     */
-    static All : BorderEdges;
-    /**
-     * The outer edges of the selection.
-     */
-    static Outside : BorderEdges;
-    /**
-     * The inner edges, horizontal and vertical.
-     */
-    static Inside : BorderEdges;
-    /**
-     * The inner horizontal edges.
-     */
-    static InsideHorizontal : BorderEdges;
-    /**
-     * The inner vertical edges.
-     */
-    static InsideVertical : BorderEdges;
-    static Top : BorderEdges;
-    static Bottom : BorderEdges;
-    static Left : BorderEdges;
-    static Right : BorderEdges;
-    /**
-     * Removes the borders.
-     */
-    static Clear : BorderEdges;
-
-
-    constructor(value: BorderEdges | string );
-}