agentic-comments 0.3.0 → 0.5.0

package/README.md

@@ -55,6 +55,33 @@ normal sync, and every replica sees the same threads.
 - A malformed thread from a bad replica is skipped. A bad message is left out, and `skipped` on the
   thread counts those. `problems()` names them.
 
+## Anchors for plain text
+
+`agentic-comments/anchor` pins a range of a plain string. It needs no Yjs and no framework.
+Offsets are UTF-16 code units, like `slice`.
+
+```ts
+import { createAnchor, resolveAnchor } from "agentic-comments/anchor";
+
+const anchor = createAnchor("Hello brave world", 6, 11);
+const edits = [{ from: 0, to: 0, insert: "Oh, " }];
+resolveAnchor(anchor, "Oh, Hello brave world", edits, 17);
+// { state: "attached", from: 10, to: 15, method: "mapped" }
+```
+
+- An edit is `{ from, to, insert }`. Edits apply one after another, each in the text left by the one before.
+- `resolveAnchor(anchor, newText, edits?, originalLength?)` maps the range through the edits. Pass
+  `originalLength`, the length of the old text, so it can check that the edits fit both texts.
+- With edits, the edits are the truth, and the quote is not searched. A range that holds other text is `edited`.
+- With no edits, it searches for the quote. One match wins. With many, the best fit of the text around the
+  quote wins. On a tie, the match at the old offsets wins, or else the anchor is `orphaned`, because a wrong
+  place is worse than none. More than 500 matches orphan too.
+- `edited` means the range exists but holds other text. `orphaned` means the content is gone, the quote is ambiguous, the edits do not fit the text, or the anchor is bad data.
+- An insert at an edge of the range stays outside it. Deleting the whole range orphans it.
+- `createAnchor` throws a `RangeError` for an empty range, a range outside the text, or a range that cuts a
+  surrogate pair in two. It does not check grapheme boundaries, so a flag or a joined emoji can still be cut.
+- `mapPosition` and `mapRange` move offsets through edits on their own.
+
 ## When the content changes
 
 Every thread and suggestion has an `anchorState`:
@@ -216,6 +243,34 @@ curl -H "authorization: Bearer $TOKEN" -H "content-type: application/json" \
   http://127.0.0.1:8787/api/v1/docs/d1/threads
 ```
 
+## HTTP client
+
+`agentic-comments/client` is a typed client for the Worker routes. It uses only `fetch`, so it runs in browsers,
+Workers, and Node.
+
+```ts
+import { createClient, CommentsApiError } from "agentic-comments/client";
+
+const comments = createClient({ baseUrl: "https://comments.example.com", token });
+await comments.createDocument({ id: "d1", text: "The quick brown fox" });
+const thread = await comments.addThread("d1", { anchor: { type: "text", quote: "fox" }, body: "Which fox?" });
+await comments.reply("d1", thread.id, { body: "This one." });
+try {
+  await comments.accept("d1", "missing");
+} catch (error) {
+  if (error instanceof CommentsApiError) console.error(error.code, error.status);
+}
+```
+
+- The methods match the routes: `me`, `createDocument`, `getDocument`, `listThreads`, `getThread`, `addThread`, `reply`,
+  `resolve`, `reopen`, `relocate`, `listSuggestions`, `suggest`, `accept`, `reject`. Each takes an optional `{ signal }`.
+- `baseUrl` is the Worker URL, `http` or `https`, with no query, hash, or credentials.
+- The client never sends an author. The Worker stamps one from the token.
+- A failed call throws `CommentsApiError`. `code` is the API error code, or `UNKNOWN` when the reply is not an API
+  error. `status` is the HTTP status. A `200` reply with the wrong shape also fails as `UNKNOWN`.
+- The client never follows a redirect and never retries. A write that you abort after the client sends it can still apply:
+  read the thread before you try again.
+
 ## Live demo
 
 A demo Worker runs at <https://agentic-comments-demo.hello-fd1.workers.dev>. It is a staging site. Check it with

package/dist/anchoring.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Plain-text anchors that survive edits. No Yjs, no framework. Offsets are UTF-16 code units, like
+ * `String.prototype.slice`. An anchor keeps its quote and some text around it, so it can be found again
+ * when you have no edit list.
+ */
+/** One edit: replace `text.slice(from, to)` with `insert`. A pure insert has `from === to`. */
+interface Edit {
+    from: number;
+    to: number;
+    insert: string;
+}
+interface TextRangeAnchor {
+    /** The text under the range when the anchor was made. */
+    quote: string;
+    /** Text just before the range. */
+    prefix: string;
+    /** Text just after the range. */
+    suffix: string;
+    /** The range at creation, in the text it was made for. */
+    from: number;
+    to: number;
+}
+interface OffsetRange {
+    from: number;
+    to: number;
+}
+/**
+ * `attached`: the range holds the quote. `edited`: the range still exists but holds other text.
+ * `orphaned`: the content is gone, or the quote is too ambiguous to trust.
+ */
+type Resolution = {
+    state: "attached";
+    from: number;
+    to: number;
+    method: "mapped" | "quote";
+} | {
+    state: "edited";
+    from: number;
+    to: number;
+} | {
+    state: "orphaned";
+};
+declare const CONTEXT_LENGTH = 32;
+declare const MAX_QUOTE_LENGTH = 2000;
+/** The most copies of a quote that `resolveAnchor` ranks. With more, the anchor is orphaned. */
+declare const MAX_MATCHES = 500;
+/** Pin the range `from..to` of `text`. Throws a `RangeError` when the range is empty, outside the text, or splits a character. */
+declare function createAnchor(text: string, from: number, to: number): TextRangeAnchor;
+/**
+ * Move one position through edits made one after another. `assoc` 1 puts a position that sits at an
+ * insert after the insert. `assoc` -1 puts it before. A position inside a replaced range moves to the
+ * end of the insert with `assoc` 1, and to the start of the insert with `assoc` -1. `length` is the text length before the first edit.
+ */
+declare function mapPosition(pos: number, edits: readonly Edit[], assoc?: 1 | -1, length?: number): number;
+/**
+ * Move a range through edits. An insert at either edge stays outside the range. Returns null when the
+ * edits delete the whole range.
+ */
+declare function mapRange(range: OffsetRange, edits: readonly Edit[], length?: number): OffsetRange | null;
+/**
+ * Find an anchor in `newText`.
+ *
+ * With `edits` (the changes from the text the anchor was made for to `newText`), the edits are the truth:
+ * the mapped range is `attached` if it holds the quote, `edited` if it holds other text, and `orphaned`
+ * if the edits delete it or it falls outside the text. The quote is not searched. Pass `originalLength`
+ * (the length of the old text) to also check that the edits fit both texts.
+ *
+ * With no edits, search for the quote. One match wins. With several, the match whose surrounding text
+ * fits best wins. On a tie, the match at the old offsets wins, else the anchor is `orphaned`: a wrong
+ * place is worse than none. A bad anchor, a half character, and too many matches also orphan.
+ */
+declare function resolveAnchor(anchor: TextRangeAnchor, newText: string, edits?: readonly Edit[], originalLength?: number): Resolution;
+
+export { CONTEXT_LENGTH, type Edit, MAX_MATCHES, MAX_QUOTE_LENGTH, type OffsetRange, type Resolution, type TextRangeAnchor, createAnchor, mapPosition, mapRange, resolveAnchor };

package/dist/anchoring.js

@@ -0,0 +1,122 @@
+// src/anchoring.ts
+var CONTEXT_LENGTH = 32;
+var MAX_QUOTE_LENGTH = 2e3;
+var MAX_MATCHES = 500;
+var isHigh = (c) => c >= 55296 && c <= 56319;
+var isLow = (c) => c >= 56320 && c <= 57343;
+var isLoneHalf = (code, atStart) => atStart ? isLow(code) : isHigh(code);
+function splits(text, index) {
+  return index > 0 && index < text.length && isHigh(text.charCodeAt(index - 1)) && isLow(text.charCodeAt(index));
+}
+var whole = (n) => typeof n === "number" && Number.isSafeInteger(n) && n >= 0;
+function createAnchor(text, from, to) {
+  if (typeof text !== "string") throw new TypeError("text must be a string");
+  if (!whole(from) || !whole(to) || to <= from || to > text.length) {
+    throw new RangeError(`the range ${String(from)}..${String(to)} is not inside the text, which has ${text.length} characters`);
+  }
+  if (splits(text, from) || splits(text, to)) throw new RangeError("the range cuts a character in two");
+  if (isLow(text.charCodeAt(from)) || isHigh(text.charCodeAt(to - 1))) throw new RangeError("the range starts or ends inside a character");
+  if (to - from > MAX_QUOTE_LENGTH) throw new RangeError(`a quote holds up to ${MAX_QUOTE_LENGTH} characters`);
+  let before = Math.max(0, from - CONTEXT_LENGTH);
+  if (splits(text, before)) before += 1;
+  let after = Math.min(text.length, to + CONTEXT_LENGTH);
+  if (splits(text, after)) after -= 1;
+  return { quote: text.slice(from, to), prefix: text.slice(before, from), suffix: text.slice(to, after), from, to };
+}
+function checkEdit(edit, length) {
+  if (typeof edit !== "object" || edit === null) throw new RangeError("an edit must be an object");
+  if (!whole(edit.from) || !whole(edit.to) || edit.to < edit.from || edit.to > length || typeof edit.insert !== "string") {
+    throw new RangeError(`the edit ${JSON.stringify([edit.from, edit.to])} is not inside a text of ${length} characters`);
+  }
+}
+function mapPosition(pos, edits, assoc = 1, length = Infinity) {
+  if (!whole(pos) || !Array.isArray(edits) || assoc !== 1 && assoc !== -1) throw new RangeError("the position must be a whole number, the edits a list, and assoc 1 or -1");
+  if (length !== Infinity && (!whole(length) || pos > length)) throw new RangeError("the position must be inside a text of a whole length");
+  let len = length;
+  let p = pos;
+  for (const edit of edits) {
+    checkEdit(edit, len);
+    const removed = edit.to - edit.from;
+    const added = edit.insert.length;
+    if (p > edit.to) p += added - removed;
+    else if (p >= edit.from) {
+      if (removed === 0) p = assoc === 1 ? p + added : p;
+      else if (p === edit.from) p = edit.from;
+      else if (p === edit.to) p = edit.from + added;
+      else p = assoc === 1 ? edit.from + added : edit.from;
+    }
+    len = len === Infinity ? len : len - removed + added;
+  }
+  return p;
+}
+function mapRange(range, edits, length = Infinity) {
+  if (!Array.isArray(edits)) throw new RangeError("the edits must be a list");
+  if (!whole(range?.from) || !whole(range?.to) || range.to <= range.from) throw new RangeError("the range must be two whole numbers, from before to");
+  let { from, to } = range;
+  let len = length;
+  for (const edit of edits) {
+    from = mapPosition(from, [edit], 1, len);
+    to = mapPosition(to, [edit], -1, len);
+    if (to <= from) return null;
+    len = len === Infinity ? len : len - (edit.to - edit.from) + edit.insert.length;
+  }
+  return { from, to };
+}
+function occurrences(text, quote, max) {
+  const out = [];
+  for (let i = text.indexOf(quote); i >= 0 && out.length < max; i = text.indexOf(quote, i + 1)) out.push(i);
+  return out;
+}
+var commonSuffix = (a, b) => {
+  let n = 0;
+  while (n < a.length && n < b.length && a[a.length - 1 - n] === b[b.length - 1 - n]) n++;
+  return n;
+};
+var commonPrefix = (a, b) => {
+  let n = 0;
+  while (n < a.length && n < b.length && a[n] === b[n]) n++;
+  return n;
+};
+function resolveAnchor(anchor, newText, edits, originalLength) {
+  if (typeof newText !== "string") throw new TypeError("text must be a string");
+  if (typeof anchor?.quote !== "string" || anchor.quote === "") return { state: "orphaned" };
+  const quote = anchor.quote;
+  if (quote.length > MAX_QUOTE_LENGTH || edits !== void 0 && !Array.isArray(edits)) return { state: "orphaned" };
+  if (!whole(anchor.from) || !whole(anchor.to) || anchor.to - anchor.from !== quote.length) return { state: "orphaned" };
+  if (isLoneHalf(quote.charCodeAt(0), true) || isLoneHalf(quote.charCodeAt(quote.length - 1), false)) return { state: "orphaned" };
+  if (originalLength !== void 0) {
+    const final = (edits ?? []).reduce((n, e) => n - (e?.to - e?.from) + (typeof e?.insert === "string" ? e.insert.length : NaN), originalLength);
+    if (!whole(originalLength) || anchor.to > originalLength || edits && final !== newText.length) return { state: "orphaned" };
+  }
+  let mapped;
+  try {
+    mapped = edits ? mapRange({ from: anchor.from, to: anchor.to }, edits, originalLength) : { from: anchor.from, to: anchor.to };
+  } catch (error) {
+    if (error instanceof RangeError) return { state: "orphaned" };
+    throw error;
+  }
+  if (edits && mapped === null) return { state: "orphaned" };
+  const valid = mapped && mapped.to <= newText.length && !splits(newText, mapped.from) && !splits(newText, mapped.to);
+  if (edits) {
+    if (!valid || !mapped) return { state: "orphaned" };
+    return newText.slice(mapped.from, mapped.to) === quote ? { state: "attached", from: mapped.from, to: mapped.to, method: "mapped" } : { state: "edited", from: mapped.from, to: mapped.to };
+  }
+  const found = occurrences(newText, quote, MAX_MATCHES + 1).filter((at) => !splits(newText, at) && !splits(newText, at + quote.length));
+  if (found.length === 0 || found.length > MAX_MATCHES) return { state: "orphaned" };
+  const result = (at) => ({ state: "attached", from: at, to: at + quote.length, method: at === anchor.from ? "mapped" : "quote" });
+  if (found.length === 1) return result(found[0]);
+  const score = (at) => commonSuffix(anchor.prefix ?? "", newText.slice(Math.max(0, at - CONTEXT_LENGTH), at)) + commonPrefix(anchor.suffix ?? "", newText.slice(at + quote.length, at + quote.length + CONTEXT_LENGTH));
+  const ranked = found.map((at) => ({ at, score: score(at) })).sort((a, b) => b.score - a.score);
+  const best = ranked.filter((r) => r.score === ranked[0].score);
+  if (best.length === 1) return result(best[0].at);
+  return best.some((r) => r.at === anchor.from) ? result(anchor.from) : { state: "orphaned" };
+}
+export {
+  CONTEXT_LENGTH,
+  MAX_MATCHES,
+  MAX_QUOTE_LENGTH,
+  createAnchor,
+  mapPosition,
+  mapRange,
+  resolveAnchor
+};

package/dist/{chunk-TTTX3R6M.js → chunk-ABXAPWXD.js}

@@ -1,12 +1,12 @@
 import {
   VERSION
-} from "./chunk-GMA5I5L6.js";
+} from "./chunk-WQHJNHAR.js";
 import {
   CommentsService
-} from "./chunk-IB6ANO32.js";
+} from "./chunk-NQWRFKJ6.js";
 import {
   CommentsError
-} from "./chunk-GSAJOCDV.js";
+} from "./chunk-BSNBDKR2.js";
 
 // src/mcp.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

package/dist/{chunk-GSAJOCDV.js → chunk-BSNBDKR2.js}

@@ -114,7 +114,7 @@ function onlyOccurrence(type, quote) {
 }
 
 // src/principal.ts
-var PRINCIPAL_KINDS = ["human", "agent_of_human", "agent_of_agent", "agent", "user_token"];
+import { PRINCIPAL_KINDS } from "agentic-identity";
 var MAX_NAME = 128;
 var issued = /* @__PURE__ */ new WeakSet();
 var Actor = class _Actor {

package/dist/{chunk-YU5U4P22.js → chunk-HXXJNFEO.js}

@@ -2,7 +2,7 @@ import {
   CommentsError,
   PRINCIPAL_KINDS,
   stamp
-} from "./chunk-GSAJOCDV.js";
+} from "./chunk-BSNBDKR2.js";
 
 // src/file-store.ts
 import { createHash } from "crypto";

package/dist/{chunk-IB6ANO32.js → chunk-NQWRFKJ6.js}

@@ -7,7 +7,7 @@ import {
   textAnchor,
   textOf,
   textRange
-} from "./chunk-GSAJOCDV.js";
+} from "./chunk-BSNBDKR2.js";
 
 // src/local-host.ts
 import * as Y from "yjs";

package/dist/{chunk-GMA5I5L6.js → chunk-WQHJNHAR.js}

@@ -1,6 +1,6 @@
 // src/version.ts
 import { createRequire } from "module";
-var VERSION = true ? "0.3.0" : readPackageVersion();
+var VERSION = true ? "0.5.0" : readPackageVersion();
 
 export {
   VERSION

package/dist/cli.js

@@ -3,17 +3,17 @@ import {
   FileStore,
   lockTimeoutFrom,
   operatorActor
-} from "./chunk-YU5U4P22.js";
+} from "./chunk-HXXJNFEO.js";
 import {
   VERSION
-} from "./chunk-GMA5I5L6.js";
+} from "./chunk-WQHJNHAR.js";
 import {
   CommentsService,
   TEXT_ROOT
-} from "./chunk-IB6ANO32.js";
+} from "./chunk-NQWRFKJ6.js";
 import {
   CommentsError
-} from "./chunk-GSAJOCDV.js";
+} from "./chunk-BSNBDKR2.js";
 
 // src/cli.ts
 import { readFileSync, realpathSync } from "fs";
@@ -155,7 +155,7 @@ async function runCli(argv, io) {
       return 0;
     }
     if (p.command === "mcp") {
-      const { startMcp } = await import("./mcp-YERA77HT.js");
+      const { startMcp } = await import("./mcp-JMEXA2RI.js");
       await startMcp(store, operatorActor(p.flags["--as"] ?? io.env.AGENTIC_COMMENTS_AS, io.env.AGENTIC_COMMENTS_SCOPES));
       return 0;
     }

package/dist/client.d.ts

@@ -0,0 +1,72 @@
+import { L as ListFilter, A as AnchorSpec } from './service-hpWbnSmc.js';
+import { C as CommentsErrorCode } from './errors-CNgWMVQT.js';
+import { PrincipalKind } from 'agentic-identity';
+export { PrincipalKind } from 'agentic-identity';
+import { T as Thread, N as NewReply, M as Message, S as Suggestion } from './suggestions-CvJwo6r4.js';
+import 'yjs';
+
+/** Codes the comment rules return, plus the ones the Worker and its auth return. */
+type ApiErrorCode = CommentsErrorCode | "UNAUTHENTICATED" | "NOT_FOUND" | "INTERNAL" | "UNKNOWN";
+/** Thrown for every reply that is not a success. `code` is the API error code and `status` is the HTTP status. */
+declare class CommentsApiError extends Error {
+    readonly code: ApiErrorCode;
+    readonly status: number;
+    constructor(code: ApiErrorCode, status: number, message: string);
+}
+interface ClientOptions {
+    /** The Worker origin, for example https://comments.example.com. The client adds /api/v1. */
+    baseUrl: string;
+    /** A bearer credential that the Worker's auth accepts. */
+    token: string;
+    fetch?: typeof fetch;
+}
+/**
+ * Every method takes an optional signal. An aborted call rejects with the signal reason, not a
+ * CommentsApiError. A write that was aborted after it was sent may still have applied: read the
+ * thread before you try again.
+ */
+interface CallOptions {
+    signal?: AbortSignal;
+}
+interface Me {
+    kind: PrincipalKind;
+    name: string;
+    scopes: string[];
+}
+type ThreadFilter = ListFilter;
+type SuggestionListFilter = Pick<ListFilter, "status" | "anchorState">;
+interface CommentsClient {
+    me(options?: CallOptions): Promise<Me>;
+    createDocument(input: {
+        id: string;
+        text?: string;
+    }, options?: CallOptions): Promise<{
+        id: string;
+    }>;
+    getDocument(docId: string, options?: CallOptions): Promise<{
+        id: string;
+        text: string;
+    }>;
+    listThreads(docId: string, filter?: ThreadFilter, options?: CallOptions): Promise<Thread[]>;
+    getThread(docId: string, threadId: string, options?: CallOptions): Promise<Thread>;
+    addThread(docId: string, input: {
+        anchor: AnchorSpec;
+        body: string;
+        mentions?: string[];
+    }, options?: CallOptions): Promise<Thread>;
+    reply(docId: string, threadId: string, input: NewReply, options?: CallOptions): Promise<Message>;
+    resolve(docId: string, threadId: string, options?: CallOptions): Promise<Thread>;
+    reopen(docId: string, threadId: string, options?: CallOptions): Promise<Thread>;
+    relocate(docId: string, threadId: string, options?: CallOptions): Promise<Thread>;
+    listSuggestions(docId: string, filter?: SuggestionListFilter, options?: CallOptions): Promise<Suggestion[]>;
+    suggest(docId: string, input: {
+        anchor: AnchorSpec;
+        change: unknown;
+        summary?: string;
+    }, options?: CallOptions): Promise<Suggestion>;
+    accept(docId: string, suggestionId: string, options?: CallOptions): Promise<Suggestion>;
+    reject(docId: string, suggestionId: string, options?: CallOptions): Promise<Suggestion>;
+}
+declare function createClient(options: ClientOptions): CommentsClient;
+
+export { AnchorSpec, type ApiErrorCode, type CallOptions, type ClientOptions, CommentsApiError, type CommentsClient, CommentsErrorCode, ListFilter, type Me, Message, NewReply, Suggestion, type SuggestionListFilter, Thread, type ThreadFilter, createClient };

package/dist/client.js

@@ -0,0 +1,135 @@
+// src/client.ts
+var CODES = {
+  INVALID_AUTHOR: true,
+  INVALID_INPUT: true,
+  INVALID_ANCHOR: true,
+  NO_THREAD: true,
+  THREAD_RESOLVED: true,
+  CORRUPT: true,
+  NO_SUGGESTION: true,
+  FORBIDDEN: true,
+  ALREADY_DECIDED: true,
+  APPLY_FAILED: true,
+  RELOCATE_FAILED: true,
+  STORE_MISSING: true,
+  STORE_EXISTS: true,
+  STORE_CORRUPT: true,
+  STORE_LOCKED: true,
+  STORE_FULL: true,
+  NO_DOCUMENT: true,
+  DOCUMENT_EXISTS: true,
+  CONFLICT: true,
+  MISCONFIGURED: true,
+  USAGE: true,
+  UNAUTHENTICATED: true,
+  NOT_FOUND: true,
+  INTERNAL: true,
+  UNKNOWN: true
+};
+var isKnownCode = (v) => typeof v === "string" && Object.hasOwn(CODES, v);
+var CommentsApiError = class extends Error {
+  code;
+  status;
+  constructor(code, status, message) {
+    super(message);
+    this.name = "CommentsApiError";
+    this.code = code;
+    this.status = status;
+  }
+};
+var KINDS = { human: true, agent_of_human: true, agent_of_agent: true, agent: true, user_token: true };
+var isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var isString = (v) => typeof v === "string";
+var SHAPES = {
+  me: (v) => isObject(v) && (typeof v.kind === "string" && Object.hasOwn(KINDS, v.kind)) && isString(v.name) && Array.isArray(v.scopes),
+  created: (v) => isObject(v) && isString(v.id),
+  document: (v) => isObject(v) && isString(v.id) && isString(v.text),
+  thread: (v) => isObject(v) && isString(v.id) && isObject(v.anchor) && (v.status === "open" || v.status === "resolved") && Array.isArray(v.messages),
+  threads: (v) => Array.isArray(v) && v.every(SHAPES.thread),
+  message: (v) => isObject(v) && isString(v.id) && isString(v.body) && isObject(v.author),
+  suggestion: (v) => isObject(v) && isString(v.id) && isObject(v.anchor) && isString(v.status) && isObject(v.author),
+  suggestions: (v) => Array.isArray(v) && v.every(SHAPES.suggestion)
+};
+function createClient(options) {
+  if (typeof options.baseUrl !== "string" || options.baseUrl === "") throw new TypeError("createClient needs a baseUrl");
+  if (typeof options.token !== "string" || options.token === "") throw new TypeError("createClient needs a token");
+  let origin;
+  try {
+    origin = new URL(options.baseUrl);
+  } catch {
+    throw new TypeError("baseUrl must be an absolute URL");
+  }
+  if (origin.protocol !== "https:" && origin.protocol !== "http:") throw new TypeError("baseUrl must be an http or https URL");
+  if (origin.search !== "" || origin.hash !== "" || origin.username !== "" || origin.password !== "") {
+    throw new TypeError("baseUrl must have no query, hash, or credentials");
+  }
+  const root = `${origin.origin}${origin.pathname.replace(/\/+$/, "")}/api/v1`;
+  const token = options.token;
+  const send = (input, init) => {
+    const run = options.fetch ?? globalThis.fetch;
+    return run(input, init);
+  };
+  const seg = (value) => {
+    if (typeof value !== "string" || /^(?:\.|%2e){0,2}$/i.test(value)) throw new TypeError("an id must be a non-empty string that is not . or ..");
+    return encodeURIComponent(value);
+  };
+  const query = (filter) => {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(filter ?? {})) if (value !== void 0) params.set(key, String(value));
+    const text = params.toString();
+    return text === "" ? "" : `?${text}`;
+  };
+  async function call(method, path, body, callOptions, shape) {
+    const headers = { authorization: `Bearer ${token}` };
+    if (body !== void 0) headers["content-type"] = "application/json";
+    const response = await send(`${root}${path}`, {
+      method,
+      headers,
+      body: body === void 0 ? void 0 : JSON.stringify(body),
+      signal: callOptions?.signal,
+      // Never follow a redirect: it would send a write to another host.
+      redirect: "manual"
+    });
+    const text = await response.text();
+    let parsed;
+    try {
+      parsed = text === "" ? void 0 : JSON.parse(text);
+    } catch {
+      parsed = void 0;
+    }
+    if (!response.ok) {
+      const error = parsed?.error;
+      const code = isKnownCode(error?.code) ? error.code : "UNKNOWN";
+      const message = typeof error?.message === "string" ? error.message : `HTTP ${response.status}`;
+      throw new CommentsApiError(code, response.status, message);
+    }
+    if (!SHAPES[shape](parsed)) throw new CommentsApiError("UNKNOWN", response.status, `the reply is not a ${shape}`);
+    return parsed;
+  }
+  const doc = (id) => `/docs/${seg(id)}`;
+  const thread = (id, threadId) => `${doc(id)}/threads/${seg(threadId)}`;
+  const suggestion = (id, suggestionId) => `${doc(id)}/suggestions/${seg(suggestionId)}`;
+  const methods = {
+    me: (o) => call("GET", "/me", void 0, o, "me"),
+    createDocument: (input, o) => call("POST", "/docs", input, o, "created"),
+    getDocument: (id, o) => call("GET", doc(id), void 0, o, "document"),
+    listThreads: (id, filter, o) => call("GET", `${doc(id)}/threads${query(filter)}`, void 0, o, "threads"),
+    getThread: (id, threadId, o) => call("GET", thread(id, threadId), void 0, o, "thread"),
+    addThread: (id, input, o) => call("POST", `${doc(id)}/threads`, input, o, "thread"),
+    reply: (id, threadId, input, o) => call("POST", `${thread(id, threadId)}/replies`, input, o, "message"),
+    resolve: (id, threadId, o) => call("POST", `${thread(id, threadId)}/resolve`, void 0, o, "thread"),
+    reopen: (id, threadId, o) => call("POST", `${thread(id, threadId)}/reopen`, void 0, o, "thread"),
+    relocate: (id, threadId, o) => call("POST", `${thread(id, threadId)}/relocate`, void 0, o, "thread"),
+    listSuggestions: (id, filter, o) => call("GET", `${doc(id)}/suggestions${query(filter)}`, void 0, o, "suggestions"),
+    suggest: (id, input, o) => call("POST", `${doc(id)}/suggestions`, input, o, "suggestion"),
+    accept: (id, suggestionId, o) => call("POST", `${suggestion(id, suggestionId)}/accept`, void 0, o, "suggestion"),
+    reject: (id, suggestionId, o) => call("POST", `${suggestion(id, suggestionId)}/reject`, void 0, o, "suggestion")
+  };
+  return Object.fromEntries(
+    Object.entries(methods).map(([name, method]) => [name, async (...args) => method(...args)])
+  );
+}
+export {
+  CommentsApiError,
+  createClient
+};

package/dist/errors-CNgWMVQT.d.ts

@@ -0,0 +1,7 @@
+type CommentsErrorCode = "INVALID_AUTHOR" | "INVALID_INPUT" | "INVALID_ANCHOR" | "NO_THREAD" | "THREAD_RESOLVED" | "CORRUPT" | "NO_SUGGESTION" | "FORBIDDEN" | "ALREADY_DECIDED" | "APPLY_FAILED" | "RELOCATE_FAILED" | "STORE_MISSING" | "STORE_EXISTS" | "STORE_CORRUPT" | "STORE_LOCKED" | "STORE_FULL" | "NO_DOCUMENT" | "DOCUMENT_EXISTS" | "CONFLICT" | "MISCONFIGURED" | "USAGE";
+declare class CommentsError extends Error {
+    readonly code: CommentsErrorCode;
+    constructor(code: CommentsErrorCode, message: string);
+}
+
+export { type CommentsErrorCode as C, CommentsError as a };

package/dist/index.d.ts

@@ -1,15 +1,11 @@
-import { a as Author, C as Comments, b as Suggestions } from './suggestions-D4ZJFzzR.js';
-export { c as ACCEPT_SCOPE, A as Actor, d as Anchor, e as AnchorKind, f as AnchorState, g as ApplyContext, h as CanvasAnchor, i as CellAnchor, j as CommentsOptions, M as Message, N as NewReply, k as NewSuggestion, l as NewThread, P as PRINCIPAL_KINDS, m as PrincipalKind, R as RelativePositionJson, n as RevertContext, o as SlideAnchor, p as StampInput, S as Suggestion, q as SuggestionFilter, r as SuggestionHost, s as TextAnchor, T as Thread, t as ThreadFilter, u as authorLabel, v as stamp, w as textAnchor, x as textOf } from './suggestions-D4ZJFzzR.js';
+import { a as Author, C as Comments, b as Suggestions } from './suggestions-CvJwo6r4.js';
+export { c as ACCEPT_SCOPE, A as Actor, d as Anchor, e as AnchorKind, f as AnchorState, g as ApplyContext, h as CanvasAnchor, i as CellAnchor, j as CommentsOptions, M as Message, N as NewReply, k as NewSuggestion, l as NewThread, R as RelativePositionJson, m as RevertContext, n as SlideAnchor, o as StampInput, S as Suggestion, p as SuggestionFilter, q as SuggestionHost, r as TextAnchor, T as Thread, s as ThreadFilter, t as authorLabel, u as stamp, v as textAnchor, w as textOf } from './suggestions-CvJwo6r4.js';
+export { a as CommentsError, C as CommentsErrorCode } from './errors-CNgWMVQT.js';
+export { PRINCIPAL_KINDS, PrincipalKind } from 'agentic-identity';
 import 'yjs';
 
 declare const VERSION: string;
 
-type CommentsErrorCode = "INVALID_AUTHOR" | "INVALID_INPUT" | "INVALID_ANCHOR" | "NO_THREAD" | "THREAD_RESOLVED" | "CORRUPT" | "NO_SUGGESTION" | "FORBIDDEN" | "ALREADY_DECIDED" | "APPLY_FAILED" | "RELOCATE_FAILED" | "STORE_MISSING" | "STORE_EXISTS" | "STORE_CORRUPT" | "STORE_LOCKED" | "STORE_FULL" | "NO_DOCUMENT" | "DOCUMENT_EXISTS" | "CONFLICT" | "MISCONFIGURED" | "USAGE";
-declare class CommentsError extends Error {
-    readonly code: CommentsErrorCode;
-    constructor(code: CommentsErrorCode, message: string);
-}
-
 type CommentEventType = "thread.created" | "message.added" | "mention" | "thread.resolved" | "thread.reopened" | "suggestion.created" | "suggestion.accepted" | "suggestion.rejected";
 /**
  * One change, in terms a notifier can route. It holds ids and never the text of a comment, a suggestion, or
@@ -102,4 +98,4 @@ declare class Notifications {
     private decided;
 }
 
-export { Author, type CommentEvent, type CommentEventType, type CommentListener, Comments, CommentsError, type CommentsErrorCode, Notifications, type NotificationsOptions, Suggestions, VERSION };
+export { Author, type CommentEvent, type CommentEventType, type CommentListener, Comments, Notifications, type NotificationsOptions, Suggestions, VERSION };

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-GMA5I5L6.js";
+} from "./chunk-WQHJNHAR.js";
 import {
   ACCEPT_SCOPE,
   Actor,
@@ -14,7 +14,7 @@ import {
   textAnchor,
   textOf,
   validDate
-} from "./chunk-GSAJOCDV.js";
+} from "./chunk-BSNBDKR2.js";
 
 // src/notifications.ts
 import * as Y from "yjs";

package/dist/local.d.ts

@@ -1,6 +1,7 @@
 import * as Y from 'yjs';
-export { A as AnchorSpec, C as CommentsService, L as ListFilter } from './service-BmMQMT_8.js';
-import { r as SuggestionHost, A as Actor } from './suggestions-D4ZJFzzR.js';
+export { A as AnchorSpec, C as CommentsService, L as ListFilter } from './service-hpWbnSmc.js';
+import { q as SuggestionHost, A as Actor } from './suggestions-CvJwo6r4.js';
+import 'agentic-identity';
 
 /** The most bytes a saved document holds. A save over this is refused, so a file never grows past what a load accepts. */
 declare const MAX_FILE: number;

package/dist/local.js

@@ -3,14 +3,14 @@ import {
   MAX_FILE,
   lockTimeoutFrom,
   operatorActor
-} from "./chunk-YU5U4P22.js";
+} from "./chunk-HXXJNFEO.js";
 import {
   CommentsService,
   TEXT_ROOT,
   VALUES_ROOT,
   localHost
-} from "./chunk-IB6ANO32.js";
-import "./chunk-GSAJOCDV.js";
+} from "./chunk-NQWRFKJ6.js";
+import "./chunk-BSNBDKR2.js";
 export {
   CommentsService,
   FileStore,

package/dist/mcp-JMEXA2RI.js

@@ -0,0 +1,11 @@
+import {
+  createMcpServer,
+  startMcp
+} from "./chunk-ABXAPWXD.js";
+import "./chunk-WQHJNHAR.js";
+import "./chunk-NQWRFKJ6.js";
+import "./chunk-BSNBDKR2.js";
+export {
+  createMcpServer,
+  startMcp
+};

package/dist/mcp-bin.js

@@ -3,15 +3,15 @@ import {
   FileStore,
   lockTimeoutFrom,
   operatorActor
-} from "./chunk-YU5U4P22.js";
+} from "./chunk-HXXJNFEO.js";
 import {
   startMcp
-} from "./chunk-TTTX3R6M.js";
+} from "./chunk-ABXAPWXD.js";
 import {
   VERSION
-} from "./chunk-GMA5I5L6.js";
-import "./chunk-IB6ANO32.js";
-import "./chunk-GSAJOCDV.js";
+} from "./chunk-WQHJNHAR.js";
+import "./chunk-NQWRFKJ6.js";
+import "./chunk-BSNBDKR2.js";
 
 // src/mcp-bin.ts
 var MCP_HELP = `agentic-comments-mcp ${VERSION}

package/dist/{service-BmMQMT_8.d.ts → service-hpWbnSmc.d.ts}

@@ -1,5 +1,5 @@
 import * as Y from 'yjs';
-import { A as Actor, T as Thread, M as Message, S as Suggestion } from './suggestions-D4ZJFzzR.js';
+import { A as Actor, T as Thread, M as Message, S as Suggestion } from './suggestions-CvJwo6r4.js';
 
 /** Where a comment or suggestion points, in terms a person or agent can write down. */
 type AnchorSpec = {

package/dist/{suggestions-D4ZJFzzR.d.ts → suggestions-CvJwo6r4.d.ts}

@@ -1,4 +1,34 @@
 import * as Y from 'yjs';
+import { PrincipalKind } from 'agentic-identity';
+
+/** What a thread keeps about who wrote a message. Scopes never reach storage. */
+interface Author {
+    kind: PrincipalKind;
+    name: string;
+}
+interface StampInput {
+    kind: PrincipalKind;
+    name: string;
+    /** Rights the host granted this principal, such as `comments:accept`. Used to decide, never stored. */
+    scopes?: string[];
+}
+/**
+ * The only author a write accepts. The host makes one from the principal it authenticated, and an
+ * operation never reads an author from its input. An object that `stamp()` did not make is refused,
+ * and a stamped one cannot change.
+ */
+declare class Actor implements Author {
+    readonly kind: PrincipalKind;
+    readonly name: string;
+    readonly scopes: readonly string[];
+    private constructor();
+    static of(input: StampInput): Actor;
+    static is(value: unknown): value is Actor;
+}
+/** Make the author for one authenticated principal. Throws when the kind or name is missing or wrong. */
+declare const stamp: (input: StampInput) => Actor;
+/** The label a UI shows. Agent work stays marked as machine-made. */
+declare function authorLabel(author: Author): "person" | "person via agent" | "agent";
 
 /** A Yjs relative position as JSON. It names an item, not an index, so it follows its text. */
 interface RelativePositionJson {
@@ -65,37 +95,6 @@ declare function textOf(type: Y.Text | Y.XmlText): string;
 /** Pin a range of a Yjs text. Later edits by any replica do not move the anchor off its text. */
 declare function textAnchor(type: Y.Text | Y.XmlText, from: number, to: number): TextAnchor;
 
-declare const PRINCIPAL_KINDS: readonly ["human", "agent_of_human", "agent_of_agent", "agent", "user_token"];
-type PrincipalKind = (typeof PRINCIPAL_KINDS)[number];
-/** What a thread keeps about who wrote a message. Scopes never reach storage. */
-interface Author {
-    kind: PrincipalKind;
-    name: string;
-}
-interface StampInput {
-    kind: PrincipalKind;
-    name: string;
-    /** Rights the host granted this principal, such as `comments:accept`. Used to decide, never stored. */
-    scopes?: string[];
-}
-/**
- * The only author a write accepts. The host makes one from the principal it authenticated, and an
- * operation never reads an author from its input. An object that `stamp()` did not make is refused,
- * and a stamped one cannot change.
- */
-declare class Actor implements Author {
-    readonly kind: PrincipalKind;
-    readonly name: string;
-    readonly scopes: readonly string[];
-    private constructor();
-    static of(input: StampInput): Actor;
-    static is(value: unknown): value is Actor;
-}
-/** Make the author for one authenticated principal. Throws when the kind or name is missing or wrong. */
-declare const stamp: (input: StampInput) => Actor;
-/** The label a UI shows. Agent work stays marked as machine-made. */
-declare function authorLabel(author: Author): "person" | "person via agent" | "agent";
-
 interface Message {
     id: string;
     at: string;
@@ -331,4 +330,4 @@ declare class Suggestions {
     settle(): void;
 }
 
-export { Actor as A, Comments as C, type Message as M, type NewReply as N, PRINCIPAL_KINDS as P, type RelativePositionJson as R, type Suggestion as S, type Thread as T, type Author as a, Suggestions as b, ACCEPT_SCOPE as c, type Anchor as d, type AnchorKind as e, type AnchorState as f, type ApplyContext as g, type CanvasAnchor as h, type CellAnchor as i, type CommentsOptions as j, type NewSuggestion as k, type NewThread as l, type PrincipalKind as m, type RevertContext as n, type SlideAnchor as o, type StampInput as p, type SuggestionFilter as q, type SuggestionHost as r, type TextAnchor as s, type ThreadFilter as t, authorLabel as u, stamp as v, textAnchor as w, textOf as x };
+export { Actor as A, Comments as C, type Message as M, type NewReply as N, type RelativePositionJson as R, type Suggestion as S, type Thread as T, type Author as a, Suggestions as b, ACCEPT_SCOPE as c, type Anchor as d, type AnchorKind as e, type AnchorState as f, type ApplyContext as g, type CanvasAnchor as h, type CellAnchor as i, type CommentsOptions as j, type NewSuggestion as k, type NewThread as l, type RevertContext as m, type SlideAnchor as n, type StampInput as o, type SuggestionFilter as p, type SuggestionHost as q, type TextAnchor as r, type ThreadFilter as s, authorLabel as t, stamp as u, textAnchor as v, textOf as w };

package/dist/worker.d.ts

@@ -1,8 +1,8 @@
 import { Hono } from 'hono';
 import { Auth, Store, PrincipalContext, Region } from 'agentic-identity';
 import { D1Like } from 'agentic-identity/cloudflare';
-import { A as Actor } from './suggestions-D4ZJFzzR.js';
-import { C as CommentsService } from './service-BmMQMT_8.js';
+import { A as Actor } from './suggestions-CvJwo6r4.js';
+import { C as CommentsService } from './service-hpWbnSmc.js';
 import 'yjs';
 
 interface WorkerEnv {

package/dist/worker.js

@@ -1,7 +1,7 @@
 import {
   CommentsService,
   TEXT_ROOT
-} from "./chunk-IB6ANO32.js";
+} from "./chunk-NQWRFKJ6.js";
 import {
   ACCEPT_SCOPE,
   CommentsError,
@@ -9,7 +9,7 @@ import {
   exact,
   invalid,
   stamp
-} from "./chunk-GSAJOCDV.js";
+} from "./chunk-BSNBDKR2.js";
 
 // src/worker.ts
 import { Hono } from "hono";

package/llms.txt

@@ -5,6 +5,7 @@ Comment threads and suggestions anchored to any content, from people and agents.
 Keywords: comments,threads,mentions,suggestions,annotations,collaboration,agents,yjs.
 
 - SDK: import { Comments, Suggestions, textAnchor } from "agentic-comments". The host calls stamp(); an agent never does.
+- Plain text anchors: import { createAnchor, resolveAnchor, mapRange } from "agentic-comments/anchor". No Yjs. resolveAnchor maps through edits, then falls back to quote + context, else orphaned.
 - Threads live on a Yjs document and merge across replicas.
 - Events: new Notifications(comments, suggestions).subscribe(listener). Ids only, never text.
 - CLI: agentic-comments <command>. MCP: agentic-comments mcp. Both use a local store file.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-comments",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Comment threads and suggestions anchored to any content, from people and agents.",
   "keywords": [
     "comments",
@@ -44,6 +44,14 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./anchor": {
+      "types": "./dist/anchoring.d.ts",
+      "import": "./dist/anchoring.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
     "./local": {
       "types": "./dist/local.d.ts",
       "import": "./dist/local.js"

package/dist/mcp-YERA77HT.js

@@ -1,11 +0,0 @@
-import {
-  createMcpServer,
-  startMcp
-} from "./chunk-TTTX3R6M.js";
-import "./chunk-GMA5I5L6.js";
-import "./chunk-IB6ANO32.js";
-import "./chunk-GSAJOCDV.js";
-export {
-  createMcpServer,
-  startMcp
-};