agentic-documents 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # Changelog
 
+## 0.6.0
+
+### Added
+
+- `agentic-documents/ui`: `mountEditor(element, { id, client, principal, room? })` and the `DocumentEditor` React component
+  render the editor in a host app, with live co-editing through agentic-realtime when a room is given. Its styles are
+  in `agentic-documents/ui.css`. `react` and `react-dom` are optional peer dependencies; the Tiptap packages and
+  `agentic-design` are now dependencies.
+- The edit log has a new op, `live`. The editor writes one `live` entry when an agent principal types, so its text is
+  marked as agent work. Its counts are 0.
+
+### Changed
+
+- The ODT export uses `agentic-formats`. The local ODT writer and the `fflate` dependency are gone. `exportOdt` and
+  `ODT_MIME` stay as thin wrappers. The ODT file now comes from the neutral text model, so its XML differs from before.
+- The ODT export holds less than before, because the agentic-formats text model has no block for a quote, a rule, or a
+  code block, no list start number, one paragraph for each list item, and no WebP image. The text stays.
+  `ExportResult` has a `warnings` field that names each loss. It is empty for `md` and `html`. The field is required, so
+  code that builds an `ExportResult` by hand must add it. The CLI prints each warning on stderr. The HTTP API sends them
+  in the `x-export-warnings` header.
+
+## 0.5.0
+
+### Breaking
+
+- A deploy from the template `wrangler.jsonc` needs `npm run build` first. The file now has an `assets` entry for
+  `dist/ui`, so `wrangler` stops when that folder is missing.
+
+### Added
+
+- Commands `list`, `rename`, and `remove` in the SDK, CLI, MCP server, HTTP API (`GET /api/v1/docs`), and
+  the typed client. The catalog keeps a title and the last save time and author. An agent needs the
+  `docs:remove` scope to remove a document.
+- A browser can open a live room: the token goes in a WebSocket subprotocol
+  (`agentic-docs.bearer.<base64url>`) on the live-room route only.
+- A web UI that the Worker serves from `dist/ui` (the `assets` entry in `wrangler.jsonc`): a document list, a
+  rich-text editor on the live room, rename, delete, share, presence, and a mark on agent text. It is built on
+  `agentic-design` and the typed client. Playwright tests run it under `wrangler dev` with an axe check (WCAG 2.2 AA rules)
+  in the light and the dark theme, and screenshots are in `docs/screenshots`.
+- The saved update may hold the marker root that the Tiptap editor writes when it opens a document.
+- `POST /checkpoint?create=false` (client option `create: false`) fails with `NO_DOCUMENT` instead of making a missing document. The UI saves this way, so a removed document stays removed.
+- Each edit log entry holds `client`, the Yjs client id of its writer, so a UI can mark agent text.
+- `agentic-documents/formats`: `importFile` (md, odt, docx) and `exportFile` (md, html, odt, docx), with the
+  `toTextDoc` and `fromTextDoc` mapping to the agentic-formats text model. Each result names lost content in `warnings`.
+- `AgenticDoc.fromBlocks(blocks, author)` makes a document from ProseMirror JSON blocks and checks them against the schema.
+
+### Changed
+
+- `esbuild` is a declared dev dependency. `ui/build.mjs` uses it.
+
+### Fixed
+
+- In the web UI, the caret goes after a new link, and text typed there does not join the link. A quick key
+  after Apply no longer replaces the linked words. Apply with no words selected keeps its link for the next text.
+- In the web UI, a key typed right after a toolbar button goes to the text, not to the button.
+
 ## 0.4.0
 
 ### Added

package/README.md

@@ -7,8 +7,8 @@
 
 Write documents with people and agents in real time.
 
-> Status: early, version 0.4.0. The document model, the text operations, the CLI, the MCP server,
-> the Worker API, and live editing in a room work. The web UI is not built yet.
+> Status: early, version 0.6.0. The document model, the text operations, the CLI, the MCP server,
+> the Worker API, live editing in a room, and a small web UI work. See [UI](#ui).
 
 ## Install
 
@@ -39,6 +39,70 @@ suggestions.accept(id, person); // the text changes now
 new Threads(doc).add({ text: "Tuesday" }, "Is this date firm?", agent);
 ```
 
+## UI
+
+The Worker serves a small web app, built on [agentic-design](https://www.npmjs.com/package/agentic-design)
+and the typed client (`agentic-documents/client`). It has a document list, a rich-text editor (headings,
+lists, bold, italic, links), rename, delete, a share dialog, the people and agents in the room, and a dotted
+underline on text that an agent wrote. The tests check each main view with axe (WCAG 2.2 AA rules) in the light and the dark theme: sign in, list, empty and error list, new-document dialog, editor, share dialog, link, rename and delete dialogs, the actions menu, and the read-only view. Axe finds only part of the faults, so it does not replace a test with a screen reader. Screenshots of
+every view are in [docs/screenshots](docs/screenshots).
+
+Run it on your machine:
+
+```sh
+npm ci
+npm run build                      # writes dist/ and dist/ui
+export WRANGLER_SEND_METRICS=false
+TOKEN=$(openssl rand -hex 32); echo "$TOKEN"
+npx wrangler dev --var AGENTIC_DOCS_REGION:unknown --var AGENTIC_DOCS_UNSAFE_REGION:1 \
+  --var "AGENTIC_DOCS_TOKENS:{\"$TOKEN\":\"human:Ada\"}"
+```
+
+Open the address that wrangler prints, paste the token, and sign in. The token stays in that tab and goes
+when you close it. A token for an agent, such as `agent_of_human:Scribe`, makes its edits show as agent text.
+A `viewer` token opens documents read only. The region setting turns the residency check off, so use it for
+local work only.
+
+How it works:
+
+- The list, rename, delete, and the share dialog use the HTTP API through the typed client.
+- The editor joins the live room of the document. A browser WebSocket cannot send an `Authorization`
+  header, so the page offers the token as a subprotocol, which only the live-room route reads.
+- The page saves the room to the stored document 1.5 seconds after a change, and when you leave the
+  document in the app (not when you close the tab). A command over HTTP then reads the new text. A save never makes a document: if someone deleted it, the page says so, stops saving, and turns read only.
+- An agent's text is the text whose writer is a logged edit by a non-human author (see the `client` field of the
+  edit log). Typing in the editor does not add to the edit log.
+- The page sets a content security policy: scripts, styles, fonts, and images come from the Worker only, and a document image that points to another host does not load.
+- Run the tests with `npm run e2e`. They start `wrangler dev` with the built UI, drive Chromium with
+  Playwright, and run an axe check (WCAG 2.2 AA) on each view in both themes. Run them once with
+  `UPDATE_SCREENSHOTS=1` to write the screenshots again.
+
+### Serve the UI from the npm package
+
+The npm package ships the built UI in `dist/ui`. You do not need a clone to serve it. Install the package in
+your Worker project and point your `wrangler.jsonc` at the files in it:
+
+```sh
+npm install agentic-documents
+```
+
+```jsonc
+{
+  "name": "my-docs",
+  "main": "node_modules/agentic-documents/dist/live-worker.js",
+  "compatibility_date": "2026-01-01",
+  "compatibility_flags": ["nodejs_compat"],
+  "assets": { "directory": "node_modules/agentic-documents/dist/ui" },
+  "durable_objects": { "bindings": [{ "name": "SYNC_ROOM", "class_name": "SyncRoom" }] },
+  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["SyncRoom"] }]
+}
+```
+
+Add the D1 and R2 bindings from the sample `wrangler.jsonc`, and set `AGENTIC_DOCS_TOKENS` as a secret.
+The Worker serves the files in `dist/ui` first. It answers `/api`, `/health`, and any other path. If you deploy from a clone
+with the sample `wrangler.jsonc`, run `npm run build` before `wrangler deploy`. The build writes `dist/ui`,
+and the sample file reads it.
+
 ## CLI
 
 Every change needs an author: `--as <kind>:<name>` or `AGENTIC_DOCS_AS`. An agent that may accept
@@ -74,6 +138,8 @@ A Cloudflare Worker (Hono) mirrors the CLI one to one under `/api/v1/docs`. A re
 curl -X POST $URL/api/v1/docs -H "authorization: Bearer $TOKEN" -d '{"id":"plan","markdown":"# Plan"}'
 curl "$URL/api/v1/docs/plan/outline" -H "authorization: Bearer $TOKEN"
 curl -X POST $URL/api/v1/docs/plan/replace -H "authorization: Bearer $TOKEN" -d '{"text":"Plan","content":"Roadmap"}'
+curl "$URL/api/v1/docs" -H "authorization: Bearer $TOKEN"   # list: id, title, creator, last edit
+curl -X POST $URL/api/v1/docs/plan/rename -H "authorization: Bearer $TOKEN" -d '{"title":"Roadmap"}'
 curl "$URL/api/v1/docs/plan/export?format=html" -H "authorization: Bearer $TOKEN"
 # add &remoteImages=true to keep web images; the default shows only images stored inside the document
 ```
@@ -89,6 +155,16 @@ curl "$URL/api/v1/docs/plan/export?format=html" -H "authorization: Bearer $TOKEN
 - Errors are `{ "error": { "code", "message", "matches" } }`. Status: 400 bad input, 401 no
   valid token, 403 `FORBIDDEN` (for example an agent without `docs:accept` that accepts), 404 not
   found, 409 a conflict (ambiguous match, stale anchor, already decided), 503 `LOCKED`.
+- `list` shows each document's title, creator kind, and last edit. `rename` sets the title and keeps the text.
+  `remove` deletes the whole document. A person may remove. An agent needs the `docs:remove` scope, for example
+  `{"as":"agent_of_human:sweeper","scopes":["docs:remove"]}`. A live room keeps its own copy of the text after `remove`, so
+  an open client can bring the document back with a save.
+- A browser cannot send an `Authorization` header on a WebSocket. It offers two subprotocols instead:
+  `agentic-docs` and `agentic-docs.bearer.<token in base64url>`. Only the live-room route reads it, and the server
+  answers with `agentic-docs`, never the token. A header value can show in the logs of a proxy or a host, so
+  keep access logs of that header off.
+- Each edit log entry holds `client`, the Yjs client id of the replica that wrote it. A UI uses it to mark text
+  an agent wrote. A client writes it, like the rest of the log.
 - `GET /health` needs no token. It reveals nothing else.
 - Create an R2 bucket with `wrangler r2 bucket create agentic-documents-data --jurisdiction eu` and a D1
   database with `wrangler d1 create agentic-documents --jurisdiction eu`. Put the database id in
@@ -119,7 +195,7 @@ try {
 }
 ```
 
-- One method per route: `create`, `read`, `outline`, `edits`, `insert`, `replace`, `delete`, `append`,
+- One method per route: `create`, `list`, `read`, `rename`, `remove`, `outline`, `edits`, `insert`, `replace`, `delete`, `append`,
   `suggest`, `suggestions`, `accept`, `reject`, `comment`, `reply`, `resolve`, `reopen`, `threads`,
   `export`, `room`, `me`, `health`, `state`, and `checkpoint`. The WebSocket route is not a method. Use
   `LiveDoc` from `agentic-documents/live` for it.
@@ -129,6 +205,69 @@ try {
 - The client never retries. A write is not safe to send twice.
 - Pass `fetch` to use your own, for a Worker service binding or for tests.
 
+## Embed the editor
+
+`agentic-documents/ui` renders the editor inside your own app. You give it a document id, a client, the principal who
+uses it, and an optional live room. With a room, people and agents edit together through agentic-realtime and see each
+other. It needs `react` and `react-dom` 19 (peer dependencies).
+
+```ts
+import { createClient } from "agentic-documents/client";
+import { mountEditor } from "agentic-documents/ui";
+import "agentic-design/styles.css";
+import "agentic-documents/ui.css";
+
+const client = createClient({ baseUrl: "https://docs.example.com", token });
+const principal = await client.me(); // { kind, name, role }
+const editor = mountEditor(document.getElementById("editor")!, {
+  id: "plan",
+  client,
+  principal,
+  room: { url: "wss://docs.example.com/api/v1/docs/plan/ws", token },
+});
+// Later: editor.update({ ...options, id: "other" }), or await editor.unmount() to save this tab's changes and leave.
+```
+
+- In a React app, render `<DocumentEditor id client principal room onError onLeave />` instead. `onLeave` gets the
+  promise of the last save.
+- `client` needs only `state` and `checkpoint`. A client from `createClient` has them, or pass your own. Keep the
+  same client object between renders: a new one opens the document again.
+- `principal` needs a `kind` (one of the principal kinds) and a `name`. A missing or unknown kind throws a
+  `TypeError`. It is never given a default. Only the `role` `editor` can change the text. Any other role, or no role,
+  opens it read only. The server still checks every write against the token. Use the principal that `client.me()`
+  returns for the same token, so the editor labels the text with the kind that the server gives the token.
+- When an agent principal types, the editor writes one `live` entry to the edit log for its Yjs client. The editor
+  and the web UI then mark that text as agent work for everyone who opens the document.
+- `room.url` is the WebSocket address of the document room. In a browser the token goes in a WebSocket subprotocol.
+  Pass `room.WebSocket` for a room that takes its token another way. Without a room, the editor saves through the
+  client and shows no other people.
+- The editor saves 1.5 seconds after this tab changes the text, and again on `unmount`. The promise from `unmount`
+  rejects when that last save fails. A save never makes a document, so a removed document stays removed.
+- The styles sit under the `.adoc` class and use the agentic-design tokens. Load `agentic-design/styles.css` first.
+- File import and export are in `agentic-documents/formats` (see [File formats](#file-formats)).
+
+## File formats
+
+`agentic-documents/formats` imports and exports files, so an app that embeds the editor needs no mapping
+code of its own. ODT and DOCX go through the neutral text model of
+[agentic-formats](https://github.com/pooriaarab/agentic-formats). Markdown and HTML use the mapping of this package.
+
+```ts
+import { exportFile, importFile } from "agentic-documents/formats";
+
+const { doc, title, warnings } = importFile(bytes, "docx", { kind: "human", name: "Ada" });
+const odt = exportFile(doc, "odt", { title }); // { contentType, data (Uint8Array for odt), warnings }
+```
+
+- `importFile(input, format, author, { limits? })` reads `md` (text or UTF-8 bytes), `odt`, or `docx` (bytes) into a
+  new `AgenticDoc`. The author makes the one `create` edit, so a file that an agent imports stays labeled as agent work.
+- `exportFile(doc, format, { title?, remoteImages? })` writes `md` or `html` (text), or `odt` or `docx` (bytes).
+- Each result has `warnings`: one line for each kind of content that the other side cannot hold. The text of that
+  content stays.
+- A file that is not valid, or that goes past a limit in `limits` (the agentic-formats defaults), fails with
+  `INVALID_INPUT`. For `md`, only `maxInputBytes` applies. A link that is not a web, mail, or relative address is dropped, and its text stays.
+- `toTextDoc(blocks)` and `fromTextDoc(model)` are the mapping itself, for an app that works with the model.
+
 ## Features
 
 - A Yjs document that a Tiptap editor can open. It uses the y-prosemirror layout.
@@ -152,10 +291,10 @@ try {
   one application and undoes the other, so the text and the edit log hold it once. An accept
   beats a reject made at the same moment.
 - Export to ODT (OpenDocument text): headings, paragraphs, bold, italic, strike, code, links, lists,
-  quotes, rules, tables, and images as embedded files. The package follows ODF 1.3 with the mimetype
-  stored first. The CLI and the API send the file bytes. LibreOffice opens it, lists keep their
-  numbers, and its own re-save reads back to the same Markdown (checked by hand with LibreOffice 24.8
-  in the PR that added it).
+  tables, and PNG, JPEG, and GIF images as embedded files. `agentic-formats` writes the file, with the
+  mimetype stored first. The CLI and the API send the file bytes. A quote, a code block, a rule, a list
+  start number, and a WebP image are not kept in full (see Limits). Each loss is in `warnings` (SDK and
+  MCP), on stderr (CLI), and in the `x-export-warnings` header (API).
 - Export to Markdown and to self-contained HTML. The HTML loads nothing from other hosts. An image
   stored in the document as a `data:` URI (PNG, JPEG, GIF, or WebP) shows. Any other image becomes
   its alt text, because a remote image tells its host who opened the file. `remoteImages` turns
@@ -225,14 +364,18 @@ Limits of live editing:
 
 ## Limits
 
-- No web UI yet.
+- The UI has no accounts. You paste a token, and the token sets your role. The share dialog shows a link and who
+  changed the document. Roles, invites, and expiring links wait for the sharing API in the Worker.
+- The UI marks agent text from the edit log, which a client writes. A modified client can mark its own text as a
+  person's, or a person's as an agent's. The last edit shown in the list is approximate when two writes race.
+- The UI is English only. It needs a browser with `WebSocket` and ES2022.
 - A document holds no roles of its own. The token table gives `editor` or `viewer`. To share a document
   by person, use `createSharing` from `agentic-identity` 0.4. A grant names its subject by kind
   (`human` or `agent`) and id, so a person and an agent with the same id hold separate roles. When you
   delete a document, call `deleteResource` on its resource so its grants do not outlive it. If
   `deleteResource` fails, treat the delete as failed and run it again. If it throws
   `EraseRefusedError`, remove the child resources or the extra owners first. Do not reuse the id
-  until it succeeds. This package has no command that deletes a whole document.
+  until it succeeds. The `remove` command deletes the document and its catalog entry. It does not touch grants.
 - The Worker keeps each document in R2 and a catalog (who made it, and when) in D1. Both come from the
   shared `agentic-identity` ports. A save is conditional on the version it read, so two writers cannot
   overwrite each other. The CLI and MCP server keep the same data in local files.
@@ -251,8 +394,15 @@ Limits of live editing:
   (tokens) and an MCP server that a trusted host starts fix the author for the caller.
 - Suggestions work on text, not on whole sections.
 - A scope on a principal is trusted as given. Nothing here proves who a caller is.
-- Export covers Markdown, HTML, and ODT. DOCX export, and ODT and DOCX import, are planned.
-- ODT export: comments and suggestions are not written. A code block loses its language. A table
+- The `export` command covers Markdown, HTML, and ODT. DOCX export, and ODT and DOCX import, are in
+  `agentic-documents/formats` only.
+- File formats through `agentic-documents/formats`: a quote becomes plain paragraphs, a code block becomes a paragraph
+  of code text, a horizontal rule is left out, a numbered list starts at 1, and a task list becomes a list that starts
+  each item with `☐` or `☑`. On import, underline, superscript, and subscript are left out, and a footnote becomes
+  text in brackets, and code text keeps only its code mark. Each one is named in `warnings`.
+- ODT export: a quote becomes plain paragraphs, a code block becomes a paragraph of code text, a rule is
+  left out, a numbered list starts at 1, a list item keeps one paragraph, and a WebP image becomes its alt text.
+  Comments and suggestions are not written. A code block loses its language. A table
   cell span is not written (the model has none yet). A task list becomes a bullet list that starts each
   item with `☐` or `☑`. A remote image is not linked, because an office program would ask its host
   for it when the file opens. It becomes its alt text.

package/dist/{chunk-TFCRPEEM.js → chunk-34C47PDC.js}

@@ -1,6 +1,6 @@
 import {
   DocError
-} from "./chunk-YBBQNCMC.js";
+} from "./chunk-GQ5E6T7Z.js";
 
 // src/adapters/file-blobs.ts
 import { createHash, randomUUID } from "crypto";

package/dist/chunk-5IQX2W52.js

@@ -0,0 +1,195 @@
+import {
+  APPLIED,
+  DocError,
+  checkAuthor
+} from "./chunk-GQ5E6T7Z.js";
+
+// src/review.ts
+import * as Y from "yjs";
+var newId = () => globalThis.crypto.randomUUID();
+function nonEmpty(value, what) {
+  if (typeof value !== "string" || value.trim() === "") throw new DocError("INVALID_INPUT", `${what} must not be empty`);
+  return value;
+}
+function anchorFor(doc, target) {
+  if ("anchor" in target) {
+    doc.resolve(target);
+    return target.anchor;
+  }
+  return doc.anchor(target.text, target.occurrence);
+}
+function isStale(doc, anchor) {
+  try {
+    doc.resolve({ anchor });
+    return { stale: false, currentText: anchor.text };
+  } catch (error) {
+    if (!(error instanceof DocError) || error.code !== "STALE_ANCHOR") throw error;
+    return { stale: true, currentText: null };
+  }
+}
+function fieldsOf(doc, name) {
+  return doc.ydoc.getMap(name);
+}
+var optional = (map, key) => map.has(key) ? { [key]: map.get(key) } : {};
+function setAll(map, values) {
+  for (const [key, value] of Object.entries(values)) if (value !== void 0) map.set(key, value);
+}
+var Threads = class {
+  constructor(doc) {
+    this.doc = doc;
+  }
+  doc;
+  get map() {
+    return fieldsOf(this.doc, "threads");
+  }
+  get(id) {
+    const thread = this.map.get(id);
+    if (!thread) throw new DocError("NO_THREAD", `no thread with id "${id}"`);
+    return thread;
+  }
+  message(body, author) {
+    return { id: newId(), at: this.doc.now().toISOString(), author, body };
+  }
+  add(target, body, author) {
+    const who = checkAuthor(author);
+    nonEmpty(body, "a comment");
+    const anchor = anchorFor(this.doc, target);
+    const id = newId();
+    this.doc.ydoc.transact(() => {
+      const thread = new Y.Map();
+      this.map.set(id, thread);
+      setAll(thread, { anchor, status: "open" });
+      const messages = new Y.Array();
+      thread.set("messages", messages);
+      messages.push([this.message(body, who)]);
+    });
+    return id;
+  }
+  reply(id, body, author) {
+    const who = checkAuthor(author);
+    nonEmpty(body, "a reply");
+    this.get(id).get("messages").push([this.message(body, who)]);
+  }
+  setStatus(id, status, author) {
+    const who = checkAuthor(author);
+    const thread = this.get(id);
+    this.doc.ydoc.transact(() => {
+      thread.set("status", status);
+      if (status === "open") {
+        thread.delete("resolvedBy");
+        thread.delete("resolvedAt");
+      } else setAll(thread, { resolvedBy: who, resolvedAt: this.doc.now().toISOString() });
+    });
+  }
+  resolve(id, author) {
+    this.setStatus(id, "resolved", author);
+  }
+  reopen(id, author) {
+    this.setStatus(id, "open", author);
+  }
+  list(filter = {}) {
+    return [...this.map.entries()].map(([id, t]) => {
+      const anchor = t.get("anchor");
+      return {
+        id,
+        anchor,
+        status: t.get("status"),
+        ...optional(t, "resolvedBy"),
+        ...optional(t, "resolvedAt"),
+        messages: t.get("messages").toArray(),
+        ...isStale(this.doc, anchor)
+      };
+    }).filter((t) => filter.status === void 0 || t.status === filter.status).sort((a, b) => a.messages[0].at.localeCompare(b.messages[0].at) || a.id.localeCompare(b.id));
+  }
+};
+var ACCEPT_SCOPE = "docs:accept";
+var sameWho = (a, b) => a.kind === b.kind && a.name === b.name;
+var isPerson = (who) => who.kind === "human" || who.kind === "user_token";
+var mayDecide = (who) => isPerson(who) || who.scopes?.includes(ACCEPT_SCOPE) === true;
+var Suggestions = class {
+  constructor(doc) {
+    this.doc = doc;
+  }
+  doc;
+  get map() {
+    return fieldsOf(this.doc, "suggestions");
+  }
+  get(id) {
+    const fields = this.map.get(id);
+    if (!fields) throw new DocError("NO_SUGGESTION", `no suggestion with id "${id}"`);
+    return { fields, suggestion: this.read(id, fields) };
+  }
+  read(id, f) {
+    const anchor = f.get("anchor");
+    return {
+      id,
+      kind: f.get("kind"),
+      ...optional(f, "at"),
+      anchor,
+      replacement: f.get("replacement"),
+      author: f.get("author"),
+      createdAt: f.get("createdAt"),
+      status: f.get("status"),
+      ...optional(f, "decidedBy"),
+      ...optional(f, "decidedAt"),
+      stale: isStale(this.doc, anchor).stale
+    };
+  }
+  /** An `at` on the target means insert. An empty replacement means delete. */
+  add(target, replacement, author) {
+    const who = checkAuthor(author);
+    const kind = target.at ? "insert" : replacement === "" ? "delete" : "replace";
+    if (kind === "insert") nonEmpty(replacement, "an inserted text");
+    const anchor = anchorFor(this.doc, target);
+    const id = newId();
+    this.doc.ydoc.transact(() => {
+      const fields = new Y.Map();
+      this.map.set(id, fields);
+      setAll(fields, { kind, at: target.at, anchor, replacement, author: who, createdAt: this.doc.now().toISOString(), status: "pending" });
+    });
+    return id;
+  }
+  decide(fields, status, author, at) {
+    setAll(fields, { status, decidedBy: author, decidedAt: at });
+  }
+  /**
+   * Apply the edit as the accepting author. The check and the edit share one transaction. Accepting
+   * an accepted suggestion changes nothing. A stale anchor throws and the suggestion stays pending.
+   */
+  accept(id, author) {
+    const who = checkAuthor(author);
+    this.doc.ydoc.transact(() => {
+      const { fields, suggestion: s } = this.get(id);
+      if (!mayDecide(author) || sameWho(s.author, who)) {
+        throw new DocError("FORBIDDEN", `${who.kind}:${who.name} cannot accept this suggestion: a person who is not its author, or an agent with the ${ACCEPT_SCOPE} scope, can`);
+      }
+      if (s.status === "accepted") return;
+      if (s.status !== "pending") throw new DocError("ALREADY_DECIDED", `suggestion "${id}" is already ${s.status}`);
+      const { at, inserted } = this.doc.edit(s.kind, { anchor: s.anchor, at: s.at }, s.replacement, who, { suggestion: { id, author: s.author } });
+      const record = { by: who, at, ...inserted };
+      this.doc.ydoc.getMap(APPLIED).set(`${id}:${this.doc.ydoc.clientID}`, record);
+      this.decide(fields, "accepted", who, at);
+    });
+  }
+  /** Same right as accept. A person can withdraw their own suggestion. An agent can never decide its own. */
+  reject(id, author) {
+    const who = checkAuthor(author);
+    this.doc.ydoc.transact(() => {
+      const { fields, suggestion: s } = this.get(id);
+      if (!mayDecide(author) || !isPerson(who) && sameWho(s.author, who)) {
+        throw new DocError("FORBIDDEN", `${who.kind}:${who.name} cannot reject this suggestion: a person, or an agent with the ${ACCEPT_SCOPE} scope that did not write it, can`);
+      }
+      if (s.status !== "pending") throw new DocError("ALREADY_DECIDED", `suggestion "${id}" is already ${s.status}`);
+      this.decide(fields, "rejected", who, this.doc.now().toISOString());
+    });
+  }
+  list(filter = {}) {
+    return [...this.map.entries()].map(([id, f]) => this.read(id, f)).filter((s) => filter.status === void 0 || s.status === filter.status).sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id));
+  }
+};
+
+export {
+  Threads,
+  isPerson,
+  Suggestions
+};

package/dist/chunk-6UYJV2EJ.js

@@ -0,0 +1,163 @@
+import {
+  Suggestions,
+  Threads
+} from "./chunk-5IQX2W52.js";
+import {
+  EXPORT_FORMATS,
+  exportFile,
+  exportText,
+  toBase64
+} from "./chunk-KC5KFB5R.js";
+import {
+  DocError
+} from "./chunk-GQ5E6T7Z.js";
+
+// src/export.ts
+function exportDoc(doc, format, options = {}) {
+  if (format === "odt") {
+    const file = exportFile(doc, "odt");
+    return { format, contentType: file.contentType, encoding: "base64", data: toBase64(file.data), warnings: file.warnings };
+  }
+  const contentType = format === "html" ? "text/html; charset=utf-8" : "text/markdown; charset=utf-8";
+  return { format, contentType, encoding: "utf8", data: exportText(doc, format, options), warnings: [] };
+}
+
+// src/commands.ts
+import { z } from "zod";
+var id = z.string().describe("Document id.");
+var content = z.string().describe("Markdown for a section target. Plain text for a text target.");
+var text = z.string().describe("Exact text to match. It must sit inside one block.");
+var occurrence = z.coerce.number().int().min(1).optional().describe("Which match, counting from 1, when the text matches more than once.");
+var side = z.enum(["before", "after"]).optional().describe("Put the new text before or after the match.");
+var thread = z.string().describe("Thread id.");
+var where = {
+  section: z.string().optional().describe("Section id from the outline. Use this or text."),
+  text: text.optional(),
+  occurrence,
+  at: z.enum(["start", "end", "before", "after"]).optional().describe("Insert at the start or end of a section, or before or after matched text.")
+};
+function target(input) {
+  const { section, text: text2, occurrence: occurrence2, at } = input;
+  if (section !== void 0) {
+    if (at !== void 0 && at !== "start" && at !== "end") throw new DocError("INVALID_INPUT", `at "${at}" does not fit a section; use start or end`);
+    return { section, at };
+  }
+  if (text2 !== void 0) {
+    if (at === "start" || at === "end") throw new DocError("INVALID_INPUT", `at "${at}" does not fit text; use before or after`);
+    return { text: text2, occurrence: occurrence2, at };
+  }
+  throw new DocError("INVALID_INPUT", "pass section or text");
+}
+var textTarget = (input) => ({
+  text: input.text,
+  occurrence: input.occurrence,
+  at: input.at
+});
+function command(name, description, readOnly, shape, run) {
+  return {
+    name,
+    description,
+    shape,
+    readOnly,
+    async run(service, raw, author) {
+      const parsed = z.object(shape).strict().safeParse(raw);
+      if (!parsed.success) {
+        throw new DocError("INVALID_INPUT", parsed.error.issues.map((i) => `${i.path.join(".") || "input"}: ${i.message}`).join("; "));
+      }
+      return run(service, parsed.data, author);
+    }
+  };
+}
+var ok = () => ({ ok: true });
+var commands = [
+  command("new", "Create a document, from Markdown if given.", false, { id, markdown: z.string().optional() }, async (s, i, a) => {
+    await s.create(i.id, i.markdown ?? "", a);
+    return { id: i.id };
+  }),
+  command("list", "List documents with their titles, creators, and last edits.", true, {}, (s) => s.list()),
+  command("rename", "Give a document a title. The text stays.", false, { id, title: z.string().describe("1 to 120 characters of plain text.") }, async (s, i, a) => {
+    await s.rename(i.id, i.title, a);
+    return ok();
+  }),
+  command("remove", "Delete a whole document. A person may. An agent needs the docs:remove scope.", false, { id }, async (s, i, a) => {
+    await s.remove(i.id, a);
+    return ok();
+  }),
+  command(
+    "read",
+    "Read a document, or one section, as Markdown.",
+    true,
+    { id, section: where.section },
+    (s, i) => s.read(i.id, (d) => i.section ? d.readSection(i.section) : d.toMarkdown())
+  ),
+  command("outline", "List sections with their ids, levels, and titles.", true, { id }, (s, i) => s.read(i.id, (d) => d.outline())),
+  command("edits", "Read the edit log. It names each author kind and holds no content.", true, { id }, (s, i) => s.read(i.id, (d) => d.edits())),
+  command("insert", "Insert Markdown into a section, or plain text next to matched text.", false, { id, ...where, content }, async (s, i, a) => {
+    await s.write(i.id, (d) => d.insert(target(i), i.content, a), a);
+    return ok();
+  }),
+  command("replace", "Replace a section body (the heading stays), or the matched text.", false, { id, ...where, content }, async (s, i, a) => {
+    await s.write(i.id, (d) => d.replace(target(i), i.content, a), a);
+    return ok();
+  }),
+  command("delete", "Delete a section with its subsections, or the matched text.", false, { id, ...where }, async (s, i, a) => {
+    await s.write(i.id, (d) => d.delete(target(i), a), a);
+    return ok();
+  }),
+  command("append", "Add Markdown at the end of the document.", false, { id, content: z.string() }, async (s, i, a) => {
+    await s.write(i.id, (d) => d.append(i.content, a), a);
+    return ok();
+  }),
+  command("suggest", "Suggest an edit to matched text. An empty replacement suggests a delete.", false, { id, text, occurrence, at: side, replacement: z.string() }, async (s, i, a) => ({
+    suggestion: await s.write(i.id, (d) => new Suggestions(d).add(textTarget(i), i.replacement, a), a)
+  })),
+  command(
+    "suggestions",
+    "List suggested edits.",
+    true,
+    { id, status: z.enum(["pending", "accepted", "rejected"]).optional() },
+    (s, i) => s.read(i.id, (d) => new Suggestions(d).list({ status: i.status }))
+  ),
+  command("accept", "Accept a suggestion. The text changes now.", false, { id, suggestion: z.string() }, async (s, i, a) => {
+    await s.write(i.id, (d) => new Suggestions(d).accept(i.suggestion, a), a);
+    return ok();
+  }),
+  command("reject", "Reject a suggestion. The text stays.", false, { id, suggestion: z.string() }, async (s, i, a) => {
+    await s.write(i.id, (d) => new Suggestions(d).reject(i.suggestion, a), a);
+    return ok();
+  }),
+  command("comment", "Start a comment thread on matched text.", false, { id, text, occurrence, body: z.string() }, async (s, i, a) => ({
+    thread: await s.write(i.id, (d) => new Threads(d).add(textTarget(i), i.body, a), a)
+  })),
+  command("reply", "Reply in a comment thread.", false, { id, thread, body: z.string() }, async (s, i, a) => {
+    await s.write(i.id, (d) => new Threads(d).reply(i.thread, i.body, a), a);
+    return ok();
+  }),
+  command("resolve", "Resolve a comment thread.", false, { id, thread }, async (s, i, a) => {
+    await s.write(i.id, (d) => new Threads(d).resolve(i.thread, a), a);
+    return ok();
+  }),
+  command("reopen", "Reopen a comment thread.", false, { id, thread }, async (s, i, a) => {
+    await s.write(i.id, (d) => new Threads(d).reopen(i.thread, a), a);
+    return ok();
+  }),
+  command(
+    "threads",
+    "List comment threads with their messages.",
+    true,
+    { id, status: z.enum(["open", "resolved"]).optional() },
+    (s, i) => s.read(i.id, (d) => new Threads(d).list({ status: i.status }))
+  ),
+  command(
+    "export",
+    "Export the document as Markdown (md), self-contained HTML (html), or OpenDocument text (odt, base64). HTML shows no remote image unless remoteImages is true.",
+    true,
+    { id, format: z.enum(EXPORT_FORMATS), remoteImages: z.union([z.boolean(), z.enum(["true", "false"])]).optional() },
+    (s, i) => s.read(i.id, (d) => exportDoc(d, i.format, { remoteImages: i.remoteImages === true || i.remoteImages === "true" }))
+  )
+];
+
+export {
+  exportDoc,
+  commands
+};