@erdemtuna/doc-review 0.9.0 → 0.10.0

package/README.md

@@ -1,260 +1,85 @@
 # Doc Review
 
-Review HTML, Markdown, and localhost pages, edit when you choose, leave contextual comments, and send all feedback to your AI agent at once.
+**Review your coding agent's work in the browser, not in a wall of chat.**
 
-[Read the original Human Review launch post](https://creatoreconomy.so/p/use-my-human-review-skill-to-edit-html-markdown-visually)
+Open an HTML file, a Markdown document, or a localhost page. Point to what needs
+changing, edit the small things yourself, and send your feedback to the agent
+in one batch.
 
-https://github.com/user-attachments/assets/7cab09c9-eaa0-4e8b-984d-2925e810b5c2
+![A landing page in Doc Review with highlighted text and a comment asking for more specific wording](https://raw.githubusercontent.com/erdemtuna/doc-review/main/assets/doc-review.png)
 
-## Problem
+*Feedback stays beside the work. Your agent gets the comments, edits, and overall note together.*
 
-Giving AI feedback on files in chat is painful.
+## Get started
 
-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`:
+Requires **Node.js 24.21.0 or newer** and a coding agent that can run shell commands.
+Install the skill once:
 
 ```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
-
-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:
+Start a fresh agent session, then ask it to open a review:
 
 ```text
-/doc-review (your file)
+/doc-review path/to/landing-page.html
 ```
 
-Review a page running on localhost:
+The same command works with Markdown or a running local app:
 
 ```text
-/doc-review (localhost URL)
-```
-
-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.
-
-**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.
-
-### 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:
-
-```sh
-npx -y @erdemtuna/doc-review poll path/to/file.html --ack b_0123456789abcdef --timeout 600
+/doc-review path/to/plan.md
+/doc-review http://localhost:3000
 ```
 
-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.
+Reviews start only when you request them. Your agent uses the installed skill
+to open the page, wait for feedback, and apply the changes.
 
-### Upgrading from servers using protocol 14 or earlier
+## From feedback to the next version
 
-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.
+1. **Open and explore.** Reviews start in **View**, so you can read and use page
+   controls without accidentally editing.
+2. **Point out what matters.** Select text or choose an element to leave a
+   comment. Switch to **Edit** for direct changes to wording, formatting, images,
+   or layout. Commenting works in either mode.
+3. **Send one batch.** Open **Comments**, add an overall note if needed, and
+   choose **Send to agent**. No need to describe where every sentence lives.
+4. **Check the result.** Use **Changes** to compare a review round's captured
+   before and after content, then continue reviewing. Comparisons show observed
+   changes, not a guarantee that every request was resolved.
 
-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.
+You can review a plan, refine a landing page, or walk through a local app without
+moving your feedback into a separate document.
 
-## What this skill lets you do
+## What happens to your edits?
 
-- **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** 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.
+| What you open | Where edits go |
+| --- | --- |
+| Plain HTML | Saved directly to the file, with Revert available |
+| Scripted HTML or Markdown | Sent to the agent to apply to the original source |
+| Localhost page | Sent to the agent to update the app's source |
 
-Doc Review works well for editing AI-generated plans, updating landing pages, reviewing localhost apps, and removing extra copy from a UX.
+Self contained HTML can run inline scripts. For an app with separate script
+dependencies, use its localhost URL instead.
 
-## What’s inside
+Doc Review runs locally and needs no Doc Review account, hosted backend, or API
+key. The page you review and the coding agent you use may still contact external
+services.
 
-- [`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.
+## Learn more
 
-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 leave the active feedback inventory; their round archive remains, and newer comments and corrections stay active.
+[Usage guide](https://github.com/erdemtuna/doc-review/blob/main/docs/usage.md):
+setup options, comments, comparisons, limitations, and upgrades.
 
-## Upstream project
+[Development](https://github.com/erdemtuna/doc-review/blob/main/docs/development.md):
+build, test, architecture, and package checks.
 
-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.
+[Releasing](https://github.com/erdemtuna/doc-review/blob/main/RELEASING.md):
+the maintainers' release process.
 
-## License
+## Credits and license
 
-MIT
+Doc Review is an independent fork of Peter Yang's
+[Human Review](https://github.com/petergyang/human-review), continuing from
+upstream v0.6.1. Licensed under
+[MIT](https://github.com/erdemtuna/doc-review/blob/main/LICENSE).

package/lib/anchor-text.js

@@ -0,0 +1,155 @@
+/**
+ * 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()}…`;
+}
+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/lib/atomic-write.js

@@ -0,0 +1,54 @@
+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();

package/lib/chrome-api.js

@@ -0,0 +1,78 @@
+export class ApiError extends Error {
+    status;
+    code;
+    targets;
+    constructor(message, status, code, targets) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.targets = targets;
+        this.name = "ApiError";
+    }
+}
+export function record(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("The review server returned an invalid response.");
+    }
+    return value;
+}
+export function createReviewApi({ token, fetch: request = globalThis.fetch, }) {
+    const pending = new Set();
+    let disposed = false;
+    async function send(path, options = {}) {
+        if (disposed)
+            throw new Error("The review connection is closed.");
+        const controller = new AbortController();
+        const abort = () => controller.abort(options.signal?.reason);
+        if (options.signal?.aborted)
+            abort();
+        else
+            options.signal?.addEventListener("abort", abort, { once: true });
+        pending.add(controller);
+        try {
+            const headers = new Headers(options.headers);
+            if (!headers.has("content-type"))
+                headers.set("content-type", "application/json");
+            headers.set("x-doc-review-token", token);
+            const response = await request(path, { ...options, headers, signal: controller.signal });
+            if (!response.ok) {
+                let detail = {};
+                try {
+                    detail = record(await response.json());
+                }
+                catch (error) {
+                    if (controller.signal.aborted)
+                        throw error;
+                    // Preserve the HTTP failure even when the error body is not JSON.
+                }
+                throw new ApiError(typeof detail.error === "string" ? detail.error : `Request failed (${response.status})`, response.status, typeof detail.code === "string" ? detail.code : undefined, Array.isArray(detail.targets) ? detail.targets : []);
+            }
+            return await response.json();
+        }
+        finally {
+            pending.delete(controller);
+            options.signal?.removeEventListener("abort", abort);
+        }
+    }
+    async function requestJson(path, options, decode) {
+        const value = await send(path, options);
+        return decode ? decode(value) : value;
+    }
+    return {
+        request: requestJson,
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            for (const controller of pending)
+                controller.abort(new Error("Review ended"));
+            pending.clear();
+        },
+    };
+}
+import { isPageResponse } from "./contracts/page.js";
+export function decodePage(value) {
+    if (!isPageResponse(value))
+        throw new Error("The review server returned an invalid page response.");
+    return value;
+}