agentic-canvas 0.9.0 → 0.11.0

package/dist/cli.js

@@ -5,22 +5,112 @@ import {
   operatorActor,
   runMcp,
   svgToPng
-} from "./chunk-33ANMQEY.js";
+} from "./chunk-EE725BJ3.js";
 import {
   openLocalStore
 } from "./chunk-NRLF6MGR.js";
 import {
   CanvasService
-} from "./chunk-M74ENUWR.js";
+} from "./chunk-Z6KLGAFP.js";
 import "./chunk-NWQED42L.js";
+import "./chunk-EDQNA2SU.js";
 import {
   CanvasError
-} from "./chunk-ZSPZMGHG.js";
-import "./chunk-JOBTIAFJ.js";
+} from "./chunk-MVWUIBGV.js";
 
 // src/cli.ts
 import { readFileSync, writeFileSync } from "fs";
 import { parseArgs } from "util";
+
+// src/client.ts
+var CanvasApiError = class extends Error {
+  constructor(code, message, status) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.name = "CanvasApiError";
+  }
+  code;
+  status;
+};
+function parseSubject(text) {
+  const at = text.indexOf(":");
+  const kind = text.slice(0, at);
+  if (at < 1 || kind !== "human" && kind !== "agent" || at === text.length - 1) throw new TypeError(`"${text}" is not human:<id> or agent:<id>`);
+  return { subjectKind: kind, subjectId: text.slice(at + 1) };
+}
+function createClient(options) {
+  const { token } = options;
+  const base = options.baseUrl.replace(/\/+$/, "");
+  if (!token) throw new TypeError("token is required");
+  const doFetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+  const seg = encodeURIComponent;
+  async function send(method, path, init, call) {
+    const headers = { authorization: `Bearer ${token}` };
+    if (init.json !== void 0) headers["content-type"] = "application/json";
+    if (init.contentType) headers["content-type"] = init.contentType;
+    let response;
+    try {
+      response = await doFetch(`${base}${path}`, {
+        method,
+        headers,
+        body: init.json === void 0 ? init.body : JSON.stringify(init.json),
+        signal: call?.signal
+      });
+    } catch (error) {
+      if (call?.signal?.aborted) throw error;
+      throw new CanvasApiError("NETWORK", error instanceof Error ? error.message : "the request failed", 0);
+    }
+    if (response.ok) return response;
+    let code = "HTTP_ERROR";
+    let message = `the server answered ${response.status}`;
+    try {
+      const { error } = await response.json();
+      if (typeof error?.code === "string") code = error.code;
+      if (typeof error?.message === "string") message = error.message;
+    } catch {
+      if (call?.signal?.aborted) throw call.signal.reason;
+    }
+    throw new CanvasApiError(code, message, response.status);
+  }
+  const parse = async (response, call) => {
+    try {
+      return await response.json();
+    } catch (error) {
+      if (call?.signal?.aborted) throw error;
+      throw new CanvasApiError("HTTP_ERROR", "the server did not answer with JSON", response.status);
+    }
+  };
+  const json = async (method, path, body, call) => parse(await send(method, path, { json: body }, call), call);
+  const bytes = async (response) => new Uint8Array(await response.arrayBuffer());
+  return {
+    me: (o) => json("GET", "/me", void 0, o),
+    listBoards: (o) => json("GET", "/boards", void 0, o),
+    createBoard: (input = {}, o) => json("POST", "/boards", input, o),
+    readBoard: (id, o) => json("GET", `/boards/${seg(id)}`, void 0, o),
+    deleteBoard: (id, o) => json("DELETE", `/boards/${seg(id)}`, void 0, o),
+    exportSvg: async (id, o) => (await send("GET", `/boards/${seg(id)}/svg`, {}, o)).text(),
+    addShape: (id, shape, o) => json("POST", `/boards/${seg(id)}/shapes`, shape, o),
+    addConnector: (id, connector, o) => json("POST", `/boards/${seg(id)}/connectors`, connector, o),
+    drawFlow: (id, text, o) => json("POST", `/boards/${seg(id)}/flow`, { text }, o),
+    update: (id, element, patch, o) => json("PATCH", `/boards/${seg(id)}/elements/${seg(element)}`, patch, o),
+    move: (id, element, dx, dy, o) => json("POST", `/boards/${seg(id)}/move`, { element, dx, dy }, o),
+    remove: (id, element, o) => json("DELETE", `/boards/${seg(id)}/elements/${seg(element)}`, void 0, o),
+    access: (id, o) => json("GET", `/boards/${seg(id)}/access`, void 0, o),
+    grant: (id, input, o) => json("POST", `/boards/${seg(id)}/grants`, input, o),
+    revoke: (id, { subjectKind, subjectId }, o) => json("DELETE", `/boards/${seg(id)}/grants?subjectKind=${seg(subjectKind)}&subjectId=${seg(subjectId)}`, void 0, o),
+    invite: (id, input, o) => json("POST", `/boards/${seg(id)}/invites`, input, o),
+    uploadImage: async (data, o) => parse(await send("POST", "/images", { body: data, contentType: "application/octet-stream" }, o), o),
+    getImage: async (id, o) => {
+      const response = await send("GET", `/images/${seg(id)}`, {}, o);
+      return { bytes: await bytes(response), type: response.headers.get("content-type") ?? "application/octet-stream" };
+    },
+    state: async (id, o) => bytes(await send("GET", `/boards/${seg(id)}/state`, {}, o)),
+    checkpoint: async (id, update, o) => parse(await send("POST", `/boards/${seg(id)}/checkpoint`, { body: update, contentType: "application/octet-stream" }, o), o)
+  };
+}
+
+// src/cli.ts
 var UsageError = class extends Error {
 };
 var HELP = `${BRAND.command} ${BRAND.version}
@@ -41,11 +131,16 @@ Commands:
   flow <board> --text <t> | --file <p>     Draw a flowchart from text ("A -> B: label"). Use --file - for stdin.
   export <board> [--format svg|png] [--out <path>]  Print SVG, or write PNG to --out.
   repair <board> [--drop <element>]...     Owner only: fix a broken or over-cap board. Needs CANVAS_ACTOR=human:<id>.
+  access <board>                           Server only. List the grants and open invites. Owner.
+  grant <board> <human|agent>:<id> --role <viewer|commenter|editor|owner>  Server only. Give a role. Owner.
+  revoke <board> <human|agent>:<id>        Server only. Take a role back. Owner.
+  invite <board> --role <viewer|commenter|editor> --email <e> | --handle <h> [--expires-in-ms <n>]  Server only. Owner.
   mcp                                      Serve these as MCP tools on stdio. Needs CANVAS_ACTOR.
 
 Live mode: set CANVAS_SERVER=<worker url> and CANVAS_TOKEN=<bearer token>. Every command then runs in the live room of
 the board on that server, so a person and an agent can edit one board at once. The token sets the actor, the kind,
 and the role, so CANVAS_ACTOR is not needed. If it is set, it must match the token. --dir, CANVAS_DIR, and repair are local only.
+The sharing commands need CANVAS_SERVER: a local store has no owners.
 
 Write commands need an actor in CANVAS_ACTOR as <kind>:<id>, such as "agent:helper".
 The operator sets it. A caller cannot pick its own kind: there is no --actor flag.
@@ -69,6 +164,10 @@ var flags = {
   file: { type: "string" },
   prefix: { type: "string" },
   format: { type: "string" },
+  role: { type: "string" },
+  email: { type: "string" },
+  handle: { type: "string" },
+  "expires-in-ms": { type: "string" },
   out: { type: "string" },
   drop: { type: "string", multiple: true },
   help: { type: "boolean" },
@@ -117,6 +216,17 @@ async function run(argv) {
       throw error;
     }
   };
+  const sharing = () => {
+    if (!server) throw new UsageError(`"${command}" needs a server: set CANVAS_SERVER and CANVAS_TOKEN`);
+    return createClient({ baseUrl: `${server.replace(/\/$/, "")}/api/v1/canvas`, token: process.env.CANVAS_TOKEN });
+  };
+  const subject = (text) => {
+    try {
+      return parseSubject(text ?? "");
+    } catch (error) {
+      throw new UsageError(error.message);
+    }
+  };
   const print = (value) => console.log(JSON.stringify(value));
   switch (command) {
     case "new":
@@ -169,9 +279,23 @@ async function run(argv) {
     case "repair":
       need(1, "<board> [--drop <element>]...");
       return print(await service.repair(board, actor(), v.drop ?? []));
+    case "access":
+      need(1, "<board>");
+      return print(await sharing().access(board));
+    case "grant":
+      need(2, "<board> <human|agent>:<id> --role <role>");
+      return print(await sharing().grant(board, { ...subject(rest[0]), role: v.role }));
+    case "revoke":
+      need(2, "<board> <human|agent>:<id>");
+      return print(await sharing().revoke(board, subject(rest[0])));
+    case "invite": {
+      need(1, "<board> --role <role> --email <e> | --handle <h> [--expires-in-ms <n>]");
+      const expiresInMs = num(v["expires-in-ms"]);
+      return print(await sharing().invite(board, { role: v.role, email: v.email, handle: v.handle, ...expiresInMs === void 0 ? {} : { expiresInMs } }));
+    }
     case "mcp":
       need(0, "");
-      return runMcp(service, actor());
+      return runMcp(service, actor(), server ? sharing() : void 0);
     default:
       throw new UsageError(`unknown command "${command}"`);
   }
@@ -182,7 +306,7 @@ run(process.argv.slice(2)).catch((error) => {
     console.error(`${error.message}
 Run "${BRAND.command} --help" for usage.`);
     process.exitCode = 2;
-  } else if (error instanceof CanvasError) {
+  } else if (error instanceof CanvasError || error instanceof CanvasApiError) {
     console.error(`${error.code}: ${error.message}`);
     process.exitCode = 1;
   } else {

package/dist/client-Dyd30StF.d.ts

@@ -0,0 +1,153 @@
+import { a as BoardData, c as ShapeType, S as Shape, E as Endpoint, C as Connector } from './read-UIJlrkwx.js';
+import { PrincipalKind } from 'agentic-identity';
+
+/** Options for every call. */
+interface CallOptions {
+    signal?: AbortSignal;
+}
+interface ShapeInput {
+    id?: string;
+    type: ShapeType;
+    x: number;
+    y: number;
+    w?: number;
+    h?: number;
+    text?: string;
+    fill?: string;
+    stroke?: string;
+    /** A `data:` URL or a `blob:` ref, for an image. */
+    src?: string;
+}
+interface ConnectorInput {
+    id?: string;
+    from: Endpoint;
+    to: Endpoint;
+    text?: string;
+    startArrow?: boolean;
+    endArrow?: boolean;
+    stroke?: string;
+}
+type ShapePatch = Partial<Pick<ShapeInput, "x" | "y" | "w" | "h" | "text" | "fill" | "stroke" | "src">>;
+type ConnectorPatch = Partial<Pick<ConnectorInput, "from" | "to" | "text" | "startArrow" | "endArrow" | "stroke">>;
+/** A role on a board, from least to most. */
+type BoardRole = "viewer" | "commenter" | "editor" | "owner";
+/** Who holds a grant. A person and an agent may share one id and hold separate roles. */
+type SubjectKind = "human" | "agent";
+interface Subject {
+    subjectKind: SubjectKind;
+    subjectId: string;
+}
+interface BoardGrant {
+    subjectKind: SubjectKind;
+    subjectId: string;
+    role: BoardRole;
+    [field: string]: unknown;
+}
+/** An open invite. It never shows the email. */
+interface BoardInvite {
+    id: string;
+    role: BoardRole;
+    [field: string]: unknown;
+}
+interface InviteInput {
+    /** Not `owner`: only a grant makes an owner. */
+    role: Exclude<BoardRole, "owner">;
+    /** The person to invite. Give this or `handle`. */
+    email?: string;
+    /** The agent to invite. Give this or `email`. */
+    handle?: string;
+    /** How long the invite lives, in milliseconds. */
+    expiresInMs?: number;
+}
+interface ImageInfo {
+    id: string;
+    ref: string;
+    type: string;
+    size: number;
+    /** False when the same bytes were stored before. */
+    created: boolean;
+}
+interface CanvasClient {
+    /** Who the token stands for. */
+    me(options?: CallOptions): Promise<{
+        actor: string;
+        kind: PrincipalKind;
+        role: "editor" | "viewer";
+    }>;
+    /** The first 100 boards, with titles. */
+    listBoards(options?: CallOptions): Promise<{
+        boards: {
+            id: string;
+            title: string;
+        }[];
+    }>;
+    createBoard(input?: {
+        id?: string;
+        title?: string;
+    }, options?: CallOptions): Promise<{
+        id: string;
+        title: string;
+    }>;
+    readBoard(id: string, options?: CallOptions): Promise<BoardData & {
+        id: string;
+    }>;
+    /** Delete a board for good, with its live room. Returns the id. */
+    deleteBoard(id: string, options?: CallOptions): Promise<{
+        deleted: string;
+    }>;
+    /** The board as an SVG document. */
+    exportSvg(id: string, options?: CallOptions): Promise<string>;
+    addShape(id: string, shape: ShapeInput, options?: CallOptions): Promise<Shape>;
+    addConnector(id: string, connector: ConnectorInput, options?: CallOptions): Promise<Connector>;
+    /** Draw a flowchart from text such as `A -> B: label`. Returns the new ids. */
+    drawFlow(id: string, text: string, options?: CallOptions): Promise<{
+        nodes: string[];
+        edges: string[];
+    }>;
+    /** Change fields of one shape or connector, such as its size or text. The patch holds at least one field. */
+    update(id: string, element: string, patch: ShapePatch | ConnectorPatch, options?: CallOptions): Promise<Shape | Connector>;
+    /** Move an element. Returns the ids that moved: a shape takes its connectors with it. */
+    move(id: string, element: string, dx: number, dy: number, options?: CallOptions): Promise<{
+        moved: string[];
+    }>;
+    /** Remove an element. Returns the ids removed. */
+    remove(id: string, element: string, options?: CallOptions): Promise<{
+        removed: string[];
+    }>;
+    /** The grants and the open invites of a board. Needs the owner role. */
+    access(id: string, options?: CallOptions): Promise<{
+        grants: BoardGrant[];
+        invites: BoardInvite[];
+    }>;
+    /** Give a person or an agent a role on a board. Needs the owner role. */
+    grant(id: string, input: Subject & {
+        role: BoardRole;
+    }, options?: CallOptions): Promise<{
+        ok: true;
+    }>;
+    /** Take a role back. The last owner cannot be removed. Needs the owner role. */
+    revoke(id: string, input: Subject, options?: CallOptions): Promise<{
+        ok: true;
+    }>;
+    /** Invite a person by email or an agent by handle. Returns the invite id. Needs the owner role. */
+    invite(id: string, input: InviteInput, options?: CallOptions): Promise<{
+        id: string;
+    }>;
+    uploadImage(bytes: Uint8Array | ArrayBuffer | Blob, options?: CallOptions): Promise<ImageInfo>;
+    /** The bytes of a stored image, and its content type. */
+    getImage(id: string, options?: CallOptions): Promise<{
+        bytes: Uint8Array;
+        type: string;
+    }>;
+    /** The stored board as a Yjs update. Only a server with live rooms serves it. */
+    state(id: string, options?: CallOptions): Promise<Uint8Array>;
+    /** Merge a live room's Yjs update into the stored board. Only a server with live rooms serves it. */
+    checkpoint(id: string, update: Uint8Array, options?: CallOptions): Promise<{
+        elements: number;
+        fixed: string[];
+    }>;
+}
+/** What the CLI and the MCP server need to share a board. Sharing lives on the server, so it needs a client. */
+type BoardSharing = Pick<CanvasClient, "access" | "grant" | "revoke" | "invite">;
+
+export type { BoardSharing as B, CanvasClient as C };

package/dist/client.d.ts

@@ -1,7 +1,68 @@
-import { E as ErrorCode, a as BoardData, c as ShapeType, S as Shape, d as Endpoint, C as Connector } from './read--Jd3kE13.js';
 import { PrincipalKind } from 'agentic-identity';
-import 'yjs';
-import 'zod';
+
+type Principal = {
+    kind: PrincipalKind;
+    id: string;
+};
+
+type ErrorCode = "INVALID" | "DUPLICATE_ID" | "NOT_FOUND" | "BAD_REFERENCE" | "LIMIT" | "UNAVAILABLE" | "FORBIDDEN";
+declare const SHAPE_TYPES: readonly ["rect", "ellipse", "diamond", "text", "sticky", "frame", "image"];
+type ShapeType = (typeof SHAPE_TYPES)[number];
+type Endpoint = {
+    id: string;
+} | {
+    x: number;
+    y: number;
+};
+interface Stamp {
+    id: string;
+    z: number;
+    groupId?: string;
+    /** Who made the element. Never changes. */
+    author: Principal;
+    /** Who made the last edit. */
+    editedBy: Principal;
+}
+interface Shape extends Stamp {
+    type: ShapeType;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    text: string;
+    fill?: string;
+    stroke?: string;
+    src?: string;
+}
+interface Connector extends Stamp {
+    type: "connector";
+    from: Endpoint;
+    to: Endpoint;
+    text: string;
+    startArrow: boolean;
+    endArrow: boolean;
+    stroke?: string;
+}
+
+interface Labels {
+    /** The author is an agent or acts for one. */
+    machineMade: boolean;
+    /** The last edit came from an agent or one acting for one. */
+    lastEditMachineMade: boolean;
+}
+type NodeData = Shape & Labels;
+type EdgeData = Connector & Labels;
+interface BoardData {
+    title: string;
+    nodes: NodeData[];
+    edges: EdgeData[];
+    groups: {
+        id: string;
+        members: string[];
+    }[];
+    /** Every non-empty text, back to front. */
+    texts: string[];
+}
 
 interface ClientOptions {
     /** The API root, for example `https://canvas.example.com/api/v1/canvas`. */
@@ -39,6 +100,36 @@ interface ConnectorInput {
 }
 type ShapePatch = Partial<Pick<ShapeInput, "x" | "y" | "w" | "h" | "text" | "fill" | "stroke" | "src">>;
 type ConnectorPatch = Partial<Pick<ConnectorInput, "from" | "to" | "text" | "startArrow" | "endArrow" | "stroke">>;
+/** A role on a board, from least to most. */
+type BoardRole = "viewer" | "commenter" | "editor" | "owner";
+/** Who holds a grant. A person and an agent may share one id and hold separate roles. */
+type SubjectKind = "human" | "agent";
+interface Subject {
+    subjectKind: SubjectKind;
+    subjectId: string;
+}
+interface BoardGrant {
+    subjectKind: SubjectKind;
+    subjectId: string;
+    role: BoardRole;
+    [field: string]: unknown;
+}
+/** An open invite. It never shows the email. */
+interface BoardInvite {
+    id: string;
+    role: BoardRole;
+    [field: string]: unknown;
+}
+interface InviteInput {
+    /** Not `owner`: only a grant makes an owner. */
+    role: Exclude<BoardRole, "owner">;
+    /** The person to invite. Give this or `handle`. */
+    email?: string;
+    /** The agent to invite. Give this or `email`. */
+    handle?: string;
+    /** How long the invite lives, in milliseconds. */
+    expiresInMs?: number;
+}
 interface ImageInfo {
     id: string;
     ref: string;
@@ -104,6 +195,25 @@ interface CanvasClient {
     remove(id: string, element: string, options?: CallOptions): Promise<{
         removed: string[];
     }>;
+    /** The grants and the open invites of a board. Needs the owner role. */
+    access(id: string, options?: CallOptions): Promise<{
+        grants: BoardGrant[];
+        invites: BoardInvite[];
+    }>;
+    /** Give a person or an agent a role on a board. Needs the owner role. */
+    grant(id: string, input: Subject & {
+        role: BoardRole;
+    }, options?: CallOptions): Promise<{
+        ok: true;
+    }>;
+    /** Take a role back. The last owner cannot be removed. Needs the owner role. */
+    revoke(id: string, input: Subject, options?: CallOptions): Promise<{
+        ok: true;
+    }>;
+    /** Invite a person by email or an agent by handle. Returns the invite id. Needs the owner role. */
+    invite(id: string, input: InviteInput, options?: CallOptions): Promise<{
+        id: string;
+    }>;
     uploadImage(bytes: Uint8Array | ArrayBuffer | Blob, options?: CallOptions): Promise<ImageInfo>;
     /** The bytes of a stored image, and its content type. */
     getImage(id: string, options?: CallOptions): Promise<{
@@ -118,6 +228,10 @@ interface CanvasClient {
         fixed: string[];
     }>;
 }
+/** What the CLI and the MCP server need to share a board. Sharing lives on the server, so it needs a client. */
+type BoardSharing = Pick<CanvasClient, "access" | "grant" | "revoke" | "invite">;
+/** `kind:id` of a person or an agent, as the CLI and the tools write it. */
+declare function parseSubject(text: string): Subject;
 declare function createClient(options: ClientOptions): CanvasClient;
 
-export { type ApiErrorCode, type CallOptions, CanvasApiError, type CanvasClient, type ClientOptions, type ConnectorInput, type ConnectorPatch, type ImageInfo, type ShapeInput, type ShapePatch, createClient };
+export { type ApiErrorCode, type BoardGrant, type BoardInvite, type BoardRole, type BoardSharing, type CallOptions, CanvasApiError, type CanvasClient, type ClientOptions, type ConnectorInput, type ConnectorPatch, type ImageInfo, type InviteInput, type ShapeInput, type ShapePatch, type Subject, type SubjectKind, createClient, parseSubject };

package/dist/client.js

@@ -9,6 +9,12 @@ var CanvasApiError = class extends Error {
   code;
   status;
 };
+function parseSubject(text) {
+  const at = text.indexOf(":");
+  const kind = text.slice(0, at);
+  if (at < 1 || kind !== "human" && kind !== "agent" || at === text.length - 1) throw new TypeError(`"${text}" is not human:<id> or agent:<id>`);
+  return { subjectKind: kind, subjectId: text.slice(at + 1) };
+}
 function createClient(options) {
   const { token } = options;
   const base = options.baseUrl.replace(/\/+$/, "");
@@ -66,6 +72,10 @@ function createClient(options) {
     update: (id, element, patch, o) => json("PATCH", `/boards/${seg(id)}/elements/${seg(element)}`, patch, o),
     move: (id, element, dx, dy, o) => json("POST", `/boards/${seg(id)}/move`, { element, dx, dy }, o),
     remove: (id, element, o) => json("DELETE", `/boards/${seg(id)}/elements/${seg(element)}`, void 0, o),
+    access: (id, o) => json("GET", `/boards/${seg(id)}/access`, void 0, o),
+    grant: (id, input, o) => json("POST", `/boards/${seg(id)}/grants`, input, o),
+    revoke: (id, { subjectKind, subjectId }, o) => json("DELETE", `/boards/${seg(id)}/grants?subjectKind=${seg(subjectKind)}&subjectId=${seg(subjectId)}`, void 0, o),
+    invite: (id, input, o) => json("POST", `/boards/${seg(id)}/invites`, input, o),
     uploadImage: async (data, o) => parse(await send("POST", "/images", { body: data, contentType: "application/octet-stream" }, o), o),
     getImage: async (id, o) => {
       const response = await send("GET", `/images/${seg(id)}`, {}, o);
@@ -77,5 +87,6 @@ function createClient(options) {
 }
 export {
   CanvasApiError,
-  createClient
+  createClient,
+  parseSubject
 };

package/dist/embed.d.ts

@@ -1,10 +1,28 @@
 import * as react from 'react';
-import { CanvasClient } from './client.js';
+import { C as CanvasClient } from './client-Dyd30StF.js';
 import { PrincipalKind } from 'agentic-identity';
-import './read--Jd3kE13.js';
-import 'yjs';
+import { SyncClient, Status } from 'agentic-realtime/client';
+import * as Y from 'yjs';
+import './read-UIJlrkwx.js';
 import 'zod';
 
+/** The presence of a room: who is here. A `SyncClient` of agentic-realtime has these. */
+type RoomPresence = Pick<SyncClient, "peers" | "onPeers">;
+/**
+ * A board that the app keeps itself, in its own Yjs room. The UI reads and writes it, and does not call a client, poll, or
+ * open a live room. The app keeps the document and its room.
+ */
+interface HostBoard {
+    /** The Yjs document. The UI opens it as a `Board`: its `elements` and `meta` maps, as this package stores them. */
+    doc: Y.Doc;
+    /** The presence of the app's room. With it, the UI shows who else is here. */
+    presence?: RoomPresence;
+    /** The connection state now. With neither `status` nor `onStatus`, the UI shows the board as live. With only `onStatus`, it shows not live until the room reports "connected". */
+    status?: () => Status;
+    /** A way to hear when the connection state changes. It returns a function that stops the listener. The UI reads it once each time it opens `doc`. */
+    onStatus?: (listener: (status: Status) => void) => () => void;
+}
+
 interface RoomOptions {
     /** The API root, for example `https://canvas.example.com/api/v1/canvas`. */
     baseUrl: string;
@@ -16,14 +34,21 @@ interface RoomOptions {
 interface BoardPrincipal {
     kind: PrincipalKind;
     name: string;
+    /** Stamped on each element the principal writes in host mode. The default is `name`, which must then be a valid id. A client mode board takes the actor from its token. */
+    id?: string;
     /** Only `editor` can change the board. Any other value, or no value, opens it read only. */
     role?: "editor" | "viewer";
 }
 interface BoardEditorOptions {
     /** The board id. */
     boardId: string;
-    /** Loads and changes the board. A client from `createClient` in `agentic-canvas/client` works. */
-    client: CanvasClient;
+    /** Loads and changes the board. A client from `createClient` in `agentic-canvas/client` works. Needed unless `host` is given. */
+    client?: CanvasClient;
+    /**
+     * The board in your own Yjs document. The UI then reads and writes that document, and calls no client, does not poll, and
+     * opens no live room. `client` or `room` together with `host` throws a `TypeError`.
+     */
+    host?: HostBoard;
     principal: BoardPrincipal;
     /** Open the board read only, even for an editor. */
     readOnly?: boolean;
@@ -43,4 +68,4 @@ interface MountedBoard {
 /** Render the board into an element, for an app that does not use React itself. */
 declare function mount(element: HTMLElement, options: BoardEditorOptions): MountedBoard;
 
-export { BoardEditor, type BoardEditorOptions, type BoardPrincipal, CanvasClient, type MountedBoard, type RoomOptions, mount };
+export { BoardEditor, type BoardEditorOptions, type BoardPrincipal, CanvasClient, type HostBoard, type MountedBoard, type RoomOptions, mount };