agentic-canvas 0.2.0 → 0.4.0

package/README.md

@@ -7,9 +7,9 @@
 
 A shared whiteboard for diagrams, drawn by people and agents.
 
-> Status: 0.2.0. The board model, the agent operations, the exports, the CLI, the
+> Status: 0.4.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. The web UI is not built yet.
+> 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.
 
 ## Install
 
@@ -37,7 +37,7 @@ npx agentic-canvas export demo --out demo.svg
 npx agentic-canvas export demo --format png --out demo.png
 ```
 
-Other commands: `add`, `connect`, `move`, `rm`. Run `npx agentic-canvas --help`.
+Other commands: `list`, `add`, `connect`, `update`, `move`, `rm`. Run `npx agentic-canvas --help`.
 `repair` is for the owner only. It needs `CANVAS_ACTOR=human:<id>`.
 Boards live in `./.agentic-canvas` (or `--dir`, or `CANVAS_DIR`). Every write
 needs an actor in `CANVAS_ACTOR`, as `<kind>:<id>`. The operator sets it. A write
@@ -51,7 +51,7 @@ CANVAS_ACTOR=agent:helper npx agentic-canvas --dir ./boards mcp
 ```
 
 The server speaks MCP on stdio. It has one tool for each CLI command: `create_board`,
-`read_board`, `add_shape`, `connect`, `move`, `remove`, `draw_flow`, `export_svg`, and
+`list_boards`, `read_board`, `add_shape`, `connect`, `update_element`, `move`, `remove`, `draw_flow`, `export_svg`, and
 `export_png`. `repair` is not a tool. Only a human operator runs it, from the CLI. The server will not start unless `CANVAS_ACTOR` is set to a valid
 `<kind>:<id>`. That actor stamps every write. No tool takes an actor, author, or kind, so a
 caller cannot choose who it writes as. An error comes back as a tool error with a code.
@@ -84,6 +84,111 @@ 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`, `listBoards`, `createBoard`, `readBoard`, `exportSvg`, `addShape`, `addConnector`,
+`drawFlow`, `update`, `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.
+
+## Live demo
+
+A demo Worker runs on workers.dev: <https://agentic-canvas-demo.hello-fd1.workers.dev>. `GET /health` answers 200
+and the web UI is at the root. The API needs a token, so a request without one gets 401. The demo's D1
+database and R2 bucket are in the EU, and its live rooms use the EU jurisdiction. The demo data can be
+reset at any time.
+
+To redeploy it, a maintainer with a Cloudflare token runs this from the repo root. The deploy is manual and
+no CI secret is used:
+
+```sh
+npm ci && npm run build
+WRANGLER_SEND_METRICS=false CLOUDFLARE_API_TOKEN=... npx wrangler deploy -c wrangler.demo.jsonc
+npx wrangler secret put CANVAS_API_TOKENS -c wrangler.demo.jsonc   # only to set or rotate tokens
+```
+
+`wrangler.demo.jsonc` holds the config. The tokens are a Worker secret and are not in the repo. To run your
+own copy, create a D1 database and an R2 bucket (both in the EU), put their names and id in a copy of that
+file, and deploy it the same way.
+
+## UI
+
+The Worker serves a small web UI at its root. It uses the published `agentic-design` package for
+tokens, controls, and overlays, and the typed `agentic-canvas/client` for every call. It is
+bundled at build time, so a build needs `agentic-design` from npm and the browser loads nothing
+from another site.
+
+Run it on your machine:
+
+```sh
+npm ci
+npm run build                      # writes the UI to ui-dist/
+cat > .dev.vars <<'EOF2'
+CANVAS_REGION=unknown
+CANVAS_API_TOKENS={"ada-token-0123456789-0123456789-0123456789":{"actor":"ada","kind":"human"}}
+EOF2
+WRANGLER_SEND_METRICS=false npx wrangler dev
+```
+
+Open the address that wrangler prints and paste the token. A token has 32 characters or more. Its
+grant sets the name, the kind (a person or an agent), and the role. A `viewer` token reads and
+cannot change a board. The token stays in the tab's session storage.
+
+What it does:
+
+- Lists boards, makes a board, and opens one. Empty, loading, and error states have a retry.
+- Draws shapes, connectors, text, and sticky notes. Select, move, resize, connect, and delete an
+  item. Pan by dragging the background, zoom with the wheel or the toolbar.
+- Marks an item an agent wrote with an "Agent" tag and in its accessible name. The side panel shows
+  who made the item and who last edited it.
+- Shows who is in the board, from the live room (`agentic-realtime`). Edits go over the HTTP API.
+  After a save, the editor raises a counter in its room presence, and the other editors read the
+  board again. The page also reads the board again every 5 seconds, so a change made through the API, the CLI, or an agent shows without a reload, a few seconds late.
+- Works with a keyboard. Tab moves between items. Arrow keys move the selected item, Shift with an
+  arrow resizes it, Delete removes it, Escape clears the selection. With nothing selected, arrow
+  keys pan, `+` and `-` zoom, and `0` resets the view. The side panel also sets text, position, and size,
+  and connects shapes, with fields, and the toolbar has pan buttons. A person who cannot drag
+  can do everything a drag does.
+
+Develop and test the UI:
+
+```sh
+npm run build                      # UI and library
+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
+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.
+
+The UI saves each edit in order, and shows "Saving…" until the last one is stored. It asks the browser to confirm before you leave a page with unsaved edits. It reads the board again at most once a second.
+
+UI limits: the UI draws with the theme colors and ignores the `fill` and `stroke` of an element.
+It shows no image pixels. A text field of a shape is plain text. Two editors who move one item
+at the same time keep the last write. The board list shows the first 100 boards.
+
 ## Features
 
 - Shapes: rectangle, ellipse, diamond, text, sticky note, frame, image.
@@ -105,23 +210,28 @@ the direction. Lines that start with `#` or `//` are comments.
   (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`,
+  `/connectors`, `/flow`, `/move`, `GET /boards`, `PATCH /boards/:id/elements/:element`, `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.
+  opens a room, `GET /me` says who a token is. The Worker seeds a room from the stored board when a client
+  joins, and saves the room to the stored board before it serves any board read or write. A raw WebSocket
+  client needs no seed and no save call. A room that no request reaches stays unsaved in the Store until the
+  next request, and it is safe in the room's own storage. `GET /boards/:id/state` and
+  `POST /boards/:id/checkpoint` still work for a client that saves by hand. Every save checks author stamps,
+  and the Worker sets them from the room's log of who sent each update (the token's actor and kind): a client
+  cannot claim another principal, and an agent cannot pass as a person, even by naming one who is in the room.
+  A new item that the log lacks (it keeps a capped number of ranges, and a hand save may hold content the room never had) has no sender: the save deletes a new element and undoes a change. A hand save puts the part of its update that the room lacks into the room as the poster, so the room refuses a client id that it holds for someone else and its log names the poster. It drops the part the room holds, saves the room, and fails if the room cannot be saved. It is one message of 1,000,000 bytes at most. A stored board over 1,000,000 bytes cannot seed a room: a live join answers 422 for it.
 - 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.
+- The board model has no UI code. It 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.
+- Canvas takes principal kinds, regions, and the Store and Blobs ports from `agentic-identity` 0.5.
   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`.

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

@@ -1,11 +1,11 @@
 import {
   CanvasService,
   MAX_LIVE_BYTES
-} from "./chunk-W7NRP3EX.js";
+} from "./chunk-J52RPFRP.js";
 import {
   CanvasError,
   principalSchema
-} from "./chunk-GGQPE65T.js";
+} from "./chunk-JZA525X5.js";
 
 // src/worker.ts
 import { parseRegion } from "agentic-identity";
@@ -1788,6 +1788,145 @@ var Hono3 = class extends Hono {
   }
 };
 
+// src/room-sync.ts
+import * as Y from "yjs";
+var SEEDER = { kind: "agent", id: "canvas-room" };
+var MAX_SEED_BYTES = 1e6;
+var SYNC = 0;
+var AUTH = 2;
+var SYNC_STEP2 = 1;
+var SYNC_UPDATE = 2;
+var same = (a, b) => a.kind === b.kind && a.id === b.id;
+function varUint(value) {
+  const out = [];
+  for (; value > 127; value = Math.floor(value / 128)) out.push(128 | value % 128);
+  return [...out, value];
+}
+async function roomState(live, id) {
+  const meta = await live.meta(id);
+  if (meta.updates === 0 && meta.compactions === 0) return null;
+  const reader = (await live.exportHistory(id)).getReader();
+  const decoder = new TextDecoder();
+  let text2 = "";
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (value) text2 += decoder.decode(value, { stream: true });
+      for (let end = text2.indexOf("\n"); end >= 0; end = text2.indexOf("\n")) {
+        let record;
+        try {
+          record = JSON.parse(text2.slice(0, end));
+        } catch {
+          throw new CanvasError("UNAVAILABLE", "the room sent an export this server cannot read");
+        }
+        text2 = text2.slice(end + 1);
+        if (record.type === "state" && typeof record.base64 === "string") return Uint8Array.from(atob(record.base64), (c) => c.charCodeAt(0));
+      }
+      if (done) throw new CanvasError("UNAVAILABLE", "the room sent no state");
+    }
+  } finally {
+    await reader.cancel().catch(() => void 0);
+  }
+}
+async function send(live, id, update, roomVector, who) {
+  if (update.length > MAX_SEED_BYTES) throw new CanvasError("LIMIT", "the update is too big to put in a room");
+  const upgrade = new Request("https://room.internal/ws", { headers: { upgrade: "websocket" } });
+  const response = await live.connect(id, upgrade, { principal: who.principal, role: "editor", name: who.principal.id });
+  const socket = response.webSocket;
+  if (!socket) throw new CanvasError("UNAVAILABLE", "the room did not open");
+  socket.accept();
+  await new Promise((resolve, reject) => {
+    const timer = setTimeout(() => fail2(new CanvasError("UNAVAILABLE", "the room did not answer")), 1e4);
+    const fail2 = (error) => (clearTimeout(timer), reject(error));
+    socket.addEventListener("message", ({ data }) => {
+      const bytes = new Uint8Array(data);
+      if (bytes[0] === AUTH && bytes[1] === 0) fail2(new CanvasError(who.refusal, "the room refused the update"));
+      else if (bytes[0] === SYNC && bytes[1] === SYNC_STEP2) clearTimeout(timer), resolve();
+    });
+    socket.addEventListener("close", () => fail2(new CanvasError("UNAVAILABLE", "the room closed before it took the update")));
+    socket.send(new Uint8Array([SYNC, SYNC_UPDATE, ...varUint(update.length), ...update]));
+    socket.send(new Uint8Array([SYNC, 0, ...varUint(roomVector.length), ...roomVector]));
+  }).finally(() => socket.close(1e3, "done"));
+}
+async function writers(live, id) {
+  const log = await live.attribution(id);
+  if (!log) throw new CanvasError("UNAVAILABLE", "the room has no log of who sent its updates");
+  const ranges = /* @__PURE__ */ new Map();
+  for (const range of log.ranges) ranges.set(range.client, [...ranges.get(range.client) ?? [], range]);
+  const reach = /* @__PURE__ */ new Map();
+  for (const [client, list] of ranges) {
+    list.sort((a, b) => a.clock - b.clock);
+    reach.set(client, list.map((r) => r.clock + r.length));
+    const ends = reach.get(client);
+    for (let i = 1; i < ends.length; i++) ends[i] = Math.max(ends[i], ends[i - 1]);
+  }
+  return ({ client, clock }) => {
+    const list = ranges.get(client) ?? [];
+    let low = 0;
+    let high = list.length;
+    while (low < high) {
+      const mid = low + high >> 1;
+      if (list[mid].clock <= clock) low = mid + 1;
+      else high = mid;
+    }
+    let first;
+    for (let i = low - 1; i >= 0 && reach.get(client)[i] > clock && !first; i--) {
+      const r = list[i];
+      if (clock < r.clock + r.length) first = r;
+    }
+    const who = first ? log.authors[first.author] : void 0;
+    return who && !same(who, SEEDER) ? { id: who.id, kind: who.kind } : void 0;
+  };
+}
+async function handSave(live, service, id, update, poster) {
+  const state = await roomState(live, id);
+  const vector = Y.encodeStateVectorFromUpdate(state ?? Y.encodeStateAsUpdate(new Y.Doc()));
+  let missing;
+  try {
+    missing = Y.diffUpdate(update, vector);
+  } catch {
+    throw new CanvasError("INVALID", "the update is not a Yjs update");
+  }
+  const { structs, ds } = Y.decodeUpdate(missing);
+  if (structs.length > 0 || ds.clients.size > 0) await send(live, id, missing, vector, { principal: poster, refusal: "FORBIDDEN" });
+  const saved2 = await pull(live, service, id, true);
+  if (saved2) return saved2;
+  const board = await service.read(id);
+  return { elements: board.nodes.length + board.edges.length + board.groups.length, fixed: [] };
+}
+async function roomAuthors(live, id) {
+  return (await live.meta(id)).contributors.filter((c) => !same(c, SEEDER)).map(({ id: who, kind }) => ({ id: who, kind }));
+}
+var saved = /* @__PURE__ */ new Map();
+function remember(id, mark) {
+  if (saved.size > 500) saved.clear();
+  saved.set(id, mark);
+}
+async function pull(live, service, id, force = false) {
+  const { updates, compactions } = await live.meta(id);
+  const mark = `${updates}:${compactions}`;
+  if (!force && saved.get(id) === mark) return null;
+  const state = await roomState(live, id);
+  if (!state) return null;
+  let result;
+  try {
+    result = await service.checkpoint(id, state, null, await roomAuthors(live, id), await writers(live, id));
+  } catch (error) {
+    if (error instanceof CanvasError && error.code !== "UNAVAILABLE") remember(id, mark);
+    throw error;
+  }
+  remember(id, mark);
+  return result;
+}
+async function seed(live, service, id) {
+  const state = await roomState(live, id);
+  const missing = await service.missingFrom(id, state ?? void 0);
+  if (!missing) return;
+  const known = new Y.Doc();
+  if (state) Y.applyUpdate(known, state);
+  await send(live, id, missing, Y.encodeStateVector(known), { principal: SEEDER, refusal: "UNAVAILABLE" });
+}
+
 // src/worker.ts
 var MIN_TOKEN_LENGTH = 32;
 var DEFAULT_MAX_IMAGE_BYTES = 1e6;
@@ -1809,8 +1948,19 @@ 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;
+  }
+}
 function authenticate(request, env) {
-  const token = /^Bearer (.+)$/.exec(request.headers.get("authorization") ?? "")?.[1];
+  const token = /^Bearer (.+)$/.exec(request.headers.get("authorization") ?? "")?.[1] ?? socketToken(request);
   if (!token || !env.CANVAS_API_TOKENS) return null;
   let grants;
   try {
@@ -1826,7 +1976,8 @@ function authenticate(request, env) {
   if (typeof found !== "object" || found === null) return null;
   const { actor, kind, role = "editor" } = found;
   const parsed = principalSchema.safeParse({ kind, id: actor });
-  return parsed.success && (role === "editor" || role === "viewer") ? { actor: parsed.data, role } : null;
+  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;
 }
 function sniffImage(bytes) {
   const at = (offset, ...sig) => sig.every((b, i) => bytes[offset + i] === b);
@@ -1916,13 +2067,35 @@ function createApp(options = {}) {
     await next();
   });
   api.get("/me", (c) => c.json({ actor: c.var.actor.id, kind: c.var.actor.kind, role: c.var.role }));
+  const saveRoom = async (c, seeding) => {
+    if (!options.live) return;
+    const id = c.req.param("id");
+    await c.var.service.assertExists(id);
+    const live = options.live(c.env);
+    await pull(live, c.var.service, id).catch((error) => console.error(JSON.stringify({ level: "error", op: "save-room", message: loggable(error) })));
+    if (seeding) {
+      await seed(live, c.var.service, id).catch((error) => {
+        console.error(JSON.stringify({ level: "error", op: "seed-room", message: loggable(error) }));
+        throw error instanceof CanvasError ? error : new CanvasError("UNAVAILABLE", "the room could not take the stored board. Try again");
+      });
+    }
+  };
+  const sync = async (c, next) => {
+    if (!/\/(ws|checkpoint)$/.test(new URL(c.req.url).pathname)) await saveRoom(c, false);
+    await next();
+  };
+  api.use("/boards/:id/*", sync);
   api.get("/boards/:id/ws", async (c) => {
     if (!options.live) return fail("NOT_FOUND", "this server hosts no live rooms", 404);
     if (c.req.header("upgrade") !== "websocket") return fail("UPGRADE_REQUIRED", "open this route as a WebSocket", 426);
     const id = c.req.param("id");
-    await c.var.service.assertExists(id);
+    await saveRoom(c, true);
     const { actor, role } = c.var;
-    return options.live(c.env).connect(id, c.req.raw, { principal: { id: actor.id, kind: actor.kind }, role, name: actor.id });
+    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 });
   });
   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) => {
@@ -1931,9 +2104,9 @@ function createApp(options = {}) {
     await c.var.service.assertExists(id);
     const update = await readLimited(c.req.raw, MAX_LIVE_BYTES);
     if (!update) throw new CanvasError("INVALID", `the update must be at most ${MAX_LIVE_BYTES} bytes`);
-    const authors = (await options.live(c.env).meta(id)).contributors.map(({ id: who, kind }) => ({ id: who, kind }));
-    return c.json(await c.var.service.checkpoint(id, update, c.var.actor, authors));
+    return c.json(await handSave(options.live(c.env), c.var.service, id, update, c.var.actor));
   });
+  api.get("/boards", async (c) => c.json({ boards: await c.var.service.list() }));
   api.post("/boards", async (c) => {
     const b = await jsonBody(c);
     const id = b.id === void 0 ? void 0 : text(b.id, "id");
@@ -1949,6 +2122,7 @@ function createApp(options = {}) {
     const b = await jsonBody(c);
     return c.json(await c.var.service.move(c.req.param("id"), text(b.element, "element"), num(b.dx, "dx"), num(b.dy, "dy"), c.var.actor));
   });
+  api.patch("/boards/:id/elements/:element", async (c) => c.json(await c.var.service.update(c.req.param("id"), c.req.param("element"), await jsonBody(c), c.var.actor)));
   api.delete("/boards/:id/elements/:element", async (c) => {
     const removed = await c.var.service.remove(c.req.param("id"), c.req.param("element"));
     console.log(JSON.stringify({ level: "info", op: "remove", actorKind: c.var.actor.kind }));
@@ -1998,6 +2172,7 @@ var app = createApp();
 var worker_default = { fetch: (request, env, ctx) => app.fetch(request, env, ctx) };
 
 export {
+  WS_PROTOCOL,
   authenticate,
   sniffImage,
   createApp,

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

@@ -5,7 +5,7 @@ import {
   principalSchema,
   readBoard,
   toSvg
-} from "./chunk-GGQPE65T.js";
+} from "./chunk-JZA525X5.js";
 import {
   FileStoreError
 } from "./chunk-NWQED42L.js";
@@ -21,6 +21,7 @@ function toBase64(bytes) {
   for (let i = 0; i < bytes.length; i += 8192) text += String.fromCharCode(...bytes.subarray(i, i + 8192));
   return btoa(text);
 }
+var sameBytes = (a, b) => a.length === b.length && a.every((v, i) => v === b[i]);
 var fromBase64 = (text) => Uint8Array.from(atob(text), (c) => c.charCodeAt(0));
 function boardKey(id) {
   try {
@@ -51,6 +52,17 @@ var CanvasService = class {
       return { id, title: board.title };
     });
   }
+  /** The first 100 boards (the store sorts by id), with titles. A board whose stored bytes are damaged shows an empty title: it stays in the list so a person can find and repair it. */
+  async list() {
+    const page = await this.store.query(COLLECTION, { limit: 100 }).catch(storeFailure);
+    return page.items.map(({ id, data }) => {
+      try {
+        return { id, title: decodeStored(data, id, Board.decode).title };
+      } catch {
+        return { id, title: "" };
+      }
+    });
+  }
   /** Throws NOT_FOUND unless the board exists. A live room opens only for a board that exists. */
   async assertExists(id) {
     boardKey(id);
@@ -76,6 +88,10 @@ var CanvasService = class {
   connect(id, connector, actor) {
     return this.change(id, (b) => b.addConnector(connector, actor));
   }
+  /** Change fields of one shape or connector: position, size, text, colors. */
+  update(id, elementId, patch, actor) {
+    return this.change(id, (b) => b.update(elementId, patch, actor));
+  }
   move(id, elementId, dx, dy, actor) {
     return this.change(id, (b) => ({ moved: b.move(elementId, dx, dy, actor) }));
   }
@@ -94,22 +110,37 @@ var CanvasService = class {
     boardKey(id);
     return this.store.transaction(async (tx) => (await this.load(tx.get(COLLECTION, id), id)).encode());
   }
+  /** What the stored board has that a room with state `room` lacks, as a Yjs update, or null when the room has all of it. */
+  async missingFrom(id, room) {
+    boardKey(id);
+    const known = new Y.Doc();
+    if (room) Y.applyUpdate(known, room);
+    const diff = await this.store.transaction(async (tx) => Y.encodeStateAsUpdate((await this.load(tx.get(COLLECTION, id), id)).doc, Y.encodeStateVector(known)));
+    const before = Y.encodeStateAsUpdate(known);
+    Y.applyUpdate(known, diff);
+    return Y.decodeUpdate(diff).structs.length === 0 && sameBytes(before, Y.encodeStateAsUpdate(known)) ? null : diff;
+  }
   /**
-   * Merge a live room's state into the stored board. `authors` are the principals the room saw send updates.
+   * `writer` names who sent each Yjs item, from the room's log. It sets the stamps where it knows (see `Board.restamp`).
+   * Merge a live room's state into the stored board. `authors` are the principals the room saw send updates. A null
+   * `actor` trusts only them: the Worker saves a room that way, with nobody present to vouch.
    * 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.
+   * authors for good, so an OLD item that the log does not name (a seeded one, or a range the log dropped) keeps the older rule: its
+   * stamp may name anyone who once sent an update in that room. A NEW item with no writer is deleted or undone.
+   * The log records who adds an item, not who deletes a key: a deleted optional key is credited to the writer of the editor
+   * stamp written in the same save, or undone if there is none.
    * 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 = []) {
+  async checkpoint(id, update, actor, authors = [], writer) {
     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);
+    const by = actor === null ? null : principalSchema.safeParse(actor);
+    if (by && !by.success) throw new CanvasError("INVALID", "the actor must be a valid principal");
+    const trusted = (who) => [...by?.success ? [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();
@@ -121,7 +152,7 @@ var CanvasService = class {
       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 fixed = /* @__PURE__ */ new Set([...next.restamp(prior, trusted, writer), ...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) });

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

@@ -184,12 +184,58 @@ var Board = class _Board {
    * author, and a changed one needs a trusted editor or it goes back to its prior state. An editor stamp changed alone
    * to an untrusted principal is put back. Unknown keys, nested Yjs types, and bad or foreign title values are deleted
    * or undone. Returns the ids it deleted or restored.
+   *
+   * `writer` says who sent the update that holds a Yjs item, or undefined when it does not know. Where it knows, it
+   * decides: a new element gets its creator as author and editor, and an old one gets the sender of its changes as editor.
+   * A client cannot claim another principal, and an agent cannot pass as a person. A new item that the log lacks has no
+   * sender: it is deleted or undone. Only an old item falls back to `trusted`. A hand save names its poster as the sender
+   * of every item that the room does not hold, in `writer`.
    */
-  restamp(prior, trusted) {
+  restamp(prior, trusted, writer) {
     const before = new Map(prior.allStored().map((e) => [e.id, e]));
     const body = ({ author: _a, editedBy: _e, ...rest }) => JSON.stringify(rest);
     const fixed = [];
+    const isNew = (item) => item.clock >= Y.getState(prior.doc.store, item.client);
+    const who = (item) => writer?.(item);
+    const pick = (writers, stamped) => writers.find((w) => isMachineMade(w.kind)) ?? (stamped && (writers.length === 0 || writers.some((w) => samePrincipal(w, stamped))) ? stamped : writers[0]);
     this.doc.transact(() => {
+      for (const el of writer ? this.allStored() : []) {
+        const entry = this.elements.get(el.id);
+        const was = prior.elements.get(el.id);
+        const by2 = (key) => {
+          const item = entry._map.get(key);
+          return item && !item.deleted ? who(item.id) : void 0;
+        };
+        if (!was) {
+          const creator = entry._item ? who(entry._item.id) : void 0;
+          const writers2 = [...entry.keys()].filter((k) => k !== "author" && k !== "editedBy").map(by2);
+          if (!creator || writers2.some((w) => !w)) this.elements.delete(el.id);
+          else {
+            const editor2 = pick(writers2, by2("editedBy")) ?? creator;
+            if (samePrincipal(el.author, creator) && samePrincipal(el.editedBy, editor2)) continue;
+            entry.set("author", creator);
+            entry.set("editedBy", editor2);
+          }
+          fixed.push(el.id);
+          continue;
+        }
+        const raw = (map, key) => JSON.stringify(map.get(key));
+        const changed = [.../* @__PURE__ */ new Set([...entry.keys(), ...was.keys()])].filter((k) => k !== "author" && k !== "editedBy" && raw(entry, k) !== raw(was, k));
+        const found = entry._map.get("editedBy");
+        const stamp = found?.deleted ? void 0 : found;
+        const stamped = stamp && isNew(stamp.id) ? who(stamp.id) : void 0;
+        const writers = changed.map((k) => entry.has(k) ? by2(k) : stamped);
+        if (writers.some((w) => !w) || stamp && isNew(stamp.id) && !stamped) {
+          this.elements.set(el.id, new Y.Map([...was.entries()]));
+          fixed.push(el.id);
+          continue;
+        }
+        const editor = pick(writers, stamped);
+        if (editor && !samePrincipal(el.editedBy, editor)) {
+          entry.set("editedBy", editor);
+          fixed.push(el.id);
+        }
+      }
       for (const el of this.allStored()) {
         const old = before.get(el.id);
         if (!old) {
@@ -216,9 +262,22 @@ var Board = class _Board {
         if (extra.length > 0 && !fixed.includes(el.id)) fixed.push(el.id);
       }
       const same = (key) => !(this.meta.get(key) instanceof Y.AbstractType) && JSON.stringify(this.meta.get(key)) === JSON.stringify(prior.meta.get(key));
+      let titleBroken = false;
+      if (writer) {
+        const found = this.meta._map.get("title");
+        const titleItem = found?.deleted ? void 0 : found;
+        const byItem = this.meta._map.get("titleBy");
+        const written = [titleItem, byItem?.deleted ? void 0 : byItem].filter((item) => item !== void 0 && isNew(item.id)).map((item) => who(item.id));
+        titleBroken = !titleItem && prior.meta.has("title") || written.some((w) => !w);
+        const titleWriter = titleBroken ? void 0 : pick(written);
+        if (titleWriter && this.titleBy && !samePrincipal(this.titleBy, titleWriter)) {
+          this.meta.set("titleBy", titleWriter);
+          fixed.push("title");
+        }
+      }
       const by = this.titleBy;
       const title = this.meta.get("title");
-      const honest = by !== void 0 && trusted(by) && (title === void 0 || titleSchema.safeParse(title).success);
+      const honest = !titleBroken && by !== void 0 && trusted(by) && (title === void 0 || titleSchema.safeParse(title).success);
       if (!honest && !(same("title") && same("titleBy"))) {
         for (const key of ["title", "titleBy"]) {
           const old = prior.meta.get(key);

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

@@ -3,11 +3,11 @@ import {
   PRINCIPAL_KINDS,
   SHAPE_TYPES,
   principalSchema
-} from "./chunk-GGQPE65T.js";
+} from "./chunk-JZA525X5.js";
 
 // src/version.ts
 import { createRequire } from "module";
-var VERSION = true ? "0.2.0" : readPackageVersion();
+var VERSION = true ? "0.4.0" : readPackageVersion();
 
 // src/brand.ts
 var BRAND = {
@@ -91,6 +91,11 @@ function createMcpServer(service, actor) {
     { description: "Make a board.", inputSchema: { id: z.string().optional(), title: z.string().optional() } },
     tool(async (a) => json(await service.create(actor, a)))
   );
+  server.registerTool(
+    "list_boards",
+    { description: "List the first 100 boards with their titles.", inputSchema: {}, annotations: read },
+    tool(async () => json({ boards: await service.list() }))
+  );
   server.registerTool(
     "read_board",
     { description: "Read a board as data: nodes, edges, groups, text, and who made what.", inputSchema: { board }, annotations: read },
@@ -121,6 +126,14 @@ function createMcpServer(service, actor) {
     { 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(
+    "update_element",
+    {
+      description: "Change fields of a shape (x, y, w, h, text, fill, stroke) or a connector. Resize with w and h.",
+      inputSchema: { board, element: z.string(), x: num.optional(), y: num.optional(), w: num.optional(), h: num.optional(), text: z.string().optional(), fill: z.string().optional(), stroke: z.string().optional() }
+    },
+    tool(async ({ board: b, element, ...patch }) => json(await service.update(b, element, patch, actor)))
+  );
   server.registerTool(
     "move",
     { description: "Move an element, or a whole group.", inputSchema: { board, element: z.string(), dx: num, dy: num } },