@erdemtuna/doc-review 0.8.1 → 0.10.0

package/lib/frame-host.js

@@ -0,0 +1,136 @@
+export function createFrameHost(initial, artifactOrigin) {
+    let current = initial;
+    let previous = null;
+    let disposed = false;
+    const loadListeners = new Set();
+    const focusListeners = new Set();
+    const detach = new Map();
+    const paintFrames = new Set();
+    function paint(callback) {
+        const id = requestAnimationFrame(() => {
+            paintFrames.delete(id);
+            if (!disposed)
+                callback();
+        });
+        paintFrames.add(id);
+    }
+    function attach(frame) {
+        const loaded = () => {
+            if (!disposed && frame === current)
+                for (const listener of loadListeners)
+                    listener();
+        };
+        const focused = () => {
+            if (!disposed && frame === current)
+                for (const listener of focusListeners)
+                    listener();
+        };
+        frame.addEventListener("load", loaded);
+        frame.addEventListener("focus", focused);
+        detach.set(frame, () => {
+            frame.removeEventListener("load", loaded);
+            frame.removeEventListener("focus", focused);
+            detach.delete(frame);
+        });
+    }
+    function remove(frame) {
+        detach.get(frame)?.();
+        frame.remove();
+    }
+    attach(initial);
+    return {
+        get current() { return current; },
+        get previous() { return previous; },
+        get visibleExecution() {
+            const visible = previous || current;
+            const savePolicy = visible.dataset.savePolicy;
+            const executionMode = visible.dataset.executionMode;
+            if ((savePolicy !== "writable" && savePolicy !== "feedback-only") ||
+                (executionMode !== "static" && executionMode !== "interactive" && executionMode !== "application"))
+                return null;
+            return {
+                executionMode,
+                savePolicy,
+                executionNotice: visible.dataset.executionNotice || null,
+            };
+        },
+        onLoad(listener) {
+            loadListeners.add(listener);
+            return () => { loadListeners.delete(listener); };
+        },
+        onFocus(listener) {
+            focusListeners.add(listener);
+            return () => { focusListeners.delete(listener); };
+        },
+        setPolicy(policy) { current.setAttribute("sandbox", policy.sandbox); },
+        navigate(path, replacing) {
+            if (disposed)
+                return;
+            const url = `${artifactOrigin}${path}`;
+            if (replacing && current.hasAttribute("src")) {
+                const next = current.cloneNode(false);
+                const Frame = current.ownerDocument.defaultView?.HTMLIFrameElement;
+                if (!Frame || !(next instanceof Frame))
+                    throw new Error("Invalid review iframe.");
+                next.src = url;
+                next.removeAttribute("data-sdk-ready");
+                delete next.dataset.executionMode;
+                delete next.dataset.savePolicy;
+                delete next.dataset.executionNotice;
+                if (previous)
+                    remove(current);
+                else {
+                    previous = current;
+                    previous.id = "previousFrame";
+                    previous.inert = true;
+                    previous.setAttribute("aria-hidden", "true");
+                    previous.tabIndex = -1;
+                }
+                current = next;
+                current.dataset.replacing = "true";
+                attach(current);
+                previous.after(current);
+            }
+            if (current.src !== url)
+                current.src = url;
+        },
+        finishReplacement() {
+            if (previous)
+                remove(previous);
+            previous = null;
+            delete current.dataset.replacing;
+        },
+        suspend() { current.removeAttribute("data-sdk-ready"); },
+        ready(execution) {
+            current.dataset.sdkReady = "true";
+            current.dataset.executionMode = execution.executionMode;
+            current.dataset.savePolicy = execution.savePolicy;
+            current.dataset.executionNotice = execution.executionNotice || "";
+        },
+        send(message, origin) {
+            current.contentWindow?.postMessage(message, origin);
+        },
+        acceptsSource(source) {
+            return !!current.contentWindow && source === current.contentWindow;
+        },
+        afterPaint(callback) {
+            const target = current;
+            paint(() => paint(() => {
+                if (!disposed && target === current)
+                    callback();
+            }));
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            for (const stop of [...detach.values()])
+                stop();
+            for (const id of paintFrames)
+                cancelAnimationFrame(id);
+            paintFrames.clear();
+            loadListeners.clear();
+            focusListeners.clear();
+        },
+    };
+}

package/lib/frame-policy.js

@@ -0,0 +1,50 @@
+const BASE_SANDBOX = "allow-scripts allow-forms allow-modals";
+const LOCALHOST_SANDBOX = `${BASE_SANDBOX} allow-popups allow-downloads allow-same-origin`;
+// Exact immutable review modules, not the artifact directory or whole origin.
+// Do not add strict-dynamic or a nonce: either would let authored code authorize
+// mutable external scripts. The capability in the SDK tag is correlation only.
+export const TRUSTED_SDK_MODULE_PATHS = Object.freeze([
+    "/sdk.js", "/anchor-text.js", "/click-target.js", "/comment-target.js",
+    "/editing.js", "/frame-channel.js", "/icons.js", "/review-mode.js",
+    "/semantic-snapshot.js", "/serialize.js", "/positioning.js",
+    "/revision-schema.js", "/view-identity.js",
+]);
+export function interactiveFileCsp(sdkOrigin) {
+    const origin = new URL(sdkOrigin);
+    if (!["http:", "https:"].includes(origin.protocol) || origin.username || origin.password ||
+        origin.pathname !== "/" || origin.search || origin.hash) {
+        throw new TypeError("The SDK origin must be an HTTP origin without a path or credentials.");
+    }
+    const modules = TRUSTED_SDK_MODULE_PATHS.map((route) => `${origin.origin}${route}`).join(" ");
+    return [
+        "default-src 'none'",
+        `script-src 'unsafe-inline' ${modules}`,
+        "script-src-attr 'unsafe-inline'",
+        "worker-src 'none'",
+        "child-src 'none'",
+        "frame-src 'none'",
+        "object-src 'none'",
+        "connect-src 'none'",
+        "base-uri 'none'",
+        "form-action 'none'",
+        "style-src 'unsafe-inline' http: https: data:",
+        "img-src http: https: data: blob:",
+        "font-src http: https: data:",
+        "media-src http: https: data: blob:",
+    ].join("; ");
+}
+export const trustedFileCsp = interactiveFileCsp;
+/**
+ * Localhost apps need their real origin so their routing and JavaScript work.
+ * Files and rendered Markdown do not: An opaque iframe origin prevents them
+ * from reading sibling files served by the artifact route.
+ */
+export function framePolicy(page, artifactOrigin) {
+    const keepsOrigin = page !== null && (typeof page === "object" || typeof page === "function") &&
+        "kind" in page && page.kind === "url";
+    return {
+        sandbox: keepsOrigin ? LOCALHOST_SANDBOX : BASE_SANDBOX,
+        incomingOrigin: keepsOrigin ? artifactOrigin : "null",
+        targetOrigin: keepsOrigin ? artifactOrigin : "*",
+    };
+}

package/lib/history-client.js

@@ -0,0 +1,112 @@
+/** A capture is valid only for the exact frame that answered the request. */
+export function sameRender(a, b) {
+    return !!a && !!b && a.key === b.key && a.renderId === b.renderId &&
+        a.generation === b.generation && !!a.renderId;
+}
+export function createCaptureRequests({ send, current, timeout = 6000 }) {
+    const pending = new Map();
+    let sequence = 0;
+    return {
+        request({ timeout: requestTimeout = timeout, signal } = {}) {
+            const identity = { ...current() };
+            if (signal?.aborted)
+                return Promise.reject(captureError("CAPTURE_CANCELLED", "Capture cancelled"));
+            if (!identity.renderId || identity.loading)
+                return Promise.reject(captureError("CAPTURE_NOT_READY", "The page is not ready to capture"));
+            const requestId = `capture-${++sequence}`;
+            return new Promise((resolve, reject) => {
+                const finish = (error, value) => {
+                    if (!pending.has(requestId))
+                        return;
+                    pending.delete(requestId);
+                    clearTimeout(timer);
+                    signal?.removeEventListener("abort", abort);
+                    if (error)
+                        reject(error);
+                    else
+                        resolve(value);
+                };
+                const abort = () => finish(captureError("CAPTURE_CANCELLED", "Capture cancelled"));
+                const timer = setTimeout(() => finish(captureError("CAPTURE_TIMEOUT", "The page did not confirm a stable capture. Recapture when it is ready.")), requestTimeout);
+                pending.set(requestId, { identity, finish });
+                signal?.addEventListener("abort", abort, { once: true });
+                try {
+                    send({ type: "eh:captureSnapshot", requestId, requireStable: true });
+                }
+                catch (error) {
+                    finish(error);
+                }
+            });
+        },
+        receive(message) {
+            const request = pending.get(message.requestId);
+            if (!request)
+                return false;
+            if (!sameRender(request.identity, current()))
+                request.finish(captureError("CAPTURE_CHANGED", "The page changed during capture. Recapture the latest version."));
+            else if (message.error || !message.snapshot)
+                request.finish(captureError(message.error?.code || "CAPTURE_UNAVAILABLE", message.error?.message || message.error || "Semantic capture is unavailable"));
+            else
+                request.finish(null, {
+                    ...request.identity, semantic: message.snapshot, sourceHash: message.sourceHash,
+                    semanticCapturedAt: Number.isFinite(message.capturedAt) ? message.capturedAt : undefined,
+                    view: message.view,
+                });
+            return true;
+        },
+        cancel(reason = "The page changed during capture") {
+            for (const request of pending.values()) {
+                request.finish(captureError("CAPTURE_CANCELLED", reason));
+            }
+            pending.clear();
+        },
+        get size() { return pending.size; },
+    };
+}
+export function captureError(code, message) {
+    return Object.assign(new Error(message), { code });
+}
+export function draftCount({ compose, commentUi }, note = "") {
+    return Number(!!compose) + Number(!!commentUi?.edit) + Number(!!note.trim());
+}
+export function excerpt(value) {
+    if (typeof value === "string")
+        return value;
+    if (!value)
+        return "";
+    return String(value.text ?? value.excerpt ?? value.content ?? value.label ?? "");
+}
+export function changeKind(item) {
+    const kind = String(item.kind || item.type || "").toLowerCase();
+    return kind === "added" || kind === "removed" ? kind : "modified";
+}
+export function pendingCaptureTarget(round, key, readyAt) {
+    if (round?.feedbackStatus !== "acknowledged" || !(readyAt > 0))
+        return null;
+    return round.targets?.find((target) => target.key === key && !target.resultRevisionId &&
+        ["pending", "failed"].includes(target.capture?.status || target.captureStatus || "pending")) || null;
+}
+export function defaultHistoryRound(rounds) {
+    return rounds.find((round) => round.completedAt || round.captureStatus === "ready" ||
+        ["complete", "completed"].includes(round.status)) || rounds[0] || null;
+}
+export function comparisonFreshness(comparison, targetKey, current) {
+    if (targetKey !== current.key)
+        return "Different page: this saved comparison does not describe the page open in Latest version.";
+    if (!current.ready || current.pendingReload || current.dirty)
+        return "Latest version is unverified: reload or finish saving before comparing it with this captured result.";
+    if (current.kind === "url") {
+        return comparison.capturedSessionId === current.sessionId && comparison.capturedGeneration === current.generation
+            ? "Same live render generation; the current DOM is not verified against the captured result. Live content may have changed."
+            : "Latest live render is different or unverified. This historical comparison cannot identify exact targets on the live page.";
+    }
+    if (!comparison.sourceHash || !current.sourceHash)
+        return "Latest source is unverified against this captured result.";
+    return comparison.sourceHash === current.sourceHash
+        ? "Latest file source matches the captured result. Runtime DOM changes are not verified by a source match."
+        : "Latest source is newer or different from the captured result. You are viewing a historical comparison.";
+}
+export function canJumpToCurrent(item, result, current) {
+    return item.confidence === "exact" && !!item.navigation?.selector && !item.unresolved && changeKind(item) !== "removed" &&
+        !!result?.renderId && sameRender(result, current);
+}

package/lib/history-coordinator.js

@@ -0,0 +1,210 @@
+import { defaultHistoryRound } from "./history-client.js";
+const idOf = (round) => round?.roundId || round?.id;
+const retryDelays = [1000, 2000, 4000];
+export function transientCaptureError(error) {
+    return ["CAPTURE_TIMEOUT", "CAPTURE_NOT_READY", "CAPTURE_UNSTABLE", "CAPTURE_BUSY", "VIEW_CHANGED"].includes(error?.code) ||
+        [408, 429, 502, 503, 504].includes(error?.status) ||
+        (error instanceof TypeError && /fetch|network|load failed/i.test(error.message));
+}
+export function requireCaptureSuccess(result, key) {
+    if (result?.ok === true)
+        return result;
+    throw Object.assign(new Error(result?.round?.targets?.find((target) => target.key === key)?.capture?.error ||
+        "Content capture is unavailable"), { code: "CAPTURE_UNAVAILABLE" });
+}
+/** One capture at a time; delayed/finished attempts never block other rounds. */
+export function createCaptureCoordinator({ candidates, ready, capture, now = Date.now, setTimer = setTimeout, clearTimer = clearTimeout }) {
+    const attempts = new Map();
+    let timer = null;
+    let active = null;
+    let epoch = 0;
+    let stopped = false;
+    function tick() {
+        clearTimer(timer);
+        timer = null;
+        if (stopped || active || !ready())
+            return;
+        const jobs = candidates();
+        const job = jobs.find(({ id }) => {
+            const attempt = attempts.get(id);
+            return !attempt || (!attempt.done && attempt.due <= now());
+        });
+        if (!job) {
+            const due = jobs.map(({ id }) => attempts.get(id)).filter((entry) => entry && !entry.done)
+                .reduce((next, entry) => Math.min(next, entry.due), Infinity);
+            if (Number.isFinite(due))
+                timer = setTimer(tick, Math.max(0, due - now()));
+            return;
+        }
+        const attempt = attempts.get(job.id) || { count: 0, due: 0, done: false };
+        attempts.set(job.id, attempt);
+        attempt.count++;
+        const controller = new AbortController();
+        const started = epoch;
+        active = controller;
+        Promise.resolve().then(() => {
+            if (controller.signal.aborted)
+                return;
+            return capture(job, controller.signal);
+        }).then(() => { attempt.done = true; }, (error) => {
+            if (transientCaptureError(error) && attempt.count <= retryDelays.length) {
+                attempt.due = now() + retryDelays[attempt.count - 1];
+            }
+            else
+                attempt.done = true;
+        }).finally(() => {
+            if (started !== epoch)
+                return;
+            active = null;
+            tick();
+        });
+    }
+    return {
+        tick,
+        reset() {
+            epoch++;
+            active?.abort();
+            active = null;
+            clearTimer(timer);
+            timer = null;
+            attempts.clear();
+        },
+        stop() {
+            this.reset();
+            stopped = true;
+        },
+        get busy() { return !!active; },
+    };
+}
+export function historyPresentation({ loading, error, round, target, comparison = {}, failure }) {
+    const modes = ["content", "source"].filter((mode) => comparison[mode]?.available === true);
+    if (loading && !round)
+        return { state: "loading", message: "Loading comparison…", modes };
+    if (error && !round)
+        return { state: "failed", message: "History could not be loaded. Try again.", modes };
+    if (!round)
+        return { state: "empty", message: "No review rounds yet. Send feedback to start.", modes };
+    if (modes.length) {
+        const partial = modes.length < 2 || !!target?.baselineUnavailable || !!target?.resultUnavailable;
+        return { state: partial ? "partial" : "available", modes,
+            message: modes.includes("content")
+                ? partial ? "Content available; some comparison coverage is missing." : "Comparison ready."
+                : "Source available. Content is pending or unavailable." };
+    }
+    if (failure || error || target?.capture?.status === "failed") {
+        return { state: "failed", message: "Content capture failed. Feedback is safe; retry when ready.", modes };
+    }
+    if (target?.capture?.status === "unavailable" || target?.resultRevisionId) {
+        return { state: "partial", message: "Comparison unavailable for these snapshots. Feedback is safe.", modes };
+    }
+    return { state: "waiting", message: round.feedbackStatus === "acknowledged"
+            ? "Waiting for a stable result snapshot. You can keep reviewing."
+            : "Waiting for the agent's result.", modes };
+}
+/** Fetch into local values, then publish atomically so selectors never relabel stale content. */
+export function createHistoryController({ request, changed = () => { }, refreshed = () => { } }) {
+    const state = {
+        rounds: [], selectedId: null, round: null, targetKey: null, mode: "content", preferredMode: null,
+        index: 0, loading: false, error: null, captureBusy: false, finalizing: false, failures: new Map(),
+    };
+    let revision = 0;
+    const targets = new Map();
+    async function refresh() {
+        const current = ++revision;
+        state.loading = true;
+        state.error = null;
+        if (state.round && (idOf(state.round) !== state.selectedId ||
+            !state.round.targets?.some((target) => target.key === state.targetKey && target.comparison)))
+            state.round = null;
+        changed();
+        try {
+            const collection = await request("");
+            if (current !== revision)
+                return false;
+            state.rounds = collection.rounds || [];
+            if (!state.rounds.some((round) => idOf(round) === state.selectedId)) {
+                state.selectedId = idOf(defaultHistoryRound(state.rounds)) || null;
+            }
+            const selectedId = state.selectedId;
+            let round = null;
+            let targetKey = state.targetKey || targets.get(selectedId);
+            if (selectedId) {
+                const detail = await request(`/${selectedId}`);
+                if (current !== revision)
+                    return false;
+                round = detail.round || detail;
+                const summary = state.rounds.find((item) => idOf(item) === selectedId);
+                for (const target of round.targets || []) {
+                    target.filename ||= summary?.targets?.find((item) => item.key === target.key)?.filename;
+                }
+                const target = round.targets?.find((item) => item.key === targetKey) || round.targets?.[0];
+                targetKey = target?.key || null;
+                if (target) {
+                    const results = await Promise.allSettled(["content", "source"].map((mode) => request(`/${selectedId}/compare?key=${encodeURIComponent(target.key)}&mode=${mode}`)));
+                    if (current !== revision)
+                        return false;
+                    target.comparison = Object.fromEntries(["content", "source"].map((mode, index) => [mode, results[index].status === "fulfilled" ? results[index].value
+                            : { available: false, counts: null, reason: results[index].reason.message }]));
+                    if (results.every((result) => result.status === "rejected"))
+                        state.error = results[0].reason;
+                }
+            }
+            state.round = round;
+            state.targetKey = targetKey;
+            if (selectedId)
+                targets.set(selectedId, targetKey);
+            state.loading = false;
+            changed();
+            refreshed();
+            return true;
+        }
+        catch (error) {
+            if (current !== revision)
+                return false;
+            state.error = error;
+            state.loading = false;
+            changed();
+            return false;
+        }
+    }
+    return {
+        state, refresh,
+        selectRound(id) {
+            state.selectedId = id;
+            state.targetKey = targets.get(id) || null;
+            state.index = 0;
+            return refresh();
+        },
+        selectTarget(key) { state.targetKey = key; state.index = 0; return refresh(); },
+        cancel() { revision++; state.loading = false; },
+    };
+}
+/**
+ * Optional capture cannot veto delivery; a failed refresh cannot masquerade as failed Send.
+ * @template T
+ * @param {{save: () => Promise<unknown>, capture: () => Promise<T>,
+ * deliver: (snapshot: T | null) => Promise<unknown>, committed: () => void,
+ * refresh: () => Promise<unknown>}} options
+ */
+export async function deliverFeedback({ save, capture, deliver, committed, refresh }) {
+    await save();
+    let snapshot = null;
+    let captureFailure = null;
+    try {
+        snapshot = await capture();
+    }
+    catch (error) {
+        captureFailure = error;
+    }
+    await deliver(snapshot);
+    committed();
+    let refreshFailure = null;
+    try {
+        if (await refresh() === false)
+            refreshFailure = new Error("History could not be refreshed");
+    }
+    catch (error) {
+        refreshFailure = error;
+    }
+    return { captureFailure, refreshFailure };
+}

package/lib/history-policy.js

@@ -0,0 +1,43 @@
+import { COMPLETED_ROUNDS_TO_KEEP, isRevisionId } from "./revision-schema.js";
+function references(value, out = new Set()) {
+    if (isRevisionId(value))
+        out.add(value);
+    else if (Array.isArray(value))
+        for (const item of value)
+            references(item, out);
+    else if (value && typeof value === "object")
+        for (const item of Object.values(value))
+            references(item, out);
+    return out;
+}
+export function unsentRevisionReferences(data) {
+    const out = new Set();
+    for (const page of Object.values(data.pages || {})) {
+        references(page.comments, out);
+        references(page.edits, out);
+        references(page.revisionRefs, out);
+    }
+    return out;
+}
+export function historyRevisionReferences(data) {
+    const out = unsentRevisionReferences(data);
+    references(data.histories, out);
+    references(data.batches, out);
+    return out;
+}
+export function retainHistory(data) {
+    const pinned = unsentRevisionReferences(data);
+    let changed = false;
+    for (const history of Object.values(data.histories || {})) {
+        const completed = history.rounds
+            .filter((round) => round.completedAt)
+            .sort((a, b) => b.completedAt - a.completedAt || b.ordinal - a.ordinal);
+        const keep = new Set(completed.slice(0, COMPLETED_ROUNDS_TO_KEEP).map((round) => round.roundId));
+        const rounds = history.rounds.filter((round) => !round.completedAt || keep.has(round.roundId) || [...references(round.targets)].some((id) => pinned.has(id)));
+        if (rounds.length !== history.rounds.length) {
+            history.rounds = rounds;
+            changed = true;
+        }
+    }
+    return changed;
+}