@erdemtuna/doc-review 0.10.0 → 0.11.1

package/README.md

@@ -6,7 +6,7 @@ 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.
 
-![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)
+![The Field Notes landing page in Review, with highlighted copy and an anchored comment asking for a concrete benefit](https://raw.githubusercontent.com/erdemtuna/doc-review/main/assets/doc-review.png)
 
 *Feedback stays beside the work. Your agent gets the comments, edits, and overall note together.*
 
@@ -42,7 +42,7 @@ to open the page, wait for feedback, and apply the changes.
 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
+3. **Send one batch.** Open **Feedback**, inspect Comments and Edits, 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
@@ -51,6 +51,14 @@ to open the page, wait for feedback, and apply the changes.
 You can review a plan, refine a landing page, or walk through a local app without
 moving your feedback into a separate document.
 
+![The Feedback panel with separate Comments and Edits sections, an overall note, and End review beside Send to agent](https://raw.githubusercontent.com/erdemtuna/doc-review/main/assets/doc-review-feedback.png)
+
+*One batch, with the context attached: comments, your edits, and the overall direction.*
+
+![The completed Field Notes review round in Changes, comparing the revised description and call to action with their originals](https://raw.githubusercontent.com/erdemtuna/doc-review/main/assets/doc-review-changes.png)
+
+*Check the result beside the original. Move between changes or switch to Source for the saved file text.*
+
 ## What happens to your edits?
 
 | What you open | Where edits go |
@@ -74,6 +82,9 @@ setup options, comments, comparisons, limitations, and upgrades.
 [Development](https://github.com/erdemtuna/doc-review/blob/main/docs/development.md):
 build, test, architecture, and package checks.
 
+[Prepared review example](docs/migration-review.md):
+disposable HTML/Markdown sessions with saved comparison rounds and a shell review checklist.
+
 [Releasing](https://github.com/erdemtuna/doc-review/blob/main/RELEASING.md):
 the maintainers' release process.
 

package/lib/SKILL.md

@@ -41,8 +41,11 @@ 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.
+Feedback is the single toolbar entry point for Comments, Edits, and the overall
+note. Comments and Edits collapse independently; their choices last until the
+tab reloads. An active comment edit keeps Comments expanded until Save or Cancel.
+The inventory scrolls independently while the overall note and bottom actions
+remain reachable. End review is on the left and Send to agent on the right.
 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

package/lib/changes-controller.js

@@ -0,0 +1,184 @@
+import { createControllerStore } from "./controller-store.js";
+import { historyPresentation } from "./history-coordinator.js";
+import { changeKind, comparisonFreshness, excerpt } from "./history-client.js";
+import { tidyMiddle } from "./anchor-text.js";
+const roundId = (round) => round?.id || round?.roundId || "";
+const timestamp = (value) => value == null ? NaN : new Date(value).getTime();
+const formatTime = (value) => {
+    const time = timestamp(value);
+    return Number.isFinite(time) ? new Date(time).toLocaleString() : "Not available";
+};
+/** Pure normalization: reading or rendering never edits the authoritative history. */
+export function changesSelection(history) {
+    const round = history.round && roundId(history.round) === history.selectedId ? history.round : null;
+    const targets = round?.targets || [];
+    const target = targets.find((item) => item.key === history.targetKey) || targets[0] || null;
+    const comparison = target?.comparison || {};
+    const modes = ["content", "source"].filter((mode) => comparison[mode]?.available === true);
+    const mode = modes.find((item) => item === history.preferredMode) || modes[0] || "content";
+    const value = comparison[mode] || {};
+    const items = value.changes || value.items || (mode === "content" ? comparison.changes || comparison.items : null) || [];
+    const index = Number.isSafeInteger(history.index) ? Math.max(0, Math.min(history.index, items.length - 1)) : 0;
+    return { round, target, targets, comparison, modes, mode, value, items, index, key: `${roundId(round)}:${target?.key || ""}` };
+}
+export function createChangesController(options) {
+    let disposed = false;
+    let diagnosticsOpen = false;
+    let limitationsOpen = false;
+    let pending = null;
+    let actionError = null;
+    let scrollSequence = 0;
+    let scrollRequest = null;
+    const getDetail = () => changesSelection(options.read().history);
+    let detailValue = getDetail().comparison[getDetail().mode] || null;
+    let detailVersion = 0;
+    function read() {
+        const context = options.read();
+        const history = context.history;
+        const selection = changesSelection(history);
+        const { round, target, comparison, modes, mode, value, items, index, key } = selection;
+        const failure = history.failures.get(key);
+        const presentation = historyPresentation({ ...history, round, target, comparison, failure });
+        const captureBusy = history.captureBusy || pending === "capture";
+        const finalizing = history.finalizing || pending === "finish";
+        const disabled = context.ended || !context.comparing;
+        const captureAllowed = !!target && !target.resultRevisionId && target.capture?.status !== "unavailable" &&
+            round?.feedbackStatus === "acknowledged";
+        const finishAllowed = !!target && !target.resultRevisionId && round?.feedbackStatus === "acknowledged" &&
+            ["pending", "failed"].includes(target.capture?.status || target.captureStatus || "pending");
+        const delay = timestamp(value.afterCapturedAt) - timestamp(round?.acknowledgedAt);
+        const view = mode === "content" ? value.viewComparison : null;
+        return {
+            disabled, loading: history.loading, key, mode, index, modes, detailVersion, scrollRequest, hasComparison: modes.length > 0,
+            rounds: history.rounds.map((item, position) => ({
+                value: roundId(item),
+                shortLabel: `Round ${item.ordinal || item.number || history.rounds.length - position}`,
+                label: `Round ${item.ordinal || item.number || history.rounds.length - position} · ${item.captureStatus === "ready" ? "completed" : item.captureStatus || item.status || item.feedbackStatus || "pending"}`,
+            })),
+            selectedId: history.selectedId || "",
+            targets: selection.targets.map((item) => ({ value: item.key, label: item.filename || item.label || item.key })),
+            targetKey: target?.key || "",
+            status: presentation.state,
+            message: history.loading ? round ? "Refreshing comparison…" : "Loading comparison…" : presentation.message,
+            error: actionError?.key === key ? actionError.message : history.error?.message || failure || target?.capture?.error || "",
+            canRetry: !!history.error && !history.loading,
+            counts: modes.length ? value.counts || null : null,
+            changes: items.map((item, position) => ({
+                value: String(position),
+                label: `${position + 1}. ${changeKind(item)} · ${tidyMiddle(item.label || excerpt(item.after) || excerpt(item.before) || "Structure", 65)}`,
+            })),
+            position: `${items.length ? index + 1 : 0} of ${items.length}`,
+            previousDisabled: disabled || history.loading || index === 0,
+            nextDisabled: disabled || history.loading || index >= items.length - 1,
+            captureAllowed, captureBusy,
+            captureDisabled: disabled || history.loading || context.sending || captureBusy || finalizing ||
+                target?.key !== context.current.key || !context.current.ready || context.current.pendingReload,
+            finishAllowed, finalizing,
+            finishDisabled: disabled || history.loading || context.sending || finalizing || captureBusy,
+            diagnosticsOpen, limitationsOpen,
+            unavailable: ["content", "source"].flatMap((item) => comparison[item]?.available === false
+                ? [`${item === "content" ? "Content" : "Source"} comparison unavailable: ${comparison[item]?.reason || "This representation could not be compared."}`] : []),
+            timing: round ? [
+                { label: "Before captured", value: formatTime(value.beforeCapturedAt) },
+                { label: "Agent acknowledged", value: formatTime(round.acknowledgedAt) },
+                { label: "After captured", value: formatTime(value.afterCapturedAt) },
+            ] : [],
+            delay: !Number.isFinite(delay) ? "" : delay >= 0
+                ? `Result captured ${Math.round(delay / 1000)} seconds after acknowledgment—not at the acknowledgment instant. A delayed capture can include later changes.`
+                : "This result snapshot predates acknowledgment. It is not proof of the page state at acknowledgment.",
+            freshness: target?.resultRevisionId || value.afterCapturedAt
+                ? comparisonFreshness(value, target?.key, context.current) : "",
+            view: view?.message ? view : null,
+            limitations: [...new Set([...(comparison.content?.limitations || []), ...(comparison.source?.limitations || [])])]
+                .map((item) => String(item).replaceAll("-", " ").replaceAll("_", " ")),
+        };
+    }
+    const store = createControllerStore(read);
+    const publish = () => {
+        if (disposed)
+            return;
+        const selection = getDetail();
+        const next = selection.comparison[selection.mode] || null;
+        if (detailValue !== next) {
+            detailValue = next;
+            detailVersion++;
+        }
+        store.publish();
+    };
+    const available = () => !disposed && !options.read().ended && options.read().comparing;
+    async function run(action, key) {
+        const current = read();
+        if (!available() || key !== current.key || pending ||
+            (action === "capture" ? !current.captureAllowed || current.captureDisabled : !current.finishAllowed || current.finishDisabled))
+            return;
+        pending = action;
+        actionError = null;
+        publish();
+        try {
+            await (action === "capture" ? options.capture() : options.finish());
+        }
+        catch (error) {
+            if (!disposed) {
+                const message = error instanceof Error ? error.message : String(error);
+                actionError = { key, message };
+                options.failed(message);
+            }
+        }
+        finally {
+            pending = null;
+            publish();
+        }
+    }
+    return {
+        getSnapshot: store.getSnapshot, subscribe: store.subscribe, publish, getDetail,
+        commands: {
+            selectRound(id) {
+                const history = options.read().history;
+                if (available() && history.selectedId !== id && history.rounds.some((round) => roundId(round) === id)) {
+                    actionError = null;
+                    scrollRequest = null;
+                    return options.selectRound(id);
+                }
+            },
+            selectTarget(key) {
+                const selection = getDetail();
+                if (available() && !options.read().history.loading && key !== selection.target?.key && selection.targets.some((target) => target.key === key)) {
+                    actionError = null;
+                    scrollRequest = null;
+                    return options.selectTarget(key);
+                }
+            },
+            selectMode(mode) {
+                const selection = getDetail();
+                if (available() && !options.read().history.loading && (mode === "content" || mode === "source") &&
+                    mode !== selection.mode && selection.modes.includes(mode)) {
+                    scrollRequest = null;
+                    options.selectMode(mode);
+                }
+            },
+            jump(index, key) {
+                const selection = getDetail();
+                if (!available() || options.read().history.loading || key !== selection.key ||
+                    !Number.isSafeInteger(index) || index < 0 || index >= selection.items.length)
+                    return;
+                scrollRequest = { sequence: ++scrollSequence, key, mode: selection.mode, index };
+                options.selectIndex(index);
+                publish();
+            },
+            capture: (key) => run("capture", key),
+            finish: (key) => run("finish", key),
+            retry() { if (available() && !options.read().history.loading)
+                return options.refresh(); },
+            disclose(name, open) {
+                if (!available())
+                    return;
+                if (name === "diagnostics")
+                    diagnosticsOpen = open;
+                else
+                    limitationsOpen = open;
+                publish();
+            },
+        },
+        dispose() { disposed = true; store.dispose(); },
+    };
+}