@canvist/web 0.0.0-stage → 0.2.0

package/dist/collab.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Collaborative editing over y-websocket, out of the box.
+ *
+ * `createEditor` here makes an editor from a build of canvist with Yjs
+ * inside (a second WebAssembly module, so editors that don't collaborate
+ * never download it), and `connect` joins it to a room on any server that
+ * speaks y-websocket's protocol: y-websocket's own server, canvist's
+ * `receiveSync` servers, or canvist Cloud Sync. The editor is the Yjs peer
+ * itself, so there is no `Y.Doc` to keep in step, and JavaScript Yjs peers
+ * in the same room see the same document.
+ *
+ * ```ts
+ * import { connect, createEditor } from "@canvist/web/collab";
+ *
+ * const editor = await createEditor(document.querySelector("#editor")!);
+ * const connection = connect(editor, {
+ * 	url: "wss://sync.example.com",
+ * 	room: "team-notes",
+ * });
+ * await connection.whenSynced();
+ * ```
+ *
+ * @module
+ */
+import type { Extensions, StarterKit } from "@canvist/headless";
+import { WebEditor } from "../wasm-collab/canvist_web.js";
+import { Editor, type EditorOptions } from "./editor.ts";
+import type { WasmSource } from "./load.ts";
+import type { Plugins } from "./plugin.ts";
+/**
+ * Load the collaborative WebAssembly module once. Without a source it is
+ * fetched from next to this file, which bundlers such as Vite follow.
+ */
+export declare function loadCollab(source?: WasmSource): Promise<void>;
+/**
+ * Create an editor that can collaborate: `@canvist/web`'s `createEditor`,
+ * with Yjs inside. `options.wasm` is where the collaborative module comes
+ * from.
+ */
+export declare function createEditor<const E extends Extensions = StarterKit, const P extends Plugins = []>(element: HTMLElement, options?: EditorOptions<E, P>): Promise<Editor<E, P>>;
+/** What a connection needs from its editor. */
+type Peer = Pick<Editor<StarterKit>, "documentChanged" | "subscribe">;
+/** Where and how to connect. */
+export interface ConnectOptions {
+    /**
+     * The server's WebSocket URL, such as `wss://sync.example.com`. The room
+     * is added as a path segment, as y-websocket's `WebsocketProvider` does.
+     */
+    readonly url: string;
+    /** The room: every peer in it edits one document. */
+    readonly room: string;
+    /** Query parameters for the URL, such as a short-lived token. */
+    readonly params?: Readonly<Record<string, string>>;
+    /** This peer's Yjs client id, unique in the room. Random by default. */
+    readonly clientId?: number;
+    /** Reconnect, with backoff, when the connection drops. Default `true`. */
+    readonly reconnect?: boolean;
+    /** The `WebSocket` class to use. Default the global one. */
+    readonly WebSocket?: typeof WebSocket;
+}
+/** Whether a {@link Connection} is open. */
+export type ConnectionStatus = "connecting" | "connected" | "disconnected";
+/**
+ * Join `editor` to a room. Until the room's document arrives, the editor
+ * keeps showing what it had; then the room's document replaces it (an
+ * empty room gets one empty paragraph). Edits travel both ways from then
+ * on, and undo reverts only this peer's changes.
+ *
+ * `editor` must come from this module's {@link createEditor}.
+ */
+export declare function connect<E extends Extensions, P extends Plugins>(editor: Editor<E, P>, options: ConnectOptions): Connection;
+/** A live link between an editor and a room. Create one with {@link connect}. */
+export declare class Connection {
+    #private;
+    /** @internal Use {@link connect}. */
+    constructor(editor: Peer, build: WebEditor, options: ConnectOptions);
+    /** Whether the connection is open. */
+    get status(): ConnectionStatus;
+    /** Whether the room's document has arrived. */
+    get synced(): boolean;
+    /** This peer's Yjs client id. */
+    get clientId(): number;
+    /**
+     * Call `listener` whenever {@link Connection.status} or
+     * {@link Connection.synced} changes. Returns a function that
+     * unsubscribes.
+     */
+    subscribe(listener: () => void): () => void;
+    /** Resolve once the room's document has arrived. */
+    whenSynced(): Promise<void>;
+    /**
+     * Close the connection for good. The editor keeps the shared document;
+     * {@link connect} it again to carry on, and it catches up with what it
+     * missed.
+     */
+    disconnect(): void;
+    [Symbol.dispose](): void;
+}
+export {};

package/dist/collab.js

@@ -0,0 +1,211 @@
+import init, { WebEditor } from "../wasm-collab/canvist_web.js";
+import { Editor } from "./editor.js";
+/** The longest wait between reconnection attempts, in milliseconds. */
+const MAX_BACKOFF_MS = 10_000;
+/** The first wait before reconnecting, in milliseconds; it doubles each time. */
+const FIRST_BACKOFF_MS = 250;
+/** The collaborative build of each editor `createEditor` here made. */
+const builds = new WeakMap();
+let loading;
+/**
+ * Load the collaborative WebAssembly module once. Without a source it is
+ * fetched from next to this file, which bundlers such as Vite follow.
+ */
+export function loadCollab(source) {
+    loading ??= init({
+        module_or_path: source ??
+            new URL("../wasm-collab/canvist_web_bg.wasm", import.meta.url),
+    }).then(() => undefined);
+    return loading;
+}
+/**
+ * Create an editor that can collaborate: `@canvist/web`'s `createEditor`,
+ * with Yjs inside. `options.wasm` is where the collaborative module comes
+ * from.
+ */
+export async function createEditor(element, options = {}) {
+    await loadCollab(options.wasm);
+    let build;
+    const editor = new Editor(element, options, (...args) => {
+        build = new WebEditor(...args);
+        return build;
+    });
+    if (build === undefined) {
+        throw new Error("the editor did not make its WebAssembly half");
+    }
+    builds.set(editor, build);
+    return editor;
+}
+/**
+ * Join `editor` to a room. Until the room's document arrives, the editor
+ * keeps showing what it had; then the room's document replaces it (an
+ * empty room gets one empty paragraph). Edits travel both ways from then
+ * on, and undo reverts only this peer's changes.
+ *
+ * `editor` must come from this module's {@link createEditor}.
+ */
+export function connect(editor, options) {
+    const build = builds.get(editor);
+    if (build === undefined) {
+        throw new TypeError("connect() needs an editor made by createEditor from @canvist/web/collab");
+    }
+    return new Connection(editor, build, options);
+}
+/** A live link between an editor and a room. Create one with {@link connect}. */
+export class Connection {
+    #editor;
+    #build;
+    #options;
+    #clientId;
+    #listeners = new Set();
+    #unsubscribe;
+    #socket;
+    #status = "connecting";
+    #synced = false;
+    #closed = false;
+    #backoff = FIRST_BACKOFF_MS;
+    #retry = 0;
+    /** @internal Use {@link connect}. */
+    constructor(editor, build, options) {
+        this.#editor = editor;
+        this.#build = build;
+        this.#options = options;
+        this.#clientId = options.clientId ?? randomClientId();
+        // Every local change goes out as soon as it is made.
+        this.#unsubscribe = editor.subscribe(() => this.#flush());
+        this.#open();
+    }
+    /** Whether the connection is open. */
+    get status() {
+        return this.#status;
+    }
+    /** Whether the room's document has arrived. */
+    get synced() {
+        return this.#synced;
+    }
+    /** This peer's Yjs client id. */
+    get clientId() {
+        return this.#clientId;
+    }
+    /**
+     * Call `listener` whenever {@link Connection.status} or
+     * {@link Connection.synced} changes. Returns a function that
+     * unsubscribes.
+     */
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    }
+    /** Resolve once the room's document has arrived. */
+    whenSynced() {
+        if (this.#synced) {
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            const unsubscribe = this.subscribe(() => {
+                if (this.#synced) {
+                    unsubscribe();
+                    resolve();
+                }
+            });
+        });
+    }
+    /**
+     * Close the connection for good. The editor keeps the shared document;
+     * {@link connect} it again to carry on, and it catches up with what it
+     * missed.
+     */
+    disconnect() {
+        this.#closed = true;
+        clearTimeout(this.#retry);
+        this.#unsubscribe();
+        this.#socket?.close();
+        this.#setStatus("disconnected");
+    }
+    [Symbol.dispose]() {
+        this.disconnect();
+    }
+    #open() {
+        const Socket = this.#options.WebSocket ?? WebSocket;
+        const socket = new Socket(roomUrl(this.#options));
+        socket.binaryType = "arraybuffer";
+        this.#socket = socket;
+        this.#setStatus("connecting");
+        socket.addEventListener("open", () => {
+            this.#backoff = FIRST_BACKOFF_MS;
+            this.#setStatus("connected");
+            // A shared document asks for what it missed and sends what it
+            // changed offline; a new one asks for the whole document.
+            this.#send(this.#build.isShared()
+                ? this.#build.syncStart()
+                : this.#build.join(this.#clientId));
+            this.#flush();
+        });
+        socket.addEventListener("message", (event) => {
+            if (event.data instanceof ArrayBuffer) {
+                this.#receive(new Uint8Array(event.data));
+            }
+        });
+        socket.addEventListener("close", () => this.#closedBy(socket));
+    }
+    #receive(message) {
+        const [replies, changed] = this.#build.receiveSync(message);
+        for (const reply of replies) {
+            this.#send(reply);
+        }
+        if (changed) {
+            this.#editor.documentChanged();
+        }
+        if (!this.#synced && this.#build.isShared()) {
+            this.#synced = true;
+            // Joining an empty room wrote its first paragraph.
+            this.#flush();
+            this.#notify();
+        }
+    }
+    #flush() {
+        if (this.#status !== "connected") {
+            return;
+        }
+        for (const message of this.#build.flushSync()) {
+            this.#send(message);
+        }
+    }
+    #send(message) {
+        if (this.#socket?.readyState === WebSocket.OPEN) {
+            // A copy the socket owns: the view's buffer type is too wide to send.
+            this.#socket.send(new Uint8Array(message));
+        }
+    }
+    #closedBy(socket) {
+        if (socket !== this.#socket || this.#closed) {
+            return;
+        }
+        this.#setStatus("disconnected");
+        if (this.#options.reconnect ?? true) {
+            this.#retry = window.setTimeout(() => this.#open(), this.#backoff);
+            this.#backoff = Math.min(this.#backoff * 2, MAX_BACKOFF_MS);
+        }
+    }
+    #setStatus(status) {
+        if (status !== this.#status) {
+            this.#status = status;
+            this.#notify();
+        }
+    }
+    #notify() {
+        for (const listener of this.#listeners) {
+            listener();
+        }
+    }
+}
+/** The room's URL, as y-websocket's `WebsocketProvider` builds it. */
+function roomUrl(options) {
+    const base = options.url.replace(/\/+$/, "");
+    const query = new URLSearchParams(options.params ?? {}).toString();
+    return `${base}/${options.room}${query === "" ? "" : `?${query}`}`;
+}
+/** A random 32-bit Yjs client id, as Yjs picks its own. */
+function randomClientId() {
+    return crypto.getRandomValues(new Uint32Array(1))[0] ?? 0;
+}

package/dist/edit-context.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The parts of the EditContext API the editor uses.
+ *
+ * EditContext (Chromium 121+) lets a canvas receive text input, IME
+ * composition, and the platform's text services as if it were a text field,
+ * without a hidden element. TypeScript's DOM library doesn't declare it
+ * yet, so these declarations cover what `input.ts` calls.
+ *
+ * @see https://w3c.github.io/edit-context/
+ * @module
+ */
+/** Text input arriving at an {@link EditContext}. */
+export interface TextUpdateEvent extends Event {
+    /** The UTF-16 range of the context's text being replaced. */
+    readonly updateRangeStart: number;
+    readonly updateRangeEnd: number;
+    /** The replacement. */
+    readonly text: string;
+    /** The selection afterwards. */
+    readonly selectionStart: number;
+    readonly selectionEnd: number;
+}
+/** The platform asks where the characters in a range are drawn. */
+export interface CharacterBoundsUpdateEvent extends Event {
+    readonly rangeStart: number;
+    readonly rangeEnd: number;
+}
+interface EditContextEvents {
+    textupdate: TextUpdateEvent;
+    characterboundsupdate: CharacterBoundsUpdateEvent;
+    compositionstart: CompositionEvent;
+    compositionend: CompositionEvent;
+}
+/** A text model the platform's input methods edit. */
+export interface EditContext extends EventTarget {
+    readonly text: string;
+    readonly selectionStart: number;
+    readonly selectionEnd: number;
+    updateText(start: number, end: number, text: string): void;
+    updateSelection(start: number, end: number): void;
+    updateControlBounds(bounds: DOMRect): void;
+    updateSelectionBounds(bounds: DOMRect): void;
+    updateCharacterBounds(start: number, bounds: DOMRect[]): void;
+    addEventListener<K extends keyof EditContextEvents>(type: K, listener: (event: EditContextEvents[K]) => void, options?: AddEventListenerOptions): void;
+    addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+}
+interface EditContextInit {
+    readonly text?: string;
+    readonly selectionStart?: number;
+    readonly selectionEnd?: number;
+}
+type EditContextConstructor = new (init?: EditContextInit) => EditContext;
+/** An element that takes an {@link EditContext}. */
+export type EditContextHost = HTMLElement & {
+    editContext: EditContext | null;
+};
+/** The browser's EditContext constructor, where it has one. */
+export declare function editContextApi(): EditContextConstructor | undefined;
+export {};

package/dist/edit-context.js

@@ -0,0 +1,16 @@
+/**
+ * The parts of the EditContext API the editor uses.
+ *
+ * EditContext (Chromium 121+) lets a canvas receive text input, IME
+ * composition, and the platform's text services as if it were a text field,
+ * without a hidden element. TypeScript's DOM library doesn't declare it
+ * yet, so these declarations cover what `input.ts` calls.
+ *
+ * @see https://w3c.github.io/edit-context/
+ * @module
+ */
+/** The browser's EditContext constructor, where it has one. */
+export function editContextApi() {
+    const scope = globalThis;
+    return scope.EditContext;
+}

package/dist/editor.d.ts

@@ -0,0 +1,301 @@
+/**
+ * The canvas editor: a DOM element that hosts the WebAssembly editor's
+ * canvas, keeps it sized to the visible part of the document, and turns
+ * scrolling, resizing, zoom, and font loading into repaints on the next
+ * animation frame.
+ *
+ * @module
+ */
+import type { CommandName, CommandParams, Commands, Content, DocJson, Extensions, Format, Position, Queries, QueryName, QueryParams, QueryResult, Range, Registered, StarterKit, ThemeOptions } from "@canvist/headless";
+import { WebEditor } from "../wasm/canvist_web.js";
+import { type InputMode } from "./input.ts";
+import { type WasmSource } from "./load.ts";
+import { type KeyPlatform } from "./platform.ts";
+import type { PluginApis, Plugins } from "./plugin.ts";
+/** Which line-breaking rules layout follows: Blink's tailoring, or ICU's defaults (Firefox and WebKit). */
+export type LineBreaks = "chromium" | "icu";
+/** Options for {@link createEditor}. */
+export interface EditorOptions<E extends Extensions, P extends Plugins> {
+    /** The extensions, TipTap's StarterKit by default. */
+    readonly extensions?: E;
+    /** Plugins, such as `fonts()` from `@canvist/web/fonts`. */
+    readonly plugins?: P;
+    /** The initial document. */
+    readonly content?: Content<E>;
+    /** The theme. Server rendering must use the same one. */
+    readonly theme?: ThemeOptions;
+    /** Line-breaking tailoring; detected from the browser by default. */
+    readonly breaks?: LineBreaks;
+    /** The client block ids are allocated under. Default 1. */
+    readonly client?: number;
+    /** Pixels beyond the viewport to lay out ahead of scrolling. Default one screen. */
+    readonly overscan?: number;
+    /** Where to load the WebAssembly module from. */
+    readonly wasm?: WasmSource;
+    /**
+     * How text input arrives: `EditContext` where the browser has it
+     * (`"auto"`, the default), or always a hidden textarea (`"textarea"`),
+     * the kill switch for EditContext problems.
+     */
+    readonly input?: InputMode;
+    /** The editor's accessible name. Default `"Editor"`. */
+    readonly label?: string;
+    /**
+     * Whether people can change the document. `false` makes it read-only:
+     * they can still select (with the pointer and navigation keys) and copy,
+     * and commands and the API still change it. Default `true`; change it
+     * later with {@link Editor.setEditable}.
+     */
+    readonly editable?: boolean;
+    /**
+     * Text shown, dimmed, where the first line starts while the document is
+     * empty, and announced as the field's placeholder. Change it later with
+     * {@link Editor.setPlaceholder}.
+     */
+    readonly placeholder?: string;
+    /**
+     * Whether `Mod` in key bindings is Cmd (`"apple"`) or Ctrl (`"other"`);
+     * detected from the browser by default.
+     */
+    readonly platform?: KeyPlatform;
+}
+/**
+ * How long input took to reach the canvas: from each input event's
+ * timestamp until the change was painted, in milliseconds, over the most
+ * recent events.
+ */
+export interface InputLatency {
+    readonly samples: number;
+    readonly p50: number;
+    readonly p95: number;
+    readonly max: number;
+}
+/** Measurement statistics, from {@link Editor.stats}. */
+export interface EditorStats {
+    readonly hits: number;
+    readonly misses: number;
+    /** The share of segment lookups answered from the cache, 0 to 1. */
+    readonly hitRate: number;
+    /** Approximate bytes held by the measurement cache. */
+    readonly bytes: number;
+    readonly measuredSegments: number;
+    readonly measureCalls: number;
+    readonly fonts: readonly {
+        readonly font: string | null;
+        readonly segments: number;
+        readonly bytes: number;
+    }[];
+}
+/** The laid-out document, from {@link Editor.geometry}. */
+export interface Geometry {
+    readonly height: number;
+    readonly blocks: readonly {
+        readonly id: string;
+        readonly rect: readonly [number, number, number, number] | null;
+        readonly text?: string;
+        /** `[utf16, downstream x, upstream x, line top, line height]` per grapheme boundary. */
+        readonly stops?: readonly (readonly [number, number, number, number, number])[];
+    }[];
+    readonly runs: readonly {
+        readonly block: string;
+        /** The run's UTF-16 offset in its block. */
+        readonly start: number;
+        readonly text: string;
+        readonly x: number;
+        readonly width: number;
+        readonly baseline: number;
+        /** The content area's height above the baseline. */
+        readonly ascent: number;
+        readonly font: string;
+        readonly rtl: boolean;
+    }[];
+}
+/** What the last frame did, for tests and profiling. */
+export interface FrameReport {
+    readonly height: number;
+    readonly laidOut: number;
+    readonly measured: number;
+    readonly drawn: number;
+    readonly full: boolean;
+    readonly painted: boolean;
+}
+/**
+ * Create an editor that renders into `element`.
+ *
+ * The element becomes the editor: give it a width (the document wraps to
+ * its content box) and, for a scrolling editor, a height and
+ * `overflow: auto`. Without a height it grows with the document and the
+ * page scrolls. Don't put padding on it; pad a wrapper instead, as with
+ * server-rendered `.cv-doc`.
+ *
+ * ```ts
+ * const editor = await createEditor(element, {
+ * 	content: { format: "markdown", input: "# Hello" },
+ * });
+ * editor.commands.toggleBold();
+ * ```
+ */
+export declare function createEditor<const E extends Extensions = StarterKit, const P extends Plugins = []>(element: HTMLElement, options?: EditorOptions<E, P>): Promise<Editor<E, P>>;
+/**
+ * Makes an editor's WebAssembly half. `@canvist/web/collab` passes one that
+ * makes a build with collaboration.
+ *
+ * @internal
+ */
+export type WebEditorFactory = (...args: ConstructorParameters<typeof WebEditor>) => WebEditor;
+/** A canvas editor. Create one with {@link createEditor}. */
+export declare class Editor<E extends Extensions, P extends Plugins = []> {
+    #private;
+    /** Run a registered command; returns whether it applied. */
+    readonly commands: Commands<Registered<E>>;
+    /** Whether a registered command would apply. Nothing changes. */
+    readonly can: Commands<Registered<E>>;
+    /** Answer a registered query. */
+    readonly query: Queries<Registered<E>>;
+    /** Each registered plugin's API, by name. */
+    readonly plugins: PluginApis<P>;
+    /** @internal Use {@link createEditor}, which loads the WebAssembly module first. */
+    constructor(element: HTMLElement, options: EditorOptions<E, P>, create?: WebEditorFactory);
+    /** The registered extensions, including the ones every editor has. */
+    get extensions(): Registered<E>;
+    /** The canvas the editor paints. */
+    get canvas(): HTMLCanvasElement;
+    /** What the last frame did. */
+    get lastFrame(): FrameReport | undefined;
+    /** How text input arrives in this browser: through `EditContext` or a hidden textarea. */
+    get inputMode(): "editcontext" | "textarea";
+    /** Focus the editor without scrolling. */
+    focus(): void;
+    /** Whether the editor has focus. */
+    get focused(): boolean;
+    /** Whether people can change the document; see {@link EditorOptions.editable}. */
+    get editable(): boolean;
+    /**
+     * Let people change the document, or make it read-only. A read-only
+     * editor shows no caret, and subscribers hear of the change.
+     */
+    setEditable(editable: boolean): void;
+    /** Show `text` while the document is empty; an empty string shows none. */
+    setPlaceholder(text: string): void;
+    /** Whether the document is a single empty text block, as a new one is. */
+    get isEmpty(): boolean;
+    /**
+     * The text of the text block holding the selection's head, or `null`
+     * when the head is not in a text block. A floating menu shows on an
+     * empty one.
+     */
+    blockText(): string | null;
+    /**
+     * Input-to-paint times over the most recent input events: from each
+     * keystroke, composition, paste, drop, or pointer event's timestamp
+     * until the editor painted the change.
+     */
+    inputLatency(): InputLatency;
+    /**
+     * Resolve once fonts the document uses have loaded (or failed), plugins
+     * have finished their setup work, and the result is painted.
+     */
+    ready(): Promise<void>;
+    /**
+     * Call `listener` after every change to the document, the selection,
+     * focus, or {@link Editor.editable}, from input, commands, or the API.
+     * Returns a function that unsubscribes. Its shape suits React's
+     * `useSyncExternalStore`.
+     */
+    subscribe(listener: () => void): () => void;
+    /** Whether server-rendered HTML still stands in for the canvas. */
+    get hydrating(): boolean;
+    /** Run the command named `name`, for callers that pick commands at runtime. */
+    run<N extends CommandName<Registered<E>>>(name: N, ...args: CommandParams<Registered<E>, N>): boolean;
+    /** Answer the query named `name`, for callers that pick queries at runtime. */
+    ask<N extends QueryName<Registered<E>>>(name: N, ...args: QueryParams<Registered<E>, N>): QueryResult<Registered<E>, N>;
+    /** Replace the document. */
+    setContent(content: Content<E>): void;
+    /** The document as `format`. */
+    export(format: Format): string;
+    /** The document as ProseMirror JSON. */
+    toJson(): DocJson<Registered<E>>;
+    /** Server-rendered HTML for the document at the editor's width, and its stylesheet. */
+    toHtml(): {
+        readonly html: string;
+        readonly css: string;
+    };
+    /** The whole document as SVG, painted from the same display list as the canvas. */
+    toSvg(): string;
+    /**
+     * Where layout put every block, line, caret stop, and text run, in
+     * document coordinates: what the parity tests compare with the DOM.
+     */
+    geometry(): Geometry;
+    /** The text selection, or `null` for a block selection. */
+    get selection(): Range | null;
+    /** Select from `anchor` to `head`, or place a caret at `anchor`. Offsets count UTF-16 code units. */
+    select(anchor: Position, head?: Position): void;
+    /** Replace the selection with `text`, as typing does (input rules apply). */
+    insertText(text: string): boolean;
+    /** Undo the last change. */
+    undo(): boolean;
+    /** Redo the last undone change. */
+    redo(): boolean;
+    /**
+     * Show the caret and blink it, as when the editor has focus. Subscribers
+     * hear of the change.
+     */
+    setFocused(focused: boolean): void;
+    /** The caret's rectangle in document coordinates, or `null` when the selection is a range. */
+    caretRect(): DOMRect | null;
+    /**
+     * The rectangle of a caret at `position` in document coordinates, or
+     * `null` when the document has no such position or it is scrolled too far
+     * away to be laid out. Collaborators' carets are drawn with it: positions
+     * from another peer may not exist here yet.
+     */
+    caretRectAt(position: Position): DOMRect | null;
+    /**
+     * The smallest rectangle around the selection in document coordinates:
+     * the caret's for a caret, or `null` while the selection is scrolled too
+     * far away to be laid out. Pass it to {@link Editor.toClientRect} to
+     * anchor a menu, or use `@canvist/web/menus`.
+     */
+    selectionRect(): DOMRect | null;
+    /** `rect`, in document coordinates, in the viewport's coordinates, as `getBoundingClientRect` reports them. */
+    toClientRect(rect: DOMRectReadOnly): DOMRect;
+    /** Measurement cache statistics. */
+    stats(): EditorStats;
+    /** The CSS `font` of every font the layout has used. */
+    fonts(): string[];
+    /**
+     * The document changed outside this editor's own calls, as a
+     * collaborator's change does: repaint, and tell subscribers.
+     *
+     * @internal Called by `@canvist/web/collab`.
+     */
+    documentChanged(): void;
+    /** Lay out and paint now instead of on the next animation frame. */
+    render(): FrameReport | undefined;
+    /** Remove the editor's elements and listeners and release its memory. */
+    destroy(): void;
+    [Symbol.dispose](): void;
+}
+/**
+ * The grid this browser snaps DOM text baselines and backgrounds to.
+ *
+ * Firefox and WebKit snap to device pixels. Chromium does too when it lays
+ * out in device units, as it does on real high-density screens; when it
+ * lays out in CSS units (as under device emulation), it snaps to whole CSS
+ * pixels and scales. Layout in device units can represent a box 1/64 of a
+ * device pixel wide, which CSS-unit layout rounds to zero.
+ */
+export declare function pixelGrid(document: Document, userAgent: string): "device" | "css";
+/**
+ * How many units per CSS pixel this browser snaps border widths down to: the
+ * device pixel ratio, 1 when it lays out in CSS pixels, or `null` when it
+ * keeps exact widths. A 1.7 px border tells them apart.
+ */
+export declare function borderScale(document: Document): number | null;
+/**
+ * The line-breaking tailoring of the browser running this code. CSS leaves
+ * the details to each engine and there is no feature test for them, so this
+ * reads the user agent.
+ */
+export declare function detectBreaks(userAgent: string): LineBreaks;