@canvist/headless 0.0.0-stage → 0.2.0

package/dist/calls.d.ts

@@ -0,0 +1,15 @@
+/**
+ * How typed commands and queries reach an engine: one method per
+ * registered name, with arguments sent as JSON. The WebAssembly documents
+ * and the native editors share it.
+ *
+ * @module
+ */
+/**
+ * An object with one method per name, each calling `invoke`. The names come
+ * from the same metadata as the type `Methods`, which is what makes the
+ * object that type.
+ */
+export declare function calls<Methods>(names: readonly string[], invoke: (name: string, args: unknown) => unknown): Methods;
+/** A command's or query's arguments as the engine reads them: JSON, or `null` for none. */
+export declare function encode(args: unknown): string;

package/dist/calls.js

@@ -0,0 +1,20 @@
+/**
+ * How typed commands and queries reach an engine: one method per
+ * registered name, with arguments sent as JSON. The WebAssembly documents
+ * and the native editors share it.
+ *
+ * @module
+ */
+/**
+ * An object with one method per name, each calling `invoke`. The names come
+ * from the same metadata as the type `Methods`, which is what makes the
+ * object that type.
+ */
+export function calls(names, invoke) {
+    const methods = Object.fromEntries(names.map((name) => [name, (args) => invoke(name, args)]));
+    return methods;
+}
+/** A command's or query's arguments as the engine reads them: JSON, or `null` for none. */
+export function encode(args) {
+    return args === undefined ? "null" : JSON.stringify(args);
+}

package/dist/create.d.ts

@@ -0,0 +1,17 @@
+import { Engine, type EngineOptions } from "./engine.ts";
+import type { StarterKit } from "./types.ts";
+/**
+ * Load canvist and create an engine with the given StarterKit extensions,
+ * all of them by default. The engine's documents only offer the registered
+ * extensions' commands, queries, blocks, and marks, so using another one
+ * is a type error. Every other extension is in `@canvist/headless/full`.
+ *
+ * ```ts
+ * const engine = await createEngine([bold, heading]);
+ * const doc = engine.parse("markdown", "Hello");
+ * doc.selectAll();
+ * doc.commands.toggleBold();
+ * doc.commands.toggleItalic(); // type error: italic is not registered
+ * ```
+ */
+export declare function createEngine<const E extends readonly StarterKit[number][] = StarterKit>(extensions?: E, options?: EngineOptions): Promise<Engine<E>>;

package/dist/create.js

@@ -0,0 +1,29 @@
+/**
+ * Creating engines from the StarterKit WebAssembly module.
+ *
+ * @module
+ */
+import { WasmEngine } from "../wasm/canvist_headless_wasm.js";
+import { Engine } from "./engine.js";
+import { starterKit } from "./extensions.generated.js";
+import { load } from "./load.js";
+/**
+ * Load canvist and create an engine with the given StarterKit extensions,
+ * all of them by default. The engine's documents only offer the registered
+ * extensions' commands, queries, blocks, and marks, so using another one
+ * is a type error. Every other extension is in `@canvist/headless/full`.
+ *
+ * ```ts
+ * const engine = await createEngine([bold, heading]);
+ * const doc = engine.parse("markdown", "Hello");
+ * doc.selectAll();
+ * doc.commands.toggleBold();
+ * doc.commands.toggleItalic(); // type error: italic is not registered
+ * ```
+ */
+export async function createEngine(extensions, options = {}) {
+    await load(options.wasm);
+    const registered = (extensions ?? starterKit);
+    const names = registered.map((extension) => extension.name);
+    return new Engine(new WasmEngine(names, options.client ?? 1), registered);
+}

package/dist/engine.d.ts

@@ -0,0 +1,125 @@
+/**
+ * The typed engine and document, over either WebAssembly module: the
+ * StarterKit one `@canvist/headless` loads, or the one with every extension
+ * `@canvist/headless/full` loads. Both export the same classes.
+ *
+ * @module
+ */
+import type { WasmDoc, WasmEngine } from "../wasm/canvist_headless_wasm.js";
+export { type CanvistError, isCanvistError } from "./errors.ts";
+import type { WasmSource } from "./load.ts";
+import type { CommandName, CommandParams, Commands, DocJson, ExtensionDescriptor, Extensions, Format, Position, Queries, QueryName, QueryParams, QueryResult, Range, Registered } from "./types.ts";
+/** Options for `createEngine`. */
+export interface EngineOptions {
+    /** The client block ids are allocated under; collaborating peers need distinct ones. Default 1. */
+    readonly client?: number;
+    /** Where to load the WebAssembly module from, for runtimes without a file system. */
+    readonly wasm?: WasmSource;
+}
+/** What {@link Doc.receiveSync} says to send. */
+export interface SyncReply {
+    /** Messages for the connection the message came from. */
+    readonly reply: readonly Uint8Array[];
+    /** Messages for every other connection to the document. */
+    readonly broadcast: readonly Uint8Array[];
+    /** Whether the document changed. */
+    readonly changed: boolean;
+}
+/** How well a shared document's state fits the schema. */
+export interface Validation {
+    /** Shared items the schema rejects; they are hidden from the document but kept. */
+    readonly rejectedBlocks: number;
+    /** Whether updates wait for earlier updates that have not arrived. */
+    readonly waiting: boolean;
+}
+/** A set of extensions that creates documents. Create one with `createEngine`. */
+export declare class Engine<E extends Extensions> {
+    #private;
+    /** @internal Use `createEngine`, which loads the WebAssembly module first. */
+    constructor(wasm: WasmEngine, extensions: E);
+    /** The registered extensions, including the ones every engine has. */
+    get extensions(): Registered<E>;
+    /**
+     * The registered extensions' metadata as Rust reports it: their
+     * descriptors, with every command, query, and field's `doc`.
+     */
+    metadata(): ExtensionDescriptor[];
+    /** A document with one empty paragraph. */
+    create(): Doc<E>;
+    /** Read `input` as `format`. */
+    parse(format: Format, input: string): Doc<E>;
+    /** Read a ProseMirror or TipTap document that uses only the registered extensions. */
+    fromJson(json: DocJson<Registered<E>>): Doc<E>;
+    /** Join a shared document from v1 Yjs state as yrs client `clientId`. */
+    fromYjs(state: Uint8Array, clientId: number): Doc<E>;
+    /** Recreate a document from {@link Doc.snapshot} text. */
+    restore(snapshot: string): Doc<E>;
+    /** Release the engine's memory now rather than when it is collected. */
+    [Symbol.dispose](): void;
+}
+/** One document and the editor that changes it. Every call is one undo step. */
+export declare class Doc<E extends Extensions> {
+    #private;
+    /** Run a registered command against the selection; 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>>;
+    /** @internal Documents come from an {@link Engine}. */
+    constructor(wasm: WasmDoc, extensions: Extensions);
+    /** 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;
+    /** Whether the command named `name` would apply. Nothing changes. */
+    canRun<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>;
+    /** The document as `format`. */
+    export(format: Format): string;
+    /** The document as ProseMirror JSON, with block ids in `attrs.id`. */
+    toJson(): DocJson<Registered<E>>;
+    /** 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;
+    /** Select the whole document. */
+    selectAll(): void;
+    /** Replace the selection with `text`, without input rules. */
+    insertText(text: string): boolean;
+    /** Type `text` one character at a time, so input rules such as `## ` apply. */
+    typeText(text: string): boolean;
+    /** Delete the selection. */
+    deleteSelection(): boolean;
+    /** Press a key binding such as `Enter`, `Tab`, or `Mod-b` (`Mod` is Ctrl). */
+    press(key: string): boolean;
+    /** Paste `content` read as `format` over the selection. */
+    paste(format: Format, content: string): boolean;
+    /** Undo the last call that changed the document. */
+    undo(): boolean;
+    /** Redo the last undone call. */
+    redo(): boolean;
+    /** The content and selection as snapshot JSON text, for {@link Engine.restore}. */
+    snapshot(): string;
+    /** Start sharing the document as yrs client `clientId`. */
+    share(clientId: number): void;
+    /** Apply a v1 Yjs update from another peer; returns whether the document changed. */
+    applyUpdate(update: Uint8Array): boolean;
+    /** The whole shared state as one v1 update. */
+    encodeState(): Uint8Array;
+    /** The v1 state vector. */
+    stateVector(): Uint8Array;
+    /** Everything a peer at `stateVector` is missing, as one v1 update. */
+    encodeDiff(stateVector: Uint8Array): Uint8Array;
+    /** Drain this peer's own v1 updates for broadcasting. */
+    takeUpdates(): Uint8Array[];
+    /** Check the shared state against the schema. */
+    validate(): Validation;
+    /** The y-sync message to greet a connecting client with. */
+    syncStart(): Uint8Array;
+    /** Handle one y-sync message from a client connection. */
+    receiveSync(message: Uint8Array): SyncReply;
+    /** This peer's changes since the last call, as y-sync messages for every connection. */
+    flushSync(): Uint8Array[];
+    /** Release the document's memory now rather than when it is collected. */
+    [Symbol.dispose](): void;
+}

package/dist/engine.js

@@ -0,0 +1,176 @@
+import { calls, encode } from "./calls.js";
+export { isCanvistError } from "./errors.js";
+import { core } from "./extensions.generated.js";
+/** A set of extensions that creates documents. Create one with `createEngine`. */
+export class Engine {
+    #wasm;
+    #extensions;
+    /** @internal Use `createEngine`, which loads the WebAssembly module first. */
+    constructor(wasm, extensions) {
+        this.#extensions = [...core, ...extensions];
+        this.#wasm = wasm;
+    }
+    /** The registered extensions, including the ones every engine has. */
+    get extensions() {
+        return this.#extensions;
+    }
+    /**
+     * The registered extensions' metadata as Rust reports it: their
+     * descriptors, with every command, query, and field's `doc`.
+     */
+    metadata() {
+        return JSON.parse(this.#wasm.metadata());
+    }
+    /** A document with one empty paragraph. */
+    create() {
+        return new Doc(this.#wasm.create(), this.#extensions);
+    }
+    /** Read `input` as `format`. */
+    parse(format, input) {
+        return new Doc(this.#wasm.parse(format, input), this.#extensions);
+    }
+    /** Read a ProseMirror or TipTap document that uses only the registered extensions. */
+    fromJson(json) {
+        return this.parse("json", JSON.stringify(json));
+    }
+    /** Join a shared document from v1 Yjs state as yrs client `clientId`. */
+    fromYjs(state, clientId) {
+        return new Doc(this.#wasm.fromYjs(state, clientId), this.#extensions);
+    }
+    /** Recreate a document from {@link Doc.snapshot} text. */
+    restore(snapshot) {
+        return new Doc(this.#wasm.restore(snapshot), this.#extensions);
+    }
+    /** Release the engine's memory now rather than when it is collected. */
+    [Symbol.dispose]() {
+        this.#wasm.free();
+    }
+}
+/** One document and the editor that changes it. Every call is one undo step. */
+export class Doc {
+    #wasm;
+    /** Run a registered command against the selection; returns whether it applied. */
+    commands;
+    /** Whether a registered command would apply. Nothing changes. */
+    can;
+    /** Answer a registered query. */
+    query;
+    /** @internal Documents come from an {@link Engine}. */
+    constructor(wasm, extensions) {
+        this.#wasm = wasm;
+        const commands = extensions.flatMap((extension) => extension.commands.map((command) => command.name));
+        const queries = extensions.flatMap((extension) => extension.queries.map((query) => query.name));
+        this.commands = calls(commands, (name, args) => this.#wasm.run(name, encode(args)));
+        this.can = calls(commands, (name, args) => this.#wasm.can(name, encode(args)));
+        this.query = calls(queries, (name, args) => JSON.parse(this.#wasm.query(name, encode(args))));
+    }
+    /** Run the command named `name`, for callers that pick commands at runtime. */
+    run(name, ...args) {
+        return this.#wasm.run(name, encode(args[0]));
+    }
+    /** Whether the command named `name` would apply. Nothing changes. */
+    canRun(name, ...args) {
+        return this.#wasm.can(name, encode(args[0]));
+    }
+    /** Answer the query named `name`, for callers that pick queries at runtime. */
+    ask(name, ...args) {
+        return JSON.parse(this.#wasm.query(name, encode(args[0])));
+    }
+    /** The document as `format`. */
+    export(format) {
+        return this.#wasm.export(format);
+    }
+    /** The document as ProseMirror JSON, with block ids in `attrs.id`. */
+    toJson() {
+        return JSON.parse(this.#wasm.export("json"));
+    }
+    /** The text selection, or `null` for a block selection. */
+    get selection() {
+        return JSON.parse(this.#wasm.selection());
+    }
+    /** Select from `anchor` to `head`, or place a caret at `anchor`. Offsets count UTF-16 code units. */
+    select(anchor, head = anchor) {
+        this.#wasm.select(Uint32Array.from(anchor.path), anchor.offset, Uint32Array.from(head.path), head.offset);
+    }
+    /** Select the whole document. */
+    selectAll() {
+        this.#wasm.selectAll();
+    }
+    /** Replace the selection with `text`, without input rules. */
+    insertText(text) {
+        return this.#wasm.insertText(text);
+    }
+    /** Type `text` one character at a time, so input rules such as `## ` apply. */
+    typeText(text) {
+        return this.#wasm.typeText(text);
+    }
+    /** Delete the selection. */
+    deleteSelection() {
+        return this.#wasm.deleteSelection();
+    }
+    /** Press a key binding such as `Enter`, `Tab`, or `Mod-b` (`Mod` is Ctrl). */
+    press(key) {
+        return this.#wasm.press(key);
+    }
+    /** Paste `content` read as `format` over the selection. */
+    paste(format, content) {
+        return this.#wasm.paste(format, content);
+    }
+    /** Undo the last call that changed the document. */
+    undo() {
+        return this.#wasm.undo();
+    }
+    /** Redo the last undone call. */
+    redo() {
+        return this.#wasm.redo();
+    }
+    /** The content and selection as snapshot JSON text, for {@link Engine.restore}. */
+    snapshot() {
+        return this.#wasm.snapshot();
+    }
+    /** Start sharing the document as yrs client `clientId`. */
+    share(clientId) {
+        this.#wasm.share(clientId);
+    }
+    /** Apply a v1 Yjs update from another peer; returns whether the document changed. */
+    applyUpdate(update) {
+        return this.#wasm.applyUpdate(update);
+    }
+    /** The whole shared state as one v1 update. */
+    encodeState() {
+        return this.#wasm.encodeState();
+    }
+    /** The v1 state vector. */
+    stateVector() {
+        return this.#wasm.stateVector();
+    }
+    /** Everything a peer at `stateVector` is missing, as one v1 update. */
+    encodeDiff(stateVector) {
+        return this.#wasm.encodeDiff(stateVector);
+    }
+    /** Drain this peer's own v1 updates for broadcasting. */
+    takeUpdates() {
+        return this.#wasm.takeUpdates();
+    }
+    /** Check the shared state against the schema. */
+    validate() {
+        return JSON.parse(this.#wasm.validate());
+    }
+    /** The y-sync message to greet a connecting client with. */
+    syncStart() {
+        return this.#wasm.syncStart();
+    }
+    /** Handle one y-sync message from a client connection. */
+    receiveSync(message) {
+        const [reply, broadcast, changed] = this.#wasm.receiveSync(message);
+        return { reply, broadcast, changed };
+    }
+    /** This peer's changes since the last call, as y-sync messages for every connection. */
+    flushSync() {
+        return this.#wasm.flushSync();
+    }
+    /** Release the document's memory now rather than when it is collected. */
+    [Symbol.dispose]() {
+        this.#wasm.free();
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The error every canvist call throws, from WebAssembly or a native editor.
+ *
+ * @module
+ */
+import type { ErrorCode } from "./types.ts";
+/** A failure inside canvist, with its stable code. */
+export interface CanvistError extends Error {
+    readonly name: "CanvistError";
+    readonly code: ErrorCode;
+}
+/** Whether `error` came from canvist, narrowing it to read its `code`. */
+export declare function isCanvistError(error: unknown): error is CanvistError;

package/dist/errors.js

@@ -0,0 +1,5 @@
+/** Whether `error` came from canvist, narrowing it to read its `code`. */
+export function isCanvistError(error) {
+    return error instanceof Error && error.name === "CanvistError" &&
+        "code" in error;
+}