agentic-canvas 0.10.0 → 0.11.0

package/dist/embed.js

@@ -1,6 +1,9 @@
 import {
-  PRINCIPAL_KINDS
-} from "./chunk-JOBTIAFJ.js";
+  Board,
+  PRINCIPAL_KINDS,
+  principalSchema,
+  readBoard
+} from "./chunk-MVWUIBGV.js";
 
 // ui/embed.tsx
 import { ToastProvider, TooltipProvider } from "agentic-design/react";
@@ -9,7 +12,7 @@ import { createRoot } from "react-dom/client";
 
 // ui/BoardView.tsx
 import { Button as Button2, EmptyState, Input, PresenceChip, PresenceStack, Select, Textarea, Toolbar, ToolbarButton, ToolbarSeparator, useToast } from "agentic-design/react";
-import { useCallback, useEffect as useEffect2, useRef as useRef2, useState as useState2 } from "react";
+import { useCallback, useEffect as useEffect2, useMemo, useRef as useRef2, useState as useState2 } from "react";
 
 // ui/errors.ts
 var isApiError = (error) => typeof error === "object" && error !== null && error.name === "CanvasApiError" && typeof error.code === "string" && typeof error.status === "number";
@@ -226,6 +229,29 @@ function Failure({ message, retry }) {
   ] });
 }
 
+// ui/host.ts
+import * as Y from "yjs";
+function checkHost(host) {
+  if (!host || !(host.doc instanceof Y.Doc)) throw new TypeError("a host board needs a Yjs document in `doc`");
+  const presence = host.presence;
+  if (presence !== void 0 && (!Array.isArray(presence?.peers) || typeof presence.onPeers !== "function")) {
+    throw new TypeError("a host presence needs peers and onPeers, as a SyncClient has");
+  }
+  if (host.status !== void 0 && typeof host.status !== "function" || host.onStatus !== void 0 && typeof host.onStatus !== "function") {
+    throw new TypeError("a host status and onStatus must be functions");
+  }
+}
+function boardCalls(board, who) {
+  return {
+    readBoard: async (id) => ({ id, ...readBoard(board) }),
+    addShape: async (_id, shape) => board.addShape(shape, who()),
+    addConnector: async (_id, connector) => board.addConnector(connector, who()),
+    update: async (_id, element, patch) => board.update(element, patch, who()),
+    move: async (_id, element, dx, dy) => ({ moved: board.move(element, dx, dy, who()) }),
+    remove: async (_id, element) => ({ removed: board.remove(element) })
+  };
+}
+
 // ui/presence.ts
 import { SyncClient } from "agentic-realtime/client";
 var WS_PROTOCOL = "agentic-canvas";
@@ -288,7 +314,7 @@ var TOOLS = [
 var POLL_MS = 5e3;
 var DEFAULT_SIZE = { rect: [140, 70], ellipse: [140, 70], diamond: [140, 90], text: [140, 40], sticky: [150, 120] };
 var DEFAULT_TEXT = { rect: "Rectangle", ellipse: "Ellipse", diamond: "Decision", text: "Text", sticky: "Note" };
-function BoardView({ id, client, room: roomOptions, me, backHref }) {
+function BoardView({ id, client: remote, host, room: roomOptions, me, backHref }) {
   const roomUrl2 = roomOptions?.baseUrl;
   const roomToken = roomOptions?.token;
   const toast = useToast();
@@ -302,6 +328,17 @@ function BoardView({ id, client, room: roomOptions, me, backHref }) {
   const queue = useRef2(Promise.resolve());
   const canvasBox = useRef2(null);
   const editable = me.role === "editor";
+  const hostDoc = host?.doc;
+  const hostPresence = host?.presence;
+  const hostRef = useRef2(host);
+  hostRef.current = host;
+  const who = useRef2({ kind: me.kind, id: me.id ?? me.actor });
+  who.current = { kind: me.kind, id: me.id ?? me.actor };
+  const client = useMemo(() => {
+    if (hostDoc) return boardCalls(new Board(hostDoc), () => who.current);
+    if (!remote) throw new TypeError("the board needs a client or a host board");
+    return remote;
+  }, [remote, hostDoc]);
   const [saving, setSaving] = useState2(0);
   const pending = useRef2(0);
   const generation = useRef2(0);
@@ -319,7 +356,7 @@ function BoardView({ id, client, room: roomOptions, me, backHref }) {
   }, [client, id]);
   const load = useCallback(async () => {
     if (pending.current > 0) return;
-    const wait = lastRead.current + 1e3 - Date.now();
+    const wait = hostDoc ? 0 : lastRead.current + 1e3 - Date.now();
     if (wait > 0) {
       clearTimeout(timer.current);
       timer.current = setTimeout(() => void load(), wait);
@@ -327,7 +364,7 @@ function BoardView({ id, client, room: roomOptions, me, backHref }) {
     }
     lastRead.current = Date.now();
     await read();
-  }, [read]);
+  }, [read, hostDoc]);
   useEffect2(() => {
     setBoard({ state: "loading" });
     lastRead.current = 0;
@@ -341,15 +378,45 @@ function BoardView({ id, client, room: roomOptions, me, backHref }) {
     return () => window.removeEventListener("beforeunload", guard);
   }, [saving]);
   useEffect2(() => {
-    if (roomUrl2 === void 0 || roomToken === void 0) return;
-    const joined = joinRoom({ board: id, baseUrl: roomUrl2, token: roomToken, name: me.actor, onPeers: setPeers, onChange: () => void load(), onStatus: setLive });
+    if (!hostDoc) return;
+    let queued = false;
+    const changed = () => {
+      if (queued) return;
+      queued = true;
+      queueMicrotask(() => (queued = false, void load()));
+    };
+    const elements = hostDoc.getMap("elements");
+    const meta = hostDoc.getMap("meta");
+    elements.observeDeep(changed);
+    meta.observe(changed);
+    return () => (elements.unobserveDeep(changed), meta.unobserve(changed));
+  }, [hostDoc, load]);
+  useEffect2(() => {
+    if (!hostPresence) return;
+    setPeers(hostPresence.peers.map(toEntry));
+    const off = hostPresence.onPeers((list) => setPeers(list.map(toEntry)));
+    return () => (off(), setPeers([]));
+  }, [hostPresence]);
+  useEffect2(() => {
+    if (!hostDoc) return;
+    const reset = () => setLive(false);
+    const { status: ask, onStatus: listen } = hostRef.current ?? {};
+    setLive(ask ? ask() === "connected" : !listen);
+    const stop = listen?.((next) => setLive(next === "connected"));
+    return () => (stop?.(), reset());
+  }, [hostDoc]);
+  useEffect2(() => {
+    if (hostDoc || roomUrl2 === void 0 || roomToken === void 0) return;
+    let left = false;
+    const joined = joinRoom({ board: id, baseUrl: roomUrl2, token: roomToken, name: me.actor, onPeers: (list) => !left && setPeers(list), onChange: () => !left && void load(), onStatus: (up) => !left && setLive(up) });
     room.current = joined;
-    return () => (joined.leave(), room.current = void 0);
-  }, [id, roomUrl2, roomToken, me.actor, load]);
+    return () => (left = true, joined.leave(), setPeers([]), room.current = void 0);
+  }, [id, hostDoc, roomUrl2, roomToken, me.actor, load]);
   useEffect2(() => {
+    if (hostDoc) return;
     const timer2 = setInterval(() => void load(), POLL_MS);
     return () => clearInterval(timer2);
-  }, [load]);
+  }, [load, hostDoc]);
   const write = useCallback(
     (change, failure, select) => {
       pending.current++;
@@ -425,7 +492,7 @@ function BoardView({ id, client, room: roomOptions, me, backHref }) {
       /* @__PURE__ */ jsx3(ToolbarButton, { label: "Reset view", icon: icon(/* @__PURE__ */ jsx3("path", { d: "M4 4h5M4 4v5M16 16h-5M16 16v-5" })), onClick: () => setView(HOME) })
     ] }),
     /* @__PURE__ */ jsx3("p", { className: "note", role: "status", children: editable ? status : "" }),
-    !editable && /* @__PURE__ */ jsx3("p", { className: "note", children: "This token can read the board but not change it." }),
+    !editable && /* @__PURE__ */ jsx3("p", { className: "note", children: host ? "This board is read only." : "This token can read the board but not change it." }),
     /* @__PURE__ */ jsxs3("div", { className: "stage", ref: canvasBox, children: [
       /* @__PURE__ */ jsx3(Canvas, { data: d, selected, editable, view, onView: setView, onSelect: setSelected, onMove: move, onResize: resize, onDelete: remove }),
       empty && /* @__PURE__ */ jsx3("div", { className: "empty-overlay", children: /* @__PURE__ */ jsx3(EmptyState, { title: "This board is empty", description: editable ? "Add a shape or a note with the tools above." : "Nothing has been drawn yet." }) }),
@@ -487,10 +554,18 @@ function Inspector({ item, nodes, editable, onText, onPlace, onDelete, onConnect
 
 // ui/embed.tsx
 import { jsx as jsx4, jsxs as jsxs4 } from "react/jsx-runtime";
-function checkPrincipal(principal) {
+function checkPrincipal(principal, options) {
   if (!principal || !PRINCIPAL_KINDS.includes(principal.kind) || typeof principal.name !== "string" || principal.name.trim() === "") {
     throw new TypeError(`the board needs a principal with a kind (${PRINCIPAL_KINDS.join(", ")}) and a name`);
   }
+  if (!options) return;
+  if (options.host) {
+    checkHost(options.host);
+    if (options.client) throw new TypeError("a host board writes to its own document, not through a `client`: give one of them");
+    const stamp = principalSchema.safeParse({ kind: options.principal.kind, id: options.principal.id ?? options.principal.name });
+    if (!stamp.success) throw new TypeError(`the principal needs an \`id\` of letters, digits, ".", "_" and "-" to stamp its writes: ${stamp.error.issues[0]?.message}`);
+    if (options.room) throw new TypeError("a host board has no live room of its own: give its presence in `host.presence`, not `room`");
+  } else if (!options.client) throw new TypeError("the board needs a `client`, or a `host` board");
 }
 var Boundary = class extends Component {
   state = { failed: false };
@@ -504,16 +579,16 @@ var Boundary = class extends Component {
     ] }) }) : this.props.children;
   }
 };
-function Board({ boardId, client, principal, readOnly, room, backHref }) {
-  checkPrincipal(principal);
+function Board2({ boardId, client, host, principal, readOnly, room, backHref }) {
+  checkPrincipal(principal, { boardId, client, host, principal, room });
   const role = principal.role === "editor" && !readOnly ? "editor" : "viewer";
-  return /* @__PURE__ */ jsx4(BoardView, { id: boardId, client, room, backHref, me: { actor: principal.name, kind: principal.kind, role } }, boardId);
+  return /* @__PURE__ */ jsx4(BoardView, { id: boardId, client, host, room, backHref, me: { actor: principal.name, id: principal.id, kind: principal.kind, role } }, boardId);
 }
 function BoardEditor(options) {
-  return /* @__PURE__ */ jsx4("div", { className: "cv-root", children: /* @__PURE__ */ jsx4(Boundary, { children: /* @__PURE__ */ jsx4(Board, { ...options }) }) });
+  return /* @__PURE__ */ jsx4("div", { className: "cv-root", children: /* @__PURE__ */ jsx4(Boundary, { children: /* @__PURE__ */ jsx4(Board2, { ...options }) }) });
 }
 function mount(element, options) {
-  checkPrincipal(options.principal);
+  checkPrincipal(options.principal, options);
   const root = createRoot(element);
   const render = (next) => root.render(
     /* @__PURE__ */ jsx4(TooltipProvider, { children: /* @__PURE__ */ jsx4(ToastProvider, { children: /* @__PURE__ */ jsx4(BoardEditor, { ...next }) }) })
@@ -521,7 +596,7 @@ function mount(element, options) {
   render(options);
   let open = true;
   return {
-    update: (next) => (checkPrincipal(next.principal), open && render(next)),
+    update: (next) => (checkPrincipal(next.principal, next), open && render(next)),
     unmount: () => {
       if (!open) return;
       open = false;

package/dist/index.js

@@ -6,34 +6,34 @@ import {
   operatorActor,
   runMcp,
   svgToPng
-} from "./chunk-NLTN7J22.js";
+} from "./chunk-EE725BJ3.js";
 import {
   createFileStore,
   openLocalStore
 } from "./chunk-NRLF6MGR.js";
 import {
   CanvasService
-} from "./chunk-M74ENUWR.js";
+} from "./chunk-Z6KLGAFP.js";
 import "./chunk-NWQED42L.js";
 import {
-  Board,
-  CanvasError,
-  MAX_ELEMENTS,
   MAX_FLOW_EDGES,
   MAX_FLOW_NODES,
-  MAX_TEXT,
-  SHAPE_TYPES,
   drawFlow,
   layoutFlow,
   parseFlow,
-  readBoard,
   toSvg
-} from "./chunk-ZSPZMGHG.js";
+} from "./chunk-EDQNA2SU.js";
 import {
+  Board,
+  CanvasError,
+  MAX_ELEMENTS,
+  MAX_TEXT,
   PRINCIPAL_KINDS,
+  SHAPE_TYPES,
   isMachineMade,
-  principalSchema
-} from "./chunk-JOBTIAFJ.js";
+  principalSchema,
+  readBoard
+} from "./chunk-MVWUIBGV.js";
 export {
   ActorConfigError,
   BRAND,

package/dist/live-worker.js

@@ -1,12 +1,12 @@
 import {
   createApp
-} from "./chunk-JQCUVXXD.js";
-import "./chunk-M74ENUWR.js";
+} from "./chunk-5II2WZIL.js";
+import "./chunk-Z6KLGAFP.js";
 import "./chunk-NWQED42L.js";
+import "./chunk-EDQNA2SU.js";
 import {
   CanvasError
-} from "./chunk-ZSPZMGHG.js";
-import "./chunk-JOBTIAFJ.js";
+} from "./chunk-MVWUIBGV.js";
 
 // src/live-worker.ts
 import { parseRegion } from "agentic-identity";

package/dist/live.js

@@ -1,11 +1,12 @@
 import {
-  Board,
-  CanvasError,
   drawFlow,
-  readBoard,
   toSvg
-} from "./chunk-ZSPZMGHG.js";
-import "./chunk-JOBTIAFJ.js";
+} from "./chunk-EDQNA2SU.js";
+import {
+  Board,
+  CanvasError,
+  readBoard
+} from "./chunk-MVWUIBGV.js";
 
 // src/live.ts
 import { parsePrincipal } from "agentic-identity";

package/dist/worker.js

@@ -5,11 +5,11 @@ import {
   identify,
   sniffImage,
   worker_default
-} from "./chunk-JQCUVXXD.js";
-import "./chunk-M74ENUWR.js";
+} from "./chunk-5II2WZIL.js";
+import "./chunk-Z6KLGAFP.js";
 import "./chunk-NWQED42L.js";
-import "./chunk-ZSPZMGHG.js";
-import "./chunk-JOBTIAFJ.js";
+import "./chunk-EDQNA2SU.js";
+import "./chunk-MVWUIBGV.js";
 export {
   WS_PROTOCOL,
   authenticate,

package/llms.txt

@@ -11,7 +11,7 @@ Keywords: whiteboard,canvas,diagrams,drawing,collaboration,agents,mcp,cli.
 - 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, listBoards, createBoard, readBoard, deleteBoard, exportSvg, addShape, addConnector, drawFlow, update, move, remove, access, grant, revoke, invite, uploadImage, getImage, state, checkpoint. A failure throws CanvasApiError with `code` and `status`. No retries.
-- UI: import { mount } from "agentic-canvas/ui"; import "agentic-canvas/ui.css" (with agentic-design/styles.css). mount(element, { boardId, client, principal: { kind, name, role }, readOnly?, room?: { baseUrl, token } }) renders the board and returns { update(options), unmount() }. BoardEditor is the same as a React component. React 19 is a peer dependency.
+- UI: import { mount } from "agentic-canvas/ui"; import "agentic-canvas/ui.css" (with agentic-design/styles.css). mount(element, { boardId, client, principal: { kind, name, role, id? }, readOnly?, room?: { baseUrl, token } }) (or host: { doc, presence?, status?, onStatus? } instead of client and room; in host mode id (default name) must be letters, digits, . _ -, to edit the app's own Yjs document with no HTTP call) renders the board and returns { update(options), unmount() }. BoardEditor is the same as a React component. React 19 is a peer dependency.
 
 ## Docs
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-canvas",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "A shared whiteboard for diagrams, drawn by people and agents.",
   "keywords": [
     "whiteboard",

package/dist/chunk-JOBTIAFJ.js

@@ -1,19 +0,0 @@
-// src/core/principal.ts
-import { PRINCIPAL_KINDS, isMachineMade, parsePrincipal } from "agentic-identity";
-import { z } from "zod";
-var principalSchema = z.object({ kind: z.string(), id: z.string() }).strict().transform((value, ctx) => {
-  try {
-    return parsePrincipal(value);
-  } catch (error) {
-    ctx.addIssue({ code: "custom", message: error instanceof Error ? error.message : "invalid principal" });
-    return z.NEVER;
-  }
-});
-var storedPrincipalSchema = z.object({ kind: z.enum(PRINCIPAL_KINDS), id: z.string().min(1).max(200) }).strict();
-
-export {
-  PRINCIPAL_KINDS,
-  isMachineMade,
-  principalSchema,
-  storedPrincipalSchema
-};