proto-comments 0.0.0-stage → 0.2.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,161 @@
-# 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 |
+| **H** | Open or close History |
+| **Esc** | Close the draft, 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 (All, Open, For Agent, Resolved). Only open comments are numbered, and they come first in History. A resolved comment shows a check and who resolved it, so the next new comment can be #1 again. Each row has the same actions as an open comment, and you can select several comments to resolve, mark for the agent or delete them at once.
+
+## 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. If the element can't be found any more, the comment has no pin, but it still opens from History.
+
+**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`). A comment or reply can be up to 5000 characters.
+
+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": {}
+}
+```
+
+A resolved comment also has `resolvedBy` (the `author` prop, or `--author` in the CLI) and `resolvedAt`. Reopening clears them.
+
+## License
+
+MIT

package/bin/proto-comments.js

@@ -0,0 +1,92 @@
+#!/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.status === 'resolved' ? '✓' : `#${c.n}`} ${c.status}${c.resolvedBy ? ` by ${c.resolvedBy}` : ''}${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);
+  /* Resolved comments can share a number with an open one; the open one wins. */
+  const find = list => list.find(c => c.n === Number(n) && c.status === 'open') || list.findLast(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);
+    const author = opts.author || 'Agent';
+    const at = new Date().toISOString();
+    c.replies.push({ author, text: words.join(' ') || 'Done.', createdAt: at });
+    if (cmd === 'resolve') Object.assign(c, { status: 'resolved', queued: false, resolvedBy: author, resolvedAt: at });
+    await storage.write(list);
+    return console.log(line(c));
+  }
+  console.log(HELP);
+}
+
+main();