@erdemtuna/doc-review 0.7.0 → 0.8.1

package/README.md

@@ -1,6 +1,6 @@
 # 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.
+Review HTML, Markdown, and localhost pages, edit when you choose, leave contextual comments, and send all 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)
 
@@ -37,6 +37,20 @@ no longer need them.
 
 ## How to use /doc-review
 
+Review is opt-in: explicitly invoke `/doc-review` or ask to open an interactive
+browser review. Writing, updating, or asking for a general review of content does
+not automatically open the browser or start polling. An explicitly started review
+continues until you end it or switch tasks.
+
+After updating installed skill instructions, start a fresh agent session or reload
+skills (in Copilot CLI, `/skills reload`). Setup copies the executing package's
+skill template; rerunning setup from an older package can restore older behavior.
+Setup updates its own `AGENTS.md` guidance inside `<!-- BEGIN doc-review -->` and
+`<!-- END doc-review -->` markers. Exact, known older generated blocks are migrated.
+Custom guidance is preserved with a migration message rather than overwritten;
+update it yourself if it requests automatic review. Invalid or duplicate markers
+must be corrected before setup can proceed.
+
 ![Doc Review visual editor](assets/doc-review.png)
 
 Open an HTML or Markdown file:
@@ -51,9 +65,15 @@ Review a page running on localhost:
 /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.
+Doc Review opens in **View** (`Editing off, comments enabled`) so links, buttons, summaries, tabs, and application controls work normally. The centered mode selector switches to **Edit** (`Direct editing on`) when you want to change content directly. Commenting stays available in both modes.
+
+Select text, or hover or focus an element, then use the nearby comment icon. `Ctrl+Alt+M` (`Cmd+Option+M` on macOS) opens a comment for the current selection. Press Enter to submit or Shift+Enter for a new line. On desktop the composer stays beside its target, or pins to the effective top or bottom scrolling edge when that target leaves view. **Back to selection** reveals the target without changing the draft. The full-width sheet is used only at the narrow responsive breakpoint.
 
-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.
+**Comments** is the single toolbar entry point for the closed-by-default review drawer. Its feedback inventory scrolls independently while the overall note and **Send to agent** controls remain fixed. Submitting a comment creates its normal highlight and increments the count, but keeps the card closed until you activate its mark or choose **Jump to**. Focus returns to the exact element or selection you reviewed.
+
+Aligned cards show **Edit**, **Close**, and **More**; drawer cards show **Jump to**, **Edit**, and **More**. Delete lives only in **More** and requires an inline confirmation. Quote hints preserve both the beginning and ending of long selections. Editing has explicit **Save** and **Cancel** controls: Enter saves, Shift+Enter adds a line, Escape cancels, and moving focus never autosaves. A draft follows its comment between aligned and drawer cards and keeps its caret through target movement.
+
+For writable HTML files, Edit saves direct changes automatically. Markdown and localhost remain editable feedback-only surfaces: their rendered HTML is never written over the source, so click Send and let the agent apply those edits.
 
 File and rendered Markdown reviews run with authored scripts and inline handlers
 blocked, an opaque iframe origin, and no popup or download permission. Their
@@ -81,6 +101,38 @@ npx -y @erdemtuna/doc-review poll path/to/file.html --ack b_0123456789abcdef --t
 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`.
 
+### Feedback reliability and limits
+
+`poll` without `--timeout` waits for at most 12 hours. Explicit timeouts include
+server discovery, reconnection, and retry backoff, not just time spent connected.
+Recoverable connection drops are retried; invalid responses, authorization errors,
+and incompatible servers fail visibly. A timeout does not discard feedback: use
+`status` to check it, then start another poll if the review is still wanted.
+
+Each edit text or HTML field is limited to 200,000 Unicode code points. Oversized
+edits carry `truncated: true` and `truncated_fields` naming incomplete fields.
+The agent must not use partial text or HTML as a complete replacement or invent
+the rest. It must obtain the full edit from an authoritative source or ask you
+for it before acknowledging the batch.
+
+External writes to a Markdown source refresh its rendered baseline without
+clearing unsent feedback. That preserves your edits; it does not automatically
+resolve conflicts with the changed source. HTML autosaves keep their existing
+behavior.
+
+### Upgrading from v0.8.0
+
+The updated CLI requires server protocol 13. An older server that is still
+running is not silently reused or forcibly replaced. End active reviews and
+shut down that specific old server (or let it exit when idle) before restarting
+Doc Review. Keep the `.doc-review` state directory: pending batches and their
+exact receipt IDs survive a controlled restart.
+
+After installing the updated package, rerun `doc-review setup --global` for
+personal skills and `doc-review setup` in projects with generated guidance.
+Reload skills or start a fresh agent session afterward. A newer CLI paired with
+older instructions is not a complete upgrade.
+
 ## What this skill lets you do
 
 - **Edit text directly and tweak basic formatting** (e.g., bold, italic).
@@ -89,8 +141,8 @@ complete acknowledgement command is included in each response's `next_step`.
 - **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.
+- **Select a phrase and leave a comment** from the contextual icon, or press Ctrl+Alt+M / Cmd+Option+M.
+- **Comment on an image, chart, control, or section** from its hover or keyboard-focus affordance without taking over its normal click.
 - **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.
@@ -107,6 +159,7 @@ Doc Review works well for editing AI-generated plans, updating landing pages, re
 - [`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.
+Comment geometry remains local, transient presentation data and is never written to review state or sent to the agent. After the agent acknowledges the exact delivered `batch_id`, the comments carried by that batch disappear; newer comments and corrections remain.
 
 ## Upstream project
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@erdemtuna/doc-review",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "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",
@@ -49,7 +49,8 @@
   },
   "devDependencies": {
     "@playwright/test": "^1.62.1",
-    "jsdom": "^29.1.1"
+    "jsdom": "^29.1.1",
+    "lucide-static": "^1.34.0"
   },
   "dependencies": {
     "marked": "^18.0.7"

package/src/SKILL.md

@@ -1,20 +1,56 @@
 ---
 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.
+description: Open an HTML file, Markdown file, or localhost page for View-first interactive browser feedback. Use only when the user explicitly invokes /doc-review or requests an interactive browser review. Do not invoke merely because you write, update, discuss, or review a document or web page.
 ---
 
 # 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.
+## Activation
+
+Start only when the user explicitly invokes `/doc-review` or asks to open an
+interactive browser review. A generic request to review, proofread, analyze, write,
+or update content is not permission to open this workflow. Another skill's
+automatic review step is not user permission.
+
+Without that request, respond normally without opening a review or polling for
+feedback. Once the user starts a review, continue its feedback loop until they
+end it; stop if they cancel or switch to a different task.
+
+## Review behavior
+
+The user reviews your HTML, Markdown, or localhost page in a real browser. It starts in View,
+where normal page controls work. They can switch to Edit, comment explicitly in either mode,
+and send 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.
 
+Comments open from a contextual icon after a text selection or an element hover/focus.
+The keyboard shortcut is Ctrl+Alt+M, or Cmd+Option+M on macOS. Enter submits the
+comment and Shift+Enter adds a new line. On desktop the composer stays attached
+to its target or pins to the effective top or bottom clipping edge; Back to
+selection reveals an offscreen target without changing the draft.
+
+Comments is the single toolbar entry point. The drawer inventory scrolls
+independently while the overall note and Send to agent controls remain fixed.
+Submitting creates the normal target mark and count but leaves the card closed
+until the user explicitly activates the mark or chooses Jump to. Focus returns
+to the reviewed element or selection. Aligned cards expose Edit, Close, and
+More; drawer cards expose Jump to, Edit, and More. Delete is available only
+through More and an inline confirmation. Long quote hints preserve both ends.
+
+Existing-comment editing uses explicit Save and Cancel controls and never saves
+on blur. Enter saves, Shift+Enter inserts a line, and Escape cancels. The draft,
+focus, and caret follow the comment between aligned and drawer cards and survive
+target movement. Closing an aligned card only hides its active presentation.
+Acknowledging the exact delivered batch removes only the comments that batch
+carried; newer comments and corrections survive.
+
 ## The loop
 
-1. Write or update the HTML or Markdown file, or start the local page being reviewed.
+1. After the explicit review request, use the requested file or localhost route.
+   Create or update content, or start a local page, only as needed for that request.
 2. Open it for the user:
 
    ```sh
@@ -34,6 +70,12 @@ keeping its formatting syntax.
    npx -y @erdemtuna/doc-review poll path/to/file.html --timeout 600
    ```
 
+   Without `--timeout`, the CLI stops after 12 hours. An explicit timeout covers
+   the entire operation, including server discovery, reconnects, and backoff.
+   Recoverable connection drops retry within that deadline; terminal errors
+   require action rather than another automatic poll. The 600-second command
+   above deliberately uses a shorter deadline.
+
    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
@@ -97,8 +139,13 @@ One batch covers every page the user visited, grouped by file or localhost URL.
 
 ## Rules
 
+- Edits marked **`truncated`** contain incomplete fields listed in
+  `truncated_fields`. Each text/HTML field is limited to 200,000 Unicode code
+  points. Never apply a truncated field as a complete replacement or guess the
+  missing content. Obtain the complete edit from an authoritative source, or ask
+  the user for it. Do not acknowledge the batch until all feedback is handled.
 - **`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
+  unless marked truncated, 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
@@ -139,5 +186,5 @@ guessing from the DOM:
 <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.
+`data-block` names a region for the edit list. `data-container` also gives the block a
+stable label for its hover/focus comment affordance.

package/src/anchor-text.js

@@ -113,3 +113,48 @@ export function tidy(text, limit = 0) {
   if (!limit || flat.length <= limit) return flat;
   return `${flat.slice(0, limit - 1).trimEnd()}…`;
 }
+
+function graphemes(text) {
+  if (typeof Intl?.Segmenter === "function") {
+    const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+    return [...segmenter.segment(text)].map(({ segment }) => segment);
+  }
+  // Array.from is deterministic and, unlike string slicing, never splits a
+  // surrogate pair. Older engines may split a multi-code-point grapheme.
+  return Array.from(text);
+}
+
+function nearbyHeadBoundary(parts, ideal) {
+  for (let index = ideal; index >= Math.max(1, ideal - 8); index -= 1) {
+    if (/^\s$/u.test(parts[index - 1])) return index - 1;
+  }
+  return ideal;
+}
+
+function nearbyTailBoundary(parts, ideal) {
+  for (let index = ideal; index < Math.min(parts.length - 1, ideal + 8); index += 1) {
+    if (/^\s$/u.test(parts[index])) return index + 1;
+  }
+  return ideal;
+}
+
+/**
+ * Collapse whitespace and preserve both ends of a long quote. `limit` counts
+ * grapheme clusters, including the ellipsis.
+ */
+export function tidyMiddle(text, limit = 0) {
+  const flat = String(text == null ? "" : text)
+    .replace(/\s+/g, " ")
+    .trim();
+  if (!limit) return flat;
+  const parts = graphemes(flat);
+  if (parts.length <= limit) return flat;
+  if (limit <= 1) return "…";
+
+  const available = limit - 1;
+  const idealHead = Math.ceil(available * 0.6);
+  const idealTailStart = parts.length - (available - idealHead);
+  const headEnd = nearbyHeadBoundary(parts, idealHead);
+  const tailStart = nearbyTailBoundary(parts, idealTailStart);
+  return `${parts.slice(0, headEnd).join("").trimEnd()}…${parts.slice(tailStart).join("").trimStart()}`;
+}

package/src/atomic-write.js

@@ -0,0 +1,53 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+
+const RETRY_DELAYS_MS = [10, 20, 40, 80, 160];
+const TRANSIENT_RENAME_ERRORS = new Set(["EPERM", "EACCES", "EBUSY"]);
+const waitState = new Int32Array(new SharedArrayBuffer(4));
+
+// Keep Store transactions synchronous; rename backoff blocks for at most 310ms.
+const sleepSync = (ms) => Atomics.wait(waitState, 0, 0, ms);
+
+export function createAtomicWriter({ fileSystem = fs, sleep = sleepSync, report = console.error } = {}) {
+  return function atomicWrite(file, data) {
+    const tmp = `${file}.${process.pid}.${crypto.randomBytes(6).toString("hex")}.doc-review.tmp`;
+    let fd;
+    let created = false;
+    try {
+      fd = fileSystem.openSync(tmp, "wx");
+      created = true;
+      fileSystem.writeFileSync(fd, data);
+      fileSystem.closeSync(fd);
+      fd = undefined;
+      for (let attempt = 0; ; attempt += 1) {
+        try {
+          fileSystem.renameSync(tmp, file);
+          return;
+        } catch (err) {
+          if (!TRANSIENT_RENAME_ERRORS.has(err.code) || attempt === RETRY_DELAYS_MS.length) throw err;
+          sleep(RETRY_DELAYS_MS[attempt]);
+        }
+      }
+    } catch (err) {
+      if (fd !== undefined) {
+        try {
+          fileSystem.closeSync(fd);
+        } catch (cleanupError) {
+          report(`Could not close atomic-write temporary file ${tmp}: ${cleanupError.message}`);
+        }
+      }
+      if (created) {
+        try {
+          fileSystem.unlinkSync(tmp);
+        } catch (cleanupError) {
+          if (cleanupError.code !== "ENOENT") {
+            report(`Could not remove atomic-write temporary file ${tmp}: ${cleanupError.message}`);
+          }
+        }
+      }
+      throw err;
+    }
+  };
+}
+
+export const atomicWrite = createAtomicWriter();