@canvist/headless 0.0.0-stage → 0.2.0

package/dist/native.js

@@ -0,0 +1,235 @@
+/**
+ * The typed editor for JavaScript hosts that run canvist natively.
+ *
+ * `@canvist/react-native` and `@canvist/lynx` show the iOS and Android
+ * `CanvistView`s, whose editors live in Rust, and reach each one through a
+ * {@link NativeBridge}: a handful of synchronous calls that pass names and
+ * JSON. {@link NativeEditor} puts the same typed API as `@canvist/web` and
+ * `@canvist/headless` over it, so commands, queries, and documents are
+ * typed from the extensions you register and calling one you did not
+ * register is a type error.
+ *
+ * This module loads no WebAssembly: it is types, metadata, and a little
+ * glue.
+ *
+ * @module
+ */
+import { calls, encode } from "./calls.js";
+import { core } from "./extensions.generated.js";
+export { isCanvistError } from "./errors.js";
+/**
+ * A native editor with commands, queries, and document types that follow
+ * its extensions. Hosts create it once their view is ready and report
+ * changes with {@link NativeEditor.notifyChange} and
+ * {@link NativeEditor.notifyFocus}; subscribers then hear of every edit,
+ * whether it came from the keyboard or from JavaScript. Edits made from
+ * JavaScript notify subscribers once the calls in the current task are
+ * done, and again when the view reports them.
+ */
+export class NativeEditor {
+    /** 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;
+    #bridge;
+    #extensions;
+    #subscribers = new Set();
+    #focused = false;
+    /** Whether subscribers will hear of edits made from JavaScript. */
+    #pending = false;
+    /** An editor over `bridge`, whose view registered `extensions`. */
+    constructor(bridge, extensions) {
+        this.#bridge = bridge;
+        this.#extensions = [...core, ...extensions];
+        const commands = this.#extensions.flatMap((extension) => extension.commands.map((command) => command.name));
+        const queries = this.#extensions.flatMap((extension) => extension.queries.map((query) => query.name));
+        this.commands = calls(commands, (name, args) => this.#edit(() => bridge.run(name, encode(args))));
+        this.can = calls(commands, (name, args) => this.#call(() => bridge.can(name, encode(args))));
+        this.query = calls(queries, (name, args) => JSON.parse(this.#call(() => bridge.query(name, encode(args)))));
+    }
+    /** The registered extensions, including the ones every editor has. */
+    get extensions() {
+        return this.#extensions;
+    }
+    /** Run the command named `name`, for callers that pick commands at runtime. */
+    run(name, ...args) {
+        return this.#edit(() => this.#bridge.run(name, encode(args[0])));
+    }
+    /** Whether the command named `name` would apply. Nothing changes. */
+    canRun(name, ...args) {
+        return this.#call(() => this.#bridge.can(name, encode(args[0])));
+    }
+    /** Answer the query named `name`, for callers that pick queries at runtime. */
+    ask(name, ...args) {
+        return JSON.parse(this.#call(() => this.#bridge.query(name, encode(args[0]))));
+    }
+    /** Replace the document. */
+    setContent(content) {
+        const [format, input] = "format" in content
+            ? [content.format, content.input]
+            : ["json", JSON.stringify(content)];
+        this.#edit(() => this.#bridge.load(format, input));
+    }
+    /** The document as `format`. */
+    export(format) {
+        return this.#call(() => this.#bridge.export(format));
+    }
+    /** The document as ProseMirror JSON, with block ids in `attrs.id`. */
+    toJson() {
+        return JSON.parse(this.#call(() => this.#bridge.export("json")));
+    }
+    /** The text selection, or `null` for a block selection. */
+    get selection() {
+        return JSON.parse(this.#call(() => this.#bridge.selection()));
+    }
+    /** Select from `anchor` to `head`, or place a caret at `anchor`. Offsets count UTF-16 code units. */
+    select(anchor, head = anchor) {
+        const range = { anchor, head };
+        this.#edit(() => this.#bridge.select(JSON.stringify(range)));
+    }
+    /** Select the whole document. */
+    selectAll() {
+        this.#edit(() => this.#bridge.selectAll());
+    }
+    /** Replace the selection with `text`, as typing does (input rules apply). */
+    insertText(text) {
+        return this.#edit(() => this.#bridge.insertText(text));
+    }
+    /** Undo the last change. */
+    undo() {
+        return this.#edit(() => this.#bridge.undo());
+    }
+    /** Redo the last undone change. */
+    redo() {
+        return this.#edit(() => this.#bridge.redo());
+    }
+    /** Whether {@link NativeEditor.undo} has anything to undo. */
+    canUndo() {
+        return this.#call(() => this.#bridge.canUndo());
+    }
+    /** Whether {@link NativeEditor.redo} has anything to redo. */
+    canRedo() {
+        return this.#call(() => this.#bridge.canRedo());
+    }
+    /** Focus the editor and show the keyboard. */
+    focus() {
+        this.#call(() => this.#bridge.focus());
+    }
+    /** Take focus away from the editor and hide the keyboard. */
+    blur() {
+        this.#call(() => this.#bridge.blur());
+    }
+    /** Whether the editor has focus, as the view last reported. */
+    get focused() {
+        return this.#focused;
+    }
+    /**
+     * Call `listener` after every change to the document, the selection, or
+     * focus. Returns a function that stops it.
+     */
+    subscribe(listener) {
+        this.#subscribers.add(listener);
+        return () => {
+            this.#subscribers.delete(listener);
+        };
+    }
+    /** For hosts: the view reported that the document or selection changed. */
+    notifyChange() {
+        this.#notify();
+    }
+    /** For hosts: the view gained or lost focus. */
+    notifyFocus(focused) {
+        if (focused === this.#focused) {
+            return;
+        }
+        this.#focused = focused;
+        this.#notify();
+    }
+    /**
+     * Make `call`, which may change the document or selection, and tell
+     * subscribers once the current task's calls are done: a handler that
+     * selects and then formats re-renders once. The view reports the change
+     * too, a moment later, but a command that only changes what typing will
+     * insert (a toggled mark at the caret) has nothing else to report.
+     */
+    #edit(call) {
+        const result = this.#call(call);
+        if (!this.#pending) {
+            this.#pending = true;
+            // A microtask; Lynx's JavaScript engine has no `queueMicrotask`.
+            void Promise.resolve().then(() => {
+                this.#pending = false;
+                this.#notify();
+            });
+        }
+        return result;
+    }
+    /** Make `call` on the bridge, rethrowing its failures as `CanvistError`s. */
+    #call(call) {
+        try {
+            return call();
+        }
+        catch (error) {
+            throw nativeError(error);
+        }
+    }
+    #notify() {
+        for (const listener of this.#subscribers) {
+            listener();
+        }
+    }
+}
+const NATIVE_ERROR = /\[canvist:(\w+)\] ([\s\S]*)$/;
+/** Every error code, so a code from native text can be checked. */
+const ERROR_CODES = {
+    config: true,
+    parse: true,
+    schema: true,
+    unknownName: true,
+    invalidArgs: true,
+    invalidPosition: true,
+    invalidKey: true,
+    editor: true,
+    snapshot: true,
+    notShared: true,
+    alreadyShared: true,
+    collab: true,
+    render: true,
+};
+function isErrorCode(code) {
+    return Object.hasOwn(ERROR_CODES, code);
+}
+/** A failure on the native side, with the code its message carries. */
+class NativeCanvistError extends Error {
+    name = "CanvistError";
+    code;
+    constructor(code, reason, cause) {
+        super(reason, cause === undefined ? {} : { cause });
+        this.code = code;
+    }
+}
+/**
+ * `error` as a `CanvistError` when its message follows the bridge's
+ * `[canvist:<code>] <reason>` contract, and unchanged otherwise.
+ */
+function nativeError(error) {
+    if (!(error instanceof Error)) {
+        return error;
+    }
+    const [, code = "", reason = ""] = NATIVE_ERROR.exec(error.message) ?? [];
+    return isErrorCode(code)
+        ? new NativeCanvistError(code, reason, error)
+        : error;
+}
+/**
+ * A `CanvistError` for a failure a native view reports outside a call,
+ * such as an editor it could not create. A code canvist does not define
+ * is reported as `editor`, with the code kept in the message.
+ */
+export function nativeCanvistError(code, reason) {
+    return isErrorCode(code)
+        ? new NativeCanvistError(code, reason)
+        : new NativeCanvistError("editor", `${code}: ${reason}`);
+}

package/dist/scene-types.d.ts

@@ -0,0 +1,223 @@
+/**
+ * The scene JSON format: canvist canvas documents of pages, frames, shapes,
+ * images, vector paths, and text frames.
+ *
+ * These types mirror `canvist_scene`'s JSON codec. A scene can be written
+ * nested, with `children` and without ids or keys, which is how people and
+ * agents write one; {@link SceneDoc.toJson} returns the canonical flat form,
+ * where every node names its `parent` and `key`.
+ *
+ * @module
+ */
+import type { DocJson, Registered, StarterKit } from "./types.ts";
+/** A colour as `#rrggbb` or `#rrggbbaa`. */
+export type HexColor = `#${string}`;
+/** A node id, `client.seq` in base 36, such as `"1.a"`. */
+export type NodeId = string;
+/** A 2D point or vector: `[x, y]`. */
+export type Vec2 = readonly [number, number];
+/** An affine transform's coefficients: `[a, b, c, d, e, f]`. */
+export type Affine = readonly [number, number, number, number, number, number];
+/** How a paint or layer blends with what is below it. */
+export type BlendMode = "normal" | "multiply" | "screen" | "overlay" | "darken" | "lighten" | "color-dodge" | "color-burn" | "hard-light" | "soft-light" | "difference" | "exclusion" | "hue" | "saturation" | "color" | "luminosity";
+/** One stop of a gradient. */
+export interface GradientStop {
+    /** Where the stop sits, 0 to 1. */
+    readonly offset: number;
+    readonly color: HexColor;
+}
+/** Fields every paint may have. */
+interface PaintCommon {
+    /** 0 to 1. Defaults to 1. */
+    readonly opacity?: number;
+    /** Defaults to `true`. */
+    readonly visible?: boolean;
+    /** Defaults to `"normal"`. */
+    readonly blend?: BlendMode;
+}
+/** A fill or stroke. Gradient points are in the node's unit box. */
+export type PaintJson = PaintCommon & ({
+    readonly type: "solid";
+    readonly color: HexColor;
+} | {
+    readonly type: "linear";
+    readonly from: Vec2;
+    readonly to: Vec2;
+    readonly stops: readonly GradientStop[];
+} | {
+    readonly type: "radial";
+    readonly center: Vec2;
+    readonly radius: Vec2;
+    readonly stops: readonly GradientStop[];
+} | {
+    readonly type: "sweep";
+    readonly center: Vec2;
+    /** Degrees clockwise from the positive x axis. */
+    readonly angle: number;
+    readonly stops: readonly GradientStop[];
+} | {
+    readonly type: "image";
+    /** The host's id for the image, such as a URL or content hash. */
+    readonly asset: string;
+    /** Defaults to `"fill"`. */
+    readonly fit?: "fill" | "fit" | "stretch" | "tile";
+});
+/** How a node's strokes are drawn. Every field has a default. */
+export interface StrokeJson {
+    readonly width?: number;
+    readonly align?: "inside" | "center" | "outside";
+    readonly cap?: "butt" | "round" | "square";
+    readonly join?: "miter" | "round" | "bevel";
+    readonly miterLimit?: number;
+    /** Alternating dash and gap lengths; empty for a solid line. */
+    readonly dashes?: readonly number[];
+}
+/** A shadow's colour, offset, blur, and spread. */
+interface ShadowJson {
+    readonly color: HexColor;
+    readonly offset?: Vec2;
+    readonly blur?: number;
+    readonly spread?: number;
+}
+/** A shadow or blur on a node. */
+export type EffectJson = {
+    readonly visible?: boolean;
+} & (({
+    readonly type: "drop-shadow";
+} & ShadowJson) | ({
+    readonly type: "inner-shadow";
+} & ShadowJson) | {
+    readonly type: "layer-blur";
+    readonly radius: number;
+} | {
+    readonly type: "background-blur";
+    readonly radius: number;
+});
+/** A node's own geometry. Most node types imply theirs. */
+export type ShapeJson = {
+    readonly type: "none";
+} | {
+    readonly type: "rect";
+} | {
+    readonly type: "ellipse";
+    /** Arc start in degrees. */
+    readonly start?: number;
+    /** Arc sweep in degrees; 360 for a full ellipse. */
+    readonly sweep?: number;
+    /** Inner radius as a fraction of the outer; 0 for a disc. */
+    readonly inner?: number;
+} | {
+    readonly type: "polygon";
+    /** Outer points, at least 3. */
+    readonly points?: number;
+    /** Inner radius as a fraction of the outer; 1 for a plain polygon. */
+    readonly ratio?: number;
+} | {
+    readonly type: "path";
+    /** SVG path data in the node's own coordinates. */
+    readonly d: string;
+    readonly rule?: "nonzero" | "evenodd";
+} | {
+    readonly type: "boolean";
+    readonly op: "union" | "subtract" | "intersect" | "exclude";
+} | {
+    readonly type: "text";
+    readonly sizing?: "fixed" | "auto-height" | "auto-width";
+} | {
+    readonly type: "instance";
+    readonly component: NodeId;
+};
+/** How a node follows its parent frame when the frame is resized. */
+export type Constraint = "start" | "end" | "both" | "center" | "scale";
+/** A frame's auto-layout. */
+export interface AutoLayoutJson {
+    readonly direction?: "row" | "column";
+    readonly gap?: number;
+    /** One number for every side, or `[top, right, bottom, left]`. */
+    readonly padding?: number | readonly [number, number, number, number];
+    readonly align?: Align;
+    readonly crossAlign?: Align;
+    readonly wrap?: boolean;
+}
+/** How auto-layout places children along an axis. */
+export type Align = "start" | "center" | "end" | "space-between" | "stretch";
+/** How a child of an auto-layout frame is sized on each axis. */
+export type Sizing = "fixed" | "fill" | "hug";
+/**
+ * A node's properties. Every one is optional and defaults by node type, so
+ * a node lists only what differs. Custom properties are `c:<name>`, and an
+ * instance's overrides are `o:<node id>:<property>`.
+ */
+export interface PropsJson {
+    readonly name?: string;
+    readonly visible?: boolean;
+    readonly locked?: boolean;
+    /** Position, rotation, and skew; size lives in `size`. */
+    readonly transform?: Affine;
+    readonly size?: Vec2;
+    readonly opacity?: number;
+    readonly blend?: BlendMode;
+    readonly fills?: readonly PaintJson[];
+    readonly strokes?: readonly PaintJson[];
+    readonly stroke?: StrokeJson;
+    readonly effects?: readonly EffectJson[];
+    /** Corner radii: top left, top right, bottom right, bottom left. */
+    readonly radius?: readonly [number, number, number, number];
+    /** Whether a frame clips its children. */
+    readonly clip?: boolean;
+    readonly constraints?: {
+        readonly horizontal?: Constraint;
+        readonly vertical?: Constraint;
+    };
+    /** A frame's auto-layout, or `null` for none. */
+    readonly layout?: AutoLayoutJson | null;
+    readonly layoutChild?: {
+        readonly width?: Sizing;
+        readonly height?: Sizing;
+        readonly absolute?: boolean;
+    };
+    readonly shape?: ShapeJson;
+    readonly [custom: `c:${string}`]: unknown;
+    readonly [override: `o:${string}`]: unknown;
+}
+/** The built-in node types. */
+export type NodeType = "page" | "frame" | "group" | "rectangle" | "ellipse" | "polygon" | "path" | "boolean" | "image" | "text" | "component" | "instance";
+/** A text frame's document: StarterKit ProseMirror JSON. */
+export type TextJson = DocJson<Registered<StarterKit>>;
+/** Fields every node has, in either form. */
+interface NodeCommon {
+    readonly type: NodeType;
+    readonly props?: PropsJson;
+    /** For text frames. */
+    readonly text?: TextJson;
+}
+/** A node in the nested form: ids and keys optional, children inline. */
+export interface NestedNodeJson extends NodeCommon {
+    readonly id?: NodeId;
+    /** A fractional key among its siblings; list order when omitted. */
+    readonly key?: string;
+    readonly children?: readonly NestedNodeJson[];
+}
+/** A node in the canonical flat form {@link SceneDoc.toJson} writes. */
+export interface FlatNodeJson extends NodeCommon {
+    readonly id: NodeId;
+    /** The parent's id, or `"root"` for a page. */
+    readonly parent: NodeId;
+    readonly key: string;
+}
+/** A scene JSON document. */
+export interface SceneJson<N extends NestedNodeJson | FlatNodeJson = NestedNodeJson | FlatNodeJson> {
+    readonly type: "canvist-scene";
+    readonly version: 1;
+    readonly nodes: readonly N[];
+}
+/** What an export draws. Every field is optional. */
+export interface ExportOptions {
+    /** The nodes to draw, with everything inside them. Omit for the first page with its background. */
+    readonly nodes?: readonly NodeId[];
+    /** Output pixels per world unit. Defaults to 1. */
+    readonly scale?: number;
+    /** Space around the drawing, in world units. Defaults to 0. */
+    readonly padding?: number;
+}
+export {};

package/dist/scene-types.js

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

package/dist/scene.d.ts

@@ -0,0 +1,105 @@
+/**
+ * canvist canvas scenes on a server: load scene JSON or Yjs state, run
+ * canvas commands and inspector edits, and export SVG and PNG with the
+ * renderer the canvas draws with.
+ *
+ * Scenes live in their own WebAssembly module, so the document entry point
+ * stays small.
+ *
+ * ```ts
+ * import { createSceneEngine } from "@canvist/headless/scene";
+ *
+ * const engine = await createSceneEngine();
+ * using doc = engine.fromJson({
+ * 	type: "canvist-scene",
+ * 	version: 1,
+ * 	nodes: [{
+ * 		type: "page",
+ * 		children: [{
+ * 			type: "rectangle",
+ * 			props: { size: [120, 80], fills: [{ type: "solid", color: "#3b2cf5" }] },
+ * 		}],
+ * 	}],
+ * });
+ * const png = doc.exportPng({ scale: 2 });
+ * ```
+ *
+ * @module
+ */
+import { WasmSceneDoc } from "../wasm-scene/canvist_headless_scene.js";
+import { type WasmSource } from "./load.ts";
+import type { ExportOptions, NodeId, SceneJson } from "./scene-types.ts";
+export { type CanvistError, isCanvistError } from "./engine.ts";
+export type { WasmSource } from "./load.ts";
+export type * from "./scene-types.ts";
+/**
+ * Load the scene WebAssembly module once. Later calls return the first
+ * call's promise. Without a source, Node, Deno, and Bun read the bundled
+ * file; runtimes without a file system pass the module they imported.
+ */
+export declare function loadScene(source?: WasmSource): Promise<void>;
+/** How to create a scene engine. */
+export interface SceneEngineOptions {
+    /** Allocate node ids, and act as Yjs client, as this id. Defaults to 1. */
+    readonly client?: number;
+    /** Where the scene module comes from; see {@link loadScene}. */
+    readonly wasm?: WasmSource;
+}
+/** Load the scene module and create an engine with every built-in canvas extension. */
+export declare function createSceneEngine(options?: SceneEngineOptions): Promise<SceneEngine>;
+/** A set of canvas extensions that creates scenes. Create one with {@link createSceneEngine}. */
+export declare class SceneEngine {
+    #private;
+    /** @internal Use {@link createSceneEngine}, which loads the module first. */
+    constructor(client: number);
+    /** Tools, commands, node types, and inspector sections, as Rust reports them. */
+    metadata(): unknown;
+    /** A scene with one empty page. */
+    create(): SceneDoc;
+    /** A scene from scene JSON, nested or flat. */
+    fromJson(json: SceneJson): SceneDoc;
+    /** A scene joined from a peer's v1 Yjs state. It is shared, so it produces updates. */
+    fromYjs(state: Uint8Array): SceneDoc;
+    /** Release the engine's memory now rather than when it is collected. */
+    [Symbol.dispose](): void;
+}
+/** One scene. Every edit is one undo step. */
+export declare class SceneDoc {
+    #private;
+    /** @internal Scenes come from a {@link SceneEngine}. */
+    constructor(wasm: WasmSceneDoc, client: number);
+    /** The scene in the canonical flat form. */
+    toJson(): SceneJson;
+    /** Run canvas command `name` (see {@link SceneEngine.metadata}) against the selection. */
+    run(name: string, args?: Readonly<Record<string, unknown>>): void;
+    /** Select nodes by id, for commands and inspector fields. */
+    select(ids: readonly NodeId[]): void;
+    /** The selected nodes' ids. */
+    selection(): NodeId[];
+    /** The inspector for the selection: sections of fields and their values. */
+    inspect(): unknown;
+    /** Set inspector field `key` on every selected node. */
+    setField(key: string, value: unknown): void;
+    /** Undo the latest change; returns whether there was one. */
+    undo(): boolean;
+    /**
+     * Provide an image asset's pixels, `width` by `height` RGBA8. Exports
+     * draw an image without pixels as a grey placeholder; SVG exports
+     * reference provided images by asset id.
+     */
+    addImage(asset: string, width: number, height: number, rgba: Uint8Array): void;
+    /** The scene, or the nodes `options` names, as an SVG document. */
+    exportSvg(options?: ExportOptions): string;
+    /** The scene, or the nodes `options` names, as a PNG image. */
+    exportPng(options?: ExportOptions): Uint8Array;
+    /** Share the scene as Yjs client `clientId` (the engine's client by default). */
+    share(clientId?: number): void;
+    /** The whole shared scene as one v1 Yjs update. */
+    encodeState(): Uint8Array;
+    /** Merge a peer's v1 update; returns whether the scene changed. */
+    applyUpdate(update: Uint8Array): boolean;
+    /** The v1 updates this scene produced since the last call. */
+    takeUpdates(): Uint8Array[];
+    /** Release the scene's memory now rather than when it is collected. */
+    [Symbol.dispose](): void;
+}