@erdemtuna/doc-review 0.11.1 → 0.13.0

package/lib/frame-controller.js

@@ -1,5 +1,6 @@
 import { record } from "./chrome-api.js";
-export function createFrameController({ sessionId, host, request, suspended, transitioning = () => { }, failed, now = Date.now, setTimer = globalThis.setTimeout, clearTimer = globalThis.clearTimeout, }) {
+import { isThemePayload } from "./contracts/frame.js";
+export function createFrameController({ sessionId, host, request, suspended, transitioning = () => { }, failed, now = Date.now, activated = () => { }, diagnostic = () => { }, setTimer = globalThis.setTimeout, clearTimer = globalThis.clearTimeout, }) {
     const state = {
         key: null, generation: 0, renderId: null, capability: null, sourceHash: null,
         execution: null, policy: null, phase: { kind: "loading" }, readyAt: 0,
@@ -17,6 +18,10 @@ export function createFrameController({ sessionId, host, request, suspended, tra
     let flushSequence = 0;
     let configuration = null;
     let expectedConfiguration = null;
+    let desired = { theme: "light", themeRevision: 1 };
+    let currentTheme = null;
+    let previousTheme = null;
+    let retainedCandidate = null;
     const alive = () => state.phase.kind !== "disposed";
     const loading = () => state.phase.kind !== "ready";
     const publish = () => { if (alive())
@@ -49,7 +54,114 @@ export function createFrameController({ sessionId, host, request, suspended, tra
             ...message, capability: state.capability, generation: state.generation, pageKey: state.key,
         }, state.policy?.targetOrigin || "*");
     }
-    function suspend() {
+    function cancelTheme(channel) {
+        if (!channel)
+            return;
+        cancelTimer(channel.timer);
+        channel.timer = null;
+        channel.pending = null;
+        channel.failed = false;
+        channel.settle?.(false);
+        channel.settle = null;
+    }
+    function clearPreviousTheme() {
+        cancelTheme(previousTheme);
+        previousTheme = null;
+        publish();
+    }
+    const stopRemoval = host.onPreviousRemoved(clearPreviousTheme);
+    const themeApplied = (channel) => channel?.applied?.themeRevision === desired.themeRevision && channel.applied.theme === desired.theme &&
+        !channel.pending && !channel.failed;
+    function handoff() {
+        if (!host.previous || loading() || !expectedConfiguration ||
+            state.configurationGeneration !== state.generation || !themeApplied(currentTheme))
+            return;
+        const started = identity();
+        const appliedConfiguration = expectedConfiguration;
+        const revision = desired.themeRevision;
+        host.afterPaint(() => {
+            if (matches(started) && !loading() && expectedConfiguration === appliedConfiguration &&
+                state.configurationGeneration === state.generation && desired.themeRevision === revision &&
+                themeApplied(currentTheme))
+                finishReplacement();
+        });
+    }
+    function exposeReady() {
+        if (state.phase.kind !== "confirming" || !state.execution || !themeApplied(currentTheme))
+            return;
+        state.phase = { kind: "ready" };
+        host.ready(state.execution);
+        publish();
+        activated(state.execution);
+    }
+    function requestTheme(channel) {
+        cancelTheme(channel);
+        channel.pending = { ...desired };
+        const pending = channel.pending;
+        const promise = new Promise((resolve) => { channel.settle = resolve; });
+        channel.timer = later(() => {
+            if (channel.pending !== pending)
+                return;
+            channel.timer = null;
+            channel.pending = null;
+            channel.failed = true;
+            channel.settle?.(false);
+            channel.settle = null;
+            publish();
+        }, 3000);
+        const message = {
+            type: "eh:setTheme", ...pending, capability: channel.capability,
+            generation: channel.generation, pageKey: channel.pageKey,
+        };
+        if (channel === currentTheme)
+            host.send(message, channel.policy.targetOrigin);
+        else if (channel.source && channel.source === host.previousWindow) {
+            channel.source.postMessage(message, channel.policy.targetOrigin);
+        }
+        publish();
+        return promise;
+    }
+    function handleThemeMessage(event) {
+        const value = event.data;
+        if (!alive() || !value || typeof value !== "object" || !("type" in value) ||
+            (value.type !== "eh:themeApplied" && value.type !== "eh:setTheme"))
+            return false;
+        const channel = [currentTheme, previousTheme].find((candidate) => candidate && candidate.source &&
+            candidate.source === event.source && candidate.policy.incomingOrigin === event.origin &&
+            "capability" in value && value.capability === candidate.capability &&
+            "generation" in value && value.generation === candidate.generation &&
+            "pageKey" in value && value.pageKey === candidate.pageKey);
+        if (!channel)
+            return true;
+        if (channel === previousTheme && channel.source !== host.previousWindow) {
+            clearPreviousTheme();
+            return true;
+        }
+        if (value.type !== "eh:themeApplied" || !isThemePayload(value)) {
+            if (!channel.diagnosed) {
+                channel.diagnosed = true;
+                diagnostic("invalid-theme-acknowledgment");
+            }
+            return true;
+        }
+        if (!channel.pending || channel.pending.themeRevision !== value.themeRevision ||
+            channel.pending.theme !== value.theme)
+            return true;
+        channel.applied = { theme: value.theme, themeRevision: value.themeRevision };
+        cancelTimer(channel.timer);
+        channel.timer = null;
+        channel.pending = null;
+        channel.failed = false;
+        channel.settle?.(true);
+        channel.settle = null;
+        if (channel === currentTheme) {
+            exposeReady();
+            handoff();
+        }
+        publish();
+        return true;
+    }
+    function suspend(preserveTheme = false) {
         if (!alive())
             return;
         suspended();
@@ -57,6 +169,13 @@ export function createFrameController({ sessionId, host, request, suspended, tra
             flush.settle(false);
         configuration?.settle(false);
         expectedConfiguration = null;
+        cancelTheme(currentTheme);
+        cancelTheme(previousTheme);
+        if (!preserveTheme) {
+            previousTheme = null;
+            retainedCandidate = null;
+        }
+        currentTheme = null;
         for (const timer of timers)
             clearTimer(timer);
         timers.clear();
@@ -73,7 +192,8 @@ export function createFrameController({ sessionId, host, request, suspended, tra
         if (!alive())
             throw new Error("Review ended");
         transitioning();
-        suspend();
+        retainedCandidate = currentTheme || retainedCandidate;
+        suspend(true);
         state.key = key;
         state.generation++;
         state.sourceHash = null;
@@ -117,6 +237,13 @@ export function createFrameController({ sessionId, host, request, suspended, tra
         state.phase = { kind: "loading" };
         initialLoad = true;
         host.navigate(value.path, state.reloading);
+        if (previousTheme?.source !== host.previousWindow)
+            clearPreviousTheme();
+        if (!previousTheme && retainedCandidate?.source === host.previousWindow)
+            previousTheme = retainedCandidate;
+        retainedCandidate = null;
+        if (previousTheme && !themeApplied(previousTheme))
+            void requestTheme(previousTheme);
         publish();
         readinessTimer = later(() => {
             if (state.key !== key || state.generation !== generation || !loading())
@@ -181,10 +308,15 @@ export function createFrameController({ sessionId, host, request, suspended, tra
                 feedbackOnly: value.savePolicy === "feedback-only",
                 executionNotice: typeof value.executionNotice === "string" ? value.executionNotice : null,
             };
-            state.phase = { kind: "ready" };
-            host.ready(state.execution);
-            publish();
-            return state.execution;
+            if (!state.policy || !state.key)
+                throw new Error("Missing frame policy.");
+            currentTheme = {
+                source: host.currentWindow, capability: state.capability, generation: state.generation,
+                pageKey: state.key, policy: { ...state.policy }, applied: null, pending: null,
+                failed: false, timer: null, settle: null, diagnosed: false,
+            };
+            await requestTheme(currentTheme);
+            return matches(started) && !loading() ? state.execution : null;
         }
         catch (error) {
             if (matches(started)) {
@@ -206,14 +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) => {
@@ -225,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) {
@@ -252,6 +385,40 @@ export function createFrameController({ sessionId, host, request, suspended, tra
     return {
         get state() { return state; },
         get loading() { return loading(); },
+        get themeSync() {
+            const channels = [currentTheme, previousTheme].filter((channel) => channel !== null);
+            const failure = channels.some((channel) => channel.failed);
+            return {
+                desired: { ...desired },
+                status: failure ? "failed" : channels.some((channel) => channel.pending) ? "pending" :
+                    themeApplied(currentTheme) ? "applied" : "idle",
+                appliedRevision: currentTheme?.applied?.themeRevision ?? null,
+                message: failure ? "Annotation theme synchronization was not confirmed. Your page and drafts are unchanged. Retry theme without reloading." : null,
+            };
+        },
+        setTheme(theme) {
+            if (!alive() || (theme !== "light" && theme !== "dark") || desired.theme === theme)
+                return;
+            if (desired.themeRevision === Number.MAX_SAFE_INTEGER)
+                throw new Error("Theme revision limit reached.");
+            desired = { theme, themeRevision: desired.themeRevision + 1 };
+            if (currentTheme)
+                void requestTheme(currentTheme);
+            if (previousTheme && previousTheme.source === host.previousWindow)
+                void requestTheme(previousTheme);
+            publish();
+        },
+        async retryTheme() {
+            if (!alive())
+                return false;
+            const pending = [];
+            if (currentTheme)
+                pending.push(requestTheme(currentTheme));
+            if (previousTheme && previousTheme.source === host.previousWindow)
+                pending.push(requestTheme(previousTheme));
+            return pending.length > 0 && (await Promise.all(pending)).every(Boolean);
+        },
+        handleThemeMessage,
         identity, matches, begin, register, suspend, ready, configure, flush, send, fail,
         subscribe(listener) {
             listeners.add(listener);
@@ -277,24 +444,21 @@ export function createFrameController({ sessionId, host, request, suspended, tra
                 return false;
             return value.capability === state.capability && value.generation === state.generation &&
                 value.pageKey === state.key && typeof value.type === "string" &&
-                (!loading() || value.type === "eh:ready");
+                (!loading() || value.type === "eh:ready" ||
+                    (state.phase.kind === "confirming" && value.type === "eh:themeApplied" &&
+                        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;
-            const started = identity();
-            const appliedConfiguration = expectedConfiguration;
-            if (host.previous)
-                host.afterPaint(() => {
-                    if (matches(started) && expectedConfiguration === appliedConfiguration && !loading())
-                        finishReplacement();
-                });
-            if (configuration && configuration.mode === mode && configuration.savePolicy === savePolicy) {
+            handoff();
+            if (configuration && configuration.mode === mode && configuration.savePolicy === savePolicy && configuration.canComment === canComment) {
                 configuration.settle(true);
             }
             return true;
@@ -313,6 +477,7 @@ export function createFrameController({ sessionId, host, request, suspended, tra
             suspend();
             state.phase = { kind: "disposed" };
             stopLoad();
+            stopRemoval();
             host.dispose();
             listeners.clear();
         },

package/lib/frame-host.js

@@ -4,6 +4,7 @@ export function createFrameHost(initial, artifactOrigin) {
     let disposed = false;
     const loadListeners = new Set();
     const focusListeners = new Set();
+    const removalListeners = new Set();
     const detach = new Map();
     const paintFrames = new Set();
     function paint(callback) {
@@ -41,6 +42,12 @@ export function createFrameHost(initial, artifactOrigin) {
     return {
         get current() { return current; },
         get previous() { return previous; },
+        get currentWindow() { return current.contentWindow; },
+        get previousWindow() { return previous?.contentWindow || null; },
+        onPreviousRemoved(listener) {
+            removalListeners.add(listener);
+            return () => { removalListeners.delete(listener); };
+        },
         get visibleExecution() {
             const visible = previous || current;
             const savePolicy = visible.dataset.savePolicy;
@@ -98,6 +105,8 @@ export function createFrameHost(initial, artifactOrigin) {
             if (previous)
                 remove(previous);
             previous = null;
+            for (const listener of removalListeners)
+                listener();
             delete current.dataset.replacing;
         },
         suspend() { current.removeAttribute("data-sdk-ready"); },
@@ -131,6 +140,7 @@ export function createFrameHost(initial, artifactOrigin) {
             paintFrames.clear();
             loadListeners.clear();
             focusListeners.clear();
+            removalListeners.clear();
         },
     };
 }

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;
 }