agentic-canvas 0.1.0 → 0.3.0

package/dist/chunk-W7NRP3EX.js

@@ -0,0 +1,164 @@
+import {
+  Board,
+  CanvasError,
+  drawFlow,
+  principalSchema,
+  readBoard,
+  toSvg
+} from "./chunk-GGQPE65T.js";
+import {
+  FileStoreError
+} from "./chunk-NWQED42L.js";
+
+// src/service.ts
+import * as Y from "yjs";
+import { assertId, StoreConflictError } from "agentic-identity";
+var COLLECTION = "boards";
+var MAX_LIVE_BYTES = 1572864;
+var BOARD_ID = /^[A-Za-z0-9_-]{1,64}$/;
+function toBase64(bytes) {
+  let text = "";
+  for (let i = 0; i < bytes.length; i += 8192) text += String.fromCharCode(...bytes.subarray(i, i + 8192));
+  return btoa(text);
+}
+var fromBase64 = (text) => Uint8Array.from(atob(text), (c) => c.charCodeAt(0));
+function boardKey(id) {
+  try {
+    if (!BOARD_ID.test(id)) throw new Error();
+    assertId(id);
+  } catch {
+    throw new CanvasError("INVALID", "board id must be 1 to 64 of A-Z, a-z, 0-9, _ and -, and not like __x__");
+  }
+  return id;
+}
+function storeFailure(error) {
+  if (error instanceof StoreConflictError) throw new CanvasError("UNAVAILABLE", "the board changed at the same time. Try again");
+  if (error instanceof FileStoreError) throw new CanvasError(error.code === "LOCKED" ? "UNAVAILABLE" : "INVALID", error.message);
+  throw error;
+}
+var CanvasService = class {
+  store;
+  constructor(store) {
+    this.store = { ...store, transaction: (fn) => store.transaction(fn).catch(storeFailure) };
+  }
+  async create(actor, options = {}) {
+    const id = boardKey(options.id ?? crypto.randomUUID());
+    const board = new Board();
+    if (options.title !== void 0) board.setTitle(options.title, actor);
+    return this.store.transaction(async (tx) => {
+      if (await tx.get(COLLECTION, id)) throw new CanvasError("DUPLICATE_ID", `board "${id}" already exists`);
+      await tx.put(COLLECTION, id, { update: toBase64(board.encode()) });
+      return { id, title: board.title };
+    });
+  }
+  /** Throws NOT_FOUND unless the board exists. A live room opens only for a board that exists. */
+  async assertExists(id) {
+    boardKey(id);
+    if (!await this.store.transaction((tx) => tx.get(COLLECTION, id))) throw new CanvasError("NOT_FOUND", `no board "${id}"`);
+  }
+  async read(id) {
+    boardKey(id);
+    return this.store.transaction(async (tx) => ({ id, ...readBoard(await this.load(tx.get(COLLECTION, id), id)) }));
+  }
+  /** Run `change` on the board and save it, all inside one transaction. */
+  async change(id, change) {
+    boardKey(id);
+    return this.store.transaction(async (tx) => {
+      const board = await this.load(tx.get(COLLECTION, id), id);
+      const result = change(board);
+      await tx.put(COLLECTION, id, { update: toBase64(board.encode()) });
+      return result;
+    });
+  }
+  add(id, shape, actor) {
+    return this.change(id, (b) => b.addShape(shape, actor));
+  }
+  connect(id, connector, actor) {
+    return this.change(id, (b) => b.addConnector(connector, actor));
+  }
+  move(id, elementId, dx, dy, actor) {
+    return this.change(id, (b) => ({ moved: b.move(elementId, dx, dy, actor) }));
+  }
+  remove(id, elementId) {
+    return this.change(id, (b) => ({ removed: b.remove(elementId) }));
+  }
+  flow(id, text, actor, options) {
+    return this.change(id, (b) => drawFlow(b, text, actor, options));
+  }
+  async exportSvg(id) {
+    boardKey(id);
+    return this.store.transaction(async (tx) => toSvg(await this.load(tx.get(COLLECTION, id), id)));
+  }
+  /** The stored board as a Yjs update. A client applies it to a room to seed it: the room does not read it. */
+  async state(id) {
+    boardKey(id);
+    return this.store.transaction(async (tx) => (await this.load(tx.get(COLLECTION, id), id)).encode());
+  }
+  /**
+   * 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.
+   */
+  async checkpoint(id, update, actor, authors = []) {
+    boardKey(id);
+    const by = principalSchema.safeParse(actor);
+    if (!by.success) throw new CanvasError("INVALID", "the actor must be a valid principal");
+    const trusted = (who) => [by.data, ...authors].some((a) => a.kind === who.kind && a.id === who.id);
+    return this.store.transaction(async (tx) => {
+      const prior = await this.load(tx.get(COLLECTION, id), id);
+      const next = prior.clone();
+      try {
+        Y.applyUpdate(next.doc, update);
+      } catch {
+        throw new CanvasError("INVALID", "the update is not a Yjs update");
+      }
+      if (next.doc.store.pendingStructs || next.doc.store.pendingDs) throw new CanvasError("INVALID", "the update is not complete: it needs changes that the board does not have");
+      const strange = [...next.doc.share.keys()].filter((key) => key !== "elements" && key !== "meta");
+      if (strange.length > 0) throw new CanvasError("INVALID", "the update holds data that is not part of a board");
+      const fixed = /* @__PURE__ */ new Set([...next.restamp(prior, trusted), ...next.repair()]);
+      const saved = next.encode();
+      if (saved.length > MAX_LIVE_BYTES) throw new CanvasError("LIMIT", `the board would hold over ${MAX_LIVE_BYTES} bytes`);
+      await tx.put(COLLECTION, id, { update: toBase64(saved) });
+      return { elements: next.list().length, fixed: [...fixed].sort() };
+    });
+  }
+  /** Owner only. Repair a board and delete the named elements. Only a human actor may call it. */
+  async repair(id, actor, drop = []) {
+    const by = principalSchema.safeParse(actor);
+    if (!by.success) throw new CanvasError("INVALID", "the actor must be a valid principal");
+    if (by.data.kind !== "human") throw new CanvasError("FORBIDDEN", "only a human owner can repair a board");
+    boardKey(id);
+    return this.store.transaction(async (tx) => {
+      const doc = await tx.get(COLLECTION, id);
+      if (!doc) throw new CanvasError("NOT_FOUND", `no board "${id}"`);
+      const board = decodeStored(doc, id, Board.open);
+      const fixed = board.repair(drop);
+      await tx.put(COLLECTION, id, { update: toBase64(board.encode()) });
+      return { id, fixed, elements: board.list().length };
+    });
+  }
+  async load(read, id) {
+    const doc = await read;
+    if (!doc) throw new CanvasError("NOT_FOUND", `no board "${id}"`);
+    return decodeStored(doc, id, Board.decode);
+  }
+};
+function decodeStored(doc, id, decode) {
+  try {
+    return decode(fromBase64(String(doc.update)));
+  } catch (error) {
+    if (error instanceof CanvasError) throw error;
+    throw new CanvasError("INVALID", `stored board "${id}" is damaged`);
+  }
+}
+
+export {
+  MAX_LIVE_BYTES,
+  CanvasService
+};

package/dist/cli.js

@@ -2,14 +2,20 @@
 import {
   ActorConfigError,
   BRAND,
-  CanvasError,
-  CanvasService,
   operatorActor,
-  runMcp
-} from "./chunk-NSZ2AC5O.js";
+  runMcp,
+  svgToPng
+} from "./chunk-AGODNBN7.js";
 import {
   openLocalStore
-} from "./chunk-I3EJ5JB7.js";
+} from "./chunk-UKST5A57.js";
+import {
+  CanvasService
+} from "./chunk-W7NRP3EX.js";
+import {
+  CanvasError
+} from "./chunk-GGQPE65T.js";
+import "./chunk-NWQED42L.js";
 
 // src/cli.ts
 import { readFileSync, writeFileSync } from "fs";
@@ -33,6 +39,10 @@ Commands:
   repair <board> [--drop <element>]...     Owner only: fix a broken or over-cap board. Needs CANVAS_ACTOR=human:<id>.
   mcp                                      Serve these as MCP tools on stdio. Needs CANVAS_ACTOR.
 
+Live mode: set CANVAS_SERVER=<worker url> and CANVAS_TOKEN=<bearer token>. Every command then runs in the live room of
+the board on that server, so a person and an agent can edit one board at once. The token sets the actor, the kind,
+and the role, so CANVAS_ACTOR is not needed. If it is set, it must match the token. --dir, CANVAS_DIR, and repair are local only.
+
 Write commands need an actor in CANVAS_ACTOR as <kind>:<id>, such as "agent:helper".
 The operator sets it. A caller cannot pick its own kind: there is no --actor flag.
 Kinds: human, agent_of_human, agent_of_agent, agent, user_token.
@@ -78,7 +88,24 @@ async function run(argv) {
   const need = (count, shape) => {
     if (positionals.length !== count + 1) throw new UsageError(`usage: ${BRAND.command} ${command} ${shape}`);
   };
+  const server = process.env.CANVAS_SERVER;
+  let live;
+  let service;
+  if (server) {
+    if (v.dir !== void 0 || process.env.CANVAS_DIR) throw new UsageError("--dir and CANVAS_DIR are local only: CANVAS_SERVER is set, so the board lives on the server");
+    const token = process.env.CANVAS_TOKEN;
+    if (!token) throw new UsageError("CANVAS_SERVER needs CANVAS_TOKEN");
+    if (command === "repair") throw new UsageError("repair runs on the local store only. Unset CANVAS_SERVER.");
+    const { LiveService, whoAmI } = await import("./live.js");
+    service = new LiveService({ server, token });
+    const claimed = process.env.CANVAS_ACTOR;
+    if (claimed || command !== "read" && command !== "export") live = (await whoAmI(server, token)).actor;
+    if (live && claimed && claimed !== `${live.kind}:${live.id}`) throw new UsageError(`CANVAS_ACTOR "${claimed}" does not match the token (${live.kind}:${live.id}). Unset CANVAS_ACTOR.`);
+  } else {
+    service = new CanvasService(openLocalStore(v.dir ?? process.env.CANVAS_DIR ?? ".agentic-canvas"));
+  }
   const actor = () => {
+    if (live) return live;
     try {
       return operatorActor();
     } catch (error) {
@@ -86,7 +113,6 @@ async function run(argv) {
       throw error;
     }
   };
-  const service = new CanvasService(openLocalStore(v.dir ?? process.env.CANVAS_DIR ?? ".agentic-canvas"));
   const print = (value) => console.log(JSON.stringify(value));
   switch (command) {
     case "new":
@@ -118,7 +144,7 @@ async function run(argv) {
       const format = v.format ?? "svg";
       if (format !== "svg" && format !== "png") throw new UsageError(`format must be svg or png, got "${format}"`);
       if (format === "png" && !v.out) throw new UsageError("png is binary: pass --out <path>");
-      const data = format === "svg" ? await service.exportSvg(board) : await service.exportPng(board);
+      const data = format === "svg" ? await service.exportSvg(board) : await svgToPng(await service.exportSvg(board));
       if (!v.out) return void process.stdout.write(`${data}
 `);
       writeFileSync(v.out, data);

package/dist/client.d.ts

@@ -0,0 +1,108 @@
+import { E as ErrorCode, B as BoardData, S as ShapeType, a as Shape, b as Endpoint, C as Connector } from './read-BY6f-mmy.js';
+import { PrincipalKind } from 'agentic-identity';
+import 'yjs';
+import 'zod';
+
+interface ClientOptions {
+    /** The API root, for example `https://canvas.example.com/api/v1/canvas`. */
+    baseUrl: string;
+    /** A bearer token. The token sets the actor, the kind, and the role. */
+    token: string;
+    /** A custom `fetch`. Defaults to the global one. */
+    fetch?: typeof fetch;
+}
+/** Options for every call. */
+interface CallOptions {
+    signal?: AbortSignal;
+}
+interface ShapeInput {
+    id?: string;
+    type: ShapeType;
+    x: number;
+    y: number;
+    w?: number;
+    h?: number;
+    text?: string;
+    fill?: string;
+    stroke?: string;
+    /** A `data:` URL or a `blob:` ref, for an image. */
+    src?: string;
+}
+interface ConnectorInput {
+    id?: string;
+    from: Endpoint;
+    to: Endpoint;
+    text?: string;
+    startArrow?: boolean;
+    endArrow?: boolean;
+    stroke?: string;
+}
+interface ImageInfo {
+    id: string;
+    ref: string;
+    type: string;
+    size: number;
+    /** False when the same bytes were stored before. */
+    created: boolean;
+}
+/**
+ * A failed call. `code` is the API error code, such as `NOT_FOUND`, `UNAUTHORIZED`, or `INVALID`. `status` is the HTTP status.
+ * A reply that is not the API's error shape has code `HTTP_ERROR`. A call that never got a reply has code `NETWORK` and status 0.
+ */
+type ApiErrorCode = ErrorCode | "UNAUTHORIZED" | "NOT_CONFIGURED" | "TOO_LARGE" | "UNSUPPORTED_TYPE" | "UPGRADE_REQUIRED" | "INTERNAL" | "NETWORK" | "HTTP_ERROR" | (string & {});
+declare class CanvasApiError extends Error {
+    readonly code: ApiErrorCode;
+    readonly status: number;
+    constructor(code: ApiErrorCode, message: string, status: number);
+}
+interface CanvasClient {
+    /** Who the token stands for. */
+    me(options?: CallOptions): Promise<{
+        actor: string;
+        kind: PrincipalKind;
+        role: "editor" | "viewer";
+    }>;
+    createBoard(input?: {
+        id?: string;
+        title?: string;
+    }, options?: CallOptions): Promise<{
+        id: string;
+        title: string;
+    }>;
+    readBoard(id: string, options?: CallOptions): Promise<BoardData & {
+        id: string;
+    }>;
+    /** The board as an SVG document. */
+    exportSvg(id: string, options?: CallOptions): Promise<string>;
+    addShape(id: string, shape: ShapeInput, options?: CallOptions): Promise<Shape>;
+    addConnector(id: string, connector: ConnectorInput, options?: CallOptions): Promise<Connector>;
+    /** Draw a flowchart from text such as `A -> B: label`. Returns the new ids. */
+    drawFlow(id: string, text: string, options?: CallOptions): Promise<{
+        nodes: string[];
+        edges: string[];
+    }>;
+    /** Move an element. Returns the ids that moved: a shape takes its connectors with it. */
+    move(id: string, element: string, dx: number, dy: number, options?: CallOptions): Promise<{
+        moved: string[];
+    }>;
+    /** Remove an element. Returns the ids removed. */
+    remove(id: string, element: string, options?: CallOptions): Promise<{
+        removed: string[];
+    }>;
+    uploadImage(bytes: Uint8Array | ArrayBuffer | Blob, options?: CallOptions): Promise<ImageInfo>;
+    /** The bytes of a stored image, and its content type. */
+    getImage(id: string, options?: CallOptions): Promise<{
+        bytes: Uint8Array;
+        type: string;
+    }>;
+    /** The stored board as a Yjs update. Only a server with live rooms serves it. */
+    state(id: string, options?: CallOptions): Promise<Uint8Array>;
+    /** Merge a live room's Yjs update into the stored board. Only a server with live rooms serves it. */
+    checkpoint(id: string, update: Uint8Array, options?: CallOptions): Promise<{
+        elements: number;
+        fixed: string[];
+    }>;
+}
+declare function createClient(options: ClientOptions): CanvasClient;
+
+export { type ApiErrorCode, type CallOptions, CanvasApiError, type CanvasClient, type ClientOptions, type ConnectorInput, type ImageInfo, type ShapeInput, createClient };

package/dist/client.js

@@ -0,0 +1,78 @@
+// src/client.ts
+var CanvasApiError = class extends Error {
+  constructor(code, message, status) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.name = "CanvasApiError";
+  }
+  code;
+  status;
+};
+function createClient(options) {
+  const { token } = options;
+  const base = options.baseUrl.replace(/\/+$/, "");
+  if (!token) throw new TypeError("token is required");
+  const doFetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+  const seg = encodeURIComponent;
+  async function send(method, path, init, call) {
+    const headers = { authorization: `Bearer ${token}` };
+    if (init.json !== void 0) headers["content-type"] = "application/json";
+    if (init.contentType) headers["content-type"] = init.contentType;
+    let response;
+    try {
+      response = await doFetch(`${base}${path}`, {
+        method,
+        headers,
+        body: init.json === void 0 ? init.body : JSON.stringify(init.json),
+        signal: call?.signal
+      });
+    } catch (error) {
+      if (call?.signal?.aborted) throw error;
+      throw new CanvasApiError("NETWORK", error instanceof Error ? error.message : "the request failed", 0);
+    }
+    if (response.ok) return response;
+    let code = "HTTP_ERROR";
+    let message = `the server answered ${response.status}`;
+    try {
+      const { error } = await response.json();
+      if (typeof error?.code === "string") code = error.code;
+      if (typeof error?.message === "string") message = error.message;
+    } catch {
+      if (call?.signal?.aborted) throw call.signal.reason;
+    }
+    throw new CanvasApiError(code, message, response.status);
+  }
+  const parse = async (response, call) => {
+    try {
+      return await response.json();
+    } catch (error) {
+      if (call?.signal?.aborted) throw error;
+      throw new CanvasApiError("HTTP_ERROR", "the server did not answer with JSON", response.status);
+    }
+  };
+  const json = async (method, path, body, call) => parse(await send(method, path, { json: body }, call), call);
+  const bytes = async (response) => new Uint8Array(await response.arrayBuffer());
+  return {
+    me: (o) => json("GET", "/me", void 0, o),
+    createBoard: (input = {}, o) => json("POST", "/boards", input, o),
+    readBoard: (id, o) => json("GET", `/boards/${seg(id)}`, void 0, o),
+    exportSvg: async (id, o) => (await send("GET", `/boards/${seg(id)}/svg`, {}, o)).text(),
+    addShape: (id, shape, o) => json("POST", `/boards/${seg(id)}/shapes`, shape, o),
+    addConnector: (id, connector, o) => json("POST", `/boards/${seg(id)}/connectors`, connector, o),
+    drawFlow: (id, text, o) => json("POST", `/boards/${seg(id)}/flow`, { text }, o),
+    move: (id, element, dx, dy, o) => json("POST", `/boards/${seg(id)}/move`, { element, dx, dy }, o),
+    remove: (id, element, o) => json("DELETE", `/boards/${seg(id)}/elements/${seg(element)}`, void 0, o),
+    uploadImage: async (data, o) => parse(await send("POST", "/images", { body: data, contentType: "application/octet-stream" }, o), o),
+    getImage: async (id, o) => {
+      const response = await send("GET", `/images/${seg(id)}`, {}, o);
+      return { bytes: await bytes(response), type: response.headers.get("content-type") ?? "application/octet-stream" };
+    },
+    state: async (id, o) => bytes(await send("GET", `/boards/${seg(id)}/state`, {}, o)),
+    checkpoint: async (id, update, o) => parse(await send("POST", `/boards/${seg(id)}/checkpoint`, { body: update, contentType: "application/octet-stream" }, o), o)
+  };
+}
+export {
+  CanvasApiError,
+  createClient
+};