@canvist/headless 0.0.0 → 0.2.0

package/readme.md

@@ -0,0 +1,96 @@
+<p align="center">
+  <a href="https://github.com/canvist/canvist">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/canvist/canvist/main/assets/brand/vector/lockup-dark.svg">
+      <img width="220" src="https://raw.githubusercontent.com/canvist/canvist/main/assets/brand/vector/lockup.svg" alt="canvist" />
+    </picture>
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/canvist/canvist/blob/main/docs/src/quick-start/server-typescript.md"><strong>Quick start</strong></a> ·
+  <a href="https://github.com/canvist/canvist/blob/main/docs/src/readme.md"><strong>Docs</strong></a> ·
+  <a href="https://github.com/canvist/canvist/blob/main/docs/src/reference/contributing.md"><strong>Contributing</strong></a> ·
+  <a href="https://github.com/canvist/canvist"><strong>canvist</strong></a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@canvist/headless"><img src="https://img.shields.io/npm/v/%40canvist%2Fheadless?color=3B2CF5" alt="npm version" /></a>
+  <a href="https://github.com/canvist/canvist/actions/workflows/headless-js.yml"><img src="https://github.com/canvist/canvist/actions/workflows/headless-js.yml/badge.svg?branch=main" alt="headless-js status" /></a>
+  <a href="https://unlicense.org"><img src="https://img.shields.io/badge/license-Unlicense-3B2CF5" alt="Unlicense" /></a>
+</p>
+
+# @canvist/headless
+
+canvist's document model and editing engine for JavaScript with no DOM: Node, Deno, Bun, and Workers. Convert between ProseMirror/TipTap JSON, HTML, Markdown, and text, run typed editing commands, and serve Yjs collaboration from the same Rust core the editor uses, compiled to WebAssembly.
+
+```sh
+npm install @canvist/headless
+```
+
+```ts
+import { createEngine } from "@canvist/headless";
+
+const engine = await createEngine(); // TipTap's StarterKit
+const doc = engine.parse("markdown", "Hello world");
+
+doc.select({ path: [0], offset: 6 }, { path: [0], offset: 11 });
+doc.commands.toggleBold();
+doc.export("html"); // "<p>Hello <strong>world</strong></p>"
+```
+
+## Types follow your extensions
+
+A document only offers the commands, queries, blocks, and marks of the extensions you registered:
+
+```ts
+import { bold, createEngine, heading } from "@canvist/headless";
+
+const engine = await createEngine([bold, heading]);
+const doc = engine.create();
+
+doc.commands.setHeading({ level: 2 }); // levels are 1 | 2 | 3 | 4 | 5 | 6
+doc.commands.toggleItalic(); // type error: italic is not registered
+doc.commands.setHeading({ level: 7 }); // type error
+```
+
+## Every other extension
+
+`@canvist/headless` compiles in TipTap's StarterKit. Every other extension canvist ships, from highlights and text styles to mentions, emoji, and media, is in `@canvist/headless/full`: a larger WebAssembly module with the same API.
+
+```ts
+import { createEngine, highlight, starterKit } from "@canvist/headless/full";
+
+const engine = await createEngine([...starterKit, highlight]);
+const doc = engine.parse("markdown", "Hello world");
+doc.selectAll();
+doc.commands.toggleHighlight();
+doc.export("html"); // "<p><mark>Hello world</mark></p>"
+```
+
+## What else it does
+
+- **Positions:** `{ path, offset }`, where `path` walks the block tree and `offset` counts UTF-16 code units, like JavaScript strings. Errors are `CanvistError`s with the same stable `code`s as the Rust and Dart packages.
+- **Collaboration:** a document can be a Yjs peer and a y-websocket-compatible server endpoint (`share`, `syncStart`, `receiveSync`). [`examples/server`](./examples/server) serves `POST /convert` and a `/sync/:room` WebSocket in a few lines.
+- **Server-side rendering:** `@canvist/headless/ssr` renders a document as HTML and CSS laid out exactly as `@canvist/web` paints it, so the live editor hydrates from it without moving a pixel, and as SVG for previews. It's a separate WebAssembly module too. See [Server-side rendering](../../docs/src/quick-start/ssr.md).
+- **Canvas scenes:** `@canvist/headless/scene` loads canvist canvas scenes and exports SVG and PNG, for thumbnails, social cards, and designs an agent writes. It's a separate WebAssembly module, so the document entry point stays small.
+- **Workers:** runtimes without a file system pass the module they imported: `createEngine(undefined, { wasm })`.
+
+A typed command costs about 0.7 µs in Node and a collaborator's keystroke about 4.6 µs, at 10,000 paragraphs. `node bench/overhead.ts` reproduces the numbers.
+
+<details>
+<summary><strong>Development</strong></summary>
+
+```sh
+npm ci
+npm run build:wasm      # the StarterKit module into wasm/, the full one into wasm-full/, the scene module into wasm-scene/, and the rendering module into wasm-ssr/
+npm test                # conformance and API tests in Node
+deno task test          # the same, plus the server example, in Deno
+npm run check:types     # tsc --noEmit, including the type-level tests
+npm run generate        # regenerate the extension descriptors
+npm run build           # JavaScript and declarations for npm, into dist/
+```
+
+The tests run the shared fixtures in [`conformance/`](../../conformance), which the Rust and Dart packages run too.
+
+</details>

package/wasm/canvist_headless_wasm.d.ts

@@ -0,0 +1,216 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * One document and its editor.
+ */
+export class WasmDoc {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Apply a v1 Yjs update; returns whether the document changed.
+     */
+    applyUpdate(update: Uint8Array): boolean;
+    /**
+     * Whether the named command would apply.
+     */
+    can(name: string, args: string): boolean;
+    /**
+     * Delete the selection.
+     */
+    deleteSelection(): boolean;
+    /**
+     * What a peer at `state_vector` is missing, as one v1 update.
+     */
+    encodeDiff(state_vector: Uint8Array): Uint8Array;
+    /**
+     * The whole shared state as one v1 update.
+     */
+    encodeState(): Uint8Array;
+    /**
+     * The document as `format`.
+     */
+    export(format_name: string): string;
+    /**
+     * This peer's changes since the last call, as y-sync update messages.
+     */
+    flushSync(): Uint8Array[];
+    /**
+     * Replace the selection with `text`, without input rules.
+     */
+    insertText(text: string): boolean;
+    /**
+     * Paste `content` read as `format` over the selection.
+     */
+    paste(format_name: string, content: string): boolean;
+    /**
+     * Press a key binding such as `Enter` or `Mod-b`.
+     */
+    press(key: string): boolean;
+    /**
+     * Answer the named query, as JSON.
+     */
+    query(name: string, args: string): string;
+    /**
+     * Handle a y-sync message: returns `[reply, broadcast, changed]`, the
+     * messages for the sender, the messages for everyone else, and whether
+     * the document changed.
+     */
+    receiveSync(message: Uint8Array): [Uint8Array[], Uint8Array[], boolean];
+    /**
+     * Redo the last undone call.
+     */
+    redo(): boolean;
+    /**
+     * Run the named command with JSON arguments.
+     */
+    run(name: string, args: string): boolean;
+    /**
+     * Select the whole document.
+     */
+    selectAll(): void;
+    /**
+     * Select from the anchor to the head; offsets count UTF-16 code units.
+     */
+    select(anchor_path: Uint32Array, anchor_offset: number, head_path: Uint32Array, head_offset: number): void;
+    /**
+     * The anchor and head as JSON positions, or `null` for a block
+     * selection.
+     */
+    selection(): string;
+    /**
+     * Start sharing the document as yrs client `client_id`.
+     */
+    share(client_id: number): void;
+    /**
+     * The content and selection as snapshot JSON.
+     */
+    snapshot(): string;
+    /**
+     * The v1 state vector.
+     */
+    stateVector(): Uint8Array;
+    /**
+     * The y-sync message to greet a connecting client with.
+     */
+    syncStart(): Uint8Array;
+    /**
+     * Drain this peer's own v1 updates.
+     */
+    takeUpdates(): Uint8Array[];
+    /**
+     * Type `text` one character at a time, running input rules.
+     */
+    typeText(text: string): boolean;
+    /**
+     * Undo the last call that changed the document.
+     */
+    undo(): boolean;
+    /**
+     * `{ rejectedBlocks, waiting }` as JSON.
+     */
+    validate(): string;
+}
+
+/**
+ * A configured set of extensions that creates documents.
+ */
+export class WasmEngine {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * A document with one empty paragraph.
+     */
+    create(): WasmDoc;
+    /**
+     * Join a shared document from v1 Yjs state as yrs client `client_id`.
+     */
+    fromYjs(state: Uint8Array, client_id: number): WasmDoc;
+    /**
+     * The registered extensions' metadata as JSON.
+     */
+    metadata(): string;
+    /**
+     * An engine with the named extensions, allocating block ids as
+     * `client`.
+     */
+    constructor(extensions: string[], client: number);
+    /**
+     * Read `input` as `format` (`json`, `html`, `markdown`, or `text`).
+     */
+    parse(format_name: string, input: string): WasmDoc;
+    /**
+     * Recreate a document from a snapshot's JSON text.
+     */
+    restore(snapshot: string): WasmDoc;
+}
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly __wbg_wasmdoc_free: (a: number, b: number) => void;
+    readonly __wbg_wasmengine_free: (a: number, b: number) => void;
+    readonly wasmdoc_applyUpdate: (a: number, b: number, c: number) => [number, number, number];
+    readonly wasmdoc_can: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
+    readonly wasmdoc_deleteSelection: (a: number) => [number, number, number];
+    readonly wasmdoc_encodeDiff: (a: number, b: number, c: number) => [number, number, number, number];
+    readonly wasmdoc_encodeState: (a: number) => [number, number, number, number];
+    readonly wasmdoc_export: (a: number, b: number, c: number) => [number, number, number, number];
+    readonly wasmdoc_flushSync: (a: number) => [number, number, number];
+    readonly wasmdoc_insertText: (a: number, b: number, c: number) => [number, number, number];
+    readonly wasmdoc_paste: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
+    readonly wasmdoc_press: (a: number, b: number, c: number) => [number, number, number];
+    readonly wasmdoc_query: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
+    readonly wasmdoc_receiveSync: (a: number, b: number, c: number) => [number, number, number];
+    readonly wasmdoc_redo: (a: number) => [number, number, number];
+    readonly wasmdoc_run: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
+    readonly wasmdoc_select: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => [number, number];
+    readonly wasmdoc_selectAll: (a: number) => [number, number];
+    readonly wasmdoc_selection: (a: number) => [number, number];
+    readonly wasmdoc_share: (a: number, b: number) => [number, number];
+    readonly wasmdoc_snapshot: (a: number) => [number, number];
+    readonly wasmdoc_stateVector: (a: number) => [number, number, number, number];
+    readonly wasmdoc_syncStart: (a: number) => [number, number, number, number];
+    readonly wasmdoc_takeUpdates: (a: number) => [number, number, number];
+    readonly wasmdoc_typeText: (a: number, b: number, c: number) => [number, number, number];
+    readonly wasmdoc_undo: (a: number) => [number, number, number];
+    readonly wasmdoc_validate: (a: number) => [number, number, number, number];
+    readonly wasmengine_create: (a: number) => [number, number, number];
+    readonly wasmengine_fromYjs: (a: number, b: number, c: number, d: number) => [number, number, number];
+    readonly wasmengine_metadata: (a: number) => [number, number];
+    readonly wasmengine_new: (a: number, b: number, c: number) => [number, number, number];
+    readonly wasmengine_parse: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
+    readonly wasmengine_restore: (a: number, b: number, c: number) => [number, number, number];
+    readonly __wbindgen_malloc: (a: number, b: number) => number;
+    readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+    readonly __wbindgen_exn_store: (a: number) => void;
+    readonly __externref_table_alloc: () => number;
+    readonly __wbindgen_externrefs: WebAssembly.Table;
+    readonly __externref_table_dealloc: (a: number) => void;
+    readonly __wbindgen_free: (a: number, b: number, c: number) => void;
+    readonly __wbindgen_start: () => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;