proto-comments 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 proto-comments contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,158 @@
-# Temporary Holding Version
+# proto-comments
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Figma-style review comments on a running React prototype.
+
+- **Comments are split by screen, not only by URL.** Prototypes often show every screen on one URL. Tell the plugin what a "screen" is, and a comment left in Settings won't show up on the deal page.
+- **Pinned to elements.** A pin follows its element when the window is resized or scrolled. Each comment records the block it's in, for example "Review before I send these invites › Emails".
+- **History.** All comments, grouped by screen. Click one to reopen its screen in the saved state, scroll to the element and open the thread.
+- **Made for a coding agent.** Comments live in one JSON file in your project. Mark the ones you want, tell the agent "apply the comments", and it resolves each with a reply saying what changed.
+
+## Install
+
+```bash
+npm install -D proto-comments
+```
+
+React 18+. Mount it once, in development only.
+
+### Next.js (App Router)
+
+Store comments through an API route:
+
+```js
+// app/api/comments/route.js
+import { createNextHandlers } from 'proto-comments/next';
+
+export const dynamic = 'force-dynamic';
+export const { GET, POST, PATCH, DELETE } = createNextHandlers(); // off outside `next dev`
+```
+
+```jsx
+// app/layout.js
+import { ProtoComments } from 'proto-comments';
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en">
+      <body>
+        {children}
+        {process.env.NODE_ENV === 'development' && <ProtoComments author="Anna" />}
+      </body>
+    </html>
+  );
+}
+```
+
+### Vite and other apps
+
+Run the bundled local server next to your dev server:
+
+```bash
+npx proto-comments serve            # http://localhost:4848/api/comments
+```
+
+```jsx
+{import.meta.env.DEV && <ProtoComments endpoint="http://localhost:4848/api/comments" author="Anna" />}
+```
+
+The server only accepts requests from `localhost` pages.
+
+Either way, comments are saved to `comments/comments.json`, relative to the folder you run the dev server from. Use `createNextHandlers({ file })` or `serve --file` to change it.
+
+## Use
+
+| | |
+| --- | --- |
+| **C** | Start commenting: hover outlines an element, click it to leave a comment |
+| **V** | Stop commenting |
+| **Esc** | Close the open comment or History |
+| Toolbar | Bottom center. Drag it by the dots; it stays where you put it |
+
+The shortcuts use physical keys, so they work in any keyboard layout. In text fields C types a letter.
+
+In a comment you can reply, resolve, mark it for the agent, or delete it. In History you can filter (Open, For Agent, Resolved, All), select several comments and **Mark for Agent**, or delete everything.
+
+## Screens in single-URL prototypes
+
+By default a screen is `location.pathname + location.hash`, and History reopens a comment by going to its URL. If your prototype switches screens in state, pass three functions:
+
+```jsx
+'use client';
+import { ProtoComments } from 'proto-comments';
+import { useApp } from '@/lib/store'; // your store
+
+export default function Review() {
+  return (
+    <ProtoComments
+      author="Anna"
+      getScreen={() => {
+        const s = useApp.getState();
+        return { key: s.view === 'settings' ? `settings:${s.tab}` : s.view, label: s.view };
+      }}
+      getSnapshot={() => structuredClone(useApp.getState())}   // must be JSON-serializable
+      restoreSnapshot={snap => useApp.setState(snap)}           // reopen that exact state
+    />
+  );
+}
+```
+
+`getScreen` is called on every animation frame, so keep it cheap.
+
+### All props
+
+| Prop | Default | |
+| --- | --- | --- |
+| `endpoint` | `'/api/comments'` | Where comments are stored |
+| `author` | `'Reviewer'` | Name on new comments and replies |
+| `getScreen` | URL | `() => ({ key, label })`. Comments show only on a screen with the same `key`; `label` groups History |
+| `getSnapshot` | `{ url }` | JSON saved with each comment |
+| `restoreSnapshot` | go to `url` | `(snapshot, comment) => void \| Promise`. Called from History when the comment is on another screen |
+| `getContext` | none | `() => string` shown in History, e.g. `"new client · admin"` |
+| `headingSelector` | none | Extra selectors for block titles, e.g. `'.card-title'`. Built-in: `h1`–`h6`, `legend`, `[class*="title"]`, `label` |
+
+**Better anchors.** A pin is found by a CSS path from the nearest ancestor with an `id` or `data-cid`, plus the element's text. Add `data-cid="…"` to key containers if your markup has few ids.
+
+**Theming.** Colors are CSS variables on `.pc-root` (`--pc-primary`, `--pc-dark`, `--pc-agent`, …). Override them in your own CSS.
+
+## Working with a coding agent
+
+The agent reads and resolves comments in the JSON file directly, or through the CLI:
+
+```bash
+npx proto-comments list              # marked "For Agent" if any, otherwise all open
+npx proto-comments list --all        # also --open, --queued
+npx proto-comments show 3            # selector, block, screen, replies
+npx proto-comments resolve 3 "Shortened the subtitle to one sentence"
+npx proto-comments reply 4 "Should this apply to the popup too?"
+```
+
+Options: `--file <path>`, `--author <name>` (default `Agent`).
+
+The page doesn't poll. It reloads comments when its tab becomes active again, so the agent's replies show up when you come back.
+
+Add this to your `CLAUDE.md` or `AGENTS.md`:
+
+```md
+## Review comments
+Comments on the prototype live in `comments/comments.json` (proto-comments).
+- "apply the comments": apply the ones marked "For Agent" (`queued: true`); if none are marked, every open comment. "apply 2 and 5": only those numbers.
+- `npx proto-comments list` shows that set; `show <n>` gives the selector, block and screen to find the component.
+- After a change: `npx proto-comments resolve <n> "what changed"`. If a comment is unclear, don't change code: `reply <n> "question"` and leave it open.
+```
+
+### Comment format
+
+```json
+{
+  "id": "c1a2b3", "n": 3, "status": "open", "queued": true,
+  "screen": "settings:preferences", "screenLabel": "Settings · Preferences", "context": "",
+  "anchor": { "selector": "#main > div.card > h3", "block": "Homepage", "text": "Default page", "tag": "h3", "offset": { "x": 0.4, "y": 0.5 } },
+  "text": "Rename to Start page", "author": "Anna", "createdAt": "2026-10-22T10:00:00.000Z",
+  "replies": [{ "author": "Agent", "text": "Renamed", "createdAt": "…" }],
+  "snapshot": {}
+}
+```
+
+## License
+
+MIT

package/bin/proto-comments.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+import http from 'node:http';
+import { createStorage, DEFAULT_FILE } from '../server/storage.js';
+
+const HELP = `proto-comments — review comments on a prototype
+
+  proto-comments serve [--port 4848]          local server for apps without their own API route (Vite etc.)
+  proto-comments list [--queued|--open|--all] default: what "apply the comments" covers
+  proto-comments show <n>                     one comment with its anchor and replies
+  proto-comments resolve <n> "what changed"   close it with a reply
+  proto-comments reply <n> "question"         reply and keep it open
+
+Options: --file <path> (default ${DEFAULT_FILE}), --author <name> (default Agent)`;
+
+function parse(argv) {
+  const opts = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (['file', 'port', 'author'].includes(key)) { opts[key] = next; i++; } else opts[key] = true;
+    } else opts._.push(a);
+  }
+  return opts;
+}
+
+const place = a => [...new Set([a.block, a.text].filter(Boolean))].join(' › ') || `<${a.tag}>`;
+const line = c => `#${c.n} ${c.status}${c.queued ? ' [For Agent]' : ''} · ${c.screenLabel} · ${place(c.anchor)}\n    ${c.text}`;
+/** Marked "For Agent" if any are marked, otherwise every open comment. */
+const todo = list => { const open = list.filter(c => c.status === 'open'); const q = open.filter(c => c.queued); return q.length ? q : open; };
+
+function serve(storage, port) {
+  const server = http.createServer(async (req, res) => {
+    const origin = req.headers.origin;
+    /* Local prototypes only: a page on another site must not be able to write comments, even with a "simple" request. */
+    const local = /^https?:\/\/(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/.test(origin || '');
+    if (origin && !local) return res.writeHead(403).end();
+    if (local) {
+      res.setHeader('Access-Control-Allow-Origin', origin);
+      res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PATCH, DELETE, OPTIONS');
+      res.setHeader('Access-Control-Allow-Headers', 'content-type');
+    }
+    if (req.method === 'OPTIONS') return res.writeHead(204).end();
+    if (req.method !== 'GET' && !String(req.headers['content-type']).startsWith('application/json')) return res.writeHead(415).end();
+    if (!req.url.startsWith('/api/comments')) return res.writeHead(404).end();
+    let raw = '';
+    for await (const chunk of req) raw += chunk;
+    try {
+      const { status, json } = await storage.handle(req.method, raw ? JSON.parse(raw) : null);
+      res.writeHead(status, { 'content-type': 'application/json' }).end(JSON.stringify(json));
+    } catch (e) {
+      res.writeHead(500, { 'content-type': 'application/json' }).end(JSON.stringify({ error: e.message }));
+    }
+  });
+  server.listen(port, '127.0.0.1', () => {
+    console.log(`proto-comments: http://localhost:${port}/api/comments → ${storage.file}`);
+  });
+}
+
+async function main() {
+  const opts = parse(process.argv.slice(2));
+  const [cmd, n, ...words] = opts._;
+  const storage = createStorage(opts.file);
+  const find = list => list.find(c => c.n === Number(n)) || (console.error(`No comment #${n}`), process.exit(1));
+
+  if (cmd === 'serve') return serve(storage, Number(opts.port) || 4848);
+  const list = await storage.read();
+  if (cmd === 'list') {
+    const shown = opts.queued ? list.filter(c => c.queued && c.status === 'open')
+      : opts.open ? list.filter(c => c.status === 'open') : opts.all ? list : todo(list);
+    return console.log(shown.map(line).join('\n') || 'No comments.');
+  }
+  if (cmd === 'show') {
+    const c = find(list);
+    console.log(`${line(c)}\n    screen: ${c.screen}${c.context ? ` (${c.context})` : ''}\n    selector: ${c.anchor.selector}`);
+    return c.replies.forEach(r => console.log(`    ↳ ${r.author}: ${r.text}`));
+  }
+  if (cmd === 'resolve' || cmd === 'reply') {
+    const c = find(list);
+    c.replies.push({ author: opts.author || 'Agent', text: words.join(' ') || 'Done.', createdAt: new Date().toISOString() });
+    if (cmd === 'resolve') { c.status = 'resolved'; c.queued = false; }
+    await storage.write(list);
+    return console.log(line(c));
+  }
+  console.log(HELP);
+}
+
+main();

package/dist/index.js

@@ -0,0 +1,649 @@
+"use client";
+
+// src/index.jsx
+import { useEffect as useEffect2, useState as useState2 } from "react";
+import { createPortal } from "react-dom";
+
+// src/store.js
+import { useSyncExternalStore } from "react";
+
+// src/anchors.js
+var ROOT_SEL = (el) => el.id ? `#${CSS.escape(el.id)}` : el.dataset?.cid ? `[data-cid="${el.dataset.cid}"]` : null;
+var textOf = (el) => (el.innerText || el.getAttribute?.("aria-label") || "").replace(/\s+/g, " ").trim().slice(0, 60);
+function selectorFor(el) {
+  const parts = [];
+  for (let n = el; n && n !== document.body; n = n.parentElement) {
+    const root = ROOT_SEL(n);
+    if (root) {
+      parts.unshift(root);
+      break;
+    }
+    const tag = n.tagName.toLowerCase();
+    const cls = [...n.classList].find((c) => !c.startsWith("pc-"));
+    const same = n.parentElement ? [...n.parentElement.children].filter((c) => c.tagName === n.tagName) : [];
+    parts.unshift(`${tag}${cls ? "." + CSS.escape(cls) : ""}${same.length > 1 ? `:nth-of-type(${same.indexOf(n) + 1})` : ""}`);
+  }
+  return parts.join(" > ");
+}
+var HEADING = 'h1, h2, h3, h4, h5, h6, legend, [class*="title"], label';
+function blockFor(el, extra = "") {
+  const sel = extra ? `${extra}, ${HEADING}` : HEADING;
+  if (el.matches(sel) || el.closest(extra ? `${extra}, h1, h2, h3, h4, h5, h6, legend` : "h1, h2, h3, h4, h5, h6, legend")) return "";
+  const own = textOf(el);
+  const before = (h) => h.compareDocumentPosition(el) & Node.DOCUMENT_POSITION_FOLLOWING;
+  for (let n = el.parentElement; n && n !== document.body; n = n.parentElement) {
+    const h = [...n.querySelectorAll(sel)].find((h2) => before(h2) && !h2.closest(".pc-root") && textOf(h2) && textOf(h2) !== own);
+    if (h) return textOf(h);
+    if (n.tagName === "MAIN") break;
+  }
+  return "";
+}
+var placeOf = (a) => [...new Set([a.block, a.text].filter(Boolean))].join(" \u203A ") || `<${a.tag}>`;
+function anchorFor(el, x, y, headingSelector) {
+  const r = el.getBoundingClientRect();
+  return {
+    selector: selectorFor(el),
+    text: textOf(el),
+    block: blockFor(el, headingSelector),
+    tag: el.tagName.toLowerCase(),
+    offset: { x: r.width ? (x - r.left) / r.width : 0, y: r.height ? (y - r.top) / r.height : 0 }
+  };
+}
+function findAnchor(a) {
+  let el = null;
+  try {
+    el = document.querySelector(a.selector);
+  } catch {
+  }
+  if (el && (!a.text || textOf(el) === a.text)) return el;
+  if (a.text) {
+    const match = [...document.querySelectorAll(a.tag)].find((n) => textOf(n) === a.text && !n.closest(".pc-root"));
+    if (match) return match;
+  }
+  return el;
+}
+
+// src/store.js
+var state = { list: [], mode: false, historyOpen: false, openId: null, draft: null, flashId: null, filter: "open" };
+var subs = /* @__PURE__ */ new Set();
+var getC = () => state;
+var setC = (patch) => {
+  state = { ...state, ...patch };
+  subs.forEach((f) => f());
+};
+var subscribe = (f) => {
+  subs.add(f);
+  return () => subs.delete(f);
+};
+var useC = (sel) => useSyncExternalStore(subscribe, () => sel(state), () => sel(state));
+var GO_KEY = "proto-comments:go";
+var DEFAULTS = {
+  endpoint: "/api/comments",
+  author: "Reviewer",
+  getScreen: () => ({ key: location.pathname + location.hash, label: location.pathname + location.hash }),
+  getSnapshot: () => ({ url: location.href }),
+  restoreSnapshot: (snap) => {
+    if (!snap?.url || snap.url === location.href) return;
+    try {
+      sessionStorage.setItem(GO_KEY, pendingId);
+    } catch {
+    }
+    location.assign(snap.url);
+    return "navigating";
+  },
+  getContext: () => "",
+  headingSelector: ""
+};
+var cfg = DEFAULTS;
+var pendingId = null;
+var setConfig = (c) => {
+  cfg = c;
+};
+var getConfig = () => cfg;
+async function api(method, body) {
+  const res = await fetch(cfg.endpoint, { method, headers: { "content-type": "application/json" }, body: body && JSON.stringify(body) });
+  if (!res.ok) throw new Error(`proto-comments: ${method} ${cfg.endpoint} \u2192 ${res.status}`);
+  return res.json();
+}
+async function loadComments() {
+  const list = await api("GET");
+  if (JSON.stringify(list) !== JSON.stringify(state.list)) setC({ list });
+}
+async function addComment(anchor, text) {
+  const screen = cfg.getScreen();
+  const c = await api("POST", { screen: screen.key, screenLabel: screen.label, context: cfg.getContext(), snapshot: cfg.getSnapshot(), anchor, text, author: cfg.author });
+  setC({ list: [...state.list, c], draft: null });
+}
+async function patchComment(id, patch) {
+  const c = await api("PATCH", { id, ...patch });
+  setC({ list: state.list.map((x) => x.id === id ? c : x) });
+}
+async function markComments(ids, queued) {
+  setC({ list: await api("PATCH", { ids, queued }) });
+}
+async function deleteComment(id) {
+  await api("DELETE", { id });
+  setC({ list: state.list.filter((x) => x.id !== id), openId: null });
+}
+async function deleteAllComments() {
+  await api("DELETE", { all: true });
+  setC({ list: [], openId: null, draft: null });
+}
+function reveal(c) {
+  findAnchor(c.anchor)?.scrollIntoView({ block: "center", behavior: "smooth" });
+  setC({ openId: c.id, flashId: c.id });
+  setTimeout(() => setC({ flashId: null }), 1600);
+}
+async function goToComment(c) {
+  const onScreen = cfg.getScreen().key === c.screen && findAnchor(c.anchor);
+  setC({ openId: null, historyOpen: false });
+  if (onScreen) return reveal(c);
+  pendingId = c.id;
+  if (await cfg.restoreSnapshot(c.snapshot, c) === "navigating") return;
+  setTimeout(() => reveal(c), 450);
+}
+function resumePendingGo() {
+  let id = null;
+  try {
+    id = sessionStorage.getItem(GO_KEY);
+    sessionStorage.removeItem(GO_KEY);
+  } catch {
+  }
+  const c = id && state.list.find((x) => x.id === id);
+  if (c) setTimeout(() => reveal(c), 450);
+}
+
+// src/ui.jsx
+import { useEffect, useRef, useState } from "react";
+
+// src/icons.jsx
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+var PATHS = {
+  comment: /* @__PURE__ */ jsx("path", { d: "M3 4.5A1.5 1.5 0 0 1 4.5 3h7A1.5 1.5 0 0 1 13 4.5v5a1.5 1.5 0 0 1-1.5 1.5H7l-3 2.5V11h0a1 1 0 0 1-1-1z" }),
+  list: /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx("path", { d: "M6 4.5h7M6 8h7M6 11.5h7" }),
+    /* @__PURE__ */ jsx("path", { d: "M3 4.5h.01M3 8h.01M3 11.5h.01" })
+  ] }),
+  x: /* @__PURE__ */ jsx("path", { d: "M4 4l8 8M12 4l-8 8" }),
+  trash: /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx("path", { d: "M3 4.5h10M6.5 4.5V3h3v1.5M4.5 4.5l.5 8.5h6l.5-8.5" }),
+    /* @__PURE__ */ jsx("path", { d: "M7 7v3.5M9 7v3.5" })
+  ] })
+};
+function Icon({ name }) {
+  return /* @__PURE__ */ jsx("svg", { className: "pc-i", viewBox: "0 0 16 16", width: "16", height: "16", fill: "none", stroke: "currentColor", strokeWidth: "1.5", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: PATHS[name] });
+}
+function Grip() {
+  return /* @__PURE__ */ jsx("svg", { viewBox: "0 0 16 16", width: "16", height: "16", fill: "currentColor", "aria-hidden": "true", children: [4, 8, 12].map((y) => [6, 10].map((x) => /* @__PURE__ */ jsx("circle", { cx: x, cy: y, r: "1.3" }, `${x}${y}`))) });
+}
+
+// src/ui.jsx
+import { Fragment as Fragment2, jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
+var when = (iso) => new Date(iso).toLocaleString("en-US", { month: "short", day: "numeric", hour: "numeric", minute: "2-digit" });
+var popStyle = (x, y) => ({
+  left: Math.max(8, Math.min(x + 18, window.innerWidth - 328)),
+  top: Math.max(8, Math.min(y - 8, window.innerHeight - 260))
+});
+function Field({ placeholder, submit, onCancel, label }) {
+  const [text, setText] = useState("");
+  const [busy, setBusy] = useState(false);
+  const go = async () => {
+    if (!text.trim() || busy) return;
+    setBusy(true);
+    try {
+      await submit(text.trim());
+      setText("");
+    } finally {
+      setBusy(false);
+    }
+  };
+  return /* @__PURE__ */ jsxs2(Fragment2, { children: [
+    /* @__PURE__ */ jsx2(
+      "textarea",
+      {
+        className: "pc-input",
+        autoFocus: true,
+        rows: 3,
+        placeholder,
+        value: text,
+        onChange: (e) => setText(e.target.value),
+        onKeyDown: (e) => {
+          if (e.key === "Enter" && !e.shiftKey) {
+            e.preventDefault();
+            go();
+          }
+        }
+      }
+    ),
+    /* @__PURE__ */ jsxs2("div", { className: "pc-actions", children: [
+      onCancel && /* @__PURE__ */ jsx2("button", { className: "pc-btn", onClick: onCancel, children: "Cancel" }),
+      /* @__PURE__ */ jsx2("button", { className: "pc-btn primary", disabled: !text.trim() || busy, onClick: go, children: label })
+    ] })
+  ] });
+}
+function Draft({ draft }) {
+  return /* @__PURE__ */ jsxs2("div", { className: "pc-pop", style: popStyle(draft.x, draft.y), children: [
+    /* @__PURE__ */ jsx2("div", { className: "pc-target", title: placeOf(draft.anchor), children: placeOf(draft.anchor) }),
+    /* @__PURE__ */ jsx2(Field, { placeholder: "Leave a comment", label: "Comment", submit: (text) => addComment(draft.anchor, text), onCancel: () => setC({ draft: null }) })
+  ] });
+}
+function Thread({ c, x, y, lost }) {
+  const resolved = c.status === "resolved";
+  return /* @__PURE__ */ jsxs2("div", { className: "pc-pop", style: popStyle(x, y), children: [
+    /* @__PURE__ */ jsxs2("div", { className: "pc-head", children: [
+      /* @__PURE__ */ jsxs2("b", { children: [
+        "#",
+        c.n
+      ] }),
+      /* @__PURE__ */ jsx2("span", { children: c.screenLabel }),
+      c.queued && /* @__PURE__ */ jsx2("i", { className: "pc-tag", children: "For Agent" }),
+      /* @__PURE__ */ jsx2("button", { className: "pc-ibtn", onClick: () => setC({ openId: null }), "aria-label": "Close", title: "Close", children: /* @__PURE__ */ jsx2(Icon, { name: "x" }) })
+    ] }),
+    /* @__PURE__ */ jsx2("div", { className: "pc-target", title: placeOf(c.anchor), children: placeOf(c.anchor) }),
+    lost && /* @__PURE__ */ jsx2("div", { className: "pc-lost", children: "The element isn't on this screen any more." }),
+    /* @__PURE__ */ jsxs2("div", { className: "pc-msg", children: [
+      /* @__PURE__ */ jsxs2("div", { className: "pc-meta", children: [
+        c.author,
+        " \xB7 ",
+        when(c.createdAt)
+      ] }),
+      c.text
+    ] }),
+    c.replies.map((r, i) => /* @__PURE__ */ jsxs2("div", { className: "pc-msg", children: [
+      /* @__PURE__ */ jsxs2("div", { className: "pc-meta", children: [
+        r.author,
+        " \xB7 ",
+        when(r.createdAt)
+      ] }),
+      r.text
+    ] }, i)),
+    /* @__PURE__ */ jsx2(Field, { placeholder: "Reply", label: "Reply", submit: (text) => patchComment(c.id, { reply: { author: getConfig().author, text } }) }),
+    /* @__PURE__ */ jsxs2("div", { className: "pc-actions start", children: [
+      /* @__PURE__ */ jsx2("button", { className: "pc-btn", onClick: () => patchComment(c.id, { status: resolved ? "open" : "resolved" }), children: resolved ? "Reopen" : "Resolve" }),
+      !resolved && /* @__PURE__ */ jsx2("button", { className: "pc-btn", onClick: () => markComments([c.id], !c.queued), children: c.queued ? "Unmark" : "Mark for Agent" }),
+      /* @__PURE__ */ jsx2("button", { className: "pc-ibtn pc-trash", onClick: () => deleteComment(c.id), "aria-label": "Delete comment", title: "Delete", children: /* @__PURE__ */ jsx2(Icon, { name: "trash" }) })
+    ] })
+  ] });
+}
+function Pin({ c, x, y }) {
+  const open = useC((s) => s.openId === c.id);
+  const flash = useC((s) => s.flashId === c.id);
+  return /* @__PURE__ */ jsx2(
+    "button",
+    {
+      className: `pc-pin${c.status === "resolved" ? " done" : ""}${c.queued ? " queued" : ""}${open ? " on" : ""}${flash ? " flash" : ""}`,
+      style: { left: x, top: y },
+      onClick: () => setC({ openId: open ? null : c.id, draft: null }),
+      "aria-label": `Comment ${c.n}`,
+      children: c.n
+    }
+  );
+}
+var FILTERS = [["open", "Open"], ["queued", "For Agent"], ["resolved", "Resolved"], ["all", "All"]];
+var matches = (c, f) => f === "all" || (f === "queued" ? c.queued && c.status === "open" : c.status === f);
+var groupBy = (items, key) => items.reduce((m, it) => {
+  var _a;
+  (m[_a = key(it)] || (m[_a] = [])).push(it);
+  return m;
+}, {});
+function History() {
+  const list = useC((s) => s.list);
+  const filter = useC((s) => s.filter);
+  const shown = list.filter((c) => matches(c, filter));
+  const groups = Object.entries(groupBy(shown, (c) => c.screenLabel));
+  const count = (f) => list.filter((c) => matches(c, f)).length;
+  const [confirm, setConfirm] = useState(false);
+  const [picked, setPicked] = useState([]);
+  const selectable = shown.filter((c) => c.status === "open").map((c) => c.id);
+  const sel = picked.filter((id) => selectable.includes(id));
+  const allPicked = selectable.length > 0 && sel.length === selectable.length;
+  const toggle = (id) => setPicked((p) => p.includes(id) ? p.filter((x) => x !== id) : [...p, id]);
+  const anyQueued = sel.some((id) => list.find((c) => c.id === id)?.queued);
+  const mark = (queued) => markComments(sel, queued).then(() => setPicked([]));
+  return /* @__PURE__ */ jsxs2("aside", { className: "pc-history", "aria-label": "Comments", children: [
+    /* @__PURE__ */ jsxs2("header", { children: [
+      /* @__PURE__ */ jsx2("b", { children: "Comments" }),
+      list.length > 0 && /* @__PURE__ */ jsx2("button", { className: "pc-btn ghost danger", onClick: () => setConfirm(true), children: "Delete all" }),
+      /* @__PURE__ */ jsx2("button", { className: "pc-ibtn", onClick: () => setC({ historyOpen: false }), "aria-label": "Close", title: "Close", children: /* @__PURE__ */ jsx2(Icon, { name: "x" }) })
+    ] }),
+    confirm && /* @__PURE__ */ jsxs2("div", { className: "pc-confirm", children: [
+      /* @__PURE__ */ jsxs2("span", { children: [
+        "Delete all ",
+        list.length,
+        " comments, open and resolved? This can't be undone."
+      ] }),
+      /* @__PURE__ */ jsxs2("div", { className: "pc-actions", children: [
+        /* @__PURE__ */ jsx2("button", { className: "pc-btn", onClick: () => setConfirm(false), children: "Cancel" }),
+        /* @__PURE__ */ jsx2("button", { className: "pc-btn danger solid", onClick: () => deleteAllComments().then(() => setConfirm(false)), children: "Delete all" })
+      ] })
+    ] }),
+    /* @__PURE__ */ jsx2("div", { className: "pc-chips", children: FILTERS.map(([f, l]) => /* @__PURE__ */ jsxs2("button", { className: `pc-chip${filter === f ? " on" : ""}`, onClick: () => setC({ filter: f }), children: [
+      l,
+      " ",
+      count(f)
+    ] }, f)) }),
+    selectable.length > 0 && /* @__PURE__ */ jsxs2("div", { className: "pc-selbar", children: [
+      /* @__PURE__ */ jsxs2("label", { className: "pc-check", children: [
+        /* @__PURE__ */ jsx2("input", { type: "checkbox", checked: allPicked, onChange: () => setPicked(allPicked ? [] : selectable) }),
+        sel.length ? `${sel.length} selected` : "Select all"
+      ] }),
+      sel.length > 0 && anyQueued && /* @__PURE__ */ jsx2("button", { className: "pc-btn", onClick: () => mark(false), children: "Unmark" }),
+      sel.length > 0 && /* @__PURE__ */ jsxs2("button", { className: "pc-btn primary", onClick: () => mark(true), children: [
+        "Mark for Agent (",
+        sel.length,
+        ")"
+      ] })
+    ] }),
+    /* @__PURE__ */ jsxs2("div", { className: "pc-groups", children: [
+      !shown.length && /* @__PURE__ */ jsx2("p", { className: "pc-empty", children: "No comments here. Press C and click an element to leave one." }),
+      groups.map(([label, items]) => /* @__PURE__ */ jsxs2("section", { children: [
+        /* @__PURE__ */ jsx2("h5", { children: label }),
+        items.map((c) => /* @__PURE__ */ jsxs2("div", { className: `pc-row${c.status === "resolved" ? " done" : ""}`, children: [
+          c.status === "open" ? /* @__PURE__ */ jsx2("input", { type: "checkbox", className: "pc-pick", checked: sel.includes(c.id), onChange: () => toggle(c.id), "aria-label": `Select comment ${c.n}` }) : /* @__PURE__ */ jsx2("span", { className: "pc-pick" }),
+          /* @__PURE__ */ jsxs2("button", { className: "pc-item", onClick: () => goToComment(c), children: [
+            /* @__PURE__ */ jsx2("span", { className: `pc-n${c.queued ? " queued" : ""}`, children: c.n }),
+            /* @__PURE__ */ jsxs2("span", { className: "pc-body", children: [
+              /* @__PURE__ */ jsxs2("span", { className: "pc-place", children: [
+                c.queued && /* @__PURE__ */ jsx2("i", { className: "pc-tag", children: "For Agent" }),
+                placeOf(c.anchor)
+              ] }),
+              /* @__PURE__ */ jsx2("span", { className: "pc-text", children: c.text }),
+              /* @__PURE__ */ jsx2("span", { className: "pc-meta", children: [c.context, when(c.createdAt), c.replies.length && `${c.replies.length} ${c.replies.length > 1 ? "replies" : "reply"}`].filter(Boolean).join(" \xB7 ") })
+            ] })
+          ] })
+        ] }, c.id))
+      ] }, label))
+    ] })
+  ] });
+}
+var POS_KEY = "proto-comments:toolbar";
+function Toolbar() {
+  const mode = useC((c) => c.mode);
+  const historyOpen = useC((c) => c.historyOpen);
+  const open = useC((c) => c.list.filter((x) => x.status === "open").length);
+  const [pos, setPos] = useState(null);
+  const drag = useRef(null);
+  useEffect(() => {
+    try {
+      const p = JSON.parse(localStorage.getItem(POS_KEY));
+      if (p) setPos(p);
+    } catch {
+    }
+  }, []);
+  const onDown = (e) => {
+    const r = e.currentTarget.parentElement.getBoundingClientRect();
+    drag.current = { dx: e.clientX - r.left, dy: e.clientY - r.top, w: r.width, h: r.height };
+    e.currentTarget.setPointerCapture(e.pointerId);
+  };
+  const onMove = (e) => {
+    const d = drag.current;
+    if (!d) return;
+    setPos({
+      x: Math.max(8, Math.min(e.clientX - d.dx, window.innerWidth - d.w - 8)),
+      y: Math.max(8, Math.min(e.clientY - d.dy, window.innerHeight - d.h - 8))
+    });
+  };
+  const onUp = () => {
+    drag.current = null;
+    try {
+      localStorage.setItem(POS_KEY, JSON.stringify(pos));
+    } catch {
+    }
+  };
+  return /* @__PURE__ */ jsxs2("div", { className: "pc-bar", style: pos ? { left: pos.x, top: pos.y, bottom: "auto", transform: "none" } : void 0, role: "toolbar", "aria-label": "Comments", children: [
+    /* @__PURE__ */ jsx2("span", { className: "pc-grip", onPointerDown: onDown, onPointerMove: onMove, onPointerUp: onUp, "aria-hidden": "true", title: "Drag", children: /* @__PURE__ */ jsx2(Grip, {}) }),
+    /* @__PURE__ */ jsxs2("button", { "aria-pressed": mode, onClick: () => setC({ mode: !getC().mode, draft: null, openId: null }), title: mode ? "Stop commenting (V)" : "Comment (C)", children: [
+      /* @__PURE__ */ jsx2(Icon, { name: "comment" }),
+      /* @__PURE__ */ jsx2("span", { children: "Comment" }),
+      /* @__PURE__ */ jsx2("kbd", { children: mode ? "V" : "C" })
+    ] }),
+    /* @__PURE__ */ jsxs2("button", { "aria-pressed": historyOpen, onClick: () => setC({ historyOpen: !historyOpen }), title: "All comments", children: [
+      /* @__PURE__ */ jsx2(Icon, { name: "list" }),
+      /* @__PURE__ */ jsx2("span", { children: "History" }),
+      open > 0 && /* @__PURE__ */ jsx2("b", { children: open })
+    ] })
+  ] });
+}
+
+// src/styles.js
+var styles_default = `
+.pc-root{
+  --pc-dark:#262A3D; --pc-dark-hover:#30354B; --pc-dark-text:#C5CAD8; --pc-dark-kbd:#3A3F57;
+  --pc-primary:#3366DD; --pc-primary-hover:#2A56C0;
+  --pc-surface:#FFFFFF; --pc-surface-2:#F6F7F9; --pc-surface-3:#EEF0F4;
+  --pc-border:#E2E5EB; --pc-border-strong:#CDD2DB;
+  --pc-text:#3B4152; --pc-text-strong:#2B3040; --pc-muted:#7A8194; --pc-faint:#A3A9B8;
+  --pc-danger:#C93C3C; --pc-danger-soft:#FDEDED; --pc-warn:#A86A00; --pc-warn-soft:#FFF3DC;
+  --pc-agent:#6B5BD6; --pc-agent-soft:#EFEDFC;
+  --pc-shadow:0 12px 32px rgba(30,35,55,.16), 0 2px 6px rgba(30,35,55,.08);
+  --pc-z:2147483000;
+  font:13px/1.45 Inter, -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif; color:var(--pc-text);
+  -webkit-font-smoothing:antialiased;
+}
+.pc-root *, .pc-root *::before, .pc-root *::after{ box-sizing:border-box; }
+.pc-root button{ font:inherit; color:inherit; cursor:pointer; }
+.pc-root textarea, .pc-root input{ font:inherit; color:inherit; }
+.pc-root :focus-visible{ outline:2px solid var(--pc-primary); outline-offset:2px; }
+.pc-i{ flex:none; }
+
+html.pc-mode, html.pc-mode *{ cursor:crosshair !important; }
+html.pc-mode .pc-root, html.pc-mode .pc-root *{ cursor:auto !important; }
+html.pc-mode .pc-root button, html.pc-mode .pc-root label{ cursor:pointer !important; }
+html.pc-mode .pc-grip{ cursor:grab !important; }
+
+/* buttons */
+.pc-btn{ display:inline-flex; align-items:center; justify-content:center; gap:6px; height:30px; padding:0 10px; border-radius:6px; border:1px solid var(--pc-border-strong); background:var(--pc-surface); color:var(--pc-text); font-weight:500; white-space:nowrap; }
+.pc-btn:hover{ border-color:var(--pc-muted); }
+.pc-btn.primary{ background:var(--pc-primary); border-color:var(--pc-primary); color:#fff; }
+.pc-btn.primary:hover{ background:var(--pc-primary-hover); }
+.pc-btn[disabled]{ opacity:.5; cursor:not-allowed; }
+.pc-btn.ghost{ border-color:transparent; background:transparent; padding:0 8px; }
+.pc-btn.danger{ color:var(--pc-danger); }
+.pc-btn.danger:hover{ background:var(--pc-danger-soft); }
+.pc-btn.danger.solid{ background:var(--pc-danger); border-color:var(--pc-danger); color:#fff; }
+.pc-btn.danger.solid:hover{ filter:brightness(.92); }
+.pc-ibtn{ width:28px; height:28px; display:inline-grid; place-items:center; border:0; border-radius:6px; background:transparent; color:var(--pc-muted); }
+.pc-ibtn:hover{ background:var(--pc-surface-3); color:var(--pc-text); }
+.pc-trash{ margin-left:auto; }
+.pc-trash:hover{ color:var(--pc-danger); background:var(--pc-danger-soft); }
+.pc-chip{ height:28px; padding:0 10px; border-radius:14px; border:1px solid var(--pc-border-strong); background:var(--pc-surface); color:var(--pc-text); }
+.pc-chip:hover{ border-color:var(--pc-muted); }
+.pc-chip.on{ background:var(--pc-dark); border-color:var(--pc-dark); color:#fff; }
+.pc-tag{ display:inline-flex; align-items:center; height:18px; padding:0 7px; margin-right:6px; border-radius:9px; background:var(--pc-agent-soft); color:var(--pc-agent); font-style:normal; font-size:10px; font-weight:600; letter-spacing:.02em; }
+
+/* toolbar */
+.pc-bar{ position:fixed; z-index:calc(var(--pc-z) + 4); left:50%; transform:translateX(-50%); bottom:calc(16px + env(safe-area-inset-bottom,0px)); display:flex; align-items:center; gap:2px; padding:4px; border-radius:10px; background:var(--pc-dark); color:var(--pc-dark-text); box-shadow:var(--pc-shadow); user-select:none; }
+.pc-bar button{ display:inline-flex; align-items:center; gap:6px; height:30px; padding:0 10px; border:0; border-radius:7px; background:transparent; color:inherit; }
+.pc-bar button:hover{ background:var(--pc-dark-hover); color:#fff; }
+.pc-bar button[aria-pressed="true"]{ background:var(--pc-primary); color:#fff; }
+.pc-bar kbd{ font:inherit; font-size:11px; padding:0 5px; border-radius:4px; background:var(--pc-dark-kbd); color:#D9DCE6; }
+.pc-bar b{ min-width:18px; height:18px; padding:0 5px; border-radius:9px; background:var(--pc-primary); color:#fff; font-size:11px; display:grid; place-items:center; }
+.pc-grip{ display:grid; place-items:center; width:20px; height:30px; margin-left:2px; opacity:.6; cursor:grab; touch-action:none; }
+.pc-grip:hover{ opacity:1; }
+.pc-hint{ position:fixed; z-index:calc(var(--pc-z) + 1); left:50%; bottom:calc(68px + env(safe-area-inset-bottom,0px)); transform:translateX(-50%); background:var(--pc-dark); color:#fff; padding:8px 12px; border-radius:8px; box-shadow:var(--pc-shadow); }
+
+/* pins and popovers */
+.pc-outline{ position:fixed; z-index:var(--pc-z); pointer-events:none; outline:2px solid var(--pc-primary); outline-offset:1px; border-radius:3px; background:rgba(51,102,221,.06); }
+.pc-outline.flash{ animation:pc-flash 1.6s ease-out forwards; }
+@keyframes pc-flash{ 0%,60%{ opacity:1 } 100%{ opacity:0 } }
+.pc-pin{ position:fixed; z-index:calc(var(--pc-z) + 1); transform:translate(-2px,-100%); min-width:26px; height:26px; padding:0 7px; border:2px solid #fff; border-radius:13px 13px 13px 2px; background:var(--pc-primary); color:#fff !important; font-size:12px !important; font-weight:600; box-shadow:var(--pc-shadow); }
+.pc-pin.on{ background:var(--pc-dark); }
+.pc-pin.queued, .pc-n.queued{ background:var(--pc-agent); }
+.pc-pin.done{ background:var(--pc-faint); }
+.pc-pin.flash{ animation:pc-pin .5s ease-out 2; }
+@keyframes pc-pin{ 50%{ transform:translate(-2px,-100%) scale(1.25) } }
+.pc-pop{ position:fixed; z-index:calc(var(--pc-z) + 2); width:320px; padding:12px; display:flex; flex-direction:column; gap:10px; background:var(--pc-surface); border:1px solid var(--pc-border); border-radius:8px; box-shadow:var(--pc-shadow); max-height:calc(100vh - 16px); overflow:auto; }
+.pc-head{ display:flex; align-items:center; gap:8px; }
+.pc-head span{ flex:1; color:var(--pc-muted); overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
+.pc-head .pc-tag{ margin:0; }
+.pc-target, .pc-place{ font-size:12px; color:var(--pc-muted); overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
+.pc-head + .pc-target{ margin-top:-4px; }
+.pc-input{ width:100%; resize:vertical; border:1px solid var(--pc-border-strong); border-radius:6px; padding:8px 10px; font-size:14px !important; background:var(--pc-surface); }
+.pc-input:focus{ outline:none; border-color:var(--pc-primary); }
+.pc-actions{ display:flex; justify-content:flex-end; gap:8px; }
+.pc-actions.start{ justify-content:flex-start; border-top:1px solid var(--pc-border); padding-top:10px; }
+.pc-msg{ font-size:14px; color:var(--pc-text-strong); white-space:pre-wrap; }
+.pc-meta{ display:block; font-size:12px; color:var(--pc-muted); margin-bottom:2px; }
+.pc-lost{ font-size:12px; color:var(--pc-warn); background:var(--pc-warn-soft); border-radius:6px; padding:6px 8px; }
+
+/* history */
+.pc-history{ position:fixed; z-index:calc(var(--pc-z) + 3); top:0; right:0; bottom:0; width:360px; max-width:100%; background:var(--pc-surface); border-left:1px solid var(--pc-border); box-shadow:var(--pc-shadow); display:flex; flex-direction:column; }
+.pc-history header{ display:flex; align-items:center; gap:4px; padding:12px 12px 8px 16px; font-size:15px; }
+.pc-history header b{ flex:1; color:var(--pc-text-strong); }
+.pc-confirm{ margin:0 16px 12px; padding:10px 12px; border-radius:8px; background:var(--pc-danger-soft); color:var(--pc-text-strong); display:flex; flex-direction:column; gap:8px; }
+.pc-chips{ display:flex; flex-wrap:wrap; gap:6px; padding:0 16px 12px; border-bottom:1px solid var(--pc-border); }
+.pc-selbar{ display:flex; align-items:center; gap:8px; min-height:44px; padding:6px 16px; border-bottom:1px solid var(--pc-border); }
+.pc-check{ flex:1; display:inline-flex; align-items:center; gap:10px; cursor:pointer; }
+.pc-check input, .pc-pick{ width:16px; height:16px; margin:0; accent-color:var(--pc-primary); flex:none; }
+.pc-groups{ flex:1; overflow:auto; padding:8px 0 16px; }
+.pc-groups h5{ margin:12px 16px 4px; font-size:12px; font-weight:600; color:var(--pc-muted); text-transform:uppercase; letter-spacing:.04em; }
+.pc-row{ display:flex; align-items:flex-start; padding-left:16px; }
+.pc-row:hover{ background:var(--pc-surface-2); }
+.pc-pick{ margin-top:11px; }
+.pc-item{ flex:1; min-width:0; display:flex; gap:10px; padding:8px 16px 8px 10px; border:0; background:transparent; text-align:left; }
+.pc-n{ flex:none; min-width:22px; height:22px; padding:0 6px; border-radius:11px 11px 11px 2px; background:var(--pc-primary); color:#fff; font-size:11px; font-weight:600; display:grid; place-items:center; }
+.pc-row.done .pc-n{ background:var(--pc-faint); }
+.pc-body{ min-width:0; display:flex; flex-direction:column; gap:2px; }
+.pc-text{ color:var(--pc-text-strong); display:-webkit-box; -webkit-line-clamp:2; -webkit-box-orient:vertical; overflow:hidden; }
+.pc-row.done .pc-text{ color:var(--pc-muted); }
+.pc-empty{ margin:16px; color:var(--pc-muted); }
+`;
+
+// src/index.jsx
+import { Fragment as Fragment3, jsx as jsx3, jsxs as jsxs3 } from "react/jsx-runtime";
+var TEXT_INPUT = 'input:not([type=checkbox]):not([type=radio]):not([type=button]):not([type=submit]):not([type=range]):not([type=color]), textarea, [contenteditable="true"]';
+var typing = (t) => t.closest?.(TEXT_INPUT);
+var ours = (t) => t.closest?.(".pc-root");
+var BLOCK = ["pointerdown", "mousedown", "mouseup", "click", "dblclick"];
+var rectOf = (el) => {
+  const r = el.getBoundingClientRect();
+  return { left: r.left, top: r.top, width: r.width, height: r.height };
+};
+function useStyles() {
+  useEffect2(() => {
+    if (document.getElementById("proto-comments-css")) return;
+    const s = document.createElement("style");
+    s.id = "proto-comments-css";
+    s.textContent = styles_default;
+    document.head.appendChild(s);
+  }, []);
+}
+function useFrame(list, openId, flashId) {
+  const [frame, setFrame] = useState2({ screen: null, pos: {} });
+  useEffect2(() => {
+    let raf, last = "";
+    const tick = () => {
+      const screen = getConfig().getScreen().key;
+      const pos = {};
+      list.forEach((c) => {
+        if (c.screen !== screen || c.status !== "open" && c.id !== openId) return;
+        const el = findAnchor(c.anchor);
+        if (!el || !el.getClientRects().length) return;
+        const r = rectOf(el);
+        pos[c.id] = { x: r.left + c.anchor.offset.x * r.width, y: r.top + c.anchor.offset.y * r.height, rect: c.id === flashId ? r : null };
+      });
+      const key = JSON.stringify([screen, pos]);
+      if (key !== last) {
+        last = key;
+        setFrame({ screen, pos });
+      }
+      raf = requestAnimationFrame(tick);
+    };
+    tick();
+    return () => cancelAnimationFrame(raf);
+  }, [list, openId, flashId]);
+  return frame;
+}
+function ProtoComments(props) {
+  const cfg2 = { ...DEFAULTS, ...Object.fromEntries(Object.entries(props).filter(([, v]) => v !== void 0)) };
+  setConfig(cfg2);
+  useStyles();
+  const [root, setRoot] = useState2(null);
+  useEffect2(() => {
+    const el = document.createElement("div");
+    el.className = "pc-root";
+    document.body.appendChild(el);
+    setRoot(el);
+    return () => el.remove();
+  }, []);
+  const { list, mode, draft, openId, historyOpen, flashId } = useC((s) => s);
+  const [hover, setHover] = useState2(null);
+  useEffect2(() => {
+    const load = () => {
+      if (document.visibilityState === "visible") return loadComments().catch((e) => console.warn(e.message));
+    };
+    Promise.resolve(load()).then(resumePendingGo);
+    document.addEventListener("visibilitychange", load);
+    window.addEventListener("focus", load);
+    return () => {
+      document.removeEventListener("visibilitychange", load);
+      window.removeEventListener("focus", load);
+    };
+  }, []);
+  useEffect2(() => {
+    const onKey = (e) => {
+      const c = getC();
+      if (e.key === "Escape" && (c.draft || c.openId || c.historyOpen)) {
+        e.stopPropagation();
+        if (c.draft) setC({ draft: null });
+        else if (c.openId) setC({ openId: null });
+        else setC({ historyOpen: false });
+        return;
+      }
+      if (e.metaKey || e.ctrlKey || e.altKey) return;
+      if (e.code === "KeyV" && c.mode && !(typing(e.target) && ours(e.target))) {
+        e.preventDefault();
+        e.stopPropagation();
+        setC({ mode: false, draft: null });
+      }
+      if (e.code === "KeyC" && !c.mode && !typing(e.target)) setC({ mode: true, openId: null });
+    };
+    window.addEventListener("keydown", onKey, true);
+    return () => window.removeEventListener("keydown", onKey, true);
+  }, []);
+  useEffect2(() => {
+    if (!mode) {
+      setHover(null);
+      return;
+    }
+    const onMove = (e) => setHover(ours(e.target) ? null : rectOf(e.target));
+    const block = (e) => {
+      if (ours(e.target)) return;
+      e.preventDefault();
+      e.stopPropagation();
+      if (e.type === "click") setC({ draft: { anchor: anchorFor(e.target, e.clientX, e.clientY, cfg2.headingSelector), x: e.clientX, y: e.clientY }, openId: null });
+    };
+    document.addEventListener("mousemove", onMove, true);
+    BLOCK.forEach((t) => document.addEventListener(t, block, true));
+    if (!ours(document.activeElement)) document.activeElement?.blur();
+    document.documentElement.classList.add("pc-mode");
+    return () => {
+      document.removeEventListener("mousemove", onMove, true);
+      BLOCK.forEach((t) => document.removeEventListener(t, block, true));
+      document.documentElement.classList.remove("pc-mode");
+    };
+  }, [mode, cfg2.headingSelector]);
+  const { pos } = useFrame(list, openId, flashId);
+  const here = list.filter((c) => pos[c.id]);
+  const open = list.find((c) => c.id === openId);
+  if (!root) return null;
+  return createPortal(
+    /* @__PURE__ */ jsxs3(Fragment3, { children: [
+      hover && !draft && /* @__PURE__ */ jsx3("div", { className: "pc-outline", style: hover }),
+      here.map((c) => /* @__PURE__ */ jsx3(Pin, { c, x: pos[c.id].x, y: pos[c.id].y }, c.id)),
+      here.map((c) => pos[c.id].rect && /* @__PURE__ */ jsx3("div", { className: "pc-outline flash", style: pos[c.id].rect }, `f${c.id}`)),
+      draft && /* @__PURE__ */ jsx3(Draft, { draft }),
+      open && (pos[open.id] ? /* @__PURE__ */ jsx3(Thread, { c: open, x: pos[open.id].x, y: pos[open.id].y }) : /* @__PURE__ */ jsx3(Thread, { c: open, x: window.innerWidth / 2 - 160, y: 120, lost: true })),
+      historyOpen && /* @__PURE__ */ jsx3(History, {}),
+      /* @__PURE__ */ jsx3(Toolbar, {}),
+      mode && /* @__PURE__ */ jsx3("div", { className: "pc-hint", children: "Click an element to comment \xB7 V to stop" })
+    ] }),
+    root
+  );
+}
+var index_default = ProtoComments;
+export {
+  ProtoComments,
+  index_default as default,
+  placeOf
+};

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "proto-comments",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Figma-style review comments on a running React prototype, split by screen even in single-URL apps, stored in a JSON file a coding agent can apply.",
+  "type": "module",
+  "license": "MIT",
+  "keywords": ["react", "prototype", "comments", "review", "feedback", "annotations", "design", "ai-agent", "claude"],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js",
+    "./next": "./server/next.js",
+    "./storage": "./server/storage.js",
+    "./package.json": "./package.json"
+  },
+  "bin": { "proto-comments": "./bin/proto-comments.js" },
+  "files": ["dist", "server", "bin", "README.md", "LICENSE"],
+  "sideEffects": false,
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "build": "node build.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "devDependencies": {
+    "esbuild": "0.24.2"
+  }
+}

package/server/next.js

@@ -0,0 +1,25 @@
+import { createStorage } from './storage.js';
+
+/**
+ * Route handlers for a Next.js App Router route, e.g. app/api/comments/route.js:
+ *
+ *   import { createNextHandlers } from 'proto-comments/next';
+ *   export const dynamic = 'force-dynamic';
+ *   export const { GET, POST, PATCH, DELETE } = createNextHandlers();
+ *
+ * Off outside `next dev` unless `enabled` is set.
+ */
+export function createNextHandlers({ file, enabled = process.env.NODE_ENV === 'development' } = {}) {
+  const storage = createStorage(file);
+  const run = method => async req => {
+    if (!enabled) return new Response('Not found', { status: 404 });
+    /* Same-origin JSON only: a page on another site must not be able to write comments, even with a "simple" request. */
+    const origin = req.headers.get('origin');
+    if (origin && new URL(origin).host !== req.headers.get('host')) return new Response('Forbidden', { status: 403 });
+    if (method !== 'GET' && !(req.headers.get('content-type') || '').startsWith('application/json')) return new Response('Unsupported Media Type', { status: 415 });
+    const body = method === 'GET' ? null : await req.json();
+    const { status, json } = await storage.handle(method, body);
+    return Response.json(json, { status });
+  };
+  return { GET: run('GET'), POST: run('POST'), PATCH: run('PATCH'), DELETE: run('DELETE') };
+}

package/server/storage.js

@@ -0,0 +1,58 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+/* Comments live in one JSON file in the project, so a coding agent can read and resolve them directly. */
+export const DEFAULT_FILE = 'comments/comments.json';
+
+export function createStorage(file = DEFAULT_FILE) {
+  const abs = path.resolve(process.cwd(), file);
+  /* Writes go one at a time, so two quick requests can't overwrite each other. */
+  let queue = Promise.resolve();
+  const locked = fn => (queue = queue.then(fn, fn));
+
+  async function read() {
+    try { return JSON.parse(await fs.readFile(abs, 'utf8')); } catch (e) { if (e.code === 'ENOENT') return []; throw e; }
+  }
+  async function write(list) {
+    await fs.mkdir(path.dirname(abs), { recursive: true });
+    await fs.writeFile(abs, JSON.stringify(list, null, 2) + '\n');
+  }
+  const now = () => new Date().toISOString();
+
+  /** One entry point for every transport (Next route, standalone server): returns { status, json }. */
+  async function handle(method, body) {
+    if (method === 'GET') return { status: 200, json: await read() };
+    return locked(async () => {
+      const list = await read();
+      if (method === 'POST') {
+        const { screen, screenLabel, context, snapshot, anchor, text, author } = body;
+        const n = Math.max(0, ...list.map(c => c.n)) + 1;
+        const c = { id: `c${Date.now().toString(36)}`, n, screen, screenLabel, context, anchor, text, author, status: 'open', queued: false, createdAt: now(), replies: [], snapshot };
+        await write([...list, c]);
+        return { status: 200, json: c };
+      }
+      if (method === 'PATCH') {
+        const { id, ids, queued, status, reply } = body;
+        if (ids) {
+          list.forEach(x => { if (ids.includes(x.id)) x.queued = !!queued; });
+          await write(list);
+          return { status: 200, json: list };
+        }
+        const c = list.find(x => x.id === id);
+        if (!c) return { status: 404, json: { error: 'Not found' } };
+        if (status) c.status = status;
+        if (status === 'resolved') c.queued = false;
+        if (reply) c.replies.push({ ...reply, createdAt: now() });
+        await write(list);
+        return { status: 200, json: c };
+      }
+      if (method === 'DELETE') {
+        await write(body.all ? [] : list.filter(x => x.id !== body.id));
+        return { status: 200, json: { ok: true } };
+      }
+      return { status: 405, json: { error: 'Method not allowed' } };
+    });
+  }
+
+  return { file: abs, read, write, handle };
+}