agentic-canvas 0.1.0 → 0.3.0

package/dist/read-BY6f-mmy.d.ts

@@ -0,0 +1,167 @@
+import * as Y from 'yjs';
+import { z } from 'zod';
+
+declare const principalSchema: z.ZodObject<{
+    kind: z.ZodEnum<["human", "agent_of_human", "agent_of_agent", "agent", "user_token"]>;
+    id: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    id: string;
+    kind: "human" | "agent_of_human" | "agent_of_agent" | "agent" | "user_token";
+}, {
+    id: string;
+    kind: "human" | "agent_of_human" | "agent_of_agent" | "agent" | "user_token";
+}>;
+type Principal = z.infer<typeof principalSchema>;
+
+type ErrorCode = "INVALID" | "DUPLICATE_ID" | "NOT_FOUND" | "BAD_REFERENCE" | "LIMIT" | "UNAVAILABLE" | "FORBIDDEN";
+declare class CanvasError extends Error {
+    readonly code: ErrorCode;
+    constructor(code: ErrorCode, message: string);
+}
+declare const SHAPE_TYPES: readonly ["rect", "ellipse", "diamond", "text", "sticky", "frame", "image"];
+type ShapeType = (typeof SHAPE_TYPES)[number];
+declare const MAX_ELEMENTS = 10000;
+declare const MAX_TEXT = 10000;
+type Endpoint = {
+    id: string;
+} | {
+    x: number;
+    y: number;
+};
+interface Stamp {
+    id: string;
+    z: number;
+    groupId?: string;
+    /** Who made the element. Never changes. */
+    author: Principal;
+    /** Who made the last edit. */
+    editedBy: Principal;
+}
+interface Shape extends Stamp {
+    type: ShapeType;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    text: string;
+    fill?: string;
+    stroke?: string;
+    src?: string;
+}
+interface Connector extends Stamp {
+    type: "connector";
+    from: Endpoint;
+    to: Endpoint;
+    text: string;
+    startArrow: boolean;
+    endArrow: boolean;
+    stroke?: string;
+}
+interface Group extends Stamp {
+    type: "group";
+}
+type CanvasElement = Shape | Connector | Group;
+/**
+ * A whiteboard on a Yjs doc. Headless: no UI code. Every write names its actor.
+ *
+ * A synced Yjs update is untrusted input. Every read checks each stored element against the same
+ * rules the write methods enforce, and returns only the checked fields. An entry that fails is
+ * hidden at once. `repair()` deletes it, and `Board.decode` runs `repair()`. This holds even
+ * when a caller writes to `doc` directly.
+ */
+declare class Board {
+    readonly doc: Y.Doc;
+    private readonly elements;
+    private readonly meta;
+    private maxElements;
+    constructor(doc?: Y.Doc, options?: {
+        maxElements?: number;
+    });
+    /** Load a saved board with no element checks. Only the owner repair path uses it. */
+    static open(update: Uint8Array): Board;
+    /**
+     * Load a saved board. Refuses a doc past the element cap. Then it deletes every entry that fails
+     * the element checks, and repairs what concurrent writers left broken.
+     */
+    static decode(update: Uint8Array): Board;
+    encode(): Uint8Array;
+    /** An independent copy. Edits to it leave this board alone. */
+    clone(): Board;
+    get title(): string;
+    get titleBy(): Principal | undefined;
+    setTitle(title: string, actor: Principal): void;
+    /** One element. An invalid entry, or a connector with a missing bound end, is hidden. */
+    get(elementId: string): CanvasElement | undefined;
+    /** All visible elements from back to front. */
+    list(): CanvasElement[];
+    /**
+     * Delete what peers can leave broken: entries that fail the element checks, connectors whose
+     * bound end is gone, and members that name a deleted group. Idempotent, so every peer may run it.
+     * `drop` names elements the owner removes too, with what they hold: a shape takes its connectors,
+     * a group takes its members. Refuses a result still past the cap, and then changes nothing.
+     * Returns the ids fixed.
+     */
+    repair(drop?: string[]): string[];
+    /**
+     * Make the author stamps of a merged board honest. `prior` is the board before the merge, and `trusted` says whether
+     * a principal really wrote in this session. A new element stamped by anyone else is deleted. An old element keeps its
+     * author, and a changed one needs a trusted editor or it goes back to its prior state. An editor stamp changed alone
+     * to an untrusted principal is put back. Unknown keys, nested Yjs types, and bad or foreign title values are deleted
+     * or undone. Returns the ids it deleted or restored.
+     */
+    restamp(prior: Board, trusted: (who: Principal) => boolean): string[];
+    addShape(input: unknown, actor: Principal): Shape;
+    addConnector(input: unknown, actor: Principal): Connector;
+    update(elementId: string, patch: unknown, actor: Principal): CanvasElement;
+    /** Shift an element, or a whole group. Returns the ids that moved. Bound connector ends follow their shapes. */
+    move(elementId: string, dx: number, dy: number, actor: Principal): string[];
+    /** Delete an element. A shape takes its connectors and a group takes its members. Returns the ids removed. */
+    remove(elementId: string): string[];
+    group(ids: string[], actor: Principal, groupId?: string): Group;
+    /** Remove a group and hand its members to the parent group. */
+    ungroup(groupId: string, actor: Principal): void;
+    /** Put an element, or a group with its inner order kept, in front of or behind every other element. */
+    reorder(elementId: string, to: "front" | "back", actor: Principal): void;
+    /** One stored element that passes the checks and whose id matches its key, or undefined. */
+    private stored;
+    /** Every stored element that passes the checks, from back to front. Refuses a doc past the cap. */
+    private storedList;
+    /** Like storedList, with no cap check. Repair needs every entry, even on a board past the cap. */
+    private allStored;
+    /** A connector is detached when a bound end does not name a stored shape. */
+    private isDetached;
+    private require;
+    private checkEnd;
+    /** The z value just past the top or the bottom. Not clamped: the caller checks the range. */
+    private edgeZ;
+    /** The element and, for a group, everything below it. Cycle-safe. */
+    private subtree;
+    private subtreeIn;
+    private create;
+    /** Apply field changes and stamp the editor, all in one transaction. An undefined value clears the field. */
+    private write;
+}
+
+interface Labels {
+    /** The author is an agent or acts for one. */
+    machineMade: boolean;
+    /** The last edit came from an agent or one acting for one. */
+    lastEditMachineMade: boolean;
+}
+type NodeData = Shape & Labels;
+type EdgeData = Connector & Labels;
+interface BoardData {
+    title: string;
+    nodes: NodeData[];
+    edges: EdgeData[];
+    groups: {
+        id: string;
+        members: string[];
+    }[];
+    /** Every non-empty text, back to front. */
+    texts: string[];
+}
+/** The board as plain data for an agent. Reads only. Embedded image bytes are left out. */
+declare function readBoard(board: Board): BoardData;
+
+export { type BoardData as B, type Connector as C, type ErrorCode as E, type Group as G, MAX_ELEMENTS as M, type NodeData as N, type Principal as P, type ShapeType as S, type Shape as a, type Endpoint as b, Board as c, type CanvasElement as d, CanvasError as e, type EdgeData as f, MAX_TEXT as g, SHAPE_TYPES as h, principalSchema as p, readBoard as r };

package/dist/service-Cpl6wKeY.d.ts

@@ -0,0 +1,109 @@
+import { S as ShapeType, c as Board, P as Principal, B as BoardData, a as Shape, C as Connector } from './read-BY6f-mmy.js';
+import { Store } from 'agentic-identity';
+
+declare const MAX_FLOW_NODES = 500;
+declare const MAX_FLOW_EDGES = 2000;
+interface FlowNode {
+    id: string;
+    text: string;
+    shape: Extract<ShapeType, "rect" | "ellipse" | "diamond">;
+}
+interface FlowEdge {
+    from: string;
+    to: string;
+    text: string;
+}
+interface FlowGraph {
+    direction: "TB" | "LR";
+    nodes: FlowNode[];
+    edges: FlowEdge[];
+}
+declare function parseFlow(source: string): FlowGraph;
+interface Placement {
+    id: string;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** Layered layout. The top-left of the result is (0, 0). The layout breaks cycles and handles self-loops. */
+declare function layoutFlow(graph: FlowGraph): Placement[];
+interface DrawOptions {
+    /**
+     * Put in front of every id. Default: a new random prefix for each call, so two agents that draw at
+     * the same time never write the same id. A prefix you pass is used as given, and it makes ids
+     * repeatable. Up to 16 of A-Z, a-z, 0-9, _ and -.
+     */
+    idPrefix?: string;
+    /** Top-left of the drawing. Default: below the shapes already on the board. */
+    origin?: {
+        x: number;
+        y: number;
+    };
+}
+/** Draw a flow on the board. All or nothing: on any error the board stays as it was. */
+declare function drawFlow(board: Board, source: string, actor: Principal, options?: DrawOptions): {
+    nodes: string[];
+    edges: string[];
+};
+
+/** One place for every board operation. The CLI, the MCP server, and the Worker call it. */
+declare class CanvasService {
+    private readonly store;
+    constructor(store: Store);
+    create(actor: Principal, options?: {
+        id?: string;
+        title?: string;
+    }): Promise<{
+        id: string;
+        title: string;
+    }>;
+    /** Throws NOT_FOUND unless the board exists. A live room opens only for a board that exists. */
+    assertExists(id: string): Promise<void>;
+    read(id: string): Promise<BoardData & {
+        id: string;
+    }>;
+    /** Run `change` on the board and save it, all inside one transaction. */
+    change<R>(id: string, change: (board: Board) => R): Promise<R>;
+    add(id: string, shape: unknown, actor: Principal): Promise<Shape>;
+    connect(id: string, connector: unknown, actor: Principal): Promise<Connector>;
+    move(id: string, elementId: string, dx: number, dy: number, actor: Principal): Promise<{
+        moved: string[];
+    }>;
+    remove(id: string, elementId: string): Promise<{
+        removed: string[];
+    }>;
+    flow(id: string, text: string, actor: Principal, options?: DrawOptions): Promise<{
+        nodes: string[];
+        edges: string[];
+    }>;
+    exportSvg(id: string): Promise<string>;
+    /** The stored board as a Yjs update. A client applies it to a room to seed it: the room does not read it. */
+    state(id: string): Promise<Uint8Array>;
+    /**
+     * Merge a live room's state into the stored board. `authors` are the principals the room saw send updates.
+     * An element stamped by anyone else is deleted, and a changed author is put back (see `Board.restamp`),
+     * so a client that writes raw Yjs cannot put another author on its work. Broken entries are repaired and
+     * a board past the element cap is refused. Returns the ids the checks fixed.
+     *
+     * Limits: the save corrects the stored board only. The room keeps what its clients wrote, so a client that sees
+     * a non-empty `fixed` must join again, or its later edits are lost at the next save. The room remembers its
+     * authors for good, so a client may stamp an element with the name of anyone who once sent an update in that room.
+     * A client that adds a root type of its own makes every later save of that room fail, because the room keeps it.
+     */
+    checkpoint(id: string, update: Uint8Array, actor: Principal, authors?: Principal[]): Promise<{
+        elements: number;
+        fixed: string[];
+    }>;
+    /** Owner only. Repair a board and delete the named elements. Only a human actor may call it. */
+    repair(id: string, actor: Principal, drop?: string[]): Promise<{
+        id: string;
+        fixed: string[];
+        elements: number;
+    }>;
+    private load;
+}
+/** What the CLI and the MCP server need. `CanvasService` runs it on a store, and `LiveService` runs it in a live room. */
+type BoardAccess = Pick<CanvasService, "create" | "read" | "add" | "connect" | "move" | "remove" | "flow" | "exportSvg">;
+
+export { type BoardAccess as B, CanvasService as C, type DrawOptions as D, type FlowEdge as F, MAX_FLOW_EDGES as M, type Placement as P, type FlowGraph as a, type FlowNode as b, MAX_FLOW_NODES as c, drawFlow as d, layoutFlow as l, parseFlow as p };

package/dist/store-file.js

@@ -1,9 +1,11 @@
 import {
-  FileStoreError,
   STORE_FILE,
   createFileStore,
   openLocalStore
-} from "./chunk-I3EJ5JB7.js";
+} from "./chunk-UKST5A57.js";
+import {
+  FileStoreError
+} from "./chunk-NWQED42L.js";
 export {
   FileStoreError,
   STORE_FILE,

package/dist/worker.d.ts

@@ -0,0 +1,55 @@
+import { Blobs } from 'agentic-identity';
+import { Realtime } from 'agentic-realtime';
+import { D1Like, R2Like } from 'agentic-identity/cloudflare';
+import { Hono } from 'hono';
+import { P as Principal } from './read-BY6f-mmy.js';
+import { C as CanvasService } from './service-Cpl6wKeY.js';
+import 'yjs';
+import 'zod';
+
+interface WorkerEnv {
+    DB: D1Like;
+    IMAGES: R2Like;
+    /**
+     * JSON: `{ "<token>": { "actor": "ada", "kind": "human", "role": "viewer" } }`. A token has 32 characters or more.
+     * A grant needs an actor id and a kind. A token with a missing or bad part gets 401.
+     * The role is "editor" (the default) or "viewer". A viewer reads and cannot write, over HTTP or in a live room.
+     * Without this setting, every request gets 401. Every token reaches every board.
+     */
+    CANVAS_API_TOKENS?: string;
+    /**
+     * "eu", "us", or "unknown": where the database and the bucket live. A real D1 reports where it served a query, and the
+     * store refuses to serve if that is outside the claim. Local `wrangler dev` reports nothing, so it needs "unknown".
+     * Without a valid value, every request gets 503.
+     */
+    CANVAS_REGION?: string;
+    /** The largest image in bytes. Defaults to 1000000. */
+    CANVAS_MAX_IMAGE_BYTES?: string;
+}
+type Role = "editor" | "viewer";
+type App = {
+    Bindings: WorkerEnv;
+    Variables: {
+        service: CanvasService;
+        blobs: Blobs;
+        actor: Principal;
+        role: Role;
+    };
+};
+interface AppOptions {
+    /** Makes the live-room server from the Worker bindings. Without it, the ws route answers 404. */
+    live?: (env: WorkerEnv) => Realtime;
+}
+/** The principal and role for a bearer token, or null. The kind is never defaulted: a grant without a valid kind gets null. */
+declare function authenticate(request: Request, env: WorkerEnv): {
+    actor: Principal;
+    role: Role;
+} | null;
+/** The image types we accept, found by their first bytes. The client's claim of a type is not trusted. */
+declare function sniffImage(bytes: Uint8Array): string | null;
+declare function createApp(options?: AppOptions): Hono<App>;
+declare const _default: {
+    fetch: (request: Request, env: WorkerEnv, ctx: unknown) => Response | Promise<Response>;
+};
+
+export { type AppOptions, type Role, type WorkerEnv, authenticate, createApp, _default as default, sniffImage };

package/dist/worker.js

@@ -0,0 +1,15 @@
+import {
+  authenticate,
+  createApp,
+  sniffImage,
+  worker_default
+} from "./chunk-V477KSZQ.js";
+import "./chunk-W7NRP3EX.js";
+import "./chunk-GGQPE65T.js";
+import "./chunk-NWQED42L.js";
+export {
+  authenticate,
+  createApp,
+  worker_default as default,
+  sniffImage
+};

package/llms.txt

@@ -6,6 +6,9 @@ Keywords: whiteboard,canvas,diagrams,drawing,collaboration,agents,mcp,cli.
 
 - SDK: import { Board, drawFlow, readBoard, toSvg } from "agentic-canvas".
 - CLI: agentic-canvas new|read|add|connect|move|rm|flow|export.
+- Live: set CANVAS_SERVER and CANVAS_TOKEN, and the CLI and `agentic-canvas mcp` edit the board in its live room.
+- SDK: import { LiveBoard, LiveService } from "agentic-canvas/live".
+- SDK: import { createClient, CanvasApiError } from "agentic-canvas/client". It calls the Worker API with fetch. Methods: me, createBoard, readBoard, exportSvg, addShape, addConnector, drawFlow, move, remove, uploadImage, getImage, state, checkpoint. A failure throws CanvasApiError with `code` and `status`. No retries.
 
 ## Docs
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-canvas",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "A shared whiteboard for diagrams, drawn by people and agents.",
   "keywords": [
     "whiteboard",
@@ -39,6 +39,22 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./worker": {
+      "types": "./dist/worker.d.ts",
+      "import": "./dist/worker.js"
+    },
+    "./live": {
+      "types": "./dist/live.d.ts",
+      "import": "./dist/live.js"
+    },
+    "./live-worker": {
+      "types": "./dist/live-worker.d.ts",
+      "import": "./dist/live-worker.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
     "./file-store": {
       "types": "./dist/store-file.d.ts",
       "import": "./dist/store-file.js"
@@ -57,7 +73,8 @@
   "dependencies": {
     "@dagrejs/dagre": "^3.1.3",
     "@modelcontextprotocol/sdk": "^1.12.0",
-    "agentic-identity": "^0.2.0",
+    "agentic-identity": "^0.4.0",
+    "agentic-realtime": "^0.1.0",
     "yjs": "^13.6.0",
     "zod": "^3.25.0"
   },
@@ -71,9 +88,12 @@
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
+    "hono": "^4.13.14",
+    "miniflare": "^4.20260730.0",
     "playwright-core": "^1.64.1",
     "tsup": "^8.0.0",
     "typescript": "^5.6.0",
-    "vitest": "^3.0.0"
+    "vitest": "^3.0.0",
+    "wrangler": "^4.155.0"
   }
 }