agentic-canvas 0.1.0 → 0.3.0

package/README.md

@@ -7,9 +7,9 @@
 
 A shared whiteboard for diagrams, drawn by people and agents.
 
-> Status: 0.1.0, the first release. The board model, the agent operations, the
-> exports, the CLI, and the MCP server work. The HTTP API and the web UI are not
-> built yet.
+> Status: 0.3.0. The board model, the agent operations, the exports, the CLI, the
+> MCP server, a small Worker API, and live co-editing work. The CLI, the MCP server,
+> and the SDK can join a live room. A remote client calls the Worker API. The web UI is not built yet.
 
 ## Install
 
@@ -84,6 +84,33 @@ The flow text takes one statement per line: `A -> B: label`. Use `[text]` for a
 box, `(text)` for an ellipse, and `{text}` for a diamond. `direction LR` sets
 the direction. Lines that start with `#` or `//` are comments.
 
+### Remote client
+
+Call a running Worker from a browser, a Worker, or Node 22. The client uses only `fetch`.
+
+```ts
+import { createClient, CanvasApiError } from "agentic-canvas/client";
+
+const canvas = createClient({ baseUrl: "https://canvas.example.com/api/v1/canvas", token });
+await canvas.createBoard({ id: "plan", title: "Plan" });
+await canvas.addShape("plan", { type: "rect", x: 0, y: 0, text: "Start" });
+await canvas.drawFlow("plan", "A -> B: go");
+const board = await canvas.readBoard("plan");
+
+try {
+  await canvas.readBoard("missing");
+} catch (error) {
+  if (error instanceof CanvasApiError) console.log(error.code, error.status); // NOT_FOUND 404
+}
+```
+
+There is one method per route: `me`, `createBoard`, `readBoard`, `exportSvg`, `addShape`, `addConnector`,
+`drawFlow`, `move`, `remove`, `uploadImage`, `getImage`, `state`, and `checkpoint`. Each takes
+`{ signal }` last, so an `AbortSignal` can stop a call. The token sets the actor. A failed call throws
+`CanvasApiError` with the API `code` and the HTTP `status`. A call that gets no reply has code `NETWORK`
+and status 0. The client never retries. A 503 means "try again", and the caller decides, because a
+repeated write can change a board twice. Pass `fetch` to use your own.
+
 ## Features
 
 - Shapes: rectangle, ellipse, diamond, text, sticky note, frame, image.
@@ -101,11 +128,30 @@ the direction. Lines that start with `#` or `//` are comments.
   and every network request blocked. A board over 16 million pixels exports as SVG only.
 - A CLI over a local file store. Several processes can write at once.
 - An MCP server (stdio) over the same service as the CLI.
+- A Worker (`agentic-canvas/worker`) under `/api/v1/canvas`. Boards live in D1 and images in R2
+  (EU jurisdiction), through the shared `Store` and `Blobs` ports. Set `CANVAS_API_TOKENS`
+  (a JSON map of token to `{ actor, kind }`, tokens of 32 characters or more) and `CANVAS_REGION`.
+  Routes: `POST /boards`, `GET /boards/:id`, `GET /boards/:id/svg`, `POST /boards/:id/shapes`,
+  `/connectors`, `/flow`, `/move`, `DELETE /boards/:id/elements/:element`, `POST /images`,
+  `GET /images/:id`. An image is stored under the SHA-256 of its bytes, and the reply gives
+  the `blob:` ref for a shape. A busy database or bucket answers 503: try again.
+- Live rooms (`agentic-canvas/live-worker`, on `agentic-realtime`). One Durable Object holds one
+  board. A token may carry `"role": "viewer"`: a viewer reads and cannot write. `GET /boards/:id/ws`
+  opens a room, `GET /me` says who a token is, `GET /boards/:id/state` and
+  `POST /boards/:id/checkpoint` seed a room from the stored board and save it back, as a merge. A save
+  checks author stamps: a client cannot put another author on its work.
+- The SDK joins a room: `import { LiveBoard, LiveService } from "agentic-canvas/live"`. The CLI and the MCP
+  server join when `CANVAS_SERVER` and `CANVAS_TOKEN` are set. The token sets the actor, so
+  `CANVAS_ACTOR` is not needed. `--dir`, `CANVAS_DIR`, and `repair` stay local.
 - Yjs underneath: two copies of a board merge without conflicts.
 - No UI code. The model is plain TypeScript on Yjs, with no outbound calls.
 
 ## Limits
 
+- Canvas takes principal kinds, regions, and the Store and Blobs ports from `agentic-identity` 0.4.
+  It does not use the sharing API yet. Its editor and viewer tokens are a separate table in
+  `CANVAS_API_TOKENS`. It has no board delete or erase. When it adopts sharing, grants are keyed
+  on kind and id, and a delete calls `deleteResource`.
 - A board holds at most 10,000 elements. A flow holds at most 500 nodes and 2,000
   edges.
 - Flow text has no chains (`A -> B -> C`). Write one edge per line.
@@ -133,7 +179,14 @@ the direction. Lines that start with `#` or `//` are comments.
 - Node 22 or newer is needed. `agentic-canvas/file-store` exports `createFileStore(path)` and
   `openLocalStore(dir)`. A writer that is paused for more than 30 seconds can lose its lock
   and then still write.
-- Delete leaves no audit record yet. The caller logs it.
+- A room remembers its authors for good, so a client can stamp an element with the name of anyone who
+  once sent an update in that room. A save corrects the stored board and not the room: after a save that
+  reports `fixed`, join again. A client that adds a root Yjs type of its own blocks later saves of that room.
+- Every Worker token reaches every board. A token has an editor or viewer role, and nothing finer yet. Local
+  `wrangler dev` cannot confirm a region, so run it with `CANVAS_REGION=unknown`. The region claim covers D1 only: R2 reports no region, so the bucket is in
+  the EU jurisdiction only if you create it so. A real D1
+  confirms `eu` or `us` on each query. The Worker has no PNG export.
+- Delete leaves no audit record yet. The Worker logs the actor kind of each delete, and no ids.
 - PNG needs the optional `playwright-core` and a Chromium. Without them it fails with
   `UNAVAILABLE`. SVG always works.
 

package/SKILL.md

@@ -36,6 +36,9 @@ agentic-canvas read demo
 agentic-canvas export demo --out demo.svg
 ```
 
+To edit a board that a person has open, use live mode. Set `CANVAS_SERVER` and `CANVAS_TOKEN`
+and run the same commands. The token names the actor, so leave `CANVAS_ACTOR` unset.
+
 ## Rules
 
 - Name the actor on every write.

package/dist/chunk-AGODNBN7.js

@@ -0,0 +1,166 @@
+import {
+  CanvasError,
+  PRINCIPAL_KINDS,
+  SHAPE_TYPES,
+  principalSchema
+} from "./chunk-GGQPE65T.js";
+
+// src/version.ts
+import { createRequire } from "module";
+var VERSION = true ? "0.3.0" : readPackageVersion();
+
+// src/brand.ts
+var BRAND = {
+  command: "agentic-canvas",
+  description: "A shared whiteboard for diagrams, drawn by people and agents.",
+  version: VERSION
+};
+
+// src/actor.ts
+var ActorConfigError = class extends Error {
+};
+function operatorActor(env = process.env) {
+  const raw = env.CANVAS_ACTOR;
+  if (!raw) throw new ActorConfigError("the operator must set CANVAS_ACTOR=<kind>:<id>");
+  const at = raw.indexOf(":");
+  const parsed = principalSchema.safeParse({ kind: raw.slice(0, at), id: raw.slice(at + 1) });
+  if (at < 0 || !parsed.success) {
+    throw new ActorConfigError(`bad CANVAS_ACTOR "${raw}": use <kind>:<id>, kind is one of ${PRINCIPAL_KINDS.join(", ")}`);
+  }
+  return parsed.data;
+}
+
+// src/png.ts
+var MAX_SIDE = 16384;
+var MAX_PIXELS = 16e6;
+var TIMEOUT_MS = 2e4;
+async function svgToPng(svg) {
+  const size = /^<svg [^>]*?width="(\d+)" height="(\d+)"/.exec(svg);
+  const width = Number(size?.[1]);
+  const height = Number(size?.[2]);
+  if (!(width > 0 && height > 0) || width > MAX_SIDE || height > MAX_SIDE || width * height > MAX_PIXELS) {
+    throw new CanvasError("LIMIT", `the board is too large for PNG: up to ${MAX_SIDE} px a side and ${MAX_PIXELS / 1e6} million pixels`);
+  }
+  let chromium;
+  try {
+    ({ chromium } = await import("playwright-core"));
+  } catch {
+    throw new CanvasError("UNAVAILABLE", "PNG export needs the playwright-core package. Install it, or export SVG.");
+  }
+  const browser = await chromium.launch().catch(() => {
+    throw new CanvasError("UNAVAILABLE", "PNG export needs Chromium. Run: npx playwright-core install chromium");
+  });
+  try {
+    const context = await browser.newContext({ viewport: { width, height }, javaScriptEnabled: false, serviceWorkers: "block" });
+    context.setDefaultTimeout(TIMEOUT_MS);
+    await context.route("**/*", (route) => route.abort());
+    const page = await context.newPage();
+    await page.setContent(`<!doctype html><body style="margin:0">${svg}</body>`);
+    return await page.screenshot({ clip: { x: 0, y: 0, width, height } });
+  } finally {
+    await browser.close();
+  }
+}
+
+// src/mcp.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+var json = (value) => ({ content: [{ type: "text", text: JSON.stringify(value) }] });
+function failure(error) {
+  if (!(error instanceof CanvasError)) console.error(error instanceof Error ? error.message : String(error));
+  const body = error instanceof CanvasError ? { code: error.code, message: error.message } : { code: "INTERNAL", message: "the board operation failed" };
+  return { isError: true, content: [{ type: "text", text: JSON.stringify(body) }] };
+}
+function tool(run) {
+  return async (args) => {
+    try {
+      return await run(args);
+    } catch (error) {
+      return failure(error);
+    }
+  };
+}
+var board = z.string().describe("Board id.");
+var num = z.number();
+function createMcpServer(service, actor) {
+  const server = new McpServer({ name: BRAND.command, version: BRAND.version });
+  const read = { readOnlyHint: true };
+  server.registerTool(
+    "create_board",
+    { description: "Make a board.", inputSchema: { id: z.string().optional(), title: z.string().optional() } },
+    tool(async (a) => json(await service.create(actor, a)))
+  );
+  server.registerTool(
+    "read_board",
+    { description: "Read a board as data: nodes, edges, groups, text, and who made what.", inputSchema: { board }, annotations: read },
+    tool(async (a) => json(await service.read(a.board)))
+  );
+  server.registerTool(
+    "add_shape",
+    {
+      description: "Add a shape. Image shapes need src.",
+      inputSchema: {
+        board,
+        id: z.string().optional(),
+        type: z.enum(SHAPE_TYPES),
+        x: num,
+        y: num,
+        w: num.optional(),
+        h: num.optional(),
+        text: z.string().optional(),
+        fill: z.string().optional(),
+        stroke: z.string().optional(),
+        src: z.string().optional()
+      }
+    },
+    tool(async ({ board: b, ...shape }) => json(await service.add(b, shape, actor)))
+  );
+  server.registerTool(
+    "connect",
+    { description: "Join two shapes with an arrow.", inputSchema: { board, from: z.string(), to: z.string(), id: z.string().optional(), text: z.string().optional() } },
+    tool(async (a) => json(await service.connect(a.board, { id: a.id, from: { id: a.from }, to: { id: a.to }, text: a.text }, actor)))
+  );
+  server.registerTool(
+    "move",
+    { description: "Move an element, or a whole group.", inputSchema: { board, element: z.string(), dx: num, dy: num } },
+    tool(async (a) => json(await service.move(a.board, a.element, a.dx, a.dy, actor)))
+  );
+  server.registerTool(
+    "remove",
+    { description: "Delete an element. A shape takes its connectors, a group its members.", inputSchema: { board, element: z.string() }, annotations: { destructiveHint: true } },
+    tool(async (a) => json(await service.remove(a.board, a.element)))
+  );
+  server.registerTool(
+    "draw_flow",
+    {
+      description: 'Draw a flowchart from text, one statement per line: "A[Box] -> B{Choice}: label". [] box, () ellipse, {} diamond.',
+      inputSchema: { board, text: z.string(), idPrefix: z.string().optional() }
+    },
+    tool(async (a) => json(await service.flow(a.board, a.text, actor, { idPrefix: a.idPrefix })))
+  );
+  server.registerTool(
+    "export_svg",
+    { description: "Export the board as SVG text.", inputSchema: { board }, annotations: read },
+    tool(async (a) => ({ content: [{ type: "text", text: await service.exportSvg(a.board) }] }))
+  );
+  server.registerTool(
+    "export_png",
+    { description: "Export the board as a PNG image. Needs the optional playwright-core and a Chromium.", inputSchema: { board }, annotations: read },
+    tool(async (a) => ({ content: [{ type: "image", data: Buffer.from(await svgToPng(await service.exportSvg(a.board))).toString("base64"), mimeType: "image/png" }] }))
+  );
+  return server;
+}
+async function runMcp(service, actor) {
+  await createMcpServer(service, actor).connect(new StdioServerTransport());
+}
+
+export {
+  VERSION,
+  BRAND,
+  ActorConfigError,
+  operatorActor,
+  svgToPng,
+  createMcpServer,
+  runMcp
+};