agentic-comments 0.1.0 → 0.3.0

package/dist/index.js

@@ -1,749 +1,210 @@
-// src/version.ts
-import { createRequire } from "module";
-var VERSION = true ? "0.1.0" : readPackageVersion();
-
-// src/threads.ts
-import * as Y2 from "yjs";
+import {
+  VERSION
+} from "./chunk-GMA5I5L6.js";
+import {
+  ACCEPT_SCOPE,
+  Actor,
+  Comments,
+  CommentsError,
+  PRINCIPAL_KINDS,
+  Suggestions,
+  authorLabel,
+  readAuthor,
+  stamp,
+  textAnchor,
+  textOf,
+  validDate
+} from "./chunk-GSAJOCDV.js";
 
-// src/anchor.ts
+// src/notifications.ts
 import * as Y from "yjs";
-
-// src/errors.ts
-var CommentsError = class extends Error {
-  constructor(code, message) {
-    super(message);
-    this.code = code;
-    this.name = "CommentsError";
-  }
-  code;
-};
-
-// src/text.ts
-var HIDDEN = /[\p{Cc}\p{Cf}]/u;
-var ID = /^[\w-]{1,64}$/;
-var BODY_FORBIDDEN = /(?![\n\r\t\u200C\u200D])[\p{Cc}\p{Cf}]/u;
-var VARIATION = /[\uFE00-\uFE0F\u{E0100}-\u{E01EF}]/u;
-var safeId = (value) => String(value).slice(0, 64).replace(/[^\p{L}\p{N}_-]/gu, "?");
-var shown = (value) => JSON.stringify(safeId(value));
-var safeText = (value) => String(value).replace(/[^\p{L}\p{N}\p{P}\p{S} ]/gu, "?").slice(0, 200);
-
-// src/anchor.ts
-var MAX_QUOTE = 2e3;
-var MAX_ANCHOR = 4096;
-var MAX_KEY = 256;
-var bad = (message) => {
-  throw new CommentsError("INVALID_ANCHOR", message);
-};
-function key(raw, field) {
-  if (typeof raw !== "string" || raw.trim() === "" || raw.length > MAX_KEY || HIDDEN.test(raw)) bad(`${field} must be text of 1 to ${MAX_KEY} characters, with no control or invisible characters`);
-  return raw;
-}
-function id(raw, field) {
-  const { client, clock } = raw ?? {};
-  if (!Number.isSafeInteger(client) || !Number.isSafeInteger(clock) || client < 0 || clock < 0) {
-    bad(`${field} must hold a client and a clock that are whole numbers of 0 or more`);
-  }
-  return { client, clock };
-}
-function position(raw, field) {
-  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return bad(`${field} must be a relative position`);
-  const p = raw;
-  const out = {};
-  if (p.type !== void 0) out.type = id(p.type, `${field}.type`);
-  if (p.item !== void 0) out.item = id(p.item, `${field}.item`);
-  if (p.tname !== void 0) out.tname = key(p.tname, `${field}.tname`);
-  if (p.assoc !== void 0) {
-    if (p.assoc !== 0 && p.assoc !== -1) bad(`${field}.assoc must be 0 or -1`);
-    out.assoc = p.assoc;
-  }
-  if (out.type === void 0 && out.item === void 0 && out.tname === void 0) bad(`${field} must name an item or a type`);
-  return out;
-}
-var parseText = (raw) => {
-  if (typeof raw.text !== "string" || raw.text === "" || raw.text.length > MAX_QUOTE) bad(`text must be 1 to ${MAX_QUOTE} characters`);
-  const start = position(raw.start, "start");
-  const end = position(raw.end, "end");
-  const owner = (p) => JSON.stringify([p.type ?? null, p.tname ?? null]);
-  if (start.item === void 0 || end.item === void 0) bad("a text range needs an item position at each end");
-  if (start.type && start.tname || end.type && end.tname || owner(start) !== owner(end)) bad("both ends of a text range must name the same Yjs type");
-  const anchor = { type: "text", text: raw.text, start, end };
-  if (JSON.stringify(anchor).length > MAX_ANCHOR) bad(`an anchor holds up to ${MAX_ANCHOR} characters of JSON, so the quoted text is too long`);
-  return anchor;
-};
-var BUILT_IN_KINDS = [
-  { type: "text", parse: parseText },
-  { type: "cell", parse: (raw) => ({ type: "cell", key: key(raw.key, "key") }) },
-  { type: "slide", parse: (raw) => ({ type: "slide", elementId: key(raw.elementId, "elementId") }) },
-  { type: "canvas", parse: (raw) => ({ type: "canvas", elementId: key(raw.elementId, "elementId") }) }
-];
-function textOf(type) {
-  return type.toDelta().map((d) => typeof d.insert === "string" ? d.insert : "\uFFFC").join("");
-}
-function textAnchor(type, from, to) {
-  try {
-    const value = textOf(type);
-    if (!Number.isSafeInteger(from) || !Number.isSafeInteger(to) || from < 0 || to <= from || to > value.length) {
-      bad(`the range ${from}..${to} is not inside the text, which has ${value.length} characters`);
-    }
-    return parseText({
-      text: value.slice(from, to),
-      start: Y.relativePositionToJSON(Y.createRelativePositionFromTypeIndex(type, from, 0)),
-      end: Y.relativePositionToJSON(Y.createRelativePositionFromTypeIndex(type, to, -1))
-    });
-  } catch (error) {
-    if (error instanceof CommentsError) throw error;
-    throw new CommentsError("INVALID_ANCHOR", `the text cannot be anchored: ${error instanceof Error ? error.message : String(error)}`);
-  }
-}
-function place(json, ydoc) {
-  try {
-    return Y.createAbsolutePositionFromRelativePosition(Y.createRelativePositionFromJSON(json), ydoc);
-  } catch {
-    return null;
-  }
-}
-function textRange(anchor, ydoc) {
-  const from = place(anchor.start, ydoc);
-  const to = place(anchor.end, ydoc);
-  if (!from || !to || !(from.type instanceof Y.Text) || to.type !== from.type) return null;
-  return { type: from.type, from: from.index, to: to.index };
-}
-function textState(anchor, ydoc) {
-  const range = textRange(anchor, ydoc);
-  if (!range || range.to <= range.from) return { state: "orphaned" };
-  const current = textOf(range.type).slice(range.from, range.to);
-  return current === anchor.text ? { state: "attached" } : { state: "edited", currentText: current.slice(0, MAX_QUOTE) };
-}
-function onlyOccurrence(type, quote) {
-  const value = textOf(type);
-  const first = value.indexOf(quote);
-  return first >= 0 && value.indexOf(quote, first + 1) < 0 ? first : void 0;
-}
-
-// src/principal.ts
-var PRINCIPAL_KINDS = ["human", "agent_of_human", "agent_of_agent", "agent", "user_token"];
-var MAX_NAME = 128;
-var issued = /* @__PURE__ */ new WeakSet();
-var Actor = class _Actor {
-  kind;
-  name;
-  scopes;
-  constructor(kind, name, scopes) {
-    this.kind = kind;
-    this.name = name;
-    this.scopes = Object.freeze([...scopes]);
-    Object.freeze(this);
-  }
-  static of(input) {
-    const author = readAuthor(input);
-    const given = author ? input.scopes : void 0;
-    const scopes = given === void 0 ? [] : Array.isArray(given) ? Array.from(given) : void 0;
-    if (!author || !scopes || !scopes.every((s) => typeof s === "string" && s !== "")) {
-      throw new CommentsError("INVALID_AUTHOR", `an author needs a kind (${PRINCIPAL_KINDS.join(", ")}), a name, and scopes that are a list of text`);
-    }
-    const actor = new _Actor(author.kind, author.name, scopes);
-    issued.add(actor);
-    return actor;
-  }
-  static is(value) {
-    return typeof value === "object" && value !== null && issued.has(value);
-  }
-};
-var stamp = (input) => Actor.of(input);
-function assertActor(value) {
-  if (!Actor.is(value) || !readAuthor(value)) throw new CommentsError("INVALID_AUTHOR", "the host must pass an author made with stamp()");
-  return value;
-}
-function readAuthor(value) {
-  if (typeof value !== "object" || value === null) return void 0;
-  const { kind, name } = value;
-  if (!PRINCIPAL_KINDS.includes(kind)) return void 0;
-  if (typeof name !== "string" || name === "" || name !== name.trim() || name.length > MAX_NAME || HIDDEN.test(name) || VARIATION.test(name) || name !== name.normalize("NFC")) return void 0;
-  return { kind, name };
-}
-function authorLabel(author) {
-  return author.kind === "human" ? "person" : author.kind === "user_token" ? "person via agent" : "agent";
-}
-
-// src/validate.ts
-var invalid = (message) => {
-  throw new CommentsError("INVALID_INPUT", message);
-};
-function exact(input, allowed, what) {
-  if (typeof input !== "object" || input === null || Array.isArray(input)) return invalid(`${what} must be an object`);
-  const extra = Object.keys(input).filter((k) => !allowed.includes(k));
-  if (extra.length > 0) invalid(`${what} does not accept ${extra.join(", ")}`);
-  return input;
-}
-var ISO_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
-var validDate = (value) => typeof value === "string" && ISO_TIME.test(value) && !Number.isNaN(Date.parse(value)) && new Date(value).toISOString() === value;
-var copy = (value) => JSON.parse(JSON.stringify(value));
-var strictCopy = (value) => JSON.parse(
-  JSON.stringify(value, (_key, v) => {
-    if (v === void 0 || typeof v === "number" && !Number.isFinite(v)) throw new Error("a value is not valid JSON data");
-    return v;
-  })
-);
-
-// src/threads.ts
-var THREADS = "comments.threads";
-var MAX_BODY = 1e4;
-var MAX_MENTIONS = 50;
-var MAX_MESSAGES = 1e3;
-var READ_LIMIT = 2 * MAX_MESSAGES;
-var STATUSES = ["open", "resolved"];
-var ANCHOR_STATES = ["attached", "edited", "orphaned", "unknown"];
-var HANDLE = /^[\p{L}\p{N}](?:[\p{L}\p{N}\p{M}_.-]{0,62}[\p{L}\p{N}\p{M}])?$/u;
-var MENTION = /(?<![\p{L}\p{N}_@.])@([\p{L}\p{N}][\p{L}\p{N}\p{M}_.-]*)(?![\p{L}\p{N}\p{M}_.-]|\/)/gu;
-function body(value) {
-  if (typeof value !== "string" || value.trim() === "" || value.length > MAX_BODY || BODY_FORBIDDEN.test(value)) {
-    invalid(`a body must be text of 1 to ${MAX_BODY} characters, with no control, invisible, or direction characters`);
-  }
-  return value;
-}
-var handle = (value) => value.normalize("NFC").replace(/^@+/, "").toLowerCase().normalize("NFC");
-var okHandle = (value) => HANDLE.test(value) && !VARIATION.test(value);
-var validHandle = (value) => typeof value === "string" && okHandle(value) && handle(value) === value;
-function mentionsOf(text, explicit) {
-  const prose = text.replace(/`[^`]*`/g, " ");
-  const found = [...prose.matchAll(MENTION)].map((m) => {
-    const name = m[1].replace(/[._-]+$/, "");
-    if (!okHandle(handle(name))) invalid(`"@${name.slice(0, 20)}" is not a valid handle: use up to 64 characters`);
-    return handle(name);
-  });
-  let listed = [];
-  if (explicit !== void 0) {
-    const snapshot = Array.isArray(explicit) ? Array.from(explicit) : [];
-    const ok = Array.isArray(explicit) && snapshot.length <= MAX_MENTIONS && snapshot.every((m) => typeof m === "string" && okHandle(handle(m)));
-    if (!ok) invalid(`mentions must be a list of up to ${MAX_MENTIONS} handles of letters, digits, and . _ -`);
-    listed = snapshot.map(handle);
-  }
-  const all = [.../* @__PURE__ */ new Set([...found, ...listed])];
-  if (all.length > MAX_MENTIONS) invalid(`a message can mention up to ${MAX_MENTIONS} handles`);
-  return all;
-}
-var Comments = class {
-  /** Every replica of a document must register the same custom anchor kinds. Others read those threads as malformed. */
-  constructor(ydoc, options = {}) {
-    this.ydoc = ydoc;
-    if (typeof options !== "object" || options === null || options.now !== void 0 && typeof options.now !== "function" || options.anchors !== void 0 && !Array.isArray(options.anchors) || options.exists !== void 0 && typeof options.exists !== "function") {
-      invalid("options must be an object with an optional now function, anchors list, and exists function");
-    }
-    this.now = options.now ?? (() => /* @__PURE__ */ new Date());
-    this.exists = options.exists;
-    for (const kind of [...BUILT_IN_KINDS, ...options.anchors ?? []]) {
-      if (typeof kind?.type !== "string" || kind.type === "" || typeof kind.parse !== "function" || this.kinds.has(kind.type)) {
-        throw new CommentsError("INVALID_ANCHOR", `the anchor type "${String(kind?.type)}" is empty, has no parse, or is already defined`);
-      }
-      this.kinds.set(kind.type, kind);
-    }
-  }
-  ydoc;
-  kinds = /* @__PURE__ */ new Map();
-  now;
-  exists;
-  get map() {
-    return this.ydoc.getMap(THREADS);
-  }
-  /** The clock, as an ISO time. Used by `Suggestions`. */
-  time() {
-    const at = this.now();
-    const text = at instanceof Date && !Number.isNaN(at.getTime()) ? at.toISOString() : "";
-    if (!ISO_TIME.test(text)) invalid("the clock must return a date between the years 0000 and 9999");
-    return text;
-  }
-  /** Whether the content under an anchor is still there. This never throws. */
-  anchorState(anchor) {
-    if (anchor.type === "text") return textState(anchor, this.ydoc);
-    if (!this.exists) return { state: "unknown" };
-    try {
-      const answer = this.exists(anchor);
-      return answer === true ? { state: "attached" } : answer === false ? { state: "orphaned" } : { state: "unknown" };
-    } catch {
-      return { state: "unknown" };
-    }
-  }
-  /** Read an anchor from stored data. This does not check the document. */
-  parseAnchor(raw) {
-    const type = raw?.type;
-    const kind = typeof raw === "object" && raw !== null && !Array.isArray(raw) && typeof type === "string" ? this.kinds.get(type) : void 0;
-    if (!kind) throw new CommentsError("INVALID_ANCHOR", `an anchor needs a type: ${[...this.kinds.keys()].join(", ")}`);
-    try {
-      const parsed = copy(kind.parse(strictCopy(raw)));
-      if (JSON.stringify(parsed).length > MAX_ANCHOR) throw new Error(`an anchor holds up to ${MAX_ANCHOR} characters of JSON`);
-      if (parsed?.type !== kind.type) throw new Error(`the "${kind.type}" kind must return an anchor of its own type`);
-      return parsed;
-    } catch (error) {
-      if (error instanceof CommentsError) throw error;
-      throw new CommentsError("INVALID_ANCHOR", error instanceof Error ? error.message : String(error));
-    }
-  }
-  /** Parse an anchor from input and check it against this document. Throws `INVALID_ANCHOR` when it fails. */
-  checkAnchor(raw) {
-    const anchor = this.parseAnchor(raw);
-    if (JSON.stringify(this.parseAnchor(anchor)) !== JSON.stringify(anchor)) {
-      throw new CommentsError("INVALID_ANCHOR", "an anchor kind must parse its own output to the same anchor");
-    }
-    this.checkInDocument(anchor);
-    return anchor;
-  }
-  /** A text anchor must name text in this document, in order, and match its quote. */
-  checkInDocument(anchor) {
-    if (anchor.type !== "text") return;
-    const at = (json) => {
-      try {
-        return Y2.createAbsolutePositionFromRelativePosition(Y2.createRelativePositionFromJSON(json), this.ydoc);
-      } catch {
-        return null;
-      }
-    };
-    const from = at(anchor.start);
-    const to = at(anchor.end);
-    const unit = from?.type;
-    if (!(unit instanceof Y2.Text) || !from || !to || to.type !== unit || to.index <= from.index || textOf(unit).slice(from.index, to.index) !== anchor.text) {
-      throw new CommentsError("INVALID_ANCHOR", "a text anchor must name text in this document, in order, matching its quoted text");
-    }
-  }
-  /** Build a message, and refuse it unless a read would show it back. Nothing is written yet. */
-  message(text, explicit, actor) {
-    const message = {
-      id: globalThis.crypto.randomUUID(),
-      at: this.time(),
-      author: { kind: actor.kind, name: actor.name },
-      body: text,
-      mentions: mentionsOf(text, explicit)
-    };
-    try {
-      return this.readMessage(copy(message));
-    } catch (error) {
-      return invalid(`the message cannot be stored: ${error.message}`);
-    }
-  }
-  readMessage(raw) {
-    const m = raw ?? {};
-    const author = readAuthor(m.author);
-    if (typeof m.id !== "string" || !ID.test(m.id) || !validDate(m.at) || !author || typeof m.body !== "string" || m.body.trim() === "" || m.body.length > MAX_BODY || BODY_FORBIDDEN.test(m.body)) {
-      throw new Error("a message has no id, ISO time, valid author, or body");
-    }
-    if (!Array.isArray(m.mentions) || m.mentions.length > MAX_MENTIONS || !m.mentions.every(validHandle)) throw new Error("a message has bad mentions");
-    return { id: m.id, at: m.at, author, body: m.body, mentions: [...m.mentions] };
-  }
-  /** A thread with a bad anchor or status is malformed. A bad message is skipped and named in `issues`. */
-  read(id2, fields) {
-    try {
-      if (!ID.test(id2)) throw new Error("the thread id is not short and plain");
-      if (!(fields instanceof Y2.Map)) throw new Error("the thread is not a map");
-      const state = fields.get("state") ?? {};
-      const by = readAuthor(state.by);
-      if (!STATUSES.includes(state.status) || !by || !validDate(state.at)) throw new Error("the thread status is not valid");
-      const list = fields.get("messages");
-      if (!(list instanceof Y2.Array)) throw new Error("the thread has no message list");
-      const messages = [];
-      const issues = [];
-      const raw = list.toArray();
-      const counts = /* @__PURE__ */ new Map();
-      for (const m of raw) counts.set(m?.id, (counts.get(m?.id) ?? 0) + 1);
-      let past = 0;
-      raw.forEach((entry, index) => {
-        try {
-          const message = this.readMessage(entry);
-          if (counts.get(message.id) > 1) throw new Error("a message id repeats");
-          if (messages.length >= READ_LIMIT) past++;
-          else messages.push(message);
-        } catch (error) {
-          issues.push(`message ${index} skipped: ${safeText(error.message)}`);
-        }
-      });
-      if (past > 0) issues.push(`${past} valid messages past the read limit are not shown`);
-      if (messages.length === 0) throw new Error("the thread has no valid message");
-      const anchor = this.parseAnchor(fields.get("anchor"));
-      const thread = { id: id2, anchor, anchorState: this.anchorState(anchor), status: state.status, statusBy: by, statusAt: state.at, messages, skipped: raw.length - messages.length };
-      return { thread, issues };
-    } catch (error) {
-      throw new CommentsError("CORRUPT", `thread ${shown(id2)} is malformed: ${safeText(error instanceof Error ? error.message : error)}`);
-    }
-  }
-  fields(id2) {
-    if (typeof id2 !== "string" || !ID.test(id2) || !this.map.has(id2)) throw new CommentsError("NO_THREAD", `no thread with id ${shown(id2)}`);
-    return { id: id2, fields: this.map.get(id2) };
-  }
-  /** Start a thread with its first message. The anchor and body are checked before anything is written. */
-  add(input, actor) {
-    const who = assertActor(actor);
-    const given = exact(input, ["anchor", "body", "mentions"], "a new thread");
-    const anchor = this.checkAnchor(given.anchor);
-    const first = this.message(body(given.body), given.mentions, who);
-    const id2 = globalThis.crypto.randomUUID();
-    this.ydoc.transact(() => {
-      const fields = new Y2.Map();
-      this.map.set(id2, fields);
-      fields.set("anchor", anchor);
-      fields.set("state", { status: "open", by: copy(first.author), at: first.at });
-      const messages = new Y2.Array();
-      fields.set("messages", messages);
-      messages.push([copy(first)]);
-    });
-    return this.get(id2);
-  }
-  /**
-   * Add a message. The resolved check runs on this replica only. A reply and a resolve made at once
-   * on two replicas both stay, and the merged thread is resolved with the reply in it.
-   */
-  reply(threadId, input, actor) {
-    const who = assertActor(actor);
-    const given = exact(input, ["body", "mentions"], "a reply");
-    const { id: id2, fields } = this.fields(threadId);
-    const text = body(given.body);
-    const { thread } = this.read(id2, fields);
-    if (thread.status === "resolved") throw new CommentsError("THREAD_RESOLVED", `thread ${shown(id2)} is resolved; reopen it to reply`);
-    if (thread.messages.length >= MAX_MESSAGES) invalid(`thread ${shown(id2)} shows ${MAX_MESSAGES} messages and takes no more`);
-    const list = fields.get("messages");
-    const message = this.message(text, given.mentions, who);
-    list.push([copy(message)]);
-    return message;
-  }
-  setStatus(threadId, status, actor) {
-    const who = assertActor(actor);
-    const { id: id2, fields } = this.fields(threadId);
-    const { thread } = this.read(id2, fields);
-    if (thread.status === status) return thread;
-    fields.set("state", { status, by: { kind: who.kind, name: who.name }, at: this.time() });
-    return this.get(id2);
-  }
-  /**
-   * Move a text anchor whose range is gone or edited to its quote, when the quote occurs exactly once in
-   * the same text. There is no fuzzy match. Throws `RELOCATE_FAILED` when it cannot say where. An attached
-   * thread is returned as it is.
-   */
-  relocate(threadId, actor) {
-    assertActor(actor);
-    const { id: id2, fields } = this.fields(threadId);
-    const { thread } = this.read(id2, fields);
-    const anchor = thread.anchor;
-    if (anchor.type !== "text") return invalid("only a text anchor can be relocated");
-    if (thread.anchorState.state === "attached") return thread;
-    const range = textRange(anchor, this.ydoc);
-    const at = range ? onlyOccurrence(range.type, anchor.text) : void 0;
-    if (!range || at === void 0) {
-      throw new CommentsError("RELOCATE_FAILED", `the quoted text does not occur exactly once, so thread ${shown(id2)} cannot be moved`);
-    }
-    fields.set("anchor", textAnchor(range.type, at, at + anchor.text.length));
-    return this.get(id2);
-  }
-  resolve(threadId, actor) {
-    return this.setStatus(threadId, "resolved", actor);
-  }
-  reopen(threadId, actor) {
-    return this.setStatus(threadId, "open", actor);
-  }
-  get(threadId) {
-    const { id: id2, fields } = this.fields(threadId);
-    return this.read(id2, fields).thread;
-  }
-  /** Threads in the order they were started. A malformed thread is skipped; `problems()` names it. */
-  list(filter = {}) {
-    const given = exact(filter, ["status", "anchorType", "mentioning", "anchorState"], "a filter");
-    if (given.status !== void 0 && !STATUSES.includes(given.status)) invalid(`status must be ${STATUSES.join(" or ")}`);
-    if (given.anchorType !== void 0 && typeof given.anchorType !== "string") invalid("anchorType must be text");
-    if (given.mentioning !== void 0 && typeof given.mentioning !== "string") invalid("mentioning must be text");
-    if (given.anchorState !== void 0 && !ANCHOR_STATES.includes(given.anchorState)) invalid(`anchorState must be ${ANCHOR_STATES.join(", ")}`);
-    const wanted = given.mentioning === void 0 ? void 0 : handle(given.mentioning);
-    return this.readAll().threads.filter((t) => given.status === void 0 || t.status === given.status).filter((t) => given.anchorType === void 0 || t.anchor.type === given.anchorType).filter((t) => given.anchorState === void 0 || t.anchorState.state === given.anchorState).filter((t) => wanted === void 0 || t.messages.some((m) => m.mentions.includes(wanted))).sort((a, b) => Date.parse(a.messages[0].at) - Date.parse(b.messages[0].at) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
-  }
-  /** Threads or messages that could not be read, for example from a replica that wrote bad data. */
-  problems() {
-    return this.readAll().problems;
-  }
-  readAll() {
-    const threads = [];
-    const problems = [];
-    for (const [id2, fields] of this.map.entries()) {
-      try {
-        const { thread, issues } = this.read(id2, fields);
-        threads.push(thread);
-        for (const reason of issues) problems.push({ id: safeId(id2), reason });
-      } catch (error) {
-        problems.push({ id: safeId(id2), reason: error.message });
-      }
-    }
-    return { threads, problems };
-  }
-};
-
-// src/suggestions.ts
-import * as Y3 from "yjs";
-var ACCEPT_SCOPE = "comments:accept";
-var MAX_CHANGE = 64e3;
-var MAX_RECEIPT = 16e3;
-var MAX_SUMMARY = 1e3;
-var SUGGESTIONS = "comments.suggestions";
-var APPLIED = "comments.suggestion-applied";
-var REJECTED = "comments.suggestion-rejected";
-var decidesOwn = (author, decider) => author.kind !== "human" && decider.kind !== "human" && author.name === decider.name;
-var clientOf = (text) => /^(0|[1-9]\d{0,9})$/.test(text) && Number(text) <= 4294967295 ? Number(text) : void 0;
-var thenable = (value) => typeof value?.then === "function";
-var Suggestions = class {
-  constructor(comments, host) {
+var DEFAULT_SEEN = 1e4;
+var ERROR_LIMIT = 100;
+var actorOf = (author) => ({ kind: author.kind, name: author.name, machineMade: author.kind !== "human" });
+var Notifications = class {
+  constructor(comments, suggestions, options = {}) {
     this.comments = comments;
-    this.host = host;
-    if (typeof host?.apply !== "function" || typeof host.revert !== "function" && host.idempotent !== true) {
-      invalid("a host needs apply, and either revert or idempotent: true, so two accepts at once cannot apply a change twice");
+    this.suggestions = suggestions;
+    this.options = options;
+    this.seenLimit = options.seenLimit ?? DEFAULT_SEEN;
+    if (!Number.isSafeInteger(this.seenLimit) || this.seenLimit < 1) throw new TypeError("seenLimit must be a whole number, 1 or more");
+    this.muted = options.muted === true;
+    const flush = () => this.flush();
+    comments.ydoc.on("afterAllTransactions", flush);
+    this.stops.push(() => comments.ydoc.off("afterAllTransactions", flush));
+    const threads = comments.threadsMap;
+    const onThreads = (events, tr) => this.threadEvents(events, tr.local ? "local" : "remote");
+    threads.observeDeep(onThreads);
+    this.stops.push(() => threads.unobserveDeep(onThreads));
+    if (suggestions) {
+      const { suggestions: made, applied, rejected } = suggestions.maps;
+      const onMade = (event, tr) => this.created(event, tr.local ? "local" : "remote");
+      const onApplied = (event, tr) => this.decided(event, tr.local ? "local" : "remote", "suggestion.accepted");
+      const onRejected = (event, tr) => this.decided(event, tr.local ? "local" : "remote", "suggestion.rejected");
+      made.observe(onMade);
+      applied.observe(onApplied);
+      rejected.observe(onRejected);
+      this.stops.push(() => made.unobserve(onMade), () => applied.unobserve(onApplied), () => rejected.unobserve(onRejected));
     }
-    void [this.map, this.applied, this.rejected];
-    this.onTransaction = (tr) => {
-      if (!tr.local && [this.applied, this.map].some((type) => tr.changedParentTypes.has(type))) this.settle();
-    };
-    this.ydoc.on("afterTransaction", this.onTransaction);
-    this.settle();
   }
   comments;
-  host;
-  onTransaction;
+  suggestions;
+  options;
+  listeners = /* @__PURE__ */ new Set();
+  seen = /* @__PURE__ */ new Set();
   failures = [];
-  /** Stop listening to the document. */
+  stops = [];
+  queue = [];
+  flushing = false;
+  closed = false;
+  seenLimit;
+  muted;
+  /** Receive every event from now on. Returns a function that stops it. */
+  subscribe(listener) {
+    if (typeof listener !== "function") throw new TypeError("a listener must be a function");
+    this.listeners.add(listener);
+    return () => void this.listeners.delete(listener);
+  }
+  /** Start sending events, for a stream created with `muted: true`. */
+  unmute() {
+    this.muted = false;
+  }
+  /** Stop watching the document and drop every listener. */
   close() {
-    this.ydoc.off("afterTransaction", this.onTransaction);
-  }
-  get ydoc() {
-    return this.comments.ydoc;
-  }
-  get map() {
-    return this.ydoc.getMap(SUGGESTIONS);
+    this.closed = true;
+    for (const stop of this.stops.splice(0)) stop();
+    this.listeners.clear();
+    this.queue.length = 0;
   }
-  get applied() {
-    return this.ydoc.getMap(APPLIED);
+  /** The most recent errors, when no `onError` was given. */
+  errors() {
+    return [...this.failures];
   }
-  get rejected() {
-    return this.ydoc.getMap(REJECTED);
-  }
-  change(raw) {
-    let clean;
+  fail(error, source) {
     try {
-      clean = strictCopy(raw);
-      if (this.host.parse) clean = strictCopy(this.host.parse(copy(clean)));
-    } catch (error) {
-      return invalid(`the change is refused: ${safeText(error instanceof Error ? error.message : error)}`);
-    }
-    if (JSON.stringify(clean).length > MAX_CHANGE) invalid(`a change holds up to ${MAX_CHANGE} characters of JSON`);
-    return clean;
-  }
-  /**
-   * Records of one kind for one suggestion, in client order. A record that is not valid is not counted:
-   * one with no author or time, a receipt that is not small JSON, or a decider who decided their own work.
-   */
-  records(entries, id2, author) {
-    const out = [];
-    for (const [key2, raw] of entries) {
-      const client = clientOf(key2.slice(id2.length + 1));
-      const r = raw ?? {};
-      const by = readAuthor(r.by);
-      if (client === void 0 || !by || !validDate(r.at) || !author || decidesOwn(author, by)) continue;
-      let receipt = null;
-      try {
-        receipt = r.receipt === void 0 ? null : strictCopy(r.receipt);
-        if (JSON.stringify(receipt).length > MAX_RECEIPT) continue;
-      } catch {
-        continue;
-      }
-      out.push({ client, by, at: r.at, receipt });
-    }
-    return out.sort((a, b) => Number(a.receipt !== null) - Number(b.receipt !== null) || a.client - b.client);
-  }
-  /** Group the entries of a decision map by suggestion id in one pass, so a read does not scan the map per suggestion. */
-  index(map) {
-    const groups = /* @__PURE__ */ new Map();
-    for (const entry of map.entries()) {
-      const id2 = entry[0].slice(0, entry[0].lastIndexOf(":"));
-      const group = groups.get(id2);
-      if (group) group.push(entry);
-      else groups.set(id2, [entry]);
+      if (this.options.onError) this.options.onError(error, source);
+      else if (this.failures.push({ source, error }) > ERROR_LIMIT) this.failures.shift();
+    } catch {
     }
-    return groups;
   }
-  read(id2, fields, indexes = { applied: this.index(this.applied), rejected: this.index(this.rejected) }) {
+  /** Data from a peer can be bad. A bad record makes no event, and never stops a write or the records after it. */
+  guard(fn) {
     try {
-      if (!ID.test(id2)) throw new Error("the suggestion id is not short and plain");
-      if (!(fields instanceof Y3.Map)) throw new Error("the suggestion is not a map");
-      const author = readAuthor(fields.get("author"));
-      const createdAt = fields.get("createdAt");
-      const summary = fields.get("summary");
-      const change = fields.get("change");
-      if (!author || !validDate(createdAt)) throw new Error("the suggestion has no valid author or time");
-      if (summary !== void 0 && !(typeof summary === "string" && summary.trim() !== "" && summary.length <= MAX_SUMMARY && !BODY_FORBIDDEN.test(summary))) {
-        throw new Error("the summary is not valid");
-      }
-      if (change === void 0 || JSON.stringify(strictCopy(change)).length > MAX_CHANGE) throw new Error("the change is missing or too large");
-      const won = this.records(indexes.applied.get(id2) ?? [], id2, author)[0];
-      const refused = this.records(indexes.rejected.get(id2) ?? [], id2, author)[0];
-      const decision = won ? { status: "accepted", ...won } : refused ? { status: "rejected", ...refused } : void 0;
-      const anchor = this.comments.parseAnchor(fields.get("anchor"));
-      return {
-        id: id2,
-        anchor,
-        anchorState: this.comments.anchorState(anchor),
-        change: copy(change),
-        ...summary === void 0 ? {} : { summary },
-        author,
-        createdAt,
-        status: decision?.status ?? "pending",
-        ...decision ? { decidedBy: decision.by, decidedAt: decision.at } : {}
-      };
+      fn();
     } catch (error) {
-      throw new CommentsError("CORRUPT", `suggestion ${shown(id2)} is malformed: ${safeText(error instanceof Error ? error.message : error)}`);
-    }
-  }
-  fields(id2) {
-    if (typeof id2 !== "string" || !ID.test(id2) || !this.map.has(id2)) throw new CommentsError("NO_SUGGESTION", `no suggestion with id ${shown(id2)}`);
-    return { id: id2, fields: this.map.get(id2) };
-  }
-  /** Propose a change. Anyone can suggest. The host stamps the author. */
-  add(input, actor) {
-    const who = assertActor(actor);
-    const given = exact(input, ["anchor", "change", "summary"], "a new suggestion");
-    const anchor = this.comments.checkAnchor(given.anchor);
-    const change = this.change(given.change);
-    const summary = given.summary;
-    if (summary !== void 0 && !(typeof summary === "string" && summary.trim() !== "" && summary.length <= MAX_SUMMARY && !BODY_FORBIDDEN.test(summary))) {
-      invalid(`a summary must be text of 1 to ${MAX_SUMMARY} characters, with no control or invisible characters`);
+      this.fail(error, "data");
     }
-    const id2 = globalThis.crypto.randomUUID();
-    const createdAt = this.comments.time();
-    this.ydoc.transact(() => {
-      const fields = new Y3.Map();
-      this.map.set(id2, fields);
-      fields.set("anchor", anchor);
-      fields.set("change", change);
-      if (summary !== void 0) fields.set("summary", summary);
-      fields.set("author", { kind: who.kind, name: who.name });
-      fields.set("createdAt", createdAt);
-    });
-    return this.get(id2);
   }
-  /** A person decides. An agent needs the accept scope, and never decides its own suggestion. */
-  mayDecide(who, s, verb) {
-    const ok = !decidesOwn(s.author, who) && (who.kind === "human" || who.scopes.includes(ACCEPT_SCOPE));
-    if (!ok) throw new CommentsError("FORBIDDEN", `${who.kind}:${shown(who.name)} cannot ${verb} this suggestion: a signed-in person, or a principal with the ${ACCEPT_SCOPE} scope that did not write it, can`);
+  emit(event) {
+    if (this.seen.has(event.id)) return;
+    this.seen.add(event.id);
+    if (this.seen.size > this.seenLimit) this.seen.delete(this.seen.values().next().value);
+    if (!this.muted) this.queue.push(event);
   }
-  /**
-   * Apply the change as the accepting author and record the decision, in one step. Accepting an
-   * accepted suggestion changes nothing. When `apply` throws, the suggestion stays pending.
-   */
-  accept(suggestionId, actor) {
-    const who = assertActor(actor);
-    if (this.ydoc._transaction !== null) {
-      throw new CommentsError("APPLY_FAILED", "accept cannot run inside another Yjs transaction, such as an observer or an apply hook");
-    }
-    const { id: id2, fields } = this.fields(suggestionId);
-    const s = this.read(id2, fields);
-    this.mayDecide(who, s, "accept");
-    if (s.status === "accepted") return s;
-    if (s.status === "rejected") throw new CommentsError("ALREADY_DECIDED", `suggestion ${shown(id2)} is already rejected`);
-    const by = { kind: who.kind, name: who.name };
-    const at = this.comments.time();
-    this.ydoc.transact((tr) => {
-      const edited = () => tr.changed.size > 0 || tr.deleteSet.clients.size > 0;
-      let receipt = null;
-      let failure;
-      try {
-        if (s.anchorState.state === "orphaned" || s.anchorState.state === "edited") {
-          throw new Error(s.anchorState.state === "orphaned" ? "the anchored content is gone" : "the anchored content has changed since the suggestion was made");
+  flush() {
+    if (this.flushing) return;
+    this.flushing = true;
+    try {
+      for (let event = this.queue.shift(); event; event = this.queue.shift()) {
+        for (const listener of [...this.listeners]) {
+          if (this.closed) return;
+          try {
+            const result = listener(event);
+            if (typeof result?.then === "function") Promise.resolve(result).catch((error) => this.fail(error, "listener"));
+          } catch (error) {
+            this.fail(error, "listener");
+          }
         }
-        this.comments.checkAnchor(s.anchor);
-        const change = this.change(s.change);
-        receipt = this.host.apply(change, { suggestionId: id2, anchor: copy(s.anchor), author: Object.freeze({ ...s.author }), by: Object.freeze({ ...by }), ydoc: this.ydoc });
-        if (thenable(receipt)) throw new Error("apply must finish at once and cannot return a promise");
-        receipt = receipt === void 0 ? null : strictCopy(receipt);
-        if (JSON.stringify(receipt).length > MAX_RECEIPT) throw new Error(`a receipt holds up to ${MAX_RECEIPT} characters of JSON`);
-      } catch (error) {
-        failure = error;
-        receipt = null;
-      }
-      if (failure !== void 0) {
-        const reason = safeText(failure instanceof Error ? failure.message : failure);
-        if (!edited()) throw new CommentsError("APPLY_FAILED", `the change could not be applied: ${reason}`);
-        this.failures.push({ id: safeId(id2), reason: `apply failed after it edited the document, so the decision is recorded without a receipt: ${reason}` });
       }
-      this.applied.set(`${id2}:${this.ydoc.clientID}`, { by, at, receipt });
-    });
-    return this.get(id2);
-  }
-  /** Same right as accept. A person can withdraw their own suggestion. */
-  reject(suggestionId, actor) {
-    const who = assertActor(actor);
-    const { id: id2, fields } = this.fields(suggestionId);
-    const s = this.read(id2, fields);
-    this.mayDecide(who, s, "reject");
-    if (s.status === "rejected") return s;
-    if (s.status === "accepted") throw new CommentsError("ALREADY_DECIDED", `suggestion ${shown(id2)} is already accepted`);
-    this.rejected.set(`${id2}:${this.ydoc.clientID}`, { by: { kind: who.kind, name: who.name }, at: this.comments.time() });
-    return this.get(id2);
-  }
-  get(suggestionId) {
-    const { id: id2, fields } = this.fields(suggestionId);
-    return this.read(id2, fields);
+    } finally {
+      this.flushing = false;
+    }
+  }
+  threadEvents(events, source) {
+    const threads = this.comments.threadsMap;
+    for (const event of events) {
+      this.guard(() => {
+        const path = event.path;
+        if (event.target === threads) {
+          for (const [id, change] of event.keys) if (change.action === "add") this.guard(() => this.threadCreated(id, source));
+        } else if (path.length === 1 && event.target instanceof Y.Map) {
+          const keys = event.keys;
+          if (keys.get("messages")?.action === "add") this.threadCreated(String(path[0]), source);
+          const change = keys.get("state");
+          if (change) this.statusChanged(String(path[0]), change.oldValue, source);
+        } else if (path.length === 2 && path[1] === "messages" && event.target instanceof Y.Array) {
+          const ids = /* @__PURE__ */ new Set();
+          for (const item of event.changes.added) for (const raw of item.content.getContent()) ids.add(raw?.id);
+          this.messagesAdded(String(path[0]), ids, source);
+        }
+      });
+    }
   }
-  /** In the order they were made. A malformed suggestion is skipped, and `problems()` names it. */
-  list(filter = {}) {
-    const given = exact(filter, ["status", "anchorState"], "a filter");
-    if (given.anchorState !== void 0 && !["attached", "edited", "orphaned", "unknown"].includes(given.anchorState)) invalid("anchorState must be attached, edited, orphaned, or unknown");
-    if (given.status !== void 0 && !["pending", "accepted", "rejected"].includes(given.status)) invalid("status must be pending, accepted, or rejected");
-    return this.readAll().suggestions.filter((s) => given.status === void 0 || s.status === given.status).filter((s) => given.anchorState === void 0 || s.anchorState.state === given.anchorState).sort((a, b) => Date.parse(a.createdAt) - Date.parse(b.createdAt) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  mentions(thread, message, source) {
+    for (const handle of message.mentions) {
+      this.emit({ id: `mention:${thread.id}:${message.id}:${handle}`, type: "mention", at: message.at, source, actor: actorOf(message.author), anchorType: thread.anchor.type, threadId: thread.id, messageId: message.id, mention: handle });
+    }
+  }
+  messageEvent(thread, message, source) {
+    this.emit({ id: `message.added:${thread.id}:${message.id}`, type: "message.added", at: message.at, source, actor: actorOf(message.author), anchorType: thread.anchor.type, threadId: thread.id, messageId: message.id });
+    this.mentions(thread, message, source);
+  }
+  statusEvent(thread, source) {
+    const type = thread.status === "resolved" ? "thread.resolved" : "thread.reopened";
+    this.emit({ id: `${type}:${thread.id}:${thread.statusAt}:${thread.statusBy.kind}:${thread.statusBy.name}`, type, at: thread.statusAt, source, actor: actorOf(thread.statusBy), anchorType: thread.anchor.type, threadId: thread.id });
+  }
+  threadCreated(id, source) {
+    const thread = this.comments.get(id);
+    const stored = this.comments.threadsMap.get(id)?.get("messages");
+    const firstId = stored instanceof Y.Array ? stored.get(0)?.id : void 0;
+    const first = thread.messages.find((m) => m.id === firstId);
+    if (first) {
+      this.emit({ id: `thread.created:${id}`, type: "thread.created", at: first.at, source, actor: actorOf(first.author), anchorType: thread.anchor.type, threadId: id, messageId: first.id });
+      this.mentions(thread, first, source);
+    } else {
+      this.fail(new Error(`thread ${JSON.stringify(id.slice(0, 64))} has no valid first message, so it makes no thread.created event`), "data");
+    }
+    for (const message of thread.messages) if (message !== first) this.messageEvent(thread, message, source);
+    if (thread.status === "resolved") this.statusEvent(thread, source);
+  }
+  messagesAdded(threadId, ids, source) {
+    const thread = this.comments.get(threadId);
+    for (const message of thread.messages) if (ids.has(message.id)) this.messageEvent(thread, message, source);
+  }
+  statusChanged(threadId, before, source) {
+    const thread = this.comments.get(threadId);
+    const old = before ?? {};
+    const real = (old.status === "open" || old.status === "resolved") && readAuthor(old.by) !== void 0;
+    if (real && old.status !== thread.status) this.statusEvent(thread, source);
+  }
+  created(event, source) {
+    for (const [id, change] of event.keys) {
+      if (change.action !== "add") continue;
+      this.guard(() => {
+        const s = this.suggestions.get(id);
+        this.emit({ id: `suggestion.created:${id}`, type: "suggestion.created", at: s.createdAt, source, actor: actorOf(s.author), anchorType: s.anchor.type, suggestionId: id });
+        if (s.status !== "pending") this.decisionEvent(s, source);
+      });
+    }
   }
-  /** Suggestions that could not be read, and reverts that failed. */
-  problems() {
-    return [...this.readAll().problems, ...this.failures];
+  decisionEvent(s, source) {
+    if (s.status === "pending" || !s.decidedBy || !s.decidedAt) return;
+    const type = s.status === "accepted" ? "suggestion.accepted" : "suggestion.rejected";
+    this.emit({ id: `${type}:${s.id}`, type, at: s.decidedAt, source, actor: actorOf(s.decidedBy), anchorType: s.anchor.type, suggestionId: s.id });
   }
-  readAll() {
-    const suggestions = [];
-    const problems = [];
-    const indexes = { applied: this.index(this.applied), rejected: this.index(this.rejected) };
-    for (const [id2, fields] of this.map.entries()) {
+  decided(event, source, type) {
+    for (const [key, change] of event.keys) {
+      if (change.action !== "add") continue;
       try {
-        suggestions.push(this.read(id2, fields, indexes));
+        const raw = event.target.get(key);
+        if (!raw || readAuthor(raw.by) === void 0 || !validDate(raw.at)) throw new Error("a decision record is not valid");
+        const id = key.slice(0, key.lastIndexOf(":"));
+        const s = this.suggestions.get(id);
+        if (s.status === (type === "suggestion.accepted" ? "accepted" : "rejected")) this.decisionEvent(s, source);
       } catch (error) {
-        problems.push({ id: safeId(id2), reason: error.message });
+        this.fail(error, "data");
       }
     }
-    return { suggestions, problems };
-  }
-  /**
-   * Two replicas can accept one suggestion before they meet. After a merge, the application of the
-   * lowest client id stays, and the host reverts each other one. Every replica reaches the same result.
-   * A revert that throws leaves its record, so the next merge tries again.
-   */
-  settle() {
-    const groups = this.index(this.applied);
-    const indexes = { applied: groups, rejected: this.index(this.rejected) };
-    this.failures = this.failures.filter((f) => f.reason.startsWith("apply failed") || f.reason.startsWith("a duplicate application has no receipt"));
-    this.ydoc.transact(() => {
-      for (const [id2, entries] of groups) {
-        if (entries.length < 2 || !ID.test(id2) || !this.map.has(id2)) continue;
-        let s;
-        try {
-          s = this.read(id2, this.map.get(id2), indexes);
-        } catch {
-          continue;
-        }
-        for (const loser of this.records(entries, id2, s.author).slice(1)) {
-          const key2 = `${id2}:${loser.client}`;
-          if (this.host.idempotent) {
-            this.applied.delete(key2);
-            continue;
-          }
-          if (loser.receipt === null) {
-            this.failures.push({ id: safeId(id2), reason: "a duplicate application has no receipt, so its edit cannot be undone and stays in the document" });
-            this.applied.delete(key2);
-            continue;
-          }
-          try {
-            this.host.revert?.(loser.receipt, { suggestionId: id2, anchor: copy(s.anchor), author: Object.freeze({ ...s.author }), by: Object.freeze({ ...loser.by }), ydoc: this.ydoc });
-            this.applied.delete(key2);
-          } catch (error) {
-            this.failures.push({ id: safeId(id2), reason: `a duplicate application could not be reverted: ${safeText(error instanceof Error ? error.message : error)}` });
-          }
-        }
-      }
-    });
   }
 };
 export {
@@ -751,6 +212,7 @@ export {
   Actor,
   Comments,
   CommentsError,
+  Notifications,
   PRINCIPAL_KINDS,
   Suggestions,
   VERSION,