@canvist/canvas 0.0.0 → 0.2.0

package/dist/broadcast.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Multiplayer between tabs of one browser, over a `BroadcastChannel`.
+ *
+ * @module
+ */
+import type { SyncMessage, Transport } from "./transport.ts";
+/** Syncs every tab of this origin that joins room `name`. */
+export declare class BroadcastTransport implements Transport {
+    #private;
+    constructor(name: string);
+    connect(_client: number, receive: (message: SyncMessage) => void): void;
+    send(message: SyncMessage): void;
+    close(): void;
+}

package/dist/broadcast.js

@@ -0,0 +1,36 @@
+/** Whether `value` is a {@link SyncMessage}. */
+function isSyncMessage(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const message = value;
+    if (typeof message.from !== "number")
+        return false;
+    switch (message.type) {
+        case "hello":
+        case "welcome":
+            return message.stateVector instanceof Uint8Array;
+        case "update":
+            return message.update instanceof Uint8Array;
+        default:
+            return false;
+    }
+}
+/** Syncs every tab of this origin that joins room `name`. */
+export class BroadcastTransport {
+    #channel;
+    constructor(name) {
+        this.#channel = new BroadcastChannel(`canvist-canvas:${name}`);
+    }
+    connect(_client, receive) {
+        this.#channel.onmessage = (event) => {
+            if (isSyncMessage(event.data))
+                receive(event.data);
+        };
+    }
+    send(message) {
+        this.#channel.postMessage(message);
+    }
+    close() {
+        this.#channel.close();
+    }
+}

package/dist/mod.d.ts

@@ -0,0 +1,93 @@
+/**
+ * The canvist canvas in the browser.
+ *
+ * `mountCanvas` puts the canvas on a `<canvas>` element: vello on WebGPU
+ * where the browser has it, `vello_cpu` and Canvas2D everywhere else. It
+ * starts from a scene you pass as scene JSON (one empty page by default),
+ * feeds DOM events to the canvas, paints on animation frames, and hands
+ * every collaboration update to a {@link Transport}.
+ *
+ * @example
+ * ```ts
+ * import { BroadcastTransport, mountCanvas } from "@canvist/canvas";
+ *
+ * const canvas = document.querySelector("canvas")!;
+ * const handle = await mountCanvas(canvas, {
+ * 	scene: { type: "canvist-scene", version: 1, nodes: [{ type: "page" }] },
+ * 	transport: new BroadcastTransport("my-room"),
+ * });
+ * handle.setTool("rectangle");
+ * const saved = handle.toJson();
+ * ```
+ *
+ * @module
+ */
+import type { SceneJson } from "@canvist/headless/scene";
+import { CanvasApp } from "../wasm/canvist_canvas_wasm.js";
+export { CanvasApp };
+export type { SceneJson } from "@canvist/headless/scene";
+export { BroadcastTransport } from "./broadcast.ts";
+export type { SyncMessage, Transport } from "./transport.ts";
+import type { Transport } from "./transport.ts";
+/** How to mount the canvas. */
+export interface MountOptions {
+    /**
+     * The scene to start from, as scene JSON (nested or flat), such as one
+     * saved from {@link CanvasHandle.toJson}. Defaults to one empty page.
+     *
+     * Peers that start from the same JSON start from the same shared state,
+     * so give every peer in a room the same scene and they merge without
+     * duplicating anything.
+     */
+    scene?: SceneJson;
+    /** Start from canvist's demo scene instead of `scene`. */
+    demo?: boolean;
+    /** Where collaboration updates go and come from. Omit to edit alone. */
+    transport?: Transport;
+    /** Use WebGPU when the browser has it. Defaults to `true`. */
+    preferGpu?: boolean;
+    /** The wasm module's URL, when it is not next to the JS glue. */
+    wasmUrl?: URL | string;
+    /** Add this many extra rectangles, for measuring frame times. */
+    stress?: number;
+    /** Called after the canvas changes, for host UI such as a toolbar. */
+    onChange?: (handle: CanvasHandle) => void;
+}
+/** One painted frame's timing, in milliseconds. */
+export interface FrameTime {
+    /** When the frame started, from `performance.now()`. */
+    at: number;
+    /** Time spent painting and presenting it. */
+    work: number;
+}
+/** A mounted canvas. */
+export interface CanvasHandle {
+    /** The wasm app, for anything this handle does not wrap. */
+    readonly app: CanvasApp;
+    /** This peer's client id. */
+    readonly client: number;
+    /** `"webgpu"` or `"cpu"`. */
+    readonly backend: string;
+    /** The registered tools' names. */
+    readonly tools: readonly string[];
+    /** Switch tools by name. Returns whether one exists. */
+    setTool(name: string): boolean;
+    /** The active tool's name. */
+    tool(): string;
+    /** Recent frame timings, oldest first. */
+    frameTimes(): readonly FrameTime[];
+    /** Forget recorded frame timings. */
+    resetFrameTimes(): void;
+    /** The scene as scene JSON, to store or to start another canvas from. */
+    toJson(): SceneJson;
+    /** The whole shared scene as one v1 Yjs update, to store or to send a joining peer. */
+    encodeState(): Uint8Array;
+    /** Merge a v1 Yjs update, such as stored state; returns whether the scene changed. */
+    applyUpdate(update: Uint8Array): boolean;
+    /** Paint on the next animation frame. */
+    requestFrame(): void;
+    /** Stop listening and painting. */
+    destroy(): void;
+}
+/** Mount the canvas on `canvas`. */
+export declare function mountCanvas(canvas: HTMLCanvasElement, options?: MountOptions): Promise<CanvasHandle>;

package/dist/mod.js

@@ -0,0 +1,313 @@
+import init, { CanvasApp } from "../wasm/canvist_canvas_wasm.js";
+export { CanvasApp };
+export { BroadcastTransport } from "./broadcast.js";
+/** The Shift bit in a modifier mask. */
+const SHIFT = 1;
+/** The Alt bit. */
+const ALT = 2;
+/** The primary bit: Cmd on Apple platforms, Ctrl elsewhere. */
+const PRIMARY = 4;
+/** The client id starting scenes are built under, which peers must not use. */
+const SEED_CLIENT = 1;
+/** One empty page: the scene a canvas starts from by default. */
+const EMPTY_SCENE = {
+    type: "canvist-scene",
+    version: 1,
+    nodes: [{ type: "page" }],
+};
+/** Frame timings kept for {@link CanvasHandle.frameTimes}. */
+const FRAME_HISTORY = 600;
+/** Single-key tool shortcuts, as in most design tools. */
+const TOOL_KEYS = {
+    v: "select",
+    h: "hand",
+    r: "rectangle",
+    o: "ellipse",
+    y: "polygon",
+    p: "pen",
+    f: "frame",
+    t: "text",
+};
+/** A random client id other than the seed id. */
+function randomClient() {
+    const [value = 0] = crypto.getRandomValues(new Uint32Array(1));
+    return value <= SEED_CLIENT ? value + SEED_CLIENT + 1 : value;
+}
+function modifierMask(event) {
+    const apple = /Mac|iPhone|iPad/.test(navigator.platform);
+    const primary = apple ? event.metaKey : event.ctrlKey;
+    return (event.shiftKey ? SHIFT : 0) | (event.altKey ? ALT : 0) |
+        (primary ? PRIMARY : 0);
+}
+let initialized;
+/** Mount the canvas on `canvas`. */
+export async function mountCanvas(canvas, options = {}) {
+    initialized ??= init(options.wasmUrl ? { module_or_path: options.wasmUrl } : undefined);
+    await initialized;
+    const client = randomClient();
+    const app = await CanvasApp.create(canvas, client, options.preferGpu ?? true, options.demo === true
+        ? undefined
+        : JSON.stringify(options.scene ?? EMPTY_SCENE));
+    if (options.stress)
+        app.add_stress(options.stress);
+    return new Mounted(canvas, app, client, options);
+}
+/** The mounted canvas: DOM events in, frames out. */
+class Mounted {
+    backend;
+    tools;
+    #frame = 0;
+    #lastFrame = 0;
+    #times = [];
+    #controller = new AbortController();
+    #resize;
+    #text = hiddenTextBox();
+    canvas;
+    app;
+    client;
+    options;
+    constructor(canvas, app, client, options) {
+        this.canvas = canvas;
+        this.app = app;
+        this.client = client;
+        this.options = options;
+        this.backend = app.backend();
+        this.tools = app.tools();
+        canvas.tabIndex = 0;
+        canvas.style.touchAction = "none";
+        canvas.after(this.#text);
+        this.#resize = new ResizeObserver(() => this.#fit());
+        this.#resize.observe(canvas);
+        this.#fit();
+        this.#listen();
+        options.transport?.connect(client, (message) => this.#receive(message));
+        options.transport?.send({
+            type: "hello",
+            from: client,
+            stateVector: app.state_vector(),
+        });
+    }
+    setTool(name) {
+        const found = this.app.set_tool(name);
+        this.#changed(found);
+        return found;
+    }
+    tool() {
+        return this.app.tool();
+    }
+    frameTimes() {
+        return this.#times;
+    }
+    resetFrameTimes() {
+        this.#times = [];
+    }
+    toJson() {
+        return JSON.parse(this.app.scene_json());
+    }
+    encodeState() {
+        return this.app.encode_state();
+    }
+    applyUpdate(update) {
+        const changed = this.app.apply_update(update);
+        if (changed) {
+            this.requestFrame();
+            this.options.onChange?.(this);
+        }
+        return changed;
+    }
+    requestFrame() {
+        if (this.#frame === 0) {
+            this.#frame = requestAnimationFrame((at) => this.#paint(at));
+        }
+    }
+    destroy() {
+        this.#controller.abort();
+        this.#resize.disconnect();
+        cancelAnimationFrame(this.#frame);
+        this.options.transport?.close();
+        this.#text.remove();
+        this.app.free();
+    }
+    #fit() {
+        const rect = this.canvas.getBoundingClientRect();
+        this.app.resize(rect.width, rect.height, devicePixelRatio);
+        this.requestFrame();
+    }
+    #paint(at) {
+        this.#frame = 0;
+        const elapsed = this.#lastFrame ? (at - this.#lastFrame) / 1000 : 0;
+        this.#lastFrame = at;
+        const coasting = this.app.frame(elapsed);
+        const start = performance.now();
+        this.app.render();
+        this.#times.push({ at: start, work: performance.now() - start });
+        if (this.#times.length > FRAME_HISTORY)
+            this.#times.shift();
+        this.canvas.style.cursor = this.app.cursor();
+        if (coasting)
+            this.requestFrame();
+        else
+            this.#lastFrame = 0;
+    }
+    /** Repaint and broadcast after an event the canvas handled. */
+    #changed(redraw) {
+        this.#focus();
+        for (const update of this.app.take_updates()) {
+            this.options.transport?.send({
+                type: "update",
+                from: this.client,
+                update,
+            });
+        }
+        if (redraw) {
+            this.requestFrame();
+            this.options.onChange?.(this);
+        }
+    }
+    #receive(message) {
+        if (message.from === this.client)
+            return;
+        switch (message.type) {
+            case "hello":
+                this.#sendMissing(message.stateVector);
+                // The newcomer may have changes of its own: ask for them.
+                this.options.transport?.send({
+                    type: "welcome",
+                    from: this.client,
+                    stateVector: this.app.state_vector(),
+                });
+                break;
+            case "welcome":
+                this.#sendMissing(message.stateVector);
+                break;
+            case "update":
+                this.#integrate(message.update);
+                break;
+        }
+    }
+    /** Send the peer with `stateVector` everything it lacks. */
+    #sendMissing(stateVector) {
+        this.options.transport?.send({
+            type: "update",
+            from: this.client,
+            update: this.app.encode_diff(stateVector),
+        });
+    }
+    /** Apply a collaborator's update, repainting if anything changed. */
+    #integrate(update) {
+        this.applyUpdate(update);
+    }
+    #listen() {
+        const signal = this.#controller.signal;
+        const canvas = this.canvas;
+        const position = (event) => {
+            const rect = canvas.getBoundingClientRect();
+            return [event.clientX - rect.left, event.clientY - rect.top];
+        };
+        const pointer = (phase) => (event) => {
+            if (phase === "down") {
+                canvas.focus();
+                canvas.setPointerCapture(event.pointerId);
+            }
+            const [x, y] = position(event);
+            this.#changed(this.app.pointer(phase, event.pointerId, event.pointerType, x, y, event.buttons, modifierMask(event), event.timeStamp));
+        };
+        canvas.addEventListener("pointerdown", pointer("down"), { signal });
+        canvas.addEventListener("pointermove", pointer("move"), { signal });
+        canvas.addEventListener("pointerup", pointer("up"), { signal });
+        canvas.addEventListener("pointercancel", pointer("cancel"), { signal });
+        canvas.addEventListener("wheel", (event) => {
+            event.preventDefault();
+            const [x, y] = position(event);
+            this.#changed(this.app.wheel(event.deltaX, event.deltaY, x, y, modifierMask(event), event.ctrlKey, event.timeStamp));
+        }, { signal, passive: false });
+        // Keys reach the canvas while it has focus, and the hidden text box
+        // while a text frame is open, so IMEs, dictation, and autocorrect
+        // deliver text the way they do to any text field.
+        const targets = [canvas, this.#text];
+        for (const target of targets) {
+            target.addEventListener("keydown", (event) => this.#key(event, true), {
+                signal,
+            });
+            target.addEventListener("keyup", (event) => this.#key(event, false), {
+                signal,
+            });
+            target.addEventListener("paste", (event) => this.#paste(event), {
+                signal,
+            });
+        }
+        this.#text.addEventListener("beforeinput", (event) => {
+            if (event.inputType === "insertText" && event.data) {
+                event.preventDefault();
+                this.#changed(this.app.type_text(event.data, event.timeStamp));
+            }
+        }, { signal });
+        this.#text.addEventListener("compositionend", (event) => {
+            this.#text.value = "";
+            if (event.data) {
+                this.#changed(this.app.type_text(event.data, event.timeStamp));
+            }
+        }, { signal });
+    }
+    /** Pasted plain text goes into the open text frame. */
+    #paste(event) {
+        const text = event.clipboardData?.getData("text/plain");
+        if (!text)
+            return;
+        event.preventDefault();
+        this.#changed(this.app.type_text(text, event.timeStamp));
+    }
+    #key(event, down) {
+        const mask = modifierMask(event);
+        const editing = this.app.editing();
+        if (event.isComposing)
+            return;
+        const shortcut = !editing && down && mask === 0
+            ? TOOL_KEYS[event.key.toLowerCase()]
+            : undefined;
+        if (shortcut) {
+            event.preventDefault();
+            this.setTool(shortcut);
+            return;
+        }
+        // Characters arrive through the text box's input events instead.
+        if (editing && isCharacter(event, mask))
+            return;
+        const used = this.app.key(event.key, down, mask, event.timeStamp);
+        if (used)
+            event.preventDefault();
+        this.#changed(used);
+    }
+    /** Keep focus on the text box while a text frame is open. */
+    #focus() {
+        const editing = this.app.editing();
+        const active = document.activeElement;
+        if (editing && active !== this.#text) {
+            this.#text.focus({ preventScroll: true });
+        }
+        else if (!editing && active === this.#text) {
+            this.canvas.focus({ preventScroll: true });
+        }
+    }
+}
+/** Whether `event` types a character rather than running a command. */
+function isCharacter(event, mask) {
+    return (mask & PRIMARY) === 0 && [...event.key].length === 1;
+}
+/** A text box the user never sees, which receives typed text. */
+function hiddenTextBox() {
+    const text = document.createElement("textarea");
+    text.setAttribute("aria-label", "Text frame");
+    text.autocapitalize = "off";
+    text.spellcheck = false;
+    Object.assign(text.style, {
+        position: "fixed",
+        top: "0",
+        left: "0",
+        width: "1px",
+        height: "1px",
+        opacity: "0",
+        pointerEvents: "none",
+    });
+    return text;
+}

package/dist/transport.d.ts

@@ -0,0 +1,34 @@
+/**
+ * How peers exchange the shared scene.
+ *
+ * Every peer starts from the same scene's state, so syncing is a state-vector
+ * handshake: a new peer says `hello` with its state vector, each existing
+ * peer answers with what the newcomer lacks and a `welcome` carrying its
+ * own state vector, and the newcomer answers that in turn. After that,
+ * every local change goes out as an `update`.
+ *
+ * @module
+ */
+/** A message between peers. `from` is the sender's client id. */
+export type SyncMessage = {
+    type: "hello";
+    from: number;
+    stateVector: Uint8Array;
+} | {
+    type: "welcome";
+    from: number;
+    stateVector: Uint8Array;
+} | {
+    type: "update";
+    from: number;
+    update: Uint8Array;
+};
+/** Carries {@link SyncMessage}s between peers. */
+export interface Transport {
+    /** Start delivering other peers' messages to `receive`. */
+    connect(client: number, receive: (message: SyncMessage) => void): void;
+    /** Send `message` to every other peer. */
+    send(message: SyncMessage): void;
+    /** Stop sending and receiving. */
+    close(): void;
+}

package/dist/transport.js

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

package/package.json

@@ -1 +1,43 @@
-{"description":"Placeholder package for @canvist/canvas","name":"@canvist/canvas","repository":"https://github.com/canvist/canvist","version":"0.0.0"}
+{
+	"name": "@canvist/canvas",
+	"version": "0.2.0",
+	"description": "canvist's design canvas for the browser: shapes, frames, images, vector paths, and text frames on the real canvist editor, rendered by vello on WebGPU with a CPU fallback, and collaborative.",
+	"license": "Unlicense",
+	"homepage": "https://github.com/canvist/canvist/tree/main/packages/canvist-canvas#readme",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/canvist/canvist.git",
+		"directory": "packages/canvist-canvas"
+	},
+	"bugs": {
+		"url": "https://github.com/canvist/canvist/issues",
+		"email": "support@canvist.dev"
+	},
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./dist/mod.d.ts",
+			"default": "./dist/mod.js"
+		},
+		"./wasm/canvist_canvas_wasm_bg.wasm": "./wasm/canvist_canvas_wasm_bg.wasm"
+	},
+	"files": [
+		"dist",
+		"wasm/*.js",
+		"wasm/*.d.ts",
+		"wasm/*.wasm"
+	],
+	"sideEffects": false,
+	"scripts": {
+		"build:wasm": "cd ../.. && wasm-pack build crates/canvist_canvas_wasm --target web --release --out-dir ../../packages/canvist-canvas/wasm --no-pack && rm packages/canvist-canvas/wasm/.gitignore",
+		"check:types": "tsc --noEmit",
+		"build": "tsc -p tsconfig.build.json",
+		"prepack": "npm run build"
+	},
+	"dependencies": {
+		"@canvist/headless": "^0.2.0"
+	},
+	"devDependencies": {
+		"typescript": "^7.0.2"
+	}
+}

package/readme.md

@@ -0,0 +1,86 @@
+<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/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://github.com/canvist/canvist/actions/workflows/canvas-web.yml"><img src="https://github.com/canvist/canvist/actions/workflows/canvas-web.yml/badge.svg?branch=main" alt="canvas-web status" /></a>
+  <a href="https://unlicense.org"><img src="https://img.shields.io/badge/license-Unlicense-3B2CF5" alt="Unlicense" /></a>
+</p>
+
+# @canvist/canvas
+
+canvist's design canvas in the browser: shapes, frames, images, vector paths, and text frames edited with the real canvist text editor. It renders with vello on WebGPU and falls back to a CPU rasteriser where WebGPU is missing. A pluggable transport handles collaboration.
+
+```sh
+npm install @canvist/canvas
+```
+
+```ts
+import { BroadcastTransport, mountCanvas } from "@canvist/canvas";
+
+const canvas = await mountCanvas(document.querySelector("canvas")!, {
+	scene: { type: "canvist-scene", version: 1, nodes: [{ type: "page" }] },
+	transport: new BroadcastTransport("my-room"),
+});
+
+canvas.setTool("rectangle");
+console.log(canvas.backend); // "webgpu" or "cpu"
+const saved = canvas.toJson(); // scene JSON, to store or start from later
+```
+
+- **`scene`** is scene JSON, nested or flat: the same format `@canvist/headless/scene` reads and agents write. It defaults to one empty page, and `demo: true` starts from canvist's demo scene instead.
+- **Collaboration.** A `Transport` carries three messages: `hello`, `welcome`, and `update` (see `src/transport.ts`). `BroadcastTransport` syncs the tabs of one browser, and a WebSocket transport is a few lines on the same interface. Give every peer the same starting scene: each builds it the same way, so merging peers duplicates nothing.
+- **State.** `encodeState()` is the shared scene as one Yjs update, and `applyUpdate(update)` merges one, such as stored state.
+
+[The design canvas quick start](../../docs/src/quick-start/canvas.md) walks through it.
+
+## The demo
+
+```bash
+deno task build && deno task demo
+```
+
+Open <http://127.0.0.1:8787/>, then open it in a second tab. The scene has rectangles, ellipses, a star, a vector path, an image, a frame that clips its children, and a text frame. Double-click the text to edit it.
+
+| Key | Tool      |
+| --- | --------- |
+| V   | Select    |
+| H   | Hand      |
+| R   | Rectangle |
+| O   | Ellipse   |
+| Y   | Star      |
+| P   | Pen       |
+| F   | Frame     |
+| T   | Text      |
+
+The wheel pans, and a trackpad pinch (or Ctrl with the wheel) zooms. Cmd/Ctrl+Z undoes only your own changes. Query parameters:
+
+- `?cpu` forces the CPU renderer.
+- `?stress=2000` adds 2,000 rectangles.
+- `?room=name` picks a room.
+- `?scene=` starts from that scene JSON instead of the demo scene.
+
+## Tests
+
+```bash
+deno task test
+```
+
+This needs Chromium from `npx playwright@1.58 install chromium`. The suite has four tests:
+
+- Two record frame times during a scripted pan and drag over a 2,000-node scene, one on WebGPU and one on the CPU fallback. They print `CANVAS_PERF` lines and fail when the 95th-percentile frame goes over budget: 8 ms on WebGPU, 33 ms on the CPU. Set `CANVIST_PERF_SLACK` to scale the budgets on slow machines.
+- One drives two tabs editing one scene: drawing a rectangle and typing in a text frame.
+- One starts two tabs from the same scene JSON and checks they share it without duplicates, and that it exports.
+
+For npm, `npm run build:wasm && npm run build` builds the module and `dist/`.