agentic-comments 0.0.0-stage → 0.2.0

package/dist/chunk-C3P5TAC3.js

@@ -0,0 +1,770 @@
+// src/errors.ts
+var CommentsError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "CommentsError";
+  }
+  code;
+};
+
+// src/anchor.ts
+import * as Y from "yjs";
+
+// 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/suggestions.ts
+import * as Y2 from "yjs";
+
+// 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/suggestions.ts
+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) {
+    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");
+    }
+    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;
+  failures = [];
+  /** Stop listening to the document. */
+  close() {
+    this.ydoc.off("afterTransaction", this.onTransaction);
+  }
+  get ydoc() {
+    return this.comments.ydoc;
+  }
+  get map() {
+    return this.ydoc.getMap(SUGGESTIONS);
+  }
+  /** The three Yjs maps that hold suggestions and their decisions. `Notifications` watches them. */
+  get maps() {
+    return { suggestions: this.map, applied: this.applied, rejected: this.rejected };
+  }
+  get applied() {
+    return this.ydoc.getMap(APPLIED);
+  }
+  get rejected() {
+    return this.ydoc.getMap(REJECTED);
+  }
+  change(raw, anchor) {
+    let clean;
+    try {
+      clean = strictCopy(raw);
+      if (this.host.parse) clean = strictCopy(this.host.parse(copy(clean), { anchor: copy(anchor) }));
+    } 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]);
+    }
+    return groups;
+  }
+  read(id2, fields, indexes = { applied: this.index(this.applied), rejected: this.index(this.rejected) }) {
+    try {
+      if (!ID.test(id2)) throw new Error("the suggestion id is not short and plain");
+      if (!(fields instanceof Y2.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 } : {}
+      };
+    } 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, anchor);
+    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`);
+    }
+    const id2 = globalThis.crypto.randomUUID();
+    const createdAt = this.comments.time();
+    this.ydoc.transact(() => {
+      const fields = new Y2.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`);
+  }
+  /**
+   * 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");
+        }
+        this.comments.checkAnchor(s.anchor);
+        const change = this.change(s.change, s.anchor);
+        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);
+  }
+  /** 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));
+  }
+  /** Suggestions that could not be read, and reverts that failed. */
+  problems() {
+    return [...this.readAll().problems, ...this.failures];
+  }
+  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()) {
+      try {
+        suggestions.push(this.read(id2, fields, indexes));
+      } catch (error) {
+        problems.push({ id: safeId(id2), reason: error.message });
+      }
+    }
+    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)}` });
+          }
+        }
+      }
+    });
+  }
+};
+
+// src/threads.ts
+import * as Y3 from "yjs";
+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 Yjs map that holds the threads. `Notifications` watches it. */
+  get threadsMap() {
+    return this.map;
+  }
+  /** 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 Y3.createAbsolutePositionFromRelativePosition(Y3.createRelativePositionFromJSON(json), this.ydoc);
+      } catch {
+        return null;
+      }
+    };
+    const from = at(anchor.start);
+    const to = at(anchor.end);
+    const unit = from?.type;
+    if (!(unit instanceof Y3.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 Y3.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 Y3.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 Y3.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 Y3.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 };
+  }
+};
+
+export {
+  CommentsError,
+  textOf,
+  textAnchor,
+  textRange,
+  PRINCIPAL_KINDS,
+  Actor,
+  stamp,
+  readAuthor,
+  authorLabel,
+  invalid,
+  exact,
+  validDate,
+  ACCEPT_SCOPE,
+  Suggestions,
+  Comments
+};