@erdemtuna/doc-review 0.7.0 → 0.8.0

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)
 
@@ -51,9 +51,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.
 
-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.
+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.
+
+**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
@@ -89,8 +95,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 +113,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.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",
@@ -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,17 +1,39 @@
 ---
 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 in a View-first browser review so the user can optionally edit, leave contextual comments, and send all feedback 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.
+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.
@@ -139,5 +161,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()}`;
+}