agentic-canvas 0.10.0 → 0.11.0

package/README.md

@@ -7,7 +7,7 @@
 
 A shared whiteboard for diagrams, drawn by people and agents.
 
-> Status: 0.10.0. The board model, the agent operations, the exports, the CLI, the
+> Status: 0.11.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.
@@ -283,6 +283,39 @@ server still checks every write against the token. The host page owns the theme.
 For a React app, `BoardEditor` is the same component without a root. Wrap it in the providers of
 `agentic-design/react`.
 
+### Use your own Yjs document
+
+An app that keeps the board in its own Yjs room gives it as `host`. The UI then reads and writes that document as a
+board (its `elements` and `meta` maps, the shape this package stores) and redraws as soon as the document changes.
+It makes no HTTP call, does not poll, and opens no live room. `client` is not needed. The default is still client
+mode: without `host`, the UI works as described above.
+
+```ts
+const board = mount(element, {
+  boardId: "b1",
+  principal: { kind: "human", name: "Ada", id: "ada", role: "editor" }, // id is stamped on what Ada writes; the default is name
+  host: {
+    doc,                       // a Y.Doc
+    presence: sync,            // optional: a SyncClient of agentic-realtime, or { peers, onPeers }
+    status: () => status,      // optional: "connecting" | "connected" | "disconnected"
+    onStatus: (listener) => stop, // optional: tell the UI when the status changes
+  },
+});
+```
+
+- Use the same `yjs` copy as the UI. A document from another copy is refused with a `TypeError`.
+- Each element the UI creates or edits is stamped with the principal's `id` and `kind`. A delete has no stamp. The `id` follows the identity rule of the
+  SDK (letters, digits, `.`, `_`, `-`). An agent kind marks its elements as machine-made. A refused write shows a message
+  and leaves the document alone. The server does not check these writes: your app and its room decide who may write.
+- In host mode `boardId` only keys the view. The UI shows the one board that the document holds (its `elements` and `meta` maps), so keep one board in each document.
+- A document pushed past the element cap (10,000) can no longer be read. If that happens after the first draw, the UI keeps the last board it drew. At mount it shows the error page with Retry. Your app should stop a peer from writing that far.
+- `client` or `room` together with `host` throws a `TypeError`, so a board never half-writes to a server. (`BoardEditor` shows an alert for these, as it does for a bad principal.) Give presence in `host.presence`.
+- The principal's `id` (default: `name`) must pass the identity rule, so a display name with a space needs an explicit `id`. A bad one throws a `TypeError` at mount.
+- The UI redraws only for changes in the document's `elements` and `meta` maps. Other data in the same document is left alone.
+- `status` and `onStatus` are read when the UI opens `doc`. A new function on `update()` does not open it again. `onStatus` alone starts as not live, until it reports "connected". With neither, the board shows as live. Give `onStatus` at mount to follow later changes. It is not picked up by a later `update()` for the same `doc`.
+- With `presence`, the UI shows the peers. It never sends a cursor, and never closes your room or your document.
+- On `unmount` the UI removes its observers from your document and leaves it as it is.
+
 Develop and test the UI:
 
 ```sh
@@ -291,7 +324,7 @@ npx playwright-core install chromium
 npm run test:e2e                   # Playwright against `wrangler dev`, with axe (WCAG 2.2 AA)
 ```
 
-The E2E run creates a board, adds a shape and a note, moves them, reloads, and checks each view
+`E2E_PORT` sets the port of the E2E server (default 18900). The E2E run creates a board, adds a shape and a note, moves them, reloads, and checks each view
 with axe in the light and the dark theme. It saves screenshots to `test-results/screens/`. The committed set in `docs/ui/` shows the UI at this release. Run `UPDATE_SCREENSHOTS=1 npm run test:e2e` to refresh it.
 
 A browser cannot set a header on a WebSocket, so the UI sends its token to the live room as a WebSocket sub-protocol (`Sec-WebSocket-Protocol`). A proxy that logs request headers can record it. The API itself takes the token only in an `Authorization` header, and the sub-protocol only on a WebSocket upgrade.
@@ -408,6 +441,7 @@ old author stays on its elements. Only new writes follow the strict rule.
 | `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. |
+| `HostBoard` (type) | The `host` option: `doc`, and optionally `presence`, `status`, and `onStatus`. |
 | `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.

package/dist/{chunk-JQCUVXXD.js → chunk-5II2WZIL.js}

@@ -3,10 +3,10 @@ import {
   MAX_LIVE_BYTES,
   isBoardId,
   isStoreId
-} from "./chunk-M74ENUWR.js";
+} from "./chunk-Z6KLGAFP.js";
 import {
   CanvasError
-} from "./chunk-ZSPZMGHG.js";
+} from "./chunk-MVWUIBGV.js";
 
 // src/worker.ts
 import { createStoreAuth, hasScope as hasScope2, parsePrincipal, parseRegion } from "agentic-identity";

package/dist/chunk-EDQNA2SU.js

@@ -0,0 +1,290 @@
+import {
+  COLOR_PATTERN,
+  CanvasError,
+  IMAGE_PATTERN,
+  MAX_ELEMENTS,
+  SHAPE_TYPES
+} from "./chunk-MVWUIBGV.js";
+
+// src/core/flow.ts
+import dagre from "@dagrejs/dagre";
+import * as Y from "yjs";
+var MAX_FLOW_NODES = 500;
+var MAX_FLOW_EDGES = 2e3;
+var MAX_FLOW_CHARS = 2e5;
+var NODE = String.raw`([A-Za-z0-9_-]{1,48})(?:\[([^\]]*)\]|\(([^)]*)\)|\{([^}]*)\})?`;
+var EDGE = new RegExp(String.raw`^${NODE}\s*->\s*${NODE}\s*(?::(.*))?$`);
+var ALONE = new RegExp(String.raw`^${NODE}$`);
+var SHAPES = ["rect", "ellipse", "diamond"];
+function parseFlow(source) {
+  if (source.length > MAX_FLOW_CHARS) throw new CanvasError("LIMIT", `flow text is over ${MAX_FLOW_CHARS} characters`);
+  const graph = { direction: "TB", nodes: [], edges: [] };
+  const byId = /* @__PURE__ */ new Map();
+  const fail = (line, message) => {
+    throw new CanvasError("INVALID", `line ${line}: ${message}`);
+  };
+  const node = (line, m, at) => {
+    const id = m[at];
+    if (/^edge_\d+$/.test(id)) fail(line, `"${id}" is reserved for connectors. Pick another node id.`);
+    const brackets = m.slice(at + 1, at + 4);
+    const open = brackets.findIndex((b) => b !== void 0);
+    const shape = SHAPES[Math.max(open, 0)];
+    const text = (open < 0 ? "" : brackets[open].trim()) || id;
+    const known = byId.get(id);
+    if (!known) {
+      const created = { id, text, shape, explicit: open >= 0 };
+      byId.set(id, created);
+      graph.nodes.push(created);
+    } else if (open >= 0) {
+      if (known.explicit && (known.text !== text || known.shape !== shape)) fail(line, `"${id}" is defined twice with different text`);
+      Object.assign(known, { text, shape, explicit: true });
+    }
+    return id;
+  };
+  source.replace(/^/, "").split(/\r?\n/).forEach((raw, index) => {
+    const line = index + 1;
+    const text = raw.trim();
+    if (text === "" || text.startsWith("#") || text.startsWith("//")) return;
+    if (/[\u0000-\u0008\u000a-\u001f\u007f]/.test(text)) fail(line, "control characters are not allowed");
+    const direction = /^direction\s+(\S+)$/.exec(text);
+    if (direction) {
+      if (direction[1] !== "TB" && direction[1] !== "LR") fail(line, `direction must be TB or LR, got "${direction[1]}"`);
+      graph.direction = direction[1];
+      return;
+    }
+    const edge = EDGE.exec(text);
+    if (edge) {
+      const from = node(line, edge, 1);
+      const to = node(line, edge, 5);
+      graph.edges.push({ from, to, text: (edge[9] ?? "").trim() });
+    } else {
+      const alone = ALONE.exec(text);
+      if (!alone) fail(line, `cannot read "${text.slice(0, 40)}". Use "A -> B: label".`);
+      else node(line, alone, 1);
+    }
+    if (graph.nodes.length > MAX_FLOW_NODES) throw new CanvasError("LIMIT", `a flow holds at most ${MAX_FLOW_NODES} nodes`);
+    if (graph.edges.length > MAX_FLOW_EDGES) throw new CanvasError("LIMIT", `a flow holds at most ${MAX_FLOW_EDGES} edges`);
+  });
+  if (graph.nodes.length === 0) throw new CanvasError("INVALID", "the flow has no nodes");
+  return { ...graph, nodes: graph.nodes.map(({ id, text, shape }) => ({ id, text, shape })) };
+}
+function sizeOf(n) {
+  const w = Math.min(360, Math.max(120, 24 + 8 * n.text.length));
+  return n.shape === "diamond" ? { w: Math.min(360, Math.round(w * 1.5)), h: 90 } : { w, h: 60 };
+}
+function layoutFlow(graph) {
+  const g = new dagre.graphlib.Graph({ multigraph: true });
+  g.setGraph({ rankdir: graph.direction, nodesep: 40, ranksep: 70, marginx: 0, marginy: 0 });
+  g.setDefaultEdgeLabel(() => ({}));
+  const index = new Map(graph.nodes.map((n, i) => [n.id, `n${i}`]));
+  const sizes = graph.nodes.map(sizeOf);
+  sizes.forEach(({ w, h }, i) => g.setNode(`n${i}`, { width: w, height: h }));
+  graph.edges.forEach((e, i) => g.setEdge(index.get(e.from), index.get(e.to), {}, String(i)));
+  dagre.layout(g);
+  const boxes = graph.nodes.map((n, i) => {
+    const { w, h } = sizes[i];
+    const c = g.node(`n${i}`);
+    return { id: n.id, x: Math.round(c.x - w / 2), y: Math.round(c.y - h / 2), w, h };
+  });
+  const minX = Math.min(...boxes.map((b) => b.x));
+  const minY = Math.min(...boxes.map((b) => b.y));
+  return boxes.map((b) => ({ ...b, x: b.x - minX, y: b.y - minY }));
+}
+function drawFlow(board, source, actor, options = {}) {
+  const prefix = options.idPrefix ?? `${crypto.randomUUID().slice(0, 8)}-`;
+  if (!/^[A-Za-z0-9_-]{0,16}$/.test(prefix)) throw new CanvasError("INVALID", "idPrefix must be up to 16 of A-Z, a-z, 0-9, _ and -");
+  const graph = parseFlow(source);
+  const placed = layoutFlow(graph);
+  const shapes = board.list().flatMap((e) => e.type === "connector" || e.type === "group" ? [] : [e]);
+  const origin = options.origin ?? {
+    x: shapes.length ? Math.min(...shapes.map((s) => s.x)) : 0,
+    y: shapes.length ? Math.max(...shapes.map((s) => s.y + s.h)) + 80 : 0
+  };
+  const work = board.clone();
+  const text = new Map(graph.nodes.map((n) => [n.id, n]));
+  for (const p of placed) {
+    const n = text.get(p.id);
+    work.addShape({ id: prefix + p.id, type: n.shape, text: n.text, x: p.x + origin.x, y: p.y + origin.y, w: p.w, h: p.h }, actor);
+  }
+  const edges = graph.edges.map((e, i) => {
+    const id = `${prefix}edge_${i + 1}`;
+    work.addConnector({ id, from: { id: prefix + e.from }, to: { id: prefix + e.to }, text: e.text }, actor);
+    return id;
+  });
+  Y.applyUpdate(board.doc, Y.encodeStateAsUpdate(work.doc, Y.encodeStateVector(board.doc)));
+  return { nodes: placed.map((p) => prefix + p.id), edges };
+}
+
+// src/core/svg.ts
+var LINE = 17;
+var num = (n) => String(Math.round(n * 100) / 100);
+var esc = (value) => (typeof value === "string" ? value : "").replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f￾￿]|[\ud800-\udbff](?![\udc00-\udfff])|(?<![\ud800-\udbff])[\udc00-\udfff]/g, "").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+var paint = (value, fallback) => typeof value === "string" && COLOR_PATTERN.test(value) ? value : fallback;
+var str = (value) => typeof value === "string" ? value : "";
+var within = (n, low, high) => typeof n === "number" && Number.isFinite(n) && n >= low && n <= high;
+var LIMIT_COORD = 1e7;
+var TYPES = /* @__PURE__ */ new Set([...SHAPE_TYPES, "connector", "group"]);
+var sane = (s) => within(s.x, -LIMIT_COORD, LIMIT_COORD) && within(s.y, -LIMIT_COORD, LIMIT_COORD) && within(s.w, 1e-6, LIMIT_COORD) && within(s.h, 1e-6, LIMIT_COORD);
+var isShape = (v) => "w" in v;
+var center = (s) => ({ x: s.x + s.w / 2, y: s.y + s.h / 2 });
+function edgePoint(s, toward) {
+  const c = center(s);
+  const dx = toward.x - c.x;
+  const dy = toward.y - c.y;
+  if (dx === 0 && dy === 0) return c;
+  const a = s.w / 2;
+  const b = s.h / 2;
+  const k = s.type === "ellipse" ? 1 / Math.hypot(dx / a, dy / b) : s.type === "diamond" ? 1 / (Math.abs(dx) / a + Math.abs(dy) / b) : Math.min(a / Math.abs(dx), b / Math.abs(dy));
+  return { x: c.x + dx * k, y: c.y + dy * k };
+}
+function wrap(text, width) {
+  const max = Math.max(4, Math.floor((width - 16) / 7.5));
+  const out = [];
+  for (const paragraph of text.split(/\r?\n/)) {
+    let line = "";
+    for (const word of paragraph.split(/\s+/).filter(Boolean)) {
+      const chars = [...word];
+      while (chars.length > max) {
+        if (line) out.push(line);
+        line = "";
+        out.push(chars.splice(0, max).join(""));
+      }
+      const rest = chars.join("");
+      if (line && [...line].length + 1 + chars.length > max) {
+        out.push(line);
+        line = rest;
+      } else line = line ? `${line} ${rest}` : rest;
+    }
+    out.push(line);
+  }
+  return out.slice(0, 40);
+}
+function label(text, cx, cy, width, extra = "") {
+  if (text === "") return "";
+  const lines = wrap(text, width);
+  const top = cy - (lines.length - 1) * LINE / 2;
+  const spans = lines.map((l, i) => `<tspan x="${num(cx)}" y="${num(top + i * LINE)}">${esc(l)}</tspan>`);
+  return `<text text-anchor="middle" dominant-baseline="central"${extra}>${spans.join("")}</text>`;
+}
+function shapeBody(s) {
+  const { x, y, w, h } = s;
+  const stroke = paint(s.stroke, "#1f2937");
+  const look = (fill, more = "") => `fill="${paint(s.fill, fill)}" stroke="${stroke}" stroke-width="2"${more}`;
+  const text = label(str(s.text), x + w / 2, y + h / 2, w);
+  switch (s.type) {
+    case "ellipse":
+      return `<ellipse cx="${num(x + w / 2)}" cy="${num(y + h / 2)}" rx="${num(w / 2)}" ry="${num(h / 2)}" ${look("#ffffff")}/>${text}`;
+    case "diamond": {
+      const pts = [[x + w / 2, y], [x + w, y + h / 2], [x + w / 2, y + h], [x, y + h / 2]];
+      return `<polygon points="${pts.map(([px, py]) => `${num(px)},${num(py)}`).join(" ")}" ${look("#ffffff")}/>${text}`;
+    }
+    case "text":
+      return text;
+    case "frame":
+      return `<rect x="${num(x)}" y="${num(y)}" width="${num(w)}" height="${num(h)}" ${look("none", ' stroke-dasharray="8 6"')}/>${label(str(s.text), x + w / 2, y - 12, w)}`;
+    case "image":
+      if (typeof s.src === "string" && s.src.startsWith("data:") && IMAGE_PATTERN.test(s.src)) {
+        return `<image href="${s.src}" x="${num(x)}" y="${num(y)}" width="${num(w)}" height="${num(h)}" preserveAspectRatio="xMidYMid meet"/>`;
+      }
+      return `<rect x="${num(x)}" y="${num(y)}" width="${num(w)}" height="${num(h)}" ${look("#f3f4f6", ' stroke-dasharray="4 4"')}/>${label("image", x + w / 2, y + h / 2, w)}`;
+    default:
+      return `<rect x="${num(x)}" y="${num(y)}" width="${num(w)}" height="${num(h)}" rx="${s.type === "sticky" ? 2 : 6}" ${look(s.type === "sticky" ? "#fde68a" : "#ffffff")}/>${text}`;
+  }
+}
+var endKey = (e) => "id" in e ? e.id : `${e.x},${e.y}`;
+var wellFormed = (e) => typeof e === "object" && e !== null && (typeof e.id === "string" || within(e.x, -LIMIT_COORD, LIMIT_COORD) && within(e.y, -LIMIT_COORD, LIMIT_COORD));
+function connectorBody(c, shapes, lane) {
+  const resolve = (e) => "id" in e ? shapes.get(e.id) : e;
+  const a = resolve(c.from);
+  const b = resolve(c.to);
+  if (!a || !b) return "";
+  let d;
+  let at;
+  if (isShape(a) && a === b) {
+    const x0 = a.x + a.w * 0.35;
+    const x1 = a.x + a.w * 0.65;
+    const lift = 45 + 32 * lane.index;
+    d = `M${num(x0)} ${num(a.y)}C${num(x0)} ${num(a.y - lift)} ${num(x1)} ${num(a.y - lift)} ${num(x1)} ${num(a.y)}`;
+    at = { x: a.x + a.w / 2, y: a.y - lift * 0.75 - 6 };
+  } else {
+    const ca = isShape(a) ? center(a) : a;
+    const cb = isShape(b) ? center(b) : b;
+    const flip = endKey(c.from) > endKey(c.to);
+    const dx = (flip ? ca.x - cb.x : cb.x - ca.x) || 0;
+    const dy = (flip ? ca.y - cb.y : cb.y - ca.y) || 0;
+    const len = Math.hypot(dx, dy) || 1;
+    const offset = (lane.index - (lane.count - 1) / 2) * 44;
+    const mid = { x: (ca.x + cb.x) / 2, y: (ca.y + cb.y) / 2 };
+    const ctrl = { x: mid.x - dy / len * 2 * offset, y: mid.y + dx / len * 2 * offset };
+    const p = isShape(a) ? edgePoint(a, ctrl) : a;
+    const q = isShape(b) ? edgePoint(b, ctrl) : b;
+    d = offset === 0 ? `M${num(p.x)} ${num(p.y)}L${num(q.x)} ${num(q.y)}` : `M${num(p.x)} ${num(p.y)}Q${num(ctrl.x)} ${num(ctrl.y)} ${num(q.x)} ${num(q.y)}`;
+    at = offset === 0 ? { x: (p.x + q.x) / 2, y: (p.y + q.y) / 2 } : { x: (p.x + q.x) / 4 + ctrl.x / 2, y: (p.y + q.y) / 4 + ctrl.y / 2 };
+  }
+  const marks = `${c.startArrow ? ' marker-start="url(#arrow)"' : ""}${c.endArrow ? ' marker-end="url(#arrow)"' : ""}`;
+  const halo = ' stroke="#ffffff" stroke-width="4" paint-order="stroke"';
+  return `<path d="${d}" fill="none" stroke="${paint(c.stroke, "#1f2937")}" stroke-width="2"${marks}/>${label(str(c.text), at.x, at.y, 160, halo)}`;
+}
+var drawable = (el) => TYPES.has(el.type) && (el.type === "connector" ? wellFormed(el.from) && wellFormed(el.to) : el.type === "group" || sane(el));
+function toSvg(board) {
+  const listed = board.list();
+  if (listed.length > MAX_ELEMENTS) throw new CanvasError("LIMIT", `a board holds at most ${MAX_ELEMENTS} elements`);
+  const all = listed.filter((el) => drawable(el));
+  const shapes = /* @__PURE__ */ new Map();
+  const box = { minX: Infinity, minY: Infinity, maxX: -Infinity, maxY: -Infinity };
+  const grow = (x, y) => {
+    box.minX = Math.min(box.minX, x);
+    box.minY = Math.min(box.minY, y);
+    box.maxX = Math.max(box.maxX, x);
+    box.maxY = Math.max(box.maxY, y);
+  };
+  for (const el of all) {
+    if (el.type === "connector") {
+      for (const e of [el.from, el.to]) if (!("id" in e)) grow(e.x, e.y);
+    } else if (el.type !== "group") {
+      shapes.set(el.id, el);
+      grow(el.x, el.y);
+      grow(el.x + el.w, el.y + el.h);
+    }
+  }
+  const pad = 80;
+  const any = box.minX !== Infinity;
+  const minX = any ? box.minX - pad : 0;
+  const minY = any ? box.minY - pad : 0;
+  const width = any ? Math.ceil(box.maxX + pad - minX) : 240;
+  const height = any ? Math.ceil(box.maxY + pad - minY) : 120;
+  const lanes = /* @__PURE__ */ new Map();
+  const groups = /* @__PURE__ */ new Map();
+  for (const el of all) {
+    if (el.type !== "connector") continue;
+    const key = [endKey(el.from), endKey(el.to)].sort().join("|");
+    groups.set(key, [...groups.get(key) ?? [], el.id]);
+  }
+  for (const ids of groups.values()) ids.forEach((id, index) => lanes.set(id, { index, count: ids.length }));
+  const body = all.map((el) => {
+    if (el.type === "group") return "";
+    const inner = el.type === "connector" ? connectorBody(el, shapes, lanes.get(el.id)) : shapeBody(el);
+    if (inner === "") return "";
+    const kind = el.author.kind;
+    const mark = `data-id="${esc(el.id)}" data-type="${el.type}" data-author-kind="${kind}" data-machine-made="${kind !== "human"}"`;
+    return `<g ${mark}>${inner}</g>`;
+  });
+  const title = esc(board.title) || "Whiteboard";
+  return [
+    `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="${num(minX)} ${num(minY)} ${width} ${height}" font-family="sans-serif" font-size="14" fill="#111827" role="img" aria-label="${title}">`,
+    `<title>${title}</title>`,
+    '<defs><marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse"><path d="M0 0L10 5L0 10z" fill="#1f2937"/></marker></defs>',
+    `<rect x="${num(minX)}" y="${num(minY)}" width="${width}" height="${height}" fill="#ffffff"/>`,
+    ...body.filter(Boolean),
+    "</svg>"
+  ].join("\n");
+}
+
+export {
+  MAX_FLOW_NODES,
+  MAX_FLOW_EDGES,
+  parseFlow,
+  layoutFlow,
+  drawFlow,
+  toSvg
+};

package/dist/{chunk-NLTN7J22.js → chunk-EE725BJ3.js}

@@ -1,14 +1,12 @@
 import {
   CanvasError,
+  PRINCIPAL_KINDS,
   SHAPE_TYPES
-} from "./chunk-ZSPZMGHG.js";
-import {
-  PRINCIPAL_KINDS
-} from "./chunk-JOBTIAFJ.js";
+} from "./chunk-MVWUIBGV.js";
 
 // src/version.ts
 import { createRequire } from "module";
-var VERSION = true ? "0.10.0" : readPackageVersion();
+var VERSION = true ? "0.11.0" : readPackageVersion();
 
 // src/brand.ts
 var BRAND = {