@erdemtuna/doc-review 0.8.0 → 0.9.0

package/README.md

@@ -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,7 +65,7 @@ Review a page running on localhost:
 /doc-review (localhost URL)
 ```
 
-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.
+Doc Review opens in **Review**, with **View** selected, so you can read, use page controls, and comment. Switch to **Edit** to change content directly. Plain HTML saves edits to the file; scripted HTML, Markdown, and localhost pages send edits to your agent. 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.
 
@@ -59,23 +73,42 @@ Select text, or hover or focus an element, then use the nearby comment icon. `Ct
 
 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
-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.
+### Files and page interactions
+
+Self-contained HTML runs its inline scripts and event handlers automatically.
+There is no approval switch or renewed approval after an agent updates the file.
+Plain HTML, including ordinary JSON data blocks and escaped code examples, keeps
+direct autosave and Revert. Scripted HTML is **feedback-only**: your edits are sent
+to the agent to apply to the original source, rather than writing script-generated
+DOM into the file. The renderer re-evaluates that distinction when the source changes.
+Markdown and localhost also remain feedback-only.
+
+If a scripted page is broken, **More > Reload without scripts** provides a
+temporary recovery mode. **Use page interactions** restores automatic behavior.
+That preference belongs to this page in this review session, not to a saved
+approval record. Disabling scripts does not make a scripted file's preview
+edits writable. A changed preference takes effect when the frame is replaced;
+reload handling preserves comment drafts and reports genuine source conflicts.
+
+The supported interactive-file mode is for self-contained documents. Separate
+script files, application imports, workers, and embedded applications are not
+made compatible by this change. Use the existing localhost review route for
+application workflows. Dependency limitations appear in contextual details,
+not as a permission task or text inserted into the authored document.
+
+Files retain an opaque iframe origin. The parent owns API authentication and
+checks the frame identity for messages and writes. Authored code shares the
+document with the SDK, so frame correlation is not proof of human authorship.
+Relative assets stay scoped to the reviewed file. Localhost reviews retain their
+existing nonopaque artifact origin, popup, and download behavior; they are fetched
+and rewritten by the review server, not guaranteed to reproduce the application's
+original cookies, storage, or origin-sensitive requests.
+
+**Compatibility:** the old per-version `/trust` API is retired and returns 410.
+Existing decision files are left unused. The CLI does not reuse background
+servers with the previous protocol. Writable HTML save and revert requests must
+identify their current served frame and source hash so delayed edits cannot
+overwrite a newer file.
 
 Agent polling returns an immutable `batch_id`. After applying the batch, the
 agent acknowledges that exact receipt and keeps waiting:
@@ -87,6 +120,109 @@ 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`.
 
+### Review and Changes
+
+**Review** keeps the document interactive. **Changes** shows a selected review
+round, with round selection and comparison navigation instead of live-page controls.
+The default comparison is the content captured when feedback was sent against
+the result captured after the agent acknowledged that exact batch. Previous
+rounds retain their own fixed endpoints rather than changing on every reload.
+
+Content comparisons use a continuous aligned before/after reading surface with
+expandable unchanged context. Source comparisons use line-numbered source hunks.
+At narrow widths, a unified view retains each change's before/after attribution.
+Content comparisons cover text, structure, formatting, links, and image
+references. File-backed reviews also retain source for a source comparison.
+Deleted passages remain readable even when there is no current element to jump
+to, and uncertain matches do not pretend to identify an exact current target.
+These are changes observed during a round, not proof of agent authorship or that
+every comment was resolved.
+
+History works in the normal browser for HTML, Markdown, and localhost pages.
+It does not use screenshots, a browser extension, or automatic Git commits.
+Live history captures the reviewed page's available content, not every possible
+application state. Changes to image bytes at an unchanged URL, canvas pixels,
+external stylesheet appearance, and inaccessible embedded content are outside
+the comparison guarantee.
+
+Send waits for edit persistence and writable HTML saves, then makes a short
+best-effort baseline capture. Missing comparison data does not require a second
+decision or prevent feedback from being sent. Available snapshots are retained;
+inactive pages can have incomplete Content coverage. A last-visited live page is
+never described as a fresh Send-time snapshot. Actual save or delivery failures
+are reported without discarding your feedback.
+
+When an active tab has reliable authored tab/panel identifiers, Content capture
+records that visible view. A result on a different tab remains pending and asks
+you to return to the original tab. Returning retries capture without clicking
+through other tabs automatically. Unknown views and older snapshots are labelled
+as visible-content comparisons whose matching view is unverified. This does not
+capture all hidden panels or every application state. File Source comparison
+still covers the whole file independently.
+
+After acknowledgement, file-source results are captured independently of the
+browser. Content results are captured when the appropriate reviewed page is
+ready. These observations can have different timestamps; neither timestamp
+claims that the document was captured at the instant of acknowledgement.
+Background capture does not disable document interaction and retries transient
+failures a bounded number of times. An unchanged file does not need a new reload
+solely to capture an acknowledged result. Available Source remains readable
+while Content is pending. Contextual retry or return-to-view actions handle
+remaining failures; a continuously changing page may still have no stable Content
+snapshot. Permanent finalization is optional in capture details, not a prerequisite
+for reading the comparison. Failed or limited captures are not reported as zero
+changes, and handled feedback remains archived even when history is unavailable.
+
+Snapshots stay in the local Doc Review state directory. The latest five
+completed rounds are retained automatically, while active rounds, pending
+captures, and unsent feedback protect their referenced revisions. History starts
+with this capability; earlier documents cannot be reconstructed from old
+feedback receipts. Review snapshots can contain document content, so treat the
+state directory as private.
+Unreferenced snapshot files are collected at startup and during periodic
+maintenance, with a one-hour grace period protecting interrupted publications.
+Capture and comparison limits fail explicitly rather than publishing truncated
+content as a complete comparison.
+
+Default capture limits are 8 MiB of file source and 4 MiB of normalized content,
+with at most 2,000 semantic blocks and 1,000,000 text characters. A single block
+is limited to 100,000 characters. Comparisons have independent size, token, and
+edit-work limits, including a 1,000,000-character budget and a 250 ms processing
+budget. A stored snapshot can therefore exceed comparison limits; the UI reports
+that limitation rather than claiming there were no changes.
+
+### 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 an HTML or 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 servers using protocol 14 or earlier
+
+The updated CLI requires server protocol 15. 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).
@@ -113,7 +249,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.
+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 leave the active feedback inventory; their round archive remains, and newer comments and corrections stay active.
 
 ## Upstream project
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@erdemtuna/doc-review",
-  "version": "0.8.0",
+  "version": "0.9.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",
@@ -53,6 +53,8 @@
     "lucide-static": "^1.34.0"
   },
   "dependencies": {
-    "marked": "^18.0.7"
+    "diff": "^9.0.0",
+    "marked": "^18.0.7",
+    "parse5": "^8.0.1"
   }
 }

package/src/SKILL.md

@@ -1,14 +1,36 @@
 ---
 name: doc-review
-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.
+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. It starts in View,
-where normal page controls work. They can switch to Edit, comment explicitly in either mode,
+## 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.
+Native page controls work; supported self-contained HTML scripts run automatically.
+They can switch to Edit, comment explicitly in either mode,
 and send the whole batch at once.
 
+Plain HTML retains direct autosave. Scripted HTML edits are feedback-only:
+apply them to the original source, never serialize the script-modified runtime
+page over the file. Source changes do not require renewed approval.
+Reload without scripts is a temporary recovery option, not permission to write
+a scripted preview over its source. Reloads can wait for unresolved editing work.
+Applications requiring external script dependencies should use localhost review;
+automatic inline execution does not add support for application imports or workers.
+
 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.
@@ -36,7 +58,8 @@ 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
@@ -56,6 +79,12 @@ carried; newer comments and corrections survive.
    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
@@ -76,6 +105,17 @@ carried; newer comments and corrections survive.
    The response's `next_step` contains the complete acknowledgement command.
    Never acknowledge a different or guessed ID.
 
+   Acknowledgement means that you handled the feedback; it is separate from
+   browser result-capture readiness. Do not wait for history capture before
+   acknowledging completed work, and do not acknowledge merely because a page
+   looks stable. The browser captures round results automatically when possible.
+   Missing comparison data does not prevent the user from sending feedback.
+   Captured differences are observations, not proof that you alone authored them.
+   Content results may wait for the same identifiable tab as the baseline.
+   The user sees a return-to-tab prompt; do not automate tab clicking to force
+   capture. Source comparison remains independent. Unknown view identity is
+   labelled unverified, not asserted as a whole-application comparison.
+
 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?
@@ -119,8 +159,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
@@ -148,8 +193,12 @@ One batch covers every page the user visited, grouped by file or localhost URL.
 - 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.
+- **Do not write a reply.** There is no chat. The user sees the updated page and
+  can choose Changes for a fixed Send-to-result comparison. Reload may wait
+  for the user to handle unsaved review work. Live result capture may require
+  a contextual retry; never describe unavailable history as no changes.
+- Review history uses local content/source snapshots, not screenshots or Git
+  commits. Do not create commits or alter repository state to populate history.
 
 ## Better edit labels (optional)
 

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();