agentic-comments 0.6.1 → 0.7.0

package/dist/ui.js

@@ -0,0 +1,332 @@
+import {
+  createClient
+} from "./chunk-UEQL27KF.js";
+
+// src/ui/panel.tsx
+import { Component, createContext, useCallback, useContext, useEffect, useId, useRef, useState } from "react";
+import { AgentBadge, Avatar, Button, Input, Textarea } from "agentic-design/react";
+
+// src/ui/rules.ts
+var LEVELS = ["comments:read", "comments:comment", "comments:write", "comments:admin"];
+var level = (scopes) => Math.max(-1, ...scopes.map((s) => LEVELS.indexOf(s)));
+function holds(me, need) {
+  return me !== void 0 && level(me.scopes) >= LEVELS.indexOf(`comments:${need}`);
+}
+function mayDecide(me, suggestion) {
+  if (suggestion.status !== "pending") return { allowed: false };
+  if (!me) return { allowed: false, reason: "Sign in to decide this suggestion." };
+  const agent = me.kind !== "human";
+  if (agent ? level(me.scopes) < LEVELS.indexOf("comments:admin") && !me.scopes.includes("comments:accept") : !holds(me, "write")) {
+    return { allowed: false, reason: agent ? "An agent needs the accept right to decide a suggestion. A person can." : "Your access cannot accept or reject suggestions." };
+  }
+  const { author } = suggestion;
+  if (agent && author.kind !== "human" && author.name === me.name) {
+    return { allowed: false, reason: "An agent cannot accept or reject its own suggestion. A person or another agent decides." };
+  }
+  return { allowed: true };
+}
+
+// src/ui/panel.tsx
+import { jsx, jsxs } from "react/jsx-runtime";
+var VIEWS = [
+  { id: "open", label: "Open" },
+  { id: "resolved", label: "Resolved" },
+  { id: "all", label: "All" }
+];
+var Ctx = createContext(void 0);
+function useCtx() {
+  const value = useContext(Ctx);
+  if (!value) throw new Error("A panel card needs a CommentsPanel above it.");
+  return value;
+}
+var when = new Intl.DateTimeFormat("en", { dateStyle: "medium", timeStyle: "short", timeZone: "UTC" });
+var stamp = (iso) => {
+  const date = new Date(iso);
+  return Number.isNaN(date.getTime()) ? iso : `${when.format(date)} UTC`;
+};
+var only = (list) => Array.isArray(list) ? list.filter((x) => typeof x === "object" && x !== null) : [];
+function failure(error) {
+  const code = typeof error?.code === "string" ? `${error.code}: ` : "";
+  return `${code}${error instanceof Error ? error.message : String(error)}`;
+}
+function Who({ author, agentLabel }) {
+  const { actingFor } = useContext(Ctx) ?? {};
+  if (author.kind === "human") {
+    return /* @__PURE__ */ jsxs("span", { className: "agd-comments__who", children: [
+      /* @__PURE__ */ jsx(Avatar, { entry: { id: `person-${author.name}`, name: author.name, kind: "person" } }),
+      /* @__PURE__ */ jsx("strong", { className: "agd-comments__name", children: author.name })
+    ] });
+  }
+  return /* @__PURE__ */ jsx(AgentBadge, { name: author.name, label: agentLabel, actingFor: actingFor?.(author) });
+}
+function anchorLabel(anchor) {
+  switch (anchor.type) {
+    case "text":
+      return "Text";
+    case "cell":
+      return `Cell ${anchor.key}`;
+    case "slide":
+      return `Slide element ${anchor.elementId}`;
+    case "canvas":
+      return `Canvas element ${anchor.elementId}`;
+    default:
+      return "Anchor";
+  }
+}
+function AnchorNote({ state }) {
+  if (state.state === "attached") return null;
+  const text = state.state === "orphaned" ? "The anchored content is gone. You can still read and reply." : state.state === "edited" ? `The text changed since this comment. It now reads: \u201C${state.currentText}\u201D` : "The panel cannot tell if the content is still there.";
+  return /* @__PURE__ */ jsx("p", { className: `agd-comments__state agd-comments__state--${state.state}`, children: text });
+}
+function Quote({ anchor }) {
+  return /* @__PURE__ */ jsxs("figure", { className: "agd-comments__anchor", children: [
+    /* @__PURE__ */ jsx("figcaption", { className: "agd-comments__label", children: anchorLabel(anchor) }),
+    anchor.type === "text" && /* @__PURE__ */ jsx("blockquote", { className: "agd-comments__quote", children: anchor.text })
+  ] });
+}
+function Body({ message }) {
+  return /* @__PURE__ */ jsxs("li", { className: "agd-comments__message", children: [
+    /* @__PURE__ */ jsxs("div", { className: "agd-comments__meta", children: [
+      /* @__PURE__ */ jsx(Who, { author: message.author, agentLabel: "Comment by an agent" }),
+      /* @__PURE__ */ jsx("time", { className: "agd-comments__time", dateTime: message.at, children: stamp(message.at) }),
+      message.editedAt && /* @__PURE__ */ jsx("span", { className: "agd-comments__time", children: "edited" })
+    ] }),
+    /* @__PURE__ */ jsx("p", { className: "agd-comments__body", children: message.body })
+  ] });
+}
+function changeText(change) {
+  if (typeof change === "object" && change !== null && "replace" in change && typeof change.replace === "string") return change.replace;
+  try {
+    return JSON.stringify(change) ?? "";
+  } catch {
+    return "";
+  }
+}
+var Status = ({ value }) => /* @__PURE__ */ jsx("span", { className: `agd-pill agd-comments__status agd-comments__status--${value}`, children: value[0].toUpperCase() + value.slice(1) });
+function ThreadCard({ thread }) {
+  const { client, docId, me, busy, act } = useCtx();
+  const id = useId();
+  const [draft, setDraft] = useState("");
+  const resolved = thread.status === "resolved";
+  const mayComment = holds(me, "comment");
+  const submit = (event) => {
+    event.preventDefault();
+    const body = draft.trim();
+    if (!body) return;
+    void act(
+      `${thread.id}:reply`,
+      async () => {
+        await client.reply(docId, thread.id, { body });
+        setDraft("");
+      },
+      "Reply sent."
+    );
+  };
+  return /* @__PURE__ */ jsx("li", { className: "agd-comments__thread", children: /* @__PURE__ */ jsxs("article", { "aria-labelledby": `${id}-h`, children: [
+    /* @__PURE__ */ jsxs("header", { className: "agd-comments__item-top", children: [
+      /* @__PURE__ */ jsxs("h3", { className: "agd-comments__item-title", id: `${id}-h`, children: [
+        anchorLabel(thread.anchor),
+        " ",
+        /* @__PURE__ */ jsx(Status, { value: thread.status })
+      ] }),
+      mayComment && /* @__PURE__ */ jsxs(Button, { size: "sm", loading: busy === `${thread.id}:status`, onClick: () => void act(`${thread.id}:status`, () => resolved ? client.reopen(docId, thread.id) : client.resolve(docId, thread.id), resolved ? "Thread reopened." : "Thread resolved.", "threads"), children: [
+        resolved ? "Reopen" : "Resolve",
+        /* @__PURE__ */ jsxs("span", { className: "agd-sr-only", children: [
+          " thread on ",
+          anchorLabel(thread.anchor)
+        ] })
+      ] })
+    ] }),
+    /* @__PURE__ */ jsx(Quote, { anchor: thread.anchor }),
+    /* @__PURE__ */ jsx(AnchorNote, { state: thread.anchorState }),
+    /* @__PURE__ */ jsx("ul", { className: "agd-comments__messages", "aria-label": "Messages", children: thread.messages.map((m) => /* @__PURE__ */ jsx(Body, { message: m }, m.id)) }),
+    resolved ? /* @__PURE__ */ jsx("p", { className: "agd-comments__note", children: "Reopen this thread to reply." }) : mayComment ? /* @__PURE__ */ jsxs("form", { className: "agd-comments__reply", onSubmit: submit, children: [
+      /* @__PURE__ */ jsx(Textarea, { label: "Reply", rows: 2, value: draft, onChange: (e) => setDraft(e.target.value), maxLength: 1e4 }),
+      /* @__PURE__ */ jsx(Button, { type: "submit", variant: "primary", size: "sm", loading: busy === `${thread.id}:reply`, children: "Reply" })
+    ] }) : null
+  ] }) });
+}
+function SuggestionCard({ suggestion }) {
+  const { client, docId, me, busy, act } = useCtx();
+  const decision = mayDecide(me, suggestion);
+  const usable = suggestion.anchorState.state === "attached";
+  const pending = suggestion.status === "pending";
+  return /* @__PURE__ */ jsxs("li", { className: "agd-comments__thread", children: [
+    /* @__PURE__ */ jsxs("div", { className: "agd-comments__meta", children: [
+      /* @__PURE__ */ jsx(Who, { author: suggestion.author, agentLabel: "Suggested by an agent" }),
+      /* @__PURE__ */ jsx("time", { className: "agd-comments__time", dateTime: suggestion.createdAt, children: stamp(suggestion.createdAt) }),
+      /* @__PURE__ */ jsx(Status, { value: suggestion.status })
+    ] }),
+    /* @__PURE__ */ jsx(Quote, { anchor: suggestion.anchor }),
+    suggestion.summary && /* @__PURE__ */ jsx("p", { className: "agd-comments__body", children: suggestion.summary }),
+    /* @__PURE__ */ jsxs("p", { className: "agd-comments__change", children: [
+      /* @__PURE__ */ jsx("span", { className: "agd-comments__label", children: "Proposed change" }),
+      /* @__PURE__ */ jsx("code", { className: "agd-comments__code", children: changeText(suggestion.change) })
+    ] }),
+    pending && /* @__PURE__ */ jsx(AnchorNote, { state: suggestion.anchorState }),
+    suggestion.decidedBy && /* @__PURE__ */ jsxs("p", { className: "agd-comments__note", children: [
+      suggestion.status === "accepted" ? "Accepted" : "Rejected",
+      " by ",
+      suggestion.decidedBy.kind === "human" ? "" : "an agent, ",
+      suggestion.decidedBy.name,
+      "."
+    ] }),
+    pending && decision.allowed && /* @__PURE__ */ jsxs("div", { className: "agd-comments__actions", children: [
+      /* @__PURE__ */ jsxs(Button, { variant: "primary", size: "sm", loading: busy === `${suggestion.id}:accept`, disabled: !usable, onClick: () => void act(`${suggestion.id}:accept`, () => client.accept(docId, suggestion.id), "Suggestion accepted.", "suggestions"), children: [
+        "Accept",
+        /* @__PURE__ */ jsx("span", { className: "agd-sr-only", children: " suggestion" })
+      ] }),
+      /* @__PURE__ */ jsxs(Button, { size: "sm", loading: busy === `${suggestion.id}:reject`, onClick: () => void act(`${suggestion.id}:reject`, () => client.reject(docId, suggestion.id), "Suggestion rejected.", "suggestions"), children: [
+        "Reject",
+        /* @__PURE__ */ jsx("span", { className: "agd-sr-only", children: " suggestion" })
+      ] })
+    ] }),
+    pending && decision.allowed && !usable && /* @__PURE__ */ jsx("p", { className: "agd-comments__note", children: suggestion.anchorState.state === "unknown" ? "The panel cannot tell if the anchored text is still there, so Accept is off. You can reject this suggestion." : "The anchored text changed or is gone. You can reject this suggestion, and you cannot accept it." }),
+    pending && !decision.allowed && decision.reason && /* @__PURE__ */ jsx("p", { className: "agd-comments__note", children: decision.reason })
+  ] });
+}
+var CardBoundary = class extends Component {
+  state = { bad: false, seen: this.props.item };
+  static getDerivedStateFromError() {
+    return { bad: true };
+  }
+  // A read gives new objects. When the item is not the one that failed, the card gets another try.
+  static getDerivedStateFromProps(props, state) {
+    return props.item === state.seen ? null : { bad: false, seen: props.item };
+  }
+  render() {
+    return this.state.bad ? /* @__PURE__ */ jsx("li", { className: "agd-comments__thread agd-comments__note", children: "This item has bad data, so the panel does not show it." }) : this.props.children;
+  }
+};
+function Section({ id, title, count, children }) {
+  return /* @__PURE__ */ jsxs("section", { className: "agd-comments__section", "aria-labelledby": id, children: [
+    /* @__PURE__ */ jsxs("h2", { className: "agd-comments__heading", id, tabIndex: -1, children: [
+      title,
+      " ",
+      /* @__PURE__ */ jsx("span", { className: "agd-comments__count", children: count })
+    ] }),
+    children
+  ] });
+}
+function CommentsPanel({ client, docId, title = "Comments", newThread = true, actingFor }) {
+  const base = useId();
+  const [notice, setNotice] = useState("");
+  const [me, setMe] = useState();
+  const [threads, setThreads] = useState();
+  const [suggestions, setSuggestions] = useState([]);
+  const [view, setView] = useState("open");
+  const [error, setError] = useState();
+  const [busy, setBusy] = useState();
+  const [quote, setQuote] = useState("");
+  const [body, setBody] = useState("");
+  const run = useRef(0);
+  const writing = useRef(false);
+  const load = useCallback(
+    async (gen) => {
+      const [m, t, s] = await Promise.all([client.me(), client.listThreads(docId), client.listSuggestions(docId)]);
+      if (gen !== run.current) return;
+      if (!(typeof m === "object" && m !== null && typeof m.kind === "string" && typeof m.name === "string" && Array.isArray(m.scopes) && m.scopes.every((x) => typeof x === "string"))) {
+        throw new Error("the client returned a principal with no kind, name, or scopes");
+      }
+      setMe(m);
+      setThreads(only(t));
+      setSuggestions(only(s));
+    },
+    [client, docId]
+  );
+  useEffect(() => {
+    const gen = ++run.current;
+    writing.current = false;
+    setMe(void 0);
+    setThreads(void 0);
+    setSuggestions([]);
+    setBusy(void 0);
+    setError(void 0);
+    setNotice("");
+    setQuote("");
+    setBody("");
+    setView("open");
+    load(gen).catch((e) => gen === run.current && setError(failure(e)));
+    return () => {
+      run.current += 1;
+    };
+  }, [load]);
+  const act = async (key, call, done, focus) => {
+    if (writing.current) {
+      setNotice("Wait for the current action to finish, then try again.");
+      return;
+    }
+    writing.current = true;
+    const gen = run.current;
+    const current = () => gen === run.current;
+    const refocus = () => focus && requestAnimationFrame(() => current() && document.getElementById(`${base}-${focus}`)?.focus());
+    setBusy(key);
+    setError(void 0);
+    setNotice("");
+    try {
+      await call();
+      await load(gen);
+      if (current()) {
+        if (done) setNotice(done);
+        refocus();
+      }
+    } catch (e) {
+      if (current()) setError(failure(e));
+      await load(gen).catch(() => void 0);
+      if (current()) refocus();
+    } finally {
+      if (current()) {
+        writing.current = false;
+        setBusy(void 0);
+      }
+    }
+  };
+  const start = (event) => {
+    event.preventDefault();
+    const q = quote.trim();
+    const b = body.trim();
+    if (!q || !b) return;
+    const gen = run.current;
+    void act(
+      "new",
+      async () => {
+        await client.addThread(docId, { anchor: { type: "text", quote: q }, body: b });
+        if (gen === run.current) {
+          setQuote("");
+          setBody("");
+        }
+      },
+      "Thread added."
+    );
+  };
+  const shown = (threads ?? []).filter((t) => view === "all" || t.status === view);
+  const pending = suggestions.filter((s) => s.status === "pending");
+  const decided = suggestions.filter((s) => s.status !== "pending");
+  return /* @__PURE__ */ jsx(Ctx.Provider, { value: { client, docId, me, busy, act, actingFor }, children: /* @__PURE__ */ jsxs("div", { className: "agd-comments", children: [
+    /* @__PURE__ */ jsxs("header", { className: "agd-comments__top", children: [
+      /* @__PURE__ */ jsx("h1", { className: "agd-comments__title", children: title }),
+      me && /* @__PURE__ */ jsxs("p", { className: "agd-comments__me", children: [
+        "Signed in as ",
+        /* @__PURE__ */ jsx(Who, { author: me, agentLabel: "Signed in as an agent" })
+      ] })
+    ] }),
+    error && /* @__PURE__ */ jsx("p", { className: "agd-comments__error", role: "alert", children: error }),
+    /* @__PURE__ */ jsx("p", { className: "agd-sr-only", role: "status", children: threads === void 0 && !error ? "Loading comments" : notice }),
+    newThread && holds(me, "comment") && /* @__PURE__ */ jsxs("form", { className: "agd-comments__new", onSubmit: start, children: [
+      /* @__PURE__ */ jsx(Input, { label: "Quote to comment on", value: quote, onChange: (e) => setQuote(e.target.value), hint: "Text that occurs once in the document.", maxLength: 2e3 }),
+      /* @__PURE__ */ jsx(Textarea, { label: "Comment", rows: 2, value: body, onChange: (e) => setBody(e.target.value), maxLength: 1e4 }),
+      /* @__PURE__ */ jsx(Button, { type: "submit", variant: "primary", loading: busy === "new", children: "Add comment" })
+    ] }),
+    /* @__PURE__ */ jsxs(Section, { id: `${base}-threads`, title: "Threads", count: shown.length, children: [
+      /* @__PURE__ */ jsx("div", { className: "agd-comments__views", role: "group", "aria-label": "Show threads", children: VIEWS.map((v) => /* @__PURE__ */ jsx(Button, { size: "sm", variant: view === v.id ? "primary" : "secondary", "aria-pressed": view === v.id, onClick: () => setView(v.id), children: v.label }, v.id)) }),
+      threads === void 0 ? null : shown.length === 0 ? /* @__PURE__ */ jsx("p", { className: "agd-comments__empty", children: view === "all" ? "No threads yet." : `No ${view} threads.` }) : /* @__PURE__ */ jsx("ul", { className: "agd-comments__list", children: shown.map((t) => /* @__PURE__ */ jsx(CardBoundary, { item: t, children: /* @__PURE__ */ jsx(ThreadCard, { thread: t }) }, t.id)) })
+    ] }),
+    /* @__PURE__ */ jsx(Section, { id: `${base}-suggestions`, title: "Suggestions", count: pending.length, children: suggestions.length === 0 ? /* @__PURE__ */ jsx("p", { className: "agd-comments__empty", children: "No suggestions." }) : /* @__PURE__ */ jsx("ul", { className: "agd-comments__list", children: [...pending, ...decided].map((s) => /* @__PURE__ */ jsx(CardBoundary, { item: s, children: /* @__PURE__ */ jsx(SuggestionCard, { suggestion: s }) }, s.id)) }) })
+  ] }) });
+}
+export {
+  CommentsPanel,
+  createClient,
+  holds,
+  mayDecide
+};

package/dist/worker.js

@@ -1,7 +1,7 @@
 import {
   CommentsService,
   TEXT_ROOT
-} from "./chunk-T77DPNIV.js";
+} from "./chunk-B7LTOLUO.js";
 import {
   ACCEPT_SCOPE,
   CommentsError,
@@ -9,7 +9,7 @@ import {
   exact,
   invalid,
   stamp
-} from "./chunk-VAVKBAHM.js";
+} from "./chunk-6MS4LASK.js";
 
 // src/worker.ts
 import { Hono } from "hono";

package/llms.txt

@@ -8,6 +8,7 @@ Keywords: comments,threads,mentions,suggestions,annotations,collaboration,agents
 - 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.
 - Lifecycle: comments.editMessage, deleteMessage, deleteThread, exportPerson, erasePerson (and the same on the CLI, MCP, HTTP API, and client). Only the author may change their own messages; comments:moderate may change anyone's.
+- React panel: import { CommentsPanel, createClient, mayDecide } from "agentic-comments/ui" and "agentic-comments/ui.css" (with agentic-design/styles.css). Threads, quotes, replies, resolve and reopen, agent badge, accept and reject. An agent never decides its own suggestion. Peer: react, react-dom.
 - 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.6.1",
+  "version": "0.7.0",
   "description": "Comment threads and suggestions anchored to any content, from people and agents.",
   "keywords": [
     "comments",
@@ -59,36 +59,64 @@
     "./worker": {
       "types": "./dist/worker.d.ts",
       "import": "./dist/worker.js"
-    }
+    },
+    "./ui": {
+      "types": "./dist/ui.d.ts",
+      "import": "./dist/ui.js"
+    },
+    "./ui.css": "./dist/ui.css"
   },
   "bin": {
     "agentic-comments": "./dist/cli.js",
     "agentic-comments-mcp": "./dist/mcp-bin.js"
   },
   "scripts": {
-    "build": "tsup",
-    "typecheck": "tsc --noEmit",
+    "build": "tsup && node scripts/build-css.mjs",
+    "typecheck": "tsc --noEmit && tsc -p ui --noEmit",
     "test": "vitest run",
-    "deploy:demo": "npm run build && WRANGLER_SEND_METRICS=false wrangler deploy --config wrangler.demo.jsonc",
+    "deploy:demo": "npm run build && npm run build:ui && WRANGLER_SEND_METRICS=false wrangler deploy --config wrangler.demo.jsonc",
     "clean": "rm -rf dist",
+    "dev": "npm run build && WRANGLER_SEND_METRICS=false wrangler dev --port 8794",
+    "dev:smoke": "npm run build && node scripts/dev-smoke.mjs 8794 /health",
     "prepack": "npm run build",
-    "ci:local": "npm run build && npm run typecheck && npm test"
+    "ci:local": "npm run build && npm run typecheck && npm test && npm run test:ui",
+    "build:ui": "node scripts/build-ui.mjs",
+    "test:ui": "npm run build && npm run build:ui && playwright test"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.32.2",
+    "agentic-design": "^0.5.0",
     "agentic-identity": "^0.8.0",
     "hono": "^4.13.14",
     "zod": "^4.6.7"
   },
   "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
     "yjs": "^13.6.0"
   },
   "devDependencies": {
+    "@axe-core/playwright": "^4.14.0",
+    "@playwright/test": "^1.64.1",
     "@types/node": "^22.0.0",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "esbuild": "^0.28.2",
     "tsup": "^8.0.0",
     "typescript": "^5.6.0",
     "vitest": "^3.0.0",
     "wrangler": "^4.155.0",
     "yjs": "^13.6.0"
-  }
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "sideEffects": [
+    "**/*.css"
+  ]
 }

package/dist/mcp-WBAHKMF4.js

@@ -1,11 +0,0 @@
-import {
-  createMcpServer,
-  startMcp
-} from "./chunk-UNJL3N2L.js";
-import "./chunk-H6JK62SP.js";
-import "./chunk-T77DPNIV.js";
-import "./chunk-VAVKBAHM.js";
-export {
-  createMcpServer,
-  startMcp
-};