@erdemtuna/doc-review 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Peter Yang
+
+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

@@ -0,0 +1,117 @@
+# Doc Review
+
+Edit HTML and Markdown files directly, leave comments like a Google Doc, and send all your feedback to your AI agent at once.
+
+[Read the original Human Review launch post](https://creatoreconomy.so/p/use-my-human-review-skill-to-edit-html-markdown-visually)
+
+https://github.com/user-attachments/assets/7cab09c9-eaa0-4e8b-984d-2925e810b5c2
+
+## Problem
+
+Giving AI feedback on files in chat is painful.
+
+Sometimes you want to change one sentence yourself. Instead, you end up typing:
+
+> In the third paragraph, change X to Y. Cut the third card because it repeats the first one. Also rewrite the CTA.
+
+Then the agent changes the file and you have to check whether it understood every instruction. This gets even harder when you’re reviewing a long plan, Markdown document, landing page, or multi-page website.
+
+## How to install /doc-review
+
+The easiest way to install the skill is to paste this into ChatGPT, Claude Code, Codex, or your favorite coding agent:
+
+```text
+Install the /doc-review skill globally from https://github.com/erdemtuna/doc-review
+```
+
+You can also install it with `npx`:
+
+```sh
+npx -y @erdemtuna/doc-review setup --global
+```
+
+This fork uses the `doc-review` command, `/doc-review` skill, and
+`~/.doc-review` state directory. It does not install a `human-review` alias or
+migrate upstream state and skill files; remove those old files manually if you
+no longer need them.
+
+## How to use /doc-review
+
+![Doc Review visual editor](assets/doc-review.png)
+
+Open an HTML or Markdown file:
+
+```text
+/doc-review (your file)
+```
+
+Review a page running on localhost:
+
+```text
+/doc-review (localhost URL)
+```
+
+Doc Review opens the file in your browser. Make direct edits, leave comments, and click Send. Your agent receives all your feedback in one batch, updates the source, and refreshes the page for another review.
+
+Note: For HTML files, direct edits and resizes save automatically. For Markdown and localhost pages, click Send so your agent can apply them to the source.
+
+File and rendered Markdown reviews run with authored scripts and inline handlers
+blocked, an opaque iframe origin, and no popup or download permission. Their
+per-render message capability is rotated for every load and navigation. It is
+kept out of document URLs, HTML attributes, authored DOM, and global JavaScript
+state; the single-use artifact URL loads a same-origin bootstrap module under a
+nonce-based CSP. Relative assets, including a same-artifact `<base>`, resolve
+beside the reviewed file, while review navigation always stays relative to the
+source file. External bases are ignored.
+
+Localhost reviews keep `allow-same-origin`, popup, and download compatibility so
+application behavior still works. Because localhost application scripts are
+trusted in that mode, the render capability provides correlation and stale
+message rejection rather than an authorization boundary. The authenticated
+parent still validates links and never exposes the raw-file save route to a
+localhost review.
+
+Agent polling returns an immutable `batch_id`. After applying the batch, the
+agent acknowledges that exact receipt and keeps waiting:
+
+```sh
+npx -y @erdemtuna/doc-review poll path/to/file.html --ack b_0123456789abcdef --timeout 600
+```
+
+A stale or repeated batch ID is harmless: it never clears newer feedback. The
+complete acknowledgement command is included in each response's `next_step`.
+
+## What this skill lets you do
+
+- **Edit text directly and tweak basic formatting** (e.g., bold, italic).
+- **Make bulleted and numbered lists** — type `- ` or `1. ` at the start of a line, or press ⌘⇧8 / ⌘⇧7. Tab and Shift+Tab indent and outdent.
+- **Add links** — select text and press ⌘K. ⌘K inside an existing link edits or removes it.
+- **Resize images** by dragging their corner, and **move images** by dragging them to a new spot.
+- **Rearrange the page** — hover any block and drag the handle on its left edge to move the whole block somewhere else.
+- **Paste images** from your clipboard — file reviews save them beside the document; localhost reviews stage them for the agent to place in the app source.
+- **Select a phrase and leave a comment** anchored to the exact text.
+- **Comment on an image, chart, or section** by clicking the element.
+- **Remove elements** without explaining the deletion in chat.
+- **Command-click links** to review multiple pages without losing your feedback.
+- **Send every edit and comment at once** instead of writing a long chat message.
+
+Doc Review works well for editing AI-generated plans, updating landing pages, reviewing localhost apps, and removing extra copy from a UX.
+
+## What’s inside
+
+- [`cli.js`](src/cli.js) contains the `doc-review`, `poll`, `status`, and `setup` commands.
+- [`server.js`](src/server.js) runs the local review session.
+- [`sdk.js`](src/sdk.js) handles editing, comments, highlights, and feedback.
+- [`chrome-client.js`](src/chrome-client.js) contains the visual review interface.
+- [`markdown.js`](src/markdown.js) renders Markdown files for review.
+- [`SKILL.md`](src/SKILL.md) teaches Claude Code, Codex, and other agents how to use Doc Review.
+
+Everything runs on your computer. Doc Review doesn’t require an account, cloud service, database, or API key.
+
+## Upstream project
+
+Doc Review is an independent fork of [Human Review](https://github.com/petergyang/human-review), originally created by Peter Yang. The fork preserves the upstream MIT license and continues from the upstream `v0.6.1` release.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@erdemtuna/doc-review",
+  "version": "0.7.0",
+  "description": "Review and edit agent-generated files and localhost pages in the browser, then send the whole batch back to your agent.",
+  "author": "Peter Yang",
+  "homepage": "https://github.com/erdemtuna/doc-review#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/erdemtuna/doc-review.git"
+  },
+  "bugs": {
+    "url": "https://github.com/erdemtuna/doc-review/issues"
+  },
+  "type": "module",
+  "bin": {
+    "doc-review": "src/cli.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "npm run test:unit",
+    "test:unit": "node --test",
+    "test:browser": "playwright test",
+    "test:all": "npm run test:unit && npm run test:browser",
+    "start": "node src/cli.js"
+  },
+  "keywords": [
+    "html",
+    "markdown",
+    "localhost",
+    "nextjs",
+    "review",
+    "comments",
+    "agent",
+    "claude-code",
+    "codex",
+    "cli"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.62.1",
+    "jsdom": "^29.1.1"
+  },
+  "dependencies": {
+    "marked": "^18.0.7"
+  }
+}

package/src/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: doc-review
+description: Open an HTML file, Markdown file, or localhost page in the browser so the user can edit text directly and leave comments on specific parts, then send all edits and comments back to you. Use after writing or updating something the user will read — specs, plans, reports, newsletter drafts, landing pages, slide decks, and locally running web pages.
+---
+
+# doc-review
+
+The user reviews your HTML, Markdown, or localhost page in a real browser: they fix small things
+by typing, select anything to comment on it, and send you the whole batch at once.
+
+Markdown files open rendered. Their quotes and edits reference the rendered text,
+and the file itself is never touched — apply every change to the Markdown source,
+keeping its formatting syntax.
+
+## The loop
+
+1. Write or update the HTML or Markdown file, or start the local page being reviewed.
+2. Open it for the user:
+
+   ```sh
+   npx -y @erdemtuna/doc-review path/to/file.html
+   ```
+
+   For a page served by a local development server, open the real route instead
+   of recreating it as a separate HTML file:
+
+   ```sh
+   npx -y @erdemtuna/doc-review http://localhost:3000/wiki
+   ```
+
+3. Wait for feedback. This blocks until they hit Send, or the timeout passes:
+
+   ```sh
+   npx -y @erdemtuna/doc-review poll path/to/file.html --timeout 600
+   ```
+
+   Keep this command in the foreground. Do not end your turn while it is waiting.
+   If your shell returns a process or session handle, keep waiting on that handle
+   until the command exits. If it prints `{"status":"timeout"}`, no feedback has
+   arrived yet — run the same poll command again to keep waiting. Feedback is
+   saved even if a poll dies, so nothing is ever lost.
+
+   If it prints `{"status":"closed"}`, the user ended the review from the
+   browser — stop polling and do not run the poll command again. Unsent
+   feedback is kept and ships the next time this target is reviewed.
+
+4. Apply what comes back, then wait again. Copy `batch_id` from the response;
+   only that exact receipt can clear the batch you handled:
+
+   ```sh
+   npx -y @erdemtuna/doc-review poll path/to/file.html --ack b_0123456789abcdef --timeout 600
+   ```
+
+   The response's `next_step` contains the complete acknowledgement command.
+   Never acknowledge a different or guessed ID.
+
+Repeat 3–4 until the user says they are done.
+
+Not sure whether feedback is already waiting — say, at the start of a new turn?
+This answers instantly without blocking:
+
+```sh
+npx -y @erdemtuna/doc-review status path/to/file.html
+```
+
+It prints `{"status": "feedback-waiting"}` when a batch is ready for a poll,
+plus counts of unsent comments and edits still in the browser.
+
+## What you get
+
+One batch covers every page the user visited, grouped by file or localhost URL.
+
+```json
+{
+  "batch_id": "b_0123456789abcdef",
+  "status": "feedback",
+  "pages": [
+    {
+      "file": "/abs/path/to/page.html",
+      "comments": [
+        { "id": "c_1", "kind": "selection", "quote": "the exact text they selected",
+          "anchor": { "prefix": "...", "quote": "...", "suffix": "..." },
+          "feedback": "what they want changed" }
+      ],
+      "edits": [
+        { "label": "Problem body", "kind": "edited",
+          "before": "the original wording",
+          "after": "their exact new wording",
+          "after_html": "their exact new wording with <strong>formatting</strong>" }
+      ]
+    }
+  ],
+  "overall_note": "feedback not tied to any one page",
+  "next_step": "Apply this feedback, then run: npx -y @erdemtuna/doc-review poll ... --ack b_0123456789abcdef --timeout 600"
+}
+```
+
+## Rules
+
+- **`edits` are changes the user already made.** `after` is their exact wording —
+  carry it across verbatim and never revert it. If the HTML was generated from
+  something else (MDX, Markdown, a template), apply `after` to the **source** too,
+  or their fix disappears on the next build.
+- When `before_html`/`after_html` are present, the user changed formatting, not
+  just words — bold, italic, underline, links. Use the HTML version to carry the
+  formatting into the source, translated to its syntax (e.g. `<strong>` → `**`
+  in Markdown/MDX).
+- A page with `kind: "url"` was edited directly in the review UI. Its `file`
+  and `url` fields name the localhost route, not a writable file. Find the
+  matching project source (such as MDX, TSX, or a template), apply every edit
+  and deletion there, then acknowledge so the route reloads. Never write the
+  rendered HTTP response back into the app.
+- When an edit's `after_html` contains `<img src="assets/...">`, the user pasted
+  an image: the file already exists in an `assets/` folder next to the reviewed
+  file. Keep that relative path — in Markdown, reference it as
+  `![](assets/...)`. Never regenerate or inline the image.
+- On a localhost page, a pasted image arrives under `staged_assets`. Copy its
+  local `path` into the app's appropriate asset folder, replace the temporary
+  preview URL in `after_html`, and preserve the image at the user's insertion
+  point. Never leave the temporary preview URL in source.
+- An edit with `kind: "moved"` means the user relocated that whole block.
+  Reposition it in the source without rewriting its content: it now sits right
+  after the block whose text starts with `moved_after`, and right before the
+  block whose text starts with `moved_before`. An empty `moved_after` means it
+  is now the first block in its container.
+- Find each comment by its `quote`; that exact string is in the file.
+- `kind: "element"` points at a whole block, so `quote` is its label, not body text.
+- Fix every page in `pages`, not just the first.
+- **Do not write a reply.** There is no chat. The user sees your work when the page
+  reloads, which happens on its own the moment you save the file.
+
+## Better edit labels (optional)
+
+Name the sections you author and the user's edit list uses your names instead of
+guessing from the DOM:
+
+```html
+<p data-block="Problem body">…</p>
+<div data-container="Metrics callout">…</div>
+```
+
+`data-block` names a region for the edit list. `data-container` also makes the block
+clickable as a comment target.

package/src/anchor-text.js

@@ -0,0 +1,115 @@
+/**
+ * Quote-with-context anchoring, in the spirit of the W3C TextQuoteSelector.
+ *
+ * These functions are pure string maths so they can be unit-tested in Node and
+ * shipped verbatim to the browser, where the DOM half of anchoring lives.
+ */
+
+export const CONTEXT_PAD = 32;
+
+/** Capture `quote` plus surrounding context so it can be re-found after edits. */
+export function buildContext(text, start, end, pad = CONTEXT_PAD) {
+  return {
+    prefix: text.slice(Math.max(0, start - pad), start),
+    quote: text.slice(start, end),
+    suffix: text.slice(end, Math.min(text.length, end + pad)),
+  };
+}
+
+function commonSuffixLength(a, b) {
+  let n = 0;
+  while (n < a.length && n < b.length && a[a.length - 1 - n] === b[b.length - 1 - n]) n += 1;
+  return n;
+}
+
+function commonPrefixLength(a, b) {
+  let n = 0;
+  while (n < a.length && n < b.length && a[n] === b[n]) n += 1;
+  return n;
+}
+
+function occurrences(text, quote) {
+  const found = [];
+  let at = text.indexOf(quote);
+  while (at !== -1) {
+    found.push(at);
+    at = text.indexOf(quote, at + 1);
+  }
+  return found;
+}
+
+function bestHit(text, hits, quote, prefix, suffix) {
+  let best = hits[0];
+  let bestScore = -1;
+  for (const at of hits) {
+    const before = text.slice(Math.max(0, at - prefix.length), at);
+    const after = text.slice(at + quote.length, at + quote.length + suffix.length);
+    const score = commonSuffixLength(prefix, before) + commonPrefixLength(suffix, after);
+    if (score > bestScore) {
+      bestScore = score;
+      best = at;
+    }
+  }
+  return { at: best, score: bestScore };
+}
+
+const collapse = (s) => String(s || "").replace(/\s+/g, " ");
+
+/** Collapse whitespace runs, keeping a map from each kept char to its original index. */
+function collapseWithMap(text) {
+  let flat = "";
+  const map = [];
+  let pendingWs = -1;
+  for (let i = 0; i < text.length; i += 1) {
+    if (/\s/.test(text[i])) {
+      if (pendingWs === -1) pendingWs = i;
+      continue;
+    }
+    if (pendingWs !== -1 && flat) {
+      flat += " ";
+      map.push(pendingWs);
+    }
+    pendingWs = -1;
+    flat += text[i];
+    map.push(i);
+  }
+  return { flat, map };
+}
+
+/**
+ * Locate `ctx.quote` in `text`, using prefix/suffix to disambiguate repeats.
+ * Returns `{ start, end, exact }` or null when the quote is gone entirely.
+ */
+export function findQuote(text, ctx) {
+  const quote = ctx && ctx.quote;
+  if (!quote) return null;
+
+  const hits = occurrences(text, quote);
+  if (hits.length === 1) {
+    return { start: hits[0], end: hits[0] + quote.length, exact: true };
+  }
+  if (hits.length > 1) {
+    const { at, score } = bestHit(text, hits, quote, ctx.prefix || "", ctx.suffix || "");
+    return { start: at, end: at + quote.length, exact: score > 0 };
+  }
+
+  // Reformatting (a prettier run, an agent rewrite) reflows whitespace without
+  // changing any words. Match again on whitespace-collapsed text and map the
+  // hit back to real offsets, so those comments survive instead of orphaning.
+  const { flat, map } = collapseWithMap(text);
+  const flatQuote = collapse(quote).trim();
+  if (!flatQuote || !map.length) return null;
+  const flatHits = occurrences(flat, flatQuote);
+  if (!flatHits.length) return null;
+  const { at } = bestHit(flat, flatHits, flatQuote, collapse(ctx.prefix || ""), collapse(ctx.suffix || ""));
+  return { start: map[at], end: map[at + flatQuote.length - 1] + 1, exact: false };
+}
+
+/** Collapse runs of whitespace for display in a comment card. */
+export function tidy(text, limit = 0) {
+  const flat = String(text == null ? "" : text)
+    .replace(/\s+/g, " ")
+    .trim();
+  if (!limit || flat.length <= limit) return flat;
+  return `${flat.slice(0, limit - 1).trimEnd()}…`;
+}