agentic-canvas 0.3.0 → 0.5.0

package/README.md

@@ -7,9 +7,10 @@
 
 A shared whiteboard for diagrams, drawn by people and agents.
 
-> Status: 0.3.0. The board model, the agent operations, the exports, the CLI, the
+> Status: 0.5.0. The board model, the agent operations, the exports, the CLI, the
 > MCP server, a small Worker API, and live co-editing work. The CLI, the MCP server,
-> and the SDK can join a live room. A remote client calls the Worker API. The web UI is not built yet.
+> 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
 
@@ -37,7 +38,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 +52,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.
@@ -104,13 +105,122 @@ try {
 }
 ```
 
-There is one method per route: `me`, `createBoard`, `readBoard`, `exportSvg`, `addShape`, `addConnector`,
-`drawFlow`, `move`, `remove`, `uploadImage`, `getImage`, `state`, and `checkpoint`. Each takes
+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.
+
+### 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
+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.
@@ -132,23 +242,107 @@ repeated write can change a board twice. Pass `fetch` to use your own.
   (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.
+
+## 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 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 that carries a token on a WebSocket: `agentic-canvas.bearer`. |
+| `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.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-W7NRP3EX.js → chunk-G4YTESPS.js}

@@ -1,14 +1,16 @@
+import {
+  FileStoreError
+} from "./chunk-NWQED42L.js";
 import {
   Board,
   CanvasError,
   drawFlow,
-  principalSchema,
   readBoard,
   toSvg
-} from "./chunk-GGQPE65T.js";
+} from "./chunk-JCYNPYYJ.js";
 import {
-  FileStoreError
-} from "./chunk-NWQED42L.js";
+  principalSchema
+} from "./chunk-SPP6PINW.js";
 
 // src/service.ts
 import * as Y from "yjs";
@@ -21,6 +23,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 +54,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 +90,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 +112,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 +154,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-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);
@@ -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);
@@ -265,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 = [];
@@ -294,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));
@@ -364,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) {
@@ -705,9 +764,6 @@ function toSvg(board) {
 }
 
 export {
-  PRINCIPAL_KINDS,
-  isMachineMade,
-  principalSchema,
   CanvasError,
   SHAPE_TYPES,
   MAX_ELEMENTS,

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
+};