agentic-canvas 0.4.0 → 0.6.0

package/README.md

@@ -7,9 +7,10 @@
 
 A shared whiteboard for diagrams, drawn by people and agents.
 
-> Status: 0.4.0. The board model, the agent operations, the exports, the CLI, the
+> Status: 0.6.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. A small web UI, served by the Worker, is new in 0.4.0.
+> The package exports `agentic-canvas/ui`, a board view you can mount in your own app, new in 0.5.0.
 
 ## Install
 
@@ -170,6 +171,37 @@ What it does:
   and connects shapes, with fields, and the toolbar has pan buttons. A person who cannot drag
   can do everything a drag does.
 
+### Mount the board in your app
+
+`agentic-canvas/ui` renders the same board UI into any element. It needs no framework in your app.
+React and react-dom (version 19 or later) are peer dependencies. The Worker's own page uses this code.
+
+```ts
+import "agentic-design/styles.css";   // tokens and fonts
+import "agentic-canvas/ui.css";       // the board styles
+import { createClient } from "agentic-canvas/client";
+import { mount } from "agentic-canvas/ui";
+
+const baseUrl = "https://canvas.example.com/api/v1/canvas";
+const token = "...";
+const board = mount(document.getElementById("board")!, {
+  boardId: "b1",
+  client: createClient({ baseUrl, token }),
+  principal: { kind: "human", name: "Ada", role: "editor" },
+  readOnly: false,
+  room: { baseUrl, token },           // optional: shows who else is in the board
+});
+
+board.update({ /* same options, for another board */ });
+board.unmount();                      // leaves the room and stops the refresh timer
+```
+
+The principal needs a known `kind` and a `name`. `mount` throws a `TypeError` without them. Only the
+role `editor` can change the board, and `readOnly: true` opens it read only for an editor too. The
+server still checks every write against the token. The host page owns the theme. `ui.css` uses CSS nesting under `.cv-root`, so it does not change the rest of your page. It needs a browser from 2023 or later.
+For a React app, `BoardEditor` is the same component without a root. Wrap it in the providers of
+`agentic-design/react`.
+
 Develop and test the UI:
 
 ```sh
@@ -229,6 +261,85 @@ at the same time keep the last write. The board list shows the first 100 boards.
 - Yjs underneath: two copies of a board merge without conflicts.
 - The board model has no UI code. It is plain TypeScript on Yjs, with no outbound calls.
 
+## Exports
+
+Every name that each entry point exports is listed here. A name marked (type) exists only at compile time.
+
+### `agentic-canvas`
+
+| Name | What it is |
+|---|---|
+| `VERSION`, `BRAND` | The package version. `BRAND` holds the command name, the description and the version that the CLI and the MCP server show. |
+| `Board`, `CanvasElement` (type), `Shape` (type), `Connector` (type), `Group` (type), `Endpoint` (type), `ShapeType` (type) | The board model. `Board` holds the elements. Each element records its `author`, which never changes, and its `editedBy`. |
+| `SHAPE_TYPES` | The shape kinds: `rect`, `ellipse`, `diamond`, `text`, `sticky`, `frame` and `image`. |
+| `MAX_ELEMENTS`, `MAX_TEXT` | The limits: 10,000 elements on a board, and 10,000 UTF-16 code units in one text. |
+| `CanvasError`, `ErrorCode` (type) | The error that the board throws, with a `code` such as `INVALID`, `NOT_FOUND` or `LIMIT`. |
+| `parseFlow(source)`, `layoutFlow(graph)`, `drawFlow(board, source, actor, options?)` | `parseFlow` reads the flow text. `layoutFlow` returns placements with the top-left at (0, 0). `drawFlow` draws the flow onto the board as the actor. |
+| `MAX_FLOW_NODES`, `MAX_FLOW_EDGES` | The flow limits: 500 nodes and 2000 edges. |
+| `FlowGraph` (type), `FlowNode` (type), `FlowEdge` (type), `Placement` (type), `DrawOptions` (type) | Types for a flow and its layout. |
+| `readBoard`, `BoardData` (type), `NodeData` (type), `EdgeData` (type) | Read a board as plain data. |
+| `toSvg(board)`, `svgToPng(svg)` | `toSvg` returns the board as SVG. `svgToPng` turns an SVG string into PNG through Chromium. |
+| `PRINCIPAL_KINDS`, `PrincipalKind` (type), `Principal` (type), `principalSchema`, `isMachineMade` | The principal kinds, the schema of a principal, and the rule that marks machine-made kinds. |
+| `operatorActor(env?)`, `ActorConfigError` | Read the actor from `CANVAS_ACTOR` as `<kind>:<id>`. It throws `ActorConfigError` when the value is missing or bad. |
+| `CanvasService` | The board operations that the CLI, the MCP server and the Worker share. It takes a `Store`. |
+| `createMcpServer(service, actor)`, `runMcp(service, actor)` | Make the MCP server, or run it on stdio. |
+| `createFileStore`, `openLocalStore`, `FileStoreOptions` (type) | Stores on one local file. See `agentic-canvas/file-store`. |
+
+### `agentic-canvas/client`
+
+| Name | What it is |
+|---|---|
+| `createClient(options)`, `CanvasApiError` | The remote client. See Remote client above. |
+| `ClientOptions` (type), `CallOptions` (type), `CanvasClient` (type), `ShapeInput` (type), `ConnectorInput` (type), `ShapePatch` (type), `ConnectorPatch` (type), `ImageInfo` (type), `ApiErrorCode` (type) | Types for the client. `ApiErrorCode` adds the client's own codes, such as `NETWORK`, to `ErrorCode`. |
+
+### `agentic-canvas/file-store`
+
+| Name | What it is |
+|---|---|
+| `createFileStore(path, options?)`, `openLocalStore(dir)` | A store on one JSON file, or on `canvas.json` in a directory. |
+| `FileStoreError` | The error that the store throws. Its `code` is `LOCKED` or `DAMAGED`. |
+| `FileStoreOptions` (type) | `lockTimeoutMs` (default 10000) and `staleAfterMs` (default 30000), plus the adapter options. |
+| `STORE_FILE` | The file name that `openLocalStore` uses, `canvas.json`. |
+
+### `agentic-canvas/live`
+
+| Name | What it is |
+|---|---|
+| `LiveBoard.join(options)` | Join one board's live room. Read the board, change it, `save` to the stored board, then `leave`. |
+| `LiveService` | The CLI and MCP commands, run in a live room. A change joins the room, runs as the token's actor, saves, and leaves. `read` and `exportSvg` join and leave without a save. `create` and `list` call the HTTP API. |
+| `whoAmI(server, token)`, `Me` (type) | Ask the Worker who a token is. It returns the actor and the role. |
+| `LiveOptions` (type) | The server, the board id, the token, and the optional name and reconnect settings. |
+
+### `agentic-canvas/ui`
+
+| Name | What it is |
+|---|---|
+| `mount(element, options)` | Render the board UI into an element. It returns `update(options)` and `unmount()`. See Mount the board in your app. |
+| `BoardEditor(options)` | The same board UI as a React component, without a root. |
+| `BoardEditorOptions` (type), `BoardPrincipal` (type), `MountedBoard` (type) | Types for the options, the principal, and the object that `mount` returns. |
+| `CanvasClient` (type), `RoomOptions` (type) | The client type, as in `agentic-canvas/client`, and the live room's base URL and token for the `room` option. |
+
+The stylesheet is a separate export, `agentic-canvas/ui.css`. Load `agentic-design/styles.css` too, for the tokens.
+
+### `agentic-canvas/worker`
+
+| Name | What it is |
+|---|---|
+| `createApp(options?)` | Make the Hono app for the Worker. Pass `live` to turn on the live-room socket. |
+| `default` | The Worker, without live rooms. |
+| `authenticate(request, env)` | Read a bearer token from the `Authorization` header, or from a WebSocket sub-protocol. Return a promise of the actor and the role, or `null`. |
+| `sniffImage(bytes)` | Find the image type from the first bytes, or return `null`. The client's claim of a type is not trusted. |
+| `WS_PROTOCOL` | The sub-protocol name for a WebSocket: `agentic-canvas`. The token travels in the entry `agentic-canvas.bearer.<token in base64url>`. |
+| `WorkerEnv` (type), `AppOptions` (type), `Role` (type) | Types for the Worker bindings, the app options and the role, `editor` or `viewer`. |
+
+### `agentic-canvas/live-worker`
+
+| Name | What it is |
+|---|---|
+| `default` | The Worker with live rooms. Bind the `SyncRoom` class as `SYNC_ROOM`. |
+| `SyncRoom` | The Durable Object class of the live rooms, re-exported from `agentic-realtime/worker`. |
+| `LiveEnv` (type) | The Worker bindings, plus `SYNC_ROOM`. |
+
 ## Limits
 
 - Canvas takes principal kinds, regions, and the Store and Blobs ports from `agentic-identity` 0.5.

package/dist/{chunk-HPUYT5TC.js → chunk-BIIC2DPZ.js}

@@ -1,15 +1,15 @@
 import {
   CanvasService,
   MAX_LIVE_BYTES
-} from "./chunk-J52RPFRP.js";
+} from "./chunk-G4YTESPS.js";
 import {
-  CanvasError,
-  principalSchema
-} from "./chunk-JZA525X5.js";
+  CanvasError
+} from "./chunk-JCYNPYYJ.js";
 
 // src/worker.ts
-import { parseRegion } from "agentic-identity";
+import { hasScope, parsePrincipal, parseRegion } from "agentic-identity";
 import { createD1Store, createR2Blobs, D1_SCHEMA } from "agentic-identity/cloudflare";
+import { acceptWebSocketProtocol, principalFromWebSocketRequest } from "agentic-identity/http";
 
 // node_modules/hono/dist/request/constants.js
 var GET_MATCH_RESULT = /* @__PURE__ */ Symbol();
@@ -1948,36 +1948,41 @@ function sameText(a, b) {
   for (let i = 0; i < Math.max(x.length, y.length); i++) diff |= (x[i] ?? 0) ^ (y[i] ?? 0);
   return diff === 0;
 }
-var WS_PROTOCOL = "agentic-canvas.bearer";
-function socketToken(request) {
-  if (request.headers.get("upgrade") !== "websocket") return void 0;
-  const [name, encoded, ...more] = (request.headers.get("sec-websocket-protocol") ?? "").split(",").map((p) => p.trim());
-  if (name !== WS_PROTOCOL || !encoded || more.length > 0 || !/^[A-Za-z0-9_-]+$/.test(encoded)) return void 0;
-  try {
-    return new TextDecoder("utf-8", { fatal: true }).decode(Uint8Array.from(atob(encoded.replace(/-/g, "+").replace(/_/g, "/")), (c) => c.charCodeAt(0)));
-  } catch {
-    return void 0;
-  }
+var WS_PROTOCOL = "agentic-canvas";
+function tokenAuth(env) {
+  return {
+    async authenticate(request) {
+      const token = /^Bearer (.+)$/.exec(request.headers.get("authorization") ?? "")?.[1];
+      if (!token || !env.CANVAS_API_TOKENS) return null;
+      let grants;
+      try {
+        grants = JSON.parse(env.CANVAS_API_TOKENS);
+      } catch {
+        return null;
+      }
+      if (typeof grants !== "object" || grants === null || Array.isArray(grants)) return null;
+      let found;
+      for (const [candidate, grant] of Object.entries(grants)) {
+        if (sameText(candidate, token) && candidate.length >= MIN_TOKEN_LENGTH) found = grant;
+      }
+      if (typeof found !== "object" || found === null) return null;
+      const { actor, kind, role = "editor" } = found;
+      let step;
+      try {
+        step = parsePrincipal({ kind, id: actor });
+      } catch {
+        return null;
+      }
+      if (step.kind === SEEDER.kind && step.id === SEEDER.id) return null;
+      if (role !== "editor" && role !== "viewer") return null;
+      return { principalId: step.id, kind: step.kind, chain: [step], scopes: role === "viewer" ? ["canvas:read"] : ["canvas:read", "canvas:write"] };
+    }
+  };
 }
-function authenticate(request, env) {
-  const token = /^Bearer (.+)$/.exec(request.headers.get("authorization") ?? "")?.[1] ?? socketToken(request);
-  if (!token || !env.CANVAS_API_TOKENS) return null;
-  let grants;
-  try {
-    grants = JSON.parse(env.CANVAS_API_TOKENS);
-  } catch {
-    return null;
-  }
-  if (typeof grants !== "object" || grants === null || Array.isArray(grants)) return null;
-  let found;
-  for (const [candidate, grant] of Object.entries(grants)) {
-    if (sameText(candidate, token) && candidate.length >= MIN_TOKEN_LENGTH) found = grant;
-  }
-  if (typeof found !== "object" || found === null) return null;
-  const { actor, kind, role = "editor" } = found;
-  const parsed = principalSchema.safeParse({ kind, id: actor });
-  const taken = parsed.success && parsed.data.kind === SEEDER.kind && parsed.data.id === SEEDER.id;
-  return parsed.success && !taken && (role === "editor" || role === "viewer") ? { actor: parsed.data, role } : null;
+async function authenticate(request, env) {
+  const found = await principalFromWebSocketRequest(request, tokenAuth(env), { protocol: WS_PROTOCOL });
+  if (found instanceof Response) return null;
+  return { actor: { kind: found.kind, id: found.principalId }, role: hasScope(found.scopes, "canvas:write") ? "editor" : "viewer" };
 }
 function sniffImage(bytes) {
   const at = (offset, ...sig) => sig.every((b, i) => bytes[offset + i] === b);
@@ -2056,7 +2061,7 @@ function createApp(options = {}) {
       return fail("NOT_CONFIGURED", 'set CANVAS_REGION to "eu", "us", or "unknown"', 503);
     }
     if (!c.env.DB || !c.env.IMAGES) return fail("NOT_CONFIGURED", "bind DB (D1) and IMAGES (R2)", 503);
-    const who = authenticate(c.req.raw, c.env);
+    const who = await authenticate(c.req.raw, c.env);
     if (!who) return fail("UNAUTHORIZED", "send a valid bearer token", 401);
     if (who.role === "viewer" && c.req.method !== "GET") return fail("FORBIDDEN", "this token is a viewer; it cannot change a board", 403);
     c.set("actor", who.actor);
@@ -2092,10 +2097,7 @@ function createApp(options = {}) {
     await saveRoom(c, true);
     const { actor, role } = c.var;
     const opened = await options.live(c.env).connect(id, c.req.raw, { principal: { id: actor.id, kind: actor.kind }, role, name: actor.id });
-    if (opened.status !== 101 || c.req.header("authorization") || !socketToken(c.req.raw)) return opened;
-    const headers = new Headers(opened.headers);
-    headers.set("sec-websocket-protocol", WS_PROTOCOL);
-    return new Response(null, { status: 101, headers, webSocket: opened.webSocket });
+    return acceptWebSocketProtocol(c.req.raw, opened, WS_PROTOCOL);
   });
   api.get("/boards/:id/state", async (c) => !options.live ? fail("NOT_FOUND", "this server hosts no live rooms", 404) : c.body(new Uint8Array(await c.var.service.state(c.req.param("id"))), 200, { "content-type": "application/octet-stream" }));
   api.post("/boards/:id/checkpoint", async (c) => {

package/dist/{chunk-J52RPFRP.js → chunk-G4YTESPS.js}

@@ -1,14 +1,16 @@
+import {
+  FileStoreError
+} from "./chunk-NWQED42L.js";
 import {
   Board,
   CanvasError,
   drawFlow,
-  principalSchema,
   readBoard,
   toSvg
-} from "./chunk-JZA525X5.js";
+} from "./chunk-JCYNPYYJ.js";
 import {
-  FileStoreError
-} from "./chunk-NWQED42L.js";
+  principalSchema
+} from "./chunk-SPP6PINW.js";
 
 // src/service.ts
 import * as Y from "yjs";

package/dist/{chunk-JZA525X5.js → chunk-JCYNPYYJ.js}

@@ -1,12 +1,12 @@
-// src/core/principal.ts
-import { PRINCIPAL_KINDS, isMachineMade } from "agentic-identity";
-import { z } from "zod";
-var principalSchema = z.object({ kind: z.enum(PRINCIPAL_KINDS), id: z.string().min(1).max(200) }).strict();
+import {
+  isMachineMade,
+  principalSchema
+} from "./chunk-SPP6PINW.js";
 
 // src/core/board.ts
 import { randomUUID } from "crypto";
 import * as Y from "yjs";
-import { z as z2 } from "zod";
+import { z } from "zod";
 var CanvasError = class extends Error {
   constructor(code, message) {
     super(message);
@@ -18,18 +18,18 @@ var CanvasError = class extends Error {
 var SHAPE_TYPES = ["rect", "ellipse", "diamond", "text", "sticky", "frame", "image"];
 var MAX_ELEMENTS = 1e4;
 var MAX_TEXT = 1e4;
-var id = z2.string().regex(/^[A-Za-z0-9_-]{1,64}$/);
-var coord = z2.number().finite().min(-1e7).max(1e7);
-var size = z2.number().finite().gt(0).max(1e7);
-var text = z2.string().max(MAX_TEXT);
+var id = z.string().regex(/^[A-Za-z0-9_-]{1,64}$/);
+var coord = z.number().finite().min(-1e7).max(1e7);
+var size = z.number().finite().gt(0).max(1e7);
+var text = z.string().max(MAX_TEXT);
 var COLOR_PATTERN = /^(#[0-9a-fA-F]{3,8}|[a-z]{3,20})$/;
 var IMAGE_PATTERN = /^(data:image\/(png|jpeg|gif|webp);base64,[A-Za-z0-9+/]+=*|blob:[A-Za-z0-9._-]{1,200})$/;
-var color = z2.string().regex(COLOR_PATTERN);
-var imageSrc = z2.string().max(2e6).regex(IMAGE_PATTERN);
-var endpoint = z2.union([z2.object({ id }).strict(), z2.object({ x: coord, y: coord }).strict()]);
-var shapeInput = z2.object({
+var color = z.string().regex(COLOR_PATTERN);
+var imageSrc = z.string().max(2e6).regex(IMAGE_PATTERN);
+var endpoint = z.union([z.object({ id }).strict(), z.object({ x: coord, y: coord }).strict()]);
+var shapeInput = z.object({
   id: id.optional(),
-  type: z2.enum(SHAPE_TYPES),
+  type: z.enum(SHAPE_TYPES),
   x: coord,
   y: coord,
   w: size.default(120),
@@ -41,40 +41,40 @@ var shapeInput = z2.object({
 }).strict().refine((s) => s.type === "image" === (s.src !== void 0), {
   message: "src is required for image shapes and allowed on no other type"
 });
-var connectorInput = z2.object({
+var connectorInput = z.object({
   id: id.optional(),
   from: endpoint,
   to: endpoint,
   text: text.default(""),
-  startArrow: z2.boolean().default(false),
-  endArrow: z2.boolean().default(true),
+  startArrow: z.boolean().default(false),
+  endArrow: z.boolean().default(true),
   stroke: color.optional()
 }).strict();
-var shapePatch = z2.object({ x: coord, y: coord, w: size, h: size, text, fill: color, stroke: color, src: imageSrc }).partial().strict();
-var connectorPatch = z2.object({ from: endpoint, to: endpoint, text, startArrow: z2.boolean(), endArrow: z2.boolean(), stroke: color }).partial().strict();
-var delta = z2.number().finite().min(-2e7).max(2e7);
+var shapePatch = z.object({ x: coord, y: coord, w: size, h: size, text, fill: color, stroke: color, src: imageSrc }).partial().strict();
+var connectorPatch = z.object({ from: endpoint, to: endpoint, text, startArrow: z.boolean(), endArrow: z.boolean(), stroke: color }).partial().strict();
+var delta = z.number().finite().min(-2e7).max(2e7);
 var MAX_Z = 1e9;
 var stampFields = {
   id,
-  z: z2.number().finite().min(-MAX_Z).max(MAX_Z),
+  z: z.number().finite().min(-MAX_Z).max(MAX_Z),
   groupId: id.optional(),
   author: principalSchema,
   editedBy: principalSchema
 };
-var storedShape = z2.object({ ...stampFields, type: z2.enum(SHAPE_TYPES), x: coord, y: coord, w: size, h: size, text, fill: color.optional(), stroke: color.optional(), src: imageSrc.optional() }).refine((s) => s.type === "image" === (s.src !== void 0), { message: "src is required for image shapes and allowed on no other type" });
-var storedConnector = z2.object({
+var storedShape = z.object({ ...stampFields, type: z.enum(SHAPE_TYPES), x: coord, y: coord, w: size, h: size, text, fill: color.optional(), stroke: color.optional(), src: imageSrc.optional() }).refine((s) => s.type === "image" === (s.src !== void 0), { message: "src is required for image shapes and allowed on no other type" });
+var storedConnector = z.object({
   ...stampFields,
-  type: z2.literal("connector"),
+  type: z.literal("connector"),
   from: endpoint,
   to: endpoint,
   text,
-  startArrow: z2.boolean(),
-  endArrow: z2.boolean(),
+  startArrow: z.boolean(),
+  endArrow: z.boolean(),
   stroke: color.optional()
 });
-var storedGroup = z2.object({ ...stampFields, type: z2.literal("group") });
-var storedElement = z2.union([storedShape, storedConnector, storedGroup]);
-var titleSchema = z2.string().max(200);
+var storedGroup = z.object({ ...stampFields, type: z.literal("group") });
+var storedElement = z.union([storedShape, storedConnector, storedGroup]);
+var titleSchema = z.string().max(200);
 function parse(schema, value) {
   const result = schema.safeParse(value);
   if (!result.success) {
@@ -133,7 +133,7 @@ var Board = class _Board {
     return value.success ? value.data : void 0;
   }
   setTitle(title, actor) {
-    const t = parse(z2.string().max(200), title);
+    const t = parse(z.string().max(200), title);
     const by = parse(principalSchema, actor);
     this.doc.transact(() => {
       this.meta.set("title", t);
@@ -324,7 +324,7 @@ var Board = class _Board {
   /** Shift an element, or a whole group. Returns the ids that moved. Bound connector ends follow their shapes. */
   move(elementId, dx, dy, actor) {
     const by = parse(principalSchema, actor);
-    const [mx, my] = parse(z2.tuple([delta, delta]), [dx, dy]);
+    const [mx, my] = parse(z.tuple([delta, delta]), [dx, dy]);
     this.require(elementId);
     const free = (e) => hasId(e) ? e : { x: e.x + mx, y: e.y + my };
     const plan = [];
@@ -353,7 +353,7 @@ var Board = class _Board {
   }
   group(ids, actor, groupId) {
     const by = parse(principalSchema, actor);
-    const members = parse(z2.array(id).min(2).max(MAX_ELEMENTS), ids);
+    const members = parse(z.array(id).min(2).max(MAX_ELEMENTS), ids);
     const gid = parse(id.optional(), groupId);
     if (new Set(members).size !== members.length) throw new CanvasError("INVALID", "member ids repeat");
     const parents = new Set(members.map((m) => this.require(m).groupId));
@@ -423,12 +423,12 @@ var Board = class _Board {
   }
   /** The z value just past the top or the bottom. Not clamped: the caller checks the range. */
   edgeZ(direction) {
-    let z3 = 0;
+    let z2 = 0;
     for (const m of this.elements.values()) {
       const value = m instanceof Y.Map ? m.get("z") : void 0;
-      if (isValidZ(value)) z3 = direction === 1 ? Math.max(z3, value) : Math.min(z3, value);
+      if (isValidZ(value)) z2 = direction === 1 ? Math.max(z2, value) : Math.min(z2, value);
     }
-    return z3 + direction;
+    return z2 + direction;
   }
   /** The element and, for a group, everything below it. Cycle-safe. */
   subtree(elementId) {
@@ -764,9 +764,6 @@ function toSvg(board) {
 }
 
 export {
-  PRINCIPAL_KINDS,
-  isMachineMade,
-  principalSchema,
   CanvasError,
   SHAPE_TYPES,
   MAX_ELEMENTS,

package/dist/{chunk-TSWXD4YG.js → chunk-SIDWRC3P.js}

@@ -1,13 +1,14 @@
 import {
   CanvasError,
-  PRINCIPAL_KINDS,
-  SHAPE_TYPES,
-  principalSchema
-} from "./chunk-JZA525X5.js";
+  SHAPE_TYPES
+} from "./chunk-JCYNPYYJ.js";
+import {
+  PRINCIPAL_KINDS
+} from "./chunk-SPP6PINW.js";
 
 // src/version.ts
 import { createRequire } from "module";
-var VERSION = true ? "0.4.0" : readPackageVersion();
+var VERSION = true ? "0.6.0" : readPackageVersion();
 
 // src/brand.ts
 var BRAND = {
@@ -16,20 +17,6 @@ var BRAND = {
   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;
@@ -62,6 +49,22 @@ async function svgToPng(svg) {
   }
 }
 
+// src/actor.ts
+import { parsePrincipal } from "agentic-identity";
+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(":");
+  try {
+    if (at < 0) throw new Error("no kind");
+    return parsePrincipal({ kind: raw.slice(0, at), id: raw.slice(at + 1) });
+  } catch {
+    throw new ActorConfigError(`bad CANVAS_ACTOR "${raw}": use <kind>:<id>, kind is one of ${PRINCIPAL_KINDS.join(", ")}`);
+  }
+}
+
 // src/mcp.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -171,9 +174,9 @@ async function runMcp(service, actor) {
 export {
   VERSION,
   BRAND,
+  svgToPng,
   ActorConfigError,
   operatorActor,
-  svgToPng,
   createMcpServer,
   runMcp
 };

package/dist/chunk-SPP6PINW.js

@@ -0,0 +1,10 @@
+// src/core/principal.ts
+import { PRINCIPAL_KINDS, isMachineMade } from "agentic-identity";
+import { z } from "zod";
+var principalSchema = z.object({ kind: z.enum(PRINCIPAL_KINDS), id: z.string().min(1).max(200) }).strict();
+
+export {
+  PRINCIPAL_KINDS,
+  isMachineMade,
+  principalSchema
+};

package/dist/cli.js

@@ -5,17 +5,18 @@ import {
   operatorActor,
   runMcp,
   svgToPng
-} from "./chunk-TSWXD4YG.js";
+} from "./chunk-SIDWRC3P.js";
 import {
   openLocalStore
 } from "./chunk-UKST5A57.js";
 import {
   CanvasService
-} from "./chunk-J52RPFRP.js";
+} from "./chunk-G4YTESPS.js";
+import "./chunk-NWQED42L.js";
 import {
   CanvasError
-} from "./chunk-JZA525X5.js";
-import "./chunk-NWQED42L.js";
+} from "./chunk-JCYNPYYJ.js";
+import "./chunk-SPP6PINW.js";
 
 // src/cli.ts
 import { readFileSync, writeFileSync } from "fs";

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { E as ErrorCode, B as BoardData, S as ShapeType, a as Shape, b as Endpoint, C as Connector } from './read-Bdg1uiFC.js';
+import { E as ErrorCode, a as BoardData, c as ShapeType, S as Shape, d as Endpoint, C as Connector } from './read-BupIJSPJ.js';
 import { PrincipalKind } from 'agentic-identity';
 import 'yjs';
 import 'zod';

package/dist/embed.d.ts

@@ -0,0 +1,46 @@
+import * as react from 'react';
+import { CanvasClient } from './client.js';
+import { PrincipalKind } from 'agentic-identity';
+import './read-BupIJSPJ.js';
+import 'yjs';
+import 'zod';
+
+interface RoomOptions {
+    /** The API root, for example `https://canvas.example.com/api/v1/canvas`. */
+    baseUrl: string;
+    /** The bearer token for the room. */
+    token: string;
+}
+
+/** Who uses the board. The server still checks every write against its own token. */
+interface BoardPrincipal {
+    kind: PrincipalKind;
+    name: string;
+    /** Only `editor` can change the board. Any other value, or no value, opens it read only. */
+    role?: "editor" | "viewer";
+}
+interface BoardEditorOptions {
+    /** The board id. */
+    boardId: string;
+    /** Loads and changes the board. A client from `createClient` in `agentic-canvas/client` works. */
+    client: CanvasClient;
+    principal: BoardPrincipal;
+    /** Open the board read only, even for an editor. */
+    readOnly?: boolean;
+    /** The live room. With one, the board shows who else is here and reads again when they save. */
+    room?: RoomOptions;
+    /** A link for a missing board to go back to. */
+    backHref?: string;
+}
+/** The board for one id, with its toolbar, presence, and side panel. It needs the providers of `agentic-design`. A bad principal shows an alert. */
+declare function BoardEditor(options: BoardEditorOptions): react.JSX.Element;
+interface MountedBoard {
+    /** Show another board, principal, or room in the same place. A bad principal throws and keeps the board as it is. */
+    update(options: BoardEditorOptions): void;
+    /** Remove the board, leave the live room, and stop its timers. */
+    unmount(): void;
+}
+/** Render the board into an element, for an app that does not use React itself. */
+declare function mount(element: HTMLElement, options: BoardEditorOptions): MountedBoard;
+
+export { BoardEditor, type BoardEditorOptions, type BoardPrincipal, CanvasClient, type MountedBoard, type RoomOptions, mount };