agentic-documents 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 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.5.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
@@ -129,6 +205,28 @@ 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.
 
+## 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, 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.
@@ -225,14 +323,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,7 +353,12 @@ 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.
+- 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: 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

package/dist/{chunk-YBBQNCMC.js → chunk-6QOYS63L.js}

@@ -361,9 +361,18 @@ var AgenticDoc = class _AgenticDoc {
     });
   }
   static fromMarkdown(markdown, author, options) {
+    checkAuthor(author);
+    return _AgenticDoc.fromBlocks(markdownToBlocks(markdown), author, options);
+  }
+  /** Make a document from blocks in ProseMirror JSON form. Blocks that the schema does not allow fail with INVALID_INPUT. */
+  static fromBlocks(content, author, options) {
     const who = checkAuthor(author);
+    try {
+      if (content.length > 0) schema.nodeFromJSON({ type: "doc", content }).check();
+    } catch (error) {
+      throw new DocError("INVALID_INPUT", `the blocks do not fit the document schema: ${error instanceof Error ? error.message : String(error)}`);
+    }
     const doc = new _AgenticDoc(new Y2.Doc(), options);
-    const content = markdownToBlocks(markdown);
     doc.change("create", who, () => {
       doc.fragment.insert(0, toYBlocks(content));
       return { inserted: content.length, deleted: 0 };
@@ -397,7 +406,7 @@ var AgenticDoc = class _AgenticDoc {
   change(op, author, run, extra = {}) {
     const at = this.now().toISOString();
     this.ydoc.transact(() => {
-      const entry = { op, at, author, ...run(), ...extra };
+      const entry = { op, at, author, client: this.ydoc.clientID, ...run(), ...extra };
       if (entry.section === void 0) delete entry.section;
       this.log.push([entry]);
     });
@@ -546,199 +555,15 @@ var AgenticDoc = class _AgenticDoc {
   }
 };
 
-// src/review.ts
-import * as Y3 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 Y3.Map();
-      this.map.set(id, thread);
-      setAll(thread, { anchor, status: "open" });
-      const messages = new Y3.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 Y3.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 {
   DOC_ERROR_CODES,
   DocError,
   markdownToBlocks,
   blocksToMarkdown,
   schema,
+  APPLIED,
   PRINCIPAL_KINDS,
+  checkAuthor,
   parseAuthor,
-  AgenticDoc,
-  Threads,
-  Suggestions
+  AgenticDoc
 };

package/dist/{chunk-TFCRPEEM.js → chunk-7R7ZPPRF.js}

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

package/dist/{chunk-R5XUTBC3.js → chunk-E7B6T5WN.js}

@@ -1,12 +1,12 @@
 import {
   MAX_LIVE_BYTES
-} from "./chunk-FZA5LQV3.js";
+} from "./chunk-YNHZCIGO.js";
 import {
   AgenticDoc,
   DOC_ERROR_CODES,
   DocError,
   PRINCIPAL_KINDS
-} from "./chunk-YBBQNCMC.js";
+} from "./chunk-6QOYS63L.js";
 
 // src/live.ts
 import * as Y from "yjs";
@@ -128,16 +128,37 @@ var LiveService = class {
       throw unreachable(error);
     }
   }
-  /** The room is only a copy, so a new document is made in the store. A room seeds from it on the next join. */
-  async create(id, markdown) {
-    const response = await fetch(`${base(this.options.server)}/api/v1/docs`, {
-      method: "POST",
-      headers: { authorization: `Bearer ${this.options.token}`, "content-type": "application/json" },
-      body: JSON.stringify({ id, markdown })
+  async call(path, init) {
+    const response = await fetch(`${base(this.options.server)}${path}`, {
+      method: init.method,
+      headers: { authorization: `Bearer ${this.options.token}`, ...init.body ? { "content-type": "application/json" } : {} },
+      body: init.body ? JSON.stringify(init.body) : void 0
     }).catch((error) => {
       throw unreachable(error);
     });
     if (!response.ok) throw await refusal(response, "the server refused the request");
+    return response;
+  }
+  /** The room is only a copy, so a new document is made in the store. A room seeds from it on the next join. */
+  async create(id, markdown) {
+    await this.call("/api/v1/docs", { method: "POST", body: { id, markdown } });
+  }
+  // The catalog lives in the store, not in a room, so these go to the HTTP API.
+  async list() {
+    const body = await (await this.call("/api/v1/docs", { method: "GET" })).json().catch(() => void 0);
+    const who = (w) => typeof w === "object" && w !== null && PRINCIPAL_KINDS.includes(w.kind) && typeof w.name === "string" && w.name !== "";
+    const row = (r) => {
+      const d = r;
+      return typeof r === "object" && r !== null && typeof d.id === "string" && typeof d.title === "string" && typeof d.createdAt === "number" && typeof d.updatedAt === "number" && who(d.createdBy) && who(d.updatedBy);
+    };
+    if (!Array.isArray(body) || !body.every(row)) throw new DocError("INVALID_INPUT", "the server sent a document list that is not valid");
+    return body;
+  }
+  async rename(id, title) {
+    await this.call(`/api/v1/docs/${encodeURIComponent(id)}/rename`, { method: "POST", body: { title } });
+  }
+  async remove(id) {
+    await this.call(`/api/v1/docs/${encodeURIComponent(id)}/remove`, { method: "POST", body: {} });
   }
   async read(id, run) {
     const live = await this.join(id);

package/dist/{chunk-IU3YIQ4Y.js → chunk-FX755I7V.js}

@@ -1,15 +1,15 @@
 import {
   DocsService,
   MAX_LIVE_BYTES
-} from "./chunk-FZA5LQV3.js";
+} from "./chunk-YNHZCIGO.js";
 import {
   commands
-} from "./chunk-GYQFTF2E.js";
+} from "./chunk-S6MQDWFK.js";
 import {
   DocError,
   PRINCIPAL_KINDS,
   parseAuthor
-} from "./chunk-YBBQNCMC.js";
+} from "./chunk-6QOYS63L.js";
 
 // src/worker.ts
 import { Hono } from "hono";
@@ -104,6 +104,22 @@ async function readCapped(request, cap) {
   }
   return whole;
 }
+var WS_PROTOCOL = "agentic-docs";
+var WS_BEARER = `${WS_PROTOCOL}.bearer.`;
+function socketBearer(c) {
+  if (c.req.header("upgrade") !== "websocket" || !c.req.path.endsWith("/ws")) return void 0;
+  for (const offered of (c.req.header("sec-websocket-protocol") ?? "").split(",")) {
+    const part = offered.trim();
+    if (!part.startsWith(WS_BEARER)) continue;
+    try {
+      const base64 = part.slice(WS_BEARER.length).replace(/-/g, "+").replace(/_/g, "/");
+      return new TextDecoder("utf-8", { fatal: true }).decode(Uint8Array.from(atob(base64), (ch) => ch.charCodeAt(0)));
+    } catch {
+      return void 0;
+    }
+  }
+  return void 0;
+}
 var DOC_ID = /^[a-z0-9][a-z0-9_-]{0,63}$/;
 function createApp(source, options = {}) {
   const app2 = new Hono();
@@ -113,7 +129,7 @@ function createApp(source, options = {}) {
   });
   app2.get("/health", (c) => c.json({ ok: true, pack: "agentic-documents" }));
   app2.use("/api/v1/*", async (c, next) => {
-    const bearer = /^Bearer (.+)$/.exec(c.req.header("authorization") ?? "")?.[1];
+    const bearer = /^Bearer (.+)$/.exec(c.req.header("authorization") ?? "")?.[1] ?? socketBearer(c);
     const identity = bearer === void 0 ? void 0 : identityFor(c.env?.AGENTIC_DOCS_TOKENS, bearer);
     if (!identity) return fail("UNAUTHENTICATED", "send a valid bearer token", 401);
     c.set("author", identity.principal);
@@ -130,13 +146,17 @@ function createApp(source, options = {}) {
     const { contributors } = await options.live(c.env ?? {}).meta(c.req.param("id"));
     return c.json({ contributors: contributors.map(({ id, kind, machine }) => ({ name: id, kind, machine })) });
   });
-  app2.get("/api/v1/docs/:id/ws", (c) => {
+  app2.get("/api/v1/docs/:id/ws", async (c) => {
     const id = c.req.param("id");
     if (!options.live) return fail("NOT_FOUND", "this server hosts no live rooms", 404);
     if (c.req.header("upgrade") !== "websocket") return fail("UPGRADE_REQUIRED", "open this route as a WebSocket", 426);
     if (!DOC_ID.test(id)) return fail("INVALID_INPUT", `invalid document id "${id}"`, 400);
     const { kind, name } = c.get("author");
-    return options.live(c.env ?? {}).connect(id, c.req.raw, { principal: { id: name, kind }, role: c.get("role"), name });
+    const opened = options.live(c.env ?? {}).connect(id, c.req.raw, { principal: { id: name, kind }, role: c.get("role"), name });
+    if (!(c.req.header("sec-websocket-protocol") ?? "").split(",").some((p) => p.trim() === WS_PROTOCOL)) return opened;
+    const room = await opened;
+    const socket = room.webSocket;
+    return socket ? new Response(null, { status: 101, webSocket: socket, headers: new Headers([...room.headers, ["sec-websocket-protocol", WS_PROTOCOL]]) }) : room;
   });
   async function run(c, command, input) {
     try {
@@ -171,12 +191,14 @@ function createApp(source, options = {}) {
   app2.post("/api/v1/docs/:id/checkpoint", async (c) => {
     if (c.get("role") === "viewer") throw new DocError("FORBIDDEN", "this token is a viewer; it cannot change a document");
     const update = await readCapped(c.req.raw, MAX_LIVE_BYTES);
-    await (await serviceOf(c)).checkpoint(c.req.param("id"), update, c.get("author"));
+    await (await serviceOf(c)).checkpoint(c.req.param("id"), update, c.get("author"), { create: c.req.query("create") !== "false" });
     return c.json({ ok: true });
   });
   const create = commands.find((c) => c.name === "new");
+  const listing = commands.find((c) => c.name === "list");
   app2.post("/api/v1/docs", async (c) => run(c, create, await body(c)));
-  for (const command of commands.filter((c) => c !== create)) {
+  app2.get("/api/v1/docs", (c) => run(c, listing, {}));
+  for (const command of commands.filter((c) => c !== create && c !== listing)) {
     const path = `/api/v1/docs/:id/${command.name}`;
     if (command.readOnly) app2.get(path, (c) => run(c, command, { ...c.req.query(), id: c.req.param("id") }));
     else app2.post(path, async (c) => run(c, command, { ...await body(c), id: c.req.param("id") }));