@erdemtuna/doc-review 0.12.0 → 0.13.0

package/lib/frame-controller.js

@@ -338,15 +338,15 @@ export function createFrameController({ sessionId, host, request, suspended, tra
             }
         }, 5000);
     }
-    function configure(mode, savePolicy, wait = true) {
+    function configure(mode, savePolicy, canComment, wait = true) {
         if (loading() || !state.capability || !state.execution)
             return Promise.resolve(false);
         configuration?.settle(false);
-        expectedConfiguration = { mode, savePolicy };
+        expectedConfiguration = { mode, savePolicy, canComment };
         state.configurationGeneration = null;
         configurationTimeout();
         if (!wait) {
-            send({ type: "eh:configureReview", mode, savePolicy });
+            send({ type: "eh:configureReview", mode, savePolicy, canComment });
             return Promise.resolve(true);
         }
         return new Promise((resolve) => {
@@ -358,8 +358,8 @@ export function createFrameController({ sessionId, host, request, suspended, tra
                 cancelTimer(timer);
                 resolve(applied);
             };
-            configuration = { mode, savePolicy, settle };
-            send({ type: "eh:configureReview", mode, savePolicy });
+            configuration = { mode, savePolicy, canComment, settle };
+            send({ type: "eh:configureReview", mode, savePolicy, canComment });
         });
     }
     function flush(strict = false) {
@@ -449,16 +449,16 @@ export function createFrameController({ sessionId, host, request, suspended, tra
                         isThemePayload(value) && value.theme === currentTheme?.pending?.theme &&
                         value.themeRevision === currentTheme.pending.themeRevision));
         },
-        configured(mode, savePolicy) {
+        configured(mode, savePolicy, canComment) {
             if (!expectedConfiguration || expectedConfiguration.mode !== mode ||
-                expectedConfiguration.savePolicy !== savePolicy || loading())
+                expectedConfiguration.savePolicy !== savePolicy || expectedConfiguration.canComment !== canComment || loading())
                 return false;
             // Confirmation is complete even when background tabs pause the visual handoff.
             cancelTimer(configurationTimer);
             configurationTimer = null;
             state.configurationGeneration = state.generation;
             handoff();
-            if (configuration && configuration.mode === mode && configuration.savePolicy === savePolicy) {
+            if (configuration && configuration.mode === mode && configuration.savePolicy === savePolicy && configuration.canComment === canComment) {
                 configuration.settle(true);
             }
             return true;

package/lib/frame-policy.js

@@ -8,6 +8,7 @@ export const TRUSTED_SDK_MODULE_PATHS = Object.freeze([
     "/editing.js", "/frame-channel.js", "/icons.js", "/review-mode.js",
     "/semantic-snapshot.js", "/serialize.js", "/positioning.js",
     "/revision-schema.js", "/view-identity.js",
+    "/thread-anchor-controller.js", "/contracts/frame.js", "/contracts/feedback.js", "/contracts/validation.js",
 ]);
 export function interactiveFileCsp(sdkOrigin) {
     const origin = new URL(sdkOrigin);

package/lib/history-policy.js

@@ -1,4 +1,4 @@
-import { COMPLETED_ROUNDS_TO_KEEP, isRevisionId } from "./revision-schema.js";
+import { isRevisionId } from "./revision-schema.js";
 function references(value, out = new Set()) {
     if (isRevisionId(value))
         out.add(value);
@@ -23,21 +23,10 @@ export function historyRevisionReferences(data) {
     const out = unsentRevisionReferences(data);
     references(data.histories, out);
     references(data.batches, out);
+    references(data.conversations, 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;
+    // Referenced comparisons are durable review records, not age/count debris.
+    return false;
 }

package/lib/history-server.js

@@ -1,9 +1,8 @@
 import fs from "node:fs";
 import crypto from "node:crypto";
-import { performance } from "node:perf_hooks";
 import { stripSdk } from "./html-transform.js";
 import { isMarkdown } from "./markdown.js";
-import { compareSemanticSnapshots, compareSources, DIFF_VERSION } from "./revision-diff.js";
+import { compareSemanticSnapshots, compareSources } from "./revision-diff.js";
 import { REVISION_LIMITS } from "./revision-schema.js";
 import { normalizeView, compareCapturedViews } from "./view-identity.js";
 const SOURCE_LIMIT = REVISION_LIMITS.sourceBytes;
@@ -61,10 +60,39 @@ function sourceFor(page) {
         mediaType: isMarkdown(page.file) ? "text/markdown" : "text/html",
     };
 }
-export function createHistoryController({ store, sessions, currentRender, readBody, json, emit, pageState, }) {
-    const cache = new Map();
-    let cachedBytes = 0;
-    const revision = (id) => id ? store.revisions.get(id) : null;
+export function compareRevisions(revisions, beforeId, afterId, mode, { baselineUnavailable, resultUnavailable } = {}) {
+    if (!["content", "source"].includes(mode))
+        throw new HistoryRequestError("Unknown comparison mode.");
+    const before = beforeId ? revisions.get(beforeId) : null;
+    const after = afterId ? revisions.get(afterId) : null;
+    const representation = mode === "content" ? "semantic" : "source";
+    if (!before?.[representation] || !after?.[representation]) {
+        return {
+            available: false, mode,
+            reason: !before?.[representation] ? baselineUnavailable || `The before ${mode} snapshot is unavailable.`
+                : resultUnavailable || `The result ${mode} snapshot has not been captured.`,
+            changes: [], limitations: [mode === "source" ? "source_unavailable" : "semantic_unavailable"],
+        };
+    }
+    const differences = mode === "source"
+        ? compareSources(revisions.readSource(before.revisionId), revisions.readSource(after.revisionId))
+        : compareSemanticSnapshots(revisions.readSemantic(before.revisionId), revisions.readSemantic(after.revisionId));
+    return {
+        ...differences, available: differences.status === "complete",
+        ...(differences.status !== "complete" ? {
+            reason: differences.status === "limited"
+                ? "This comparison exceeds its processing limits. Its contents have not been partially displayed."
+                : "The captured content cannot be compared.",
+        } : {}),
+        mode, baselineRevisionId: before.revisionId, resultRevisionId: after.revisionId,
+        beforeCapturedAt: before[representation].capturedAt, afterCapturedAt: after[representation].capturedAt,
+        sourceHash: after.source?.provenance.sourceHash ?? null,
+        capturedSessionId: after.semantic?.provenance.sessionId ?? null,
+        capturedGeneration: after.semantic?.provenance.generation ?? null,
+        ...(mode === "content" ? { viewComparison: compareCapturedViews(before.semantic?.view, after.semantic?.view) } : {}),
+    };
+}
+export function createConversationCapture({ store, currentRender }) {
     const saveRevision = (value) => {
         const provenance = {
             pageKey: value.documentId,
@@ -90,13 +118,6 @@ export function createHistoryController({ store, sessions, currentRender, readBo
             } : {}),
         });
     };
-    const roundFor = (session, roundId) => store.getRound(session.entryKey, roundId);
-    function changed(entryKey, roundId) {
-        for (const session of sessions.values()) {
-            if (session.entryKey === entryKey)
-                emit(session, "history", { roundId });
-        }
-    }
     function currentFrame(session, input, key) {
         const render = typeof input.renderId === "string" ? currentRender(input.renderId) : null;
         if (!render || render.sessionId !== session.id || render.pageKey !== key ||
@@ -108,11 +129,13 @@ export function createHistoryController({ store, sessions, currentRender, readBo
         }
         return render;
     }
-    function checkedSource(page, render, expectedHash) {
+    function checkedSource(page, render, expectedHash, session) {
         const source = sourceFor(page);
+        const write = store.data.conversations.writes[page.key];
+        const savedInReview = write?.reviewId === session.reviewId && write?.hash === source?.hash;
         if (source && (typeof expectedHash !== "string" ||
             source.hash !== expectedHash ||
-            render.sourceHash !== expectedHash)) {
+            (render.sourceHash !== expectedHash && !savedInReview))) {
             throw new HistoryRequestError("The source changed since this version was reviewed. Reload and recapture it.", {
                 status: 409, code: "history_source_changed",
             });
@@ -131,7 +154,7 @@ export function createHistoryController({ store, sessions, currentRender, readBo
             input.semanticCapturedAt < render.createdAt || input.semanticCapturedAt > Date.now() + 5000)) {
             throw new HistoryRequestError("The content capture timestamp does not belong to this rendered version.");
         }
-        const source = checkedSource(page, render, input.expectedSourceHash);
+        const source = checkedSource(page, render, input.expectedSourceHash, session);
         return {
             documentId: key,
             capturedAt: Date.now(),
@@ -151,314 +174,7 @@ export function createHistoryController({ store, sessions, currentRender, readBo
             },
         };
     }
-    function prepareBaseline(session, pages, input) {
-        if (input === undefined)
-            return null;
-        if (!input || typeof input !== "object" || Array.isArray(input)) {
-            throw new HistoryRequestError("Invalid history submission.");
-        }
-        if (input.allowUnavailable !== undefined && typeof input.allowUnavailable !== "boolean") {
-            throw new HistoryRequestError("Invalid missing-comparison choice.");
-        }
-        const keys = pages.length ? pages.map((page) => page.key) : [session.entryKey];
-        const pending = [];
-        const unavailable = [];
-        for (const key of keys) {
-            const page = store.page(key);
-            let value = null;
-            let reason = null;
-            try {
-                value = snapshot(session, key, input, "send");
-            }
-            catch (error) {
-                if (!(error instanceof HistoryRequestError) && !["ENOENT", "EACCES", "EPERM"].includes(error.code))
-                    throw error;
-                reason = error.message;
-                unavailable.push({ key, filename: pageState(key)?.filename || key, reason });
-                if (input.allowUnavailable) {
-                    try {
-                        const source = sourceFor(page);
-                        if (source) {
-                            value = {
-                                documentId: key, capturedAt: Date.now(), source, semantic: null,
-                                provenance: { captureReason: "send-source-only", pageKey: key },
-                                limitations: ["semantic_before_unavailable"],
-                            };
-                        }
-                    }
-                    catch (sourceError) {
-                        if (!(sourceError instanceof HistoryRequestError) && !["ENOENT", "EACCES", "EPERM"].includes(sourceError.code)) {
-                            throw sourceError;
-                        }
-                        reason = sourceError.message;
-                    }
-                }
-            }
-            pending.push({ key, value, reason });
-        }
-        if (unavailable.length && !input.allowUnavailable) {
-            throw new HistoryRequestError("Some pages need to be recaptured before their comparison can be saved.", {
-                status: 409, code: "history_baseline_unavailable", targets: unavailable,
-            });
-        }
-        const targets = pending.map(({ key, value, reason }) => ({
-            key,
-            ...(value ? { baselineRevisionId: saveRevision(value).revisionId } : {
-                baselineUnavailable: reason || "The before snapshot is unavailable.",
-            }),
-            ownerSessionId: session.id,
-        }));
-        return { targets, unavailable };
-    }
-    function presentRound(round) {
-        return {
-            ...round,
-            sentAt: round.sentAt ?? round.createdAt,
-            targets: round.targets.map((target) => ({
-                ...target,
-                captureStatus: target.capture?.status || (target.resultRevisionId ? "ready" : "pending"),
-                filename: pageState(target.key)?.filename || target.key,
-                kind: store.page(target.key)?.kind === "url" ? "url" : "file",
-            })),
-        };
-    }
-    function list(session) {
-        return {
-            activeKey: session.activeKey,
-            rounds: store.listHistory(session.entryKey).map(presentRound),
-        };
-    }
-    function captureSources(entryKey, roundId) {
-        const rounds = roundId ? [store.getRound(entryKey, roundId)] : store.listHistory(entryKey);
-        for (const round of rounds) {
-            if (round?.feedbackStatus !== "acknowledged" || round.completedAt)
-                continue;
-            for (const target of round.targets) {
-                if (target.sourceResultRevisionId || target.resultRevisionId ||
-                    target.capture?.status === "unavailable" || store.page(target.key)?.kind === "url")
-                    continue;
-                try {
-                    const saved = saveRevision({
-                        documentId: target.key, capturedAt: Date.now(),
-                        source: sourceFor(store.page(target.key)),
-                        provenance: { captureReason: "acknowledged-source-result" },
-                    });
-                    store.recordSourceResult(entryKey, round.roundId, target.key, { revisionId: saved.revisionId });
-                    console.info("[doc-review]", { event: "history-source-captured", roundId: round.roundId, key: target.key });
-                }
-                catch (error) {
-                    try {
-                        store.recordSourceResult(entryKey, round.roundId, target.key, { unavailable: String(error.message).slice(0, 500) });
-                    }
-                    catch (persistenceError) {
-                        console.error("[doc-review]", { event: "history-source-failure-not-persisted", code: persistenceError.code || "history_storage_failed" });
-                    }
-                    console.error("[doc-review]", { event: "history-source-unavailable", roundId: round.roundId, key: target.key, code: error.code || "history_storage_failed" });
-                }
-            }
-        }
-    }
-    function comparison(round, key, mode) {
-        if (!["content", "source"].includes(mode))
-            throw new HistoryRequestError("Unknown comparison mode.");
-        const target = round.targets.find((item) => item.key === key);
-        if (!target)
-            throw new HistoryRequestError("This target does not belong to the selected round.", { status: 404 });
-        const before = revision(target.baselineRevisionId);
-        const after = revision(mode === "source" ? target.sourceResultRevisionId || target.resultRevisionId : target.resultRevisionId);
-        const representation = mode === "content" ? "semantic" : "source";
-        if (!before?.[representation] || !after?.[representation]) {
-            return {
-                available: false,
-                mode,
-                reason: !before?.[representation]
-                    ? target.baselineUnavailable || `The before ${mode} snapshot is unavailable.`
-                    : (mode === "source" ? target.sourceResultUnavailable : target.resultUnavailable) || `The result ${mode} snapshot has not been captured.`,
-                changes: [],
-                limitations: [mode === "source" ? "source_unavailable" : "semantic_unavailable"],
-            };
-        }
-        const cacheKey = `${DIFF_VERSION}:${before.revisionId}:${after.revisionId}:${mode}`;
-        if (cache.has(cacheKey))
-            return cache.get(cacheKey).value;
-        const started = performance.now();
-        const differences = mode === "source"
-            ? compareSources(store.revisions.readSource(before.revisionId), store.revisions.readSource(after.revisionId))
-            : compareSemanticSnapshots(store.revisions.readSemantic(before.revisionId), store.revisions.readSemantic(after.revisionId));
-        const result = {
-            ...differences,
-            available: differences.status === "complete",
-            ...(differences.status !== "complete" ? {
-                reason: differences.status === "limited"
-                    ? "This comparison exceeds its processing limits. Its contents have not been partially displayed."
-                    : "The captured content cannot be compared.",
-            } : {}),
-            mode,
-            baselineRevisionId: before.revisionId,
-            resultRevisionId: after.revisionId,
-            beforeCapturedAt: before[representation].capturedAt,
-            afterCapturedAt: after[representation].capturedAt,
-            sourceHash: after.source?.provenance.sourceHash ?? null,
-            capturedSessionId: after.semantic?.provenance.sessionId ?? null,
-            capturedGeneration: after.semantic?.provenance.generation ?? null,
-            ...(mode === "content" ? { viewComparison: compareCapturedViews(before.semantic?.view, after.semantic?.view) } : {}),
-        };
-        const bytes = Buffer.byteLength(JSON.stringify(result));
-        while (cache.size && (cache.size >= 16 || cachedBytes + bytes > 8 * 1024 * 1024)) {
-            const oldest = cache.keys().next().value;
-            cachedBytes -= cache.get(oldest).bytes;
-            cache.delete(oldest);
-        }
-        if (bytes <= 8 * 1024 * 1024) {
-            cache.set(cacheKey, { value: result, bytes });
-            cachedBytes += bytes;
-        }
-        console.info("[doc-review]", {
-            event: "history-compared", roundId: round.roundId, key, mode,
-            durationMs: Math.round(performance.now() - started), changes: result.changes.length,
-        });
-        return result;
-    }
-    async function handle(req, res, url) {
-        const match = url.pathname.match(/^\/api\/session\/(\w+)\/history(?:\/([\w-]+))?(?:\/(compare|capture))?$/);
-        if (!match)
-            return false;
-        const session = sessions.get(match[1]);
-        if (!session) {
-            json(res, 404, { error: "unknown session" });
-            return true;
-        }
-        try {
-            if (!match[2] && req.method === "GET") {
-                json(res, 200, list(session));
-                return true;
-            }
-            let round = roundFor(session, match[2]);
-            if (!round)
-                throw new HistoryRequestError("Unknown round in this review history.", { status: 404 });
-            if (!match[3] && req.method === "GET") {
-                json(res, 200, { round: presentRound(round) });
-                return true;
-            }
-            if (match[3] === "compare" && req.method === "GET") {
-                json(res, 200, comparison(round, url.searchParams.get("key") || session.activeKey, url.searchParams.get("mode") || "content"));
-                return true;
-            }
-            if (match[3] === "capture" && req.method === "POST") {
-                const body = await readBody(req);
-                if (!body || typeof body !== "object" || Array.isArray(body)) {
-                    throw new HistoryRequestError("Invalid capture request.");
-                }
-                round = roundFor(session, match[2]);
-                if (!round)
-                    throw new HistoryRequestError("Unknown round in this review history.", { status: 404 });
-                const key = typeof body.key === "string" ? body.key : session.activeKey;
-                const target = round.targets.find((item) => item.key === key);
-                if (!target)
-                    throw new HistoryRequestError("This target does not belong to the selected round.", { status: 404 });
-                if (round.feedbackStatus !== "acknowledged") {
-                    throw new HistoryRequestError("The round has not been acknowledged.", { status: 409 });
-                }
-                if (target.resultRevisionId) {
-                    json(res, 200, { ok: true, alreadyCaptured: true, round: presentRound(round) });
-                    return true;
-                }
-                if (body.manual !== undefined && typeof body.manual !== "boolean") {
-                    throw new HistoryRequestError("Invalid manual capture choice.");
-                }
-                if (body.finalUnavailable !== undefined && body.finalUnavailable !== true) {
-                    throw new HistoryRequestError("Invalid final capture choice.");
-                }
-                if (body.finalUnavailable === true) {
-                    if (body.manual !== true)
-                        throw new HistoryRequestError("Finishing without content capture must be an explicit choice.");
-                    if (target.capture?.status === "unavailable") {
-                        json(res, 200, { ok: true, alreadyFinalized: true, round: presentRound(round) });
-                        return true;
-                    }
-                    captureSources(session.entryKey, round.roundId);
-                    const claimed = store.claimCapture(session.entryKey, round.roundId, key, {
-                        ownerSessionId: session.id, generation: 0,
-                    });
-                    const updated = store.markCaptureUnavailable(session.entryKey, round.roundId, key, {
-                        captureId: claimed.captureId, ownerSessionId: session.id, generation: 0,
-                        reason: "Content capture was explicitly finished with the available snapshots.", final: true,
-                    });
-                    changed(session.entryKey, round.roundId);
-                    json(res, 200, { ok: true, round: presentRound(updated.round) });
-                    return true;
-                }
-                const baseline = revision(target.baselineRevisionId);
-                const owner = target.ownerSessionId || baseline?.semantic?.provenance.sessionId;
-                if (owner && owner !== session.id && body.manual !== true) {
-                    throw new HistoryRequestError("The review window that sent this round owns automatic capture. Use Capture result to capture here.", {
-                        status: 409, code: "history_capture_owner",
-                    });
-                }
-                const render = currentFrame(session, body, key);
-                if (!target.sourceResultRevisionId)
-                    captureSources(session.entryKey, round.roundId);
-                const claimed = store.claimCapture(session.entryKey, round.roundId, key, {
-                    ownerSessionId: session.id, generation: render.generation,
-                });
-                const ownership = {
-                    captureId: claimed.captureId, ownerSessionId: session.id, generation: render.generation,
-                };
-                let updated;
-                let saved;
-                try {
-                    if (typeof body.error === "string" && body.error.trim()) {
-                        if (body.error.length > 500)
-                            throw new HistoryRequestError("Capture failure reason is too long.");
-                        updated = store.markCaptureUnavailable(session.entryKey, round.roundId, key, {
-                            ...ownership, reason: body.error, final: false,
-                        });
-                    }
-                    else {
-                        const value = snapshot(session, key, body, body.manual === true ? "manual-result" : "automatic-result");
-                        const viewComparison = compareCapturedViews(baseline?.semantic?.view, value.view);
-                        if (viewComparison.status === "mismatch") {
-                            throw new HistoryRequestError(viewComparison.message, { status: 409, code: "history_view_mismatch" });
-                        }
-                        value.provenance.captureId = claimed.captureId;
-                        saved = saveRevision(value);
-                        updated = store.recordCaptureResult(session.entryKey, round.roundId, key, {
-                            ...ownership, revisionId: saved.revisionId,
-                        });
-                    }
-                }
-                catch (error) {
-                    try {
-                        store.markCaptureUnavailable(session.entryKey, round.roundId, key, {
-                            ...ownership, reason: String(error.message).slice(0, 500), final: false,
-                        });
-                        changed(session.entryKey, round.roundId);
-                    }
-                    catch (persistenceError) {
-                        console.error("[doc-review]", { event: "history-failure-not-persisted", code: persistenceError.code || "history_failed" });
-                    }
-                    throw error;
-                }
-                changed(session.entryKey, round.roundId);
-                console.info("[doc-review]", {
-                    event: saved ? "history-captured" : "history-capture-unavailable",
-                    roundId: round.roundId, key, ...(saved ? { revisionId: saved.revisionId } : {}),
-                });
-                json(res, 200, { ok: !!saved, round: presentRound(updated.round) });
-                return true;
-            }
-            json(res, 405, { error: "method not allowed" });
-        }
-        catch (error) {
-            const status = historyErrorStatus(error);
-            console.error("[doc-review]", { event: "history-failed", status, code: error.code || "history_failed" });
-            json(res, status, {
-                error: error.message,
-                code: error.code || "history_failed",
-                ...(error.targets?.length ? { targets: error.targets } : {}),
-            });
-        }
-        return true;
-    }
-    return { prepareBaseline, captureSources, list, handle, changed };
+    return {
+        captureObservation: (session, key, input, reason) => saveRevision(snapshot(session, key, input, reason)),
+    };
 }

package/lib/html-transform.js

@@ -35,11 +35,26 @@ export function injectSdk(html, key, { src = "/sdk.js", baseHref = "", nonce = "
             ? prepared.replace(/<head(\s[^>]*)?>/i, (head) => `${head}${restoreRoute}`)
             : `${restoreRoute}${prepared}`;
     }
-    // Put the trusted module before authored markup can enter an unclosed
-    // script/style/textarea raw-text context. Removing this exact tag restores
-    // every authored byte.
+    // Consume only the document's safe opening prefix. Inserting before <html>
+    // invents an implicit head and redistributes authored whitespace into it.
+    // Never search ahead for <head>: it could be inside unclosed raw text.
     const doctype = /^(\uFEFF?\s*(?:<!--[\s\S]*?-->\s*)*<!doctype[^>]*>)/i.exec(prepared);
-    const at = doctype ? doctype[0].length : 0;
+    let at = doctype ? doctype[0].length : 0;
+    const trivia = () => {
+        const match = /^(?:[\t\n\f\r ]|<!--[\s\S]*?-->)+/.exec(prepared.slice(at));
+        if (match)
+            at += match[0].length;
+    };
+    const opening = (name) => {
+        const match = new RegExp(`^<${name}(?=[\\t\\n\\f\\r />])(?:[^"'<>]|"[^"]*"|'[^']*')*>`, "i").exec(prepared.slice(at));
+        if (match)
+            at += match[0].length;
+        return !!match;
+    };
+    trivia();
+    if (opening("html"))
+        trivia();
+    opening("head");
     return `${prepared.slice(0, at)}${tag}${prepared.slice(at)}`;
 }
 /** Remove any injected tag, so a file saved with one never keeps it. */