agentic-canvas 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pooria Arab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,142 @@
-# Temporary Holding Version
+# agentic-canvas
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/agentic-canvas)](https://www.npmjs.com/package/agentic-canvas)
+[![MIT license](https://img.shields.io/badge/license-MIT-blue)](https://opensource.org/license/mit)
+
+[Package](https://www.npmjs.com/package/agentic-canvas) · [Source](https://github.com/pooriaarab/agentic-canvas) · [Support](https://github.com/pooriaarab/agentic-canvas/issues)
+
+A shared whiteboard for diagrams, drawn by people and agents.
+
+> Status: 0.1.0, the first release. The board model, the agent operations, the
+> exports, the CLI, and the MCP server work. The HTTP API and the web UI are not
+> built yet.
+
+## Install
+
+Node 22 or newer.
+
+```sh
+npm install agentic-canvas
+```
+
+To build from source instead, run `npm ci` and `npm run build`.
+
+PNG export is optional. It needs the `playwright-core` package (Apache-2.0) and a
+Chromium: `npm i playwright-core && npx playwright-core install chromium`.
+The Chromium download is a one-time call to the Playwright CDN at install time. PNG export
+itself makes no network call.
+
+## Quick start
+
+```sh
+export CANVAS_ACTOR=agent:helper          # who writes: <kind>:<id>
+npx agentic-canvas new --id demo --title "Release flow"
+npx agentic-canvas flow demo --text $'direction LR\nCode(Write code) -> Test{Tests pass?}: push\nTest -> Ship[Ship it]: yes'
+npx agentic-canvas read demo              # nodes, edges, text as JSON
+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`.
+`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
+fails when it is unset, empty, or has a bad kind. The CLI has no `--actor` flag and no
+default actor, so a caller cannot pick its own kind. Only the operator can set `human`.
+
+## MCP server
+
+```sh
+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
+`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.
+
+## SDK
+
+```ts
+import { Board } from "agentic-canvas";
+
+const me = { kind: "human", id: "ada" } as const;
+const bot = { kind: "agent_of_human", id: "helper" } as const;
+
+const board = new Board();
+board.addShape({ id: "a", type: "rect", x: 0, y: 0, text: "Start" }, me);
+board.addShape({ id: "b", type: "diamond", x: 240, y: 0, text: "Ok?" }, bot);
+board.addConnector({ from: { id: "a" }, to: { id: "b" }, text: "next" }, bot);
+board.list(); // every element, back to front
+```
+
+Read the board as data, and draw a flowchart from text:
+
+```ts
+import { drawFlow, readBoard } from "agentic-canvas";
+
+drawFlow(board, "direction LR\nS(Start) -> D{Ok?}: go\nD -> E[Done]: yes", bot);
+readBoard(board); // { title, nodes, edges, groups, texts }
+```
+
+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.
+
+## Features
+
+- Shapes: rectangle, ellipse, diamond, text, sticky note, frame, image.
+- Connectors that bind to shapes and follow them when they move.
+- Z-order, and groups that nest.
+- Every element keeps the kind of its author and of its last editor. An agent
+  edit stays visible as machine-made.
+- `readBoard`: nodes, edges, groups, and text as plain data, with a machine-made
+  flag on each.
+- `drawFlow`: a flowchart from text with a layered layout. It adds nothing when
+  anything fails.
+- `toSvg`: a deterministic SVG. It fetches nothing and marks machine-made work
+  with `data-machine-made`.
+- `svgToPng`: PNG through a headless Chromium with JavaScript off, service workers blocked,
+  and every network request blocked. A board over 16 million pixels exports as SVG only.
+- A CLI over a local file store. Several processes can write at once.
+- An MCP server (stdio) over the same service as the CLI.
+- Yjs underneath: two copies of a board merge without conflicts.
+- No UI code. The model is plain TypeScript on Yjs, with no outbound calls.
+
+## Limits
+
+- A board holds at most 10,000 elements. A flow holds at most 500 nodes and 2,000
+  edges.
+- Flow text has no chains (`A -> B -> C`). Write one edge per line.
+- `readBoard` leaves out embedded image bytes.
+- Images hold a `data:` PNG, JPEG, GIF, or WebP, or a `blob:` key. Remote URLs and
+  SVG are refused.
+- Two peers that make the same explicit id at the same time keep only one element, with no
+  error. Explicit ids are safe with one writer. Leave `id` empty and the board picks a random one.
+- A synced update is untrusted. An element that fails the write rules is hidden, and `repair()`
+  deletes it. A board past the element cap refuses to load or read. A human operator runs
+  `repair --drop <element>` to delete elements until it fits.
+- `update` cannot clear a required field. Only `fill` and `stroke` accept `undefined`.
+- Z values stop at ±1e9. New elements that pass the limit land at the limit and tie with it.
+  While an element sits at +1e9, a front move fails with `LIMIT`. While one sits at -1e9, a back
+  move fails. Remove every element at the limit to clear it.
+- Delete against connect can leave a connector with a missing end. Readers hide it. `repair()`
+  removes it, and `Board.decode` runs `repair()` for you.
+- `move` writes absolute positions. Two peers that move one shape at the same time do not add up:
+  the last writer wins.
+- Frames are plain shapes. They do not own the shapes inside them yet.
+- The store is one file, `canvas.json`, in the store folder. A write takes `canvas.json.lock`.
+  A lock whose owner is gone, or that is older than 30 seconds, is taken over. A lock that
+  cannot be read counts as held: the call then waits 10 seconds and fails with `UNAVAILABLE`.
+  Remove the lock by hand if no process runs.
+- Node 22 or newer is needed. `agentic-canvas/file-store` exports `createFileStore(path)` and
+  `openLocalStore(dir)`. A writer that is paused for more than 30 seconds can lose its lock
+  and then still write.
+- Delete leaves no audit record yet. The caller logs it.
+- PNG needs the optional `playwright-core` and a Chromium. Without them it fails with
+  `UNAVAILABLE`. SVG always works.
+
+## License
+
+MIT.

package/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: agentic-canvas
+description: A shared whiteboard for diagrams, drawn by people and agents. Keywords: whiteboard,canvas,diagrams,drawing,collaboration,agents,mcp,cli.
+---
+
+# agentic-canvas
+
+A shared whiteboard for diagrams, drawn by people and agents.
+
+## Use the SDK
+
+```js
+import { Board } from "agentic-canvas";
+
+const bot = { kind: "agent_of_human", id: "helper" };
+const board = new Board();
+board.addShape({ id: "a", type: "rect", x: 0, y: 0, text: "Start" }, bot);
+```
+
+Draw a flowchart from text, then read the board:
+
+```js
+import { drawFlow, readBoard } from "agentic-canvas";
+
+drawFlow(board, "A[Start] -> B{Ok?}: go\nB -> C: yes", bot);
+readBoard(board);
+```
+
+## Use the CLI
+
+```sh
+export CANVAS_ACTOR=agent:helper
+agentic-canvas new --id demo
+agentic-canvas flow demo --text "A -> B: go"
+agentic-canvas read demo
+agentic-canvas export demo --out demo.svg
+```
+
+## Rules
+
+- Name the actor on every write.
+- Report a `CanvasError` as a failure.

package/dist/chunk-I3EJ5JB7.js

@@ -0,0 +1,237 @@
+// src/store-file.ts
+import { randomUUID } from "crypto";
+import { mkdirSync } from "fs";
+import { link, open, readFile, rename, unlink } from "fs/promises";
+import { join } from "path";
+
+// src/store-errors.ts
+var FileStoreError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "FileStoreError";
+  }
+  code;
+};
+
+// src/store-file.ts
+import { assertCollection, assertId, createMemoryStore, parseRegion, StoreConflictError } from "agentic-identity";
+var MAX_TRANSACTION_RUNS = 50;
+var clone = (value) => JSON.parse(JSON.stringify(value));
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var codeOf = (error) => error?.code;
+function processIsAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return codeOf(error) === "EPERM";
+  }
+}
+function lockIsStale(text, staleAfterMs) {
+  let held;
+  try {
+    held = JSON.parse(text);
+  } catch {
+    return false;
+  }
+  if (typeof held !== "object" || held === null) return false;
+  const { pid, at } = held;
+  if (typeof pid !== "number" || !Number.isInteger(pid) || pid < 1 || typeof at !== "number" || !Number.isFinite(at)) return false;
+  return !processIsAlive(pid) || Date.now() - at > staleAfterMs;
+}
+function createFileStore(path, options = {}) {
+  const region = parseRegion(options.region ?? "unknown");
+  const lockPath = `${path}.lock`;
+  const timeoutMs = options.lockTimeoutMs ?? 1e4;
+  const staleAfterMs = options.staleAfterMs ?? 3e4;
+  for (const ms of [timeoutMs, staleAfterMs]) if (typeof ms !== "number" || !Number.isFinite(ms) || ms < 0) throw new TypeError("lockTimeoutMs and staleAfterMs must be finite numbers of 0 or more");
+  let queue = Promise.resolve();
+  async function load() {
+    let text;
+    try {
+      text = await readFile(path, "utf8");
+    } catch (error) {
+      if (codeOf(error) === "ENOENT") return /* @__PURE__ */ new Map();
+      throw error;
+    }
+    try {
+      const data = JSON.parse(text);
+      if (typeof data !== "object" || data === null || Array.isArray(data)) throw new Error();
+      return new Map(
+        Object.entries(data).map(([name, docs]) => {
+          if (typeof docs !== "object" || docs === null || Array.isArray(docs)) throw new Error();
+          for (const doc of Object.values(docs)) if (typeof doc !== "object" || doc === null || Array.isArray(doc)) throw new Error();
+          return [name, new Map(Object.entries(docs))];
+        })
+      );
+    } catch {
+      throw new FileStoreError("DAMAGED", `the database file is not valid JSON. Repair or remove it`);
+    }
+  }
+  async function save(snapshot) {
+    const text = JSON.stringify(Object.fromEntries([...snapshot].map(([name, docs]) => [name, Object.fromEntries(docs)])));
+    const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+      const handle = await open(temp, "w");
+      try {
+        await handle.writeFile(text);
+        await handle.sync();
+      } finally {
+        await handle.close();
+      }
+      await rename(temp, path);
+    } catch (error) {
+      await unlink(temp).catch(() => void 0);
+      throw error;
+    }
+  }
+  async function takeOverIfStale() {
+    let seen;
+    try {
+      seen = await readFile(lockPath, "utf8");
+    } catch {
+      return;
+    }
+    if (!lockIsStale(seen, staleAfterMs)) return;
+    const aside = `${lockPath}.stale.${randomUUID()}`;
+    try {
+      await rename(lockPath, aside);
+    } catch {
+      return;
+    }
+    if (await readFile(aside, "utf8").catch(() => "") !== seen) await link(aside, lockPath).catch(() => void 0);
+    await unlink(aside).catch(() => void 0);
+  }
+  async function acquire() {
+    const token = randomUUID();
+    const deadline = Date.now() + timeoutMs;
+    for (; ; ) {
+      try {
+        const handle = await open(lockPath, "wx");
+        try {
+          await handle.writeFile(JSON.stringify({ pid: process.pid, at: Date.now(), token }));
+        } finally {
+          await handle.close();
+        }
+        return token;
+      } catch (error) {
+        if (codeOf(error) !== "EEXIST") throw error;
+      }
+      await takeOverIfStale();
+      if (Date.now() > deadline) throw new FileStoreError("LOCKED", `the database file is locked. If no agentic-canvas process runs, remove the .lock file next to it`);
+      await sleep(5 + Math.random() * 15);
+    }
+  }
+  async function release(token) {
+    const text = await readFile(lockPath, "utf8").catch(() => "");
+    if (text.includes(`"token":"${token}"`)) await unlink(lockPath).catch(() => void 0);
+  }
+  async function memoryOf(snapshot, only) {
+    const memory = createMemoryStore({ region });
+    for (const [name, docs] of snapshot) if (only === void 0 || only === name) for (const [id, doc] of docs) await memory.put(name, id, doc);
+    return memory;
+  }
+  const recording = (inner, log) => ({
+    get: (collection, id) => inner.get(collection, id),
+    query: (collection, query) => inner.query(collection, query),
+    put: async (collection, id, doc) => {
+      await inner.put(collection, id, doc);
+      log.push([collection, id, clone(doc)]);
+    },
+    delete: async (collection, id) => {
+      await inner.delete(collection, id);
+      log.push([collection, id, null]);
+    }
+  });
+  const locked = (body) => {
+    const run = queue.then(async () => {
+      const token = await acquire();
+      try {
+        return await body();
+      } finally {
+        await release(token);
+      }
+    });
+    queue = run.catch(() => void 0);
+    return run;
+  };
+  async function commit(snapshot, log) {
+    for (const [name, id, doc] of log) {
+      if (doc === null) snapshot.get(name)?.delete(id);
+      else snapshot.set(name, (snapshot.get(name) ?? /* @__PURE__ */ new Map()).set(id, doc));
+    }
+    if (log.length > 0) await save(snapshot);
+  }
+  const writeOne = (write) => locked(async () => {
+    const log = [];
+    await write(recording(createMemoryStore({ region }), log));
+    await commit(await load(), log);
+  });
+  const watching = (inner, seen) => ({
+    ...inner,
+    async get(collection, id) {
+      const doc = await inner.get(collection, id);
+      if (!seen.has(`${collection}/${id}`)) seen.set(`${collection}/${id}`, JSON.stringify(doc));
+      return doc;
+    },
+    async query(collection, query) {
+      const page = await inner.query(collection, query);
+      for (const item of page.items) if (!seen.has(`${collection}/${item.id}`)) seen.set(`${collection}/${item.id}`, JSON.stringify(item.data));
+      return page;
+    }
+  });
+  const unchanged = (snapshot, seen) => [...seen].every(([key, text]) => {
+    const slash = key.indexOf("/");
+    return JSON.stringify(snapshot.get(key.slice(0, slash))?.get(key.slice(slash + 1)) ?? null) === text;
+  });
+  return {
+    region,
+    async get(collection, id) {
+      assertCollection(collection);
+      assertId(id);
+      const doc = (await load()).get(collection)?.get(id);
+      return doc ? clone(doc) : null;
+    },
+    async query(collection, query) {
+      assertCollection(collection);
+      return (await memoryOf(await load(), collection)).query(collection, query);
+    },
+    put: (collection, id, doc) => writeOne((ops) => ops.put(collection, id, doc)),
+    delete: (collection, id) => writeOne((ops) => ops.delete(collection, id)),
+    // Optimistic, as the port requires: run on a copy of the file with no lock, then take the lock and commit
+    // only if every doc the run read is unchanged. Else run again. The memory adapter keeps the rule that
+    // every read comes before the first write.
+    async transaction(fn) {
+      for (let run = 0; run < MAX_TRANSACTION_RUNS; run++) {
+        const log = [];
+        const seen = /* @__PURE__ */ new Map();
+        const result = await (await memoryOf(await load())).transaction(async (tx) => {
+          log.length = 0;
+          seen.clear();
+          return fn(watching(recording(tx, log), seen));
+        });
+        const done = log.length === 0 ? unchanged(await load(), seen) : await locked(async () => {
+          const current = await load();
+          if (!unchanged(current, seen)) return false;
+          await commit(current, log);
+          return true;
+        });
+        if (done) return result;
+      }
+      throw new StoreConflictError();
+    }
+  };
+}
+function openLocalStore(dir) {
+  mkdirSync(dir, { recursive: true });
+  return createFileStore(join(dir, STORE_FILE));
+}
+var STORE_FILE = "canvas.json";
+
+export {
+  FileStoreError,
+  createFileStore,
+  openLocalStore,
+  STORE_FILE
+};