@erdemtuna/doc-review 0.9.0 → 0.11.0

package/lib/feedback-panel-controller.js

@@ -0,0 +1,161 @@
+import { createControllerStore } from "./controller-store.js";
+export const createNoteDraft = () => ({ text: "", selectionStart: 0, selectionEnd: 0, composing: false });
+function savePresentation(state) {
+    if (state.save.conflict)
+        return "Source changed — reload latest before saving. Your page edits remain in this tab.";
+    if (state.kind === "url")
+        return "Localhost page — your direct edits go to the agent for source updates";
+    if (state.markdown)
+        return "Markdown source — edits go to the agent as feedback";
+    if (state.save.dynamic)
+        return "Live page — edits go to the agent, the file is left alone";
+    if (state.save.status === "saving")
+        return `Saving to ${state.filename}…`;
+    if (state.save.status === "failed")
+        return "Couldn't save — retry before sending";
+    return `Saved to ${state.filename}${state.save.savedAt ? ` · ${state.save.savedAt}` : ""}`;
+}
+export function createFeedbackPanelController(options) {
+    let disposed = false;
+    let expanded = false;
+    let editsOpen = true;
+    let dialog = null;
+    let copyStatus = "idle";
+    let copyError = "";
+    const fingerprint = (action, state) => JSON.stringify(action === "revert"
+        ? state.edits : [state.total, state.drafts, state.note.text]);
+    const valid = (owned, full = true) => {
+        const state = options.read();
+        return !disposed && !state.ended && state.available && !state.delivery.sending &&
+            state.identity === owned.identity && (!full ||
+            (state.source === owned.source && fingerprint(owned.action, state) === owned.fingerprint));
+    };
+    const store = createControllerStore(() => {
+        const state = options.read();
+        const busy = state.delivery.sending;
+        const sent = state.delivery.sent || state.agent === "working" || state.agent === "stranded";
+        const count = state.total;
+        const hasNote = !!state.note.text.trim();
+        return {
+            note: state.note, ended: state.ended, disabled: state.ended || !state.available,
+            edits: expanded ? state.edits : state.edits.slice(0, 5), editCount: state.edits.length, expanded, editsOpen,
+            saveText: savePresentation(state), saveError: state.save.conflict || state.save.status === "failed",
+            saveStatus: state.save.status, drafts: state.drafts, busy, delivery: state.delivery,
+            sendDisabled: state.ended || !state.available || (!count && !hasNote) || busy || sent || !!dialog || state.note.composing,
+            sendText: busy ? "Sending feedback…" : state.agent === "working" ? "Feedback delivered"
+                : state.agent === "stranded" ? "Sent — agent is not listening"
+                    : state.delivery.sent ? "Sent — waiting for agent" : count ? `Send ${count} to agent`
+                        : hasNote ? "Send note to agent" : "Nothing to send yet",
+            agent: state.agent, prompt: state.prompt, copyStatus, copyError,
+            dialog: dialog ? { ...dialog, stale: !valid(dialog) } : null,
+        };
+    });
+    const publish = () => { if (!disposed)
+        store.publish(); };
+    const available = () => !disposed && !options.read().ended && options.read().available;
+    async function send() {
+        const state = options.read();
+        if (!available() || dialog || state.note.composing || (!state.total && !state.note.text.trim()) ||
+            state.delivery.sending || state.delivery.sent || state.agent === "working" || state.agent === "stranded")
+            return;
+        await options.send();
+    }
+    return {
+        getSnapshot: store.getSnapshot, subscribe: store.subscribe, publish,
+        commands: {
+            setEditsOpen(open) {
+                if (!available() || dialog)
+                    return;
+                editsOpen = open;
+                publish();
+            },
+            updateNote(value) {
+                if (!available() || dialog)
+                    return;
+                Object.assign(options.read().note, value);
+                publish();
+            },
+            expand() { if (available()) {
+                expanded = !expanded;
+                publish();
+            } },
+            send,
+            open(action) {
+                const state = options.read();
+                if (!available() || dialog || state.delivery.sending || (action === "revert" && !state.edits.length))
+                    return;
+                if (action === "revert")
+                    editsOpen = true;
+                const drafts = state.drafts + Number(!!state.note.text.trim());
+                dialog = {
+                    action, identity: state.identity, source: state.source, fingerprint: fingerprint(action, state),
+                    pending: false, error: "",
+                    description: action === "revert" ? `Discard all ${state.edits.length} of your edits? Comments and the overall note are kept.`
+                        : `${state.total ? `${state.total} unsent ${state.total === 1 ? "item will" : "items will"} be kept for next time. ` : ""}${drafts ? `${drafts} open ${drafts === 1 ? "draft (including any overall note) is" : "drafts (including any overall note) are"} only in this tab and will not be sent. ` : ""}The waiting agent will be told to stop polling.`,
+                };
+                publish();
+            },
+            cancel() { if (dialog && !dialog.pending) {
+                dialog = null;
+                publish();
+            } },
+            async confirm() {
+                const owned = dialog;
+                if (!owned || owned.pending)
+                    return;
+                if (!valid(owned)) {
+                    owned.error = "The page or feedback changed. Cancel and review the current state before trying again.";
+                    publish();
+                    return;
+                }
+                owned.pending = true;
+                owned.error = "";
+                publish();
+                try {
+                    // Flush the SDK debounce window before either destructive request.
+                    await options.flush(owned.action);
+                    if (!valid(owned, false))
+                        throw new Error("The page changed while preparing this action. Cancel and try again on the current page.");
+                    if (owned.action === "revert")
+                        await options.revert();
+                    else
+                        await options.end();
+                    if (!disposed && dialog === owned)
+                        dialog = null;
+                }
+                catch (error) {
+                    if (!disposed && dialog === owned) {
+                        owned.error = error instanceof Error ? error.message : String(error);
+                        options.failed(owned.error);
+                    }
+                }
+                finally {
+                    owned.pending = false;
+                    publish();
+                }
+            },
+            async copy() {
+                const prompt = options.read().prompt;
+                if (!available() || !prompt || copyStatus === "copying")
+                    return;
+                copyStatus = "copying";
+                copyError = "";
+                publish();
+                try {
+                    await options.copy(prompt);
+                    if (!disposed)
+                        copyStatus = "copied";
+                }
+                catch {
+                    if (!disposed) {
+                        copyStatus = "failed";
+                        copyError = "Couldn't copy — select the prompt and copy it manually";
+                        options.failed(copyError);
+                    }
+                }
+                publish();
+            },
+        },
+        dispose() { disposed = true; dialog = null; store.dispose(); },
+    };
+}

package/lib/frame-channel.js

@@ -0,0 +1,42 @@
+let channel = null;
+export function initializeChannel(capability, generation, pageKey) {
+    if (channel)
+        throw new Error("Doc Review frame channel is already initialized.");
+    channel = {
+        capability: String(capability),
+        generation: Number(generation),
+        pageKey: String(pageKey),
+    };
+}
+export function initializeChannelFromDocument() {
+    const script = document.querySelector("script[data-eh-sdk][data-eh-bootstrap]");
+    if (!script)
+        throw new Error("Doc Review frame bootstrap is missing.");
+    const capability = script.nonce;
+    const generation = Number(script.dataset.generation);
+    const pageKey = String(script.dataset.pageKey || "");
+    script.remove();
+    if (!capability || !Number.isSafeInteger(generation) || !pageKey) {
+        throw new Error("Doc Review frame bootstrap is invalid.");
+    }
+    initializeChannel(capability, generation, pageKey);
+}
+export function frameMessage(type, payload = {}) {
+    if (!channel)
+        throw new Error("Doc Review frame channel is not initialized.");
+    return {
+        ...payload,
+        type,
+        capability: channel.capability,
+        generation: channel.generation,
+        pageKey: channel.pageKey,
+    };
+}
+export function matchesFrameMessage(message) {
+    return !!(channel &&
+        message && (typeof message === "object" || typeof message === "function") &&
+        "capability" in message && "generation" in message && "pageKey" in message &&
+        message.capability === channel.capability &&
+        message.generation === channel.generation &&
+        message.pageKey === channel.pageKey);
+}

package/lib/frame-controller.js

@@ -0,0 +1,313 @@
+import { record } from "./chrome-api.js";
+export function createFrameController({ sessionId, host, request, suspended, transitioning = () => { }, failed, now = Date.now, 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,
+        configurationGeneration: null, pendingReload: false, reloading: false,
+    };
+    const listeners = new Set();
+    const timers = new Set();
+    const flushes = new Map();
+    let readinessTimer = null;
+    let replacementTimer = null;
+    let readinessRetries = 0;
+    let initialLoad = false;
+    let readyGeneration = null;
+    let sourceRevision = 0;
+    let flushSequence = 0;
+    let configuration = null;
+    let expectedConfiguration = null;
+    const alive = () => state.phase.kind !== "disposed";
+    const loading = () => state.phase.kind !== "ready";
+    const publish = () => { if (alive())
+        for (const listener of listeners)
+            listener(); };
+    const identity = () => ({
+        key: state.key, renderId: state.renderId, generation: state.generation, loading: loading(),
+    });
+    const matches = (value) => alive() && value.key === state.key &&
+        value.generation === state.generation && value.renderId === state.renderId;
+    const cancelTimer = (timer) => {
+        if (timer !== null) {
+            clearTimer(timer);
+            timers.delete(timer);
+        }
+    };
+    function later(callback, delay) {
+        const timer = setTimer(() => {
+            timers.delete(timer);
+            if (alive())
+                callback();
+        }, delay);
+        timers.add(timer);
+        return timer;
+    }
+    function send(message) {
+        if (!alive() || loading() || !state.capability)
+            return;
+        host.send({
+            ...message, capability: state.capability, generation: state.generation, pageKey: state.key,
+        }, state.policy?.targetOrigin || "*");
+    }
+    function suspend() {
+        if (!alive())
+            return;
+        suspended();
+        for (const flush of flushes.values())
+            flush.settle(false);
+        configuration?.settle(false);
+        expectedConfiguration = null;
+        for (const timer of timers)
+            clearTimer(timer);
+        timers.clear();
+        readinessTimer = replacementTimer = null;
+        state.capability = null;
+        state.renderId = null;
+        state.execution = null;
+        state.phase = { kind: "suspended" };
+        readyGeneration = null;
+        state.configurationGeneration = null;
+        host.suspend();
+    }
+    function begin(key = state.key) {
+        if (!alive())
+            throw new Error("Review ended");
+        transitioning();
+        suspend();
+        state.key = key;
+        state.generation++;
+        state.sourceHash = null;
+        sourceRevision++;
+        state.readyAt = 0;
+        state.phase = { kind: "loading" };
+        return state.generation;
+    }
+    function finishReplacement() {
+        cancelTimer(replacementTimer);
+        replacementTimer = null;
+        host.finishReplacement();
+        publish();
+    }
+    function fail(message) {
+        if (!alive())
+            return;
+        suspend();
+        state.phase = { kind: "failed", message };
+        state.pendingReload = true;
+        finishReplacement();
+        failed(message);
+    }
+    async function register(key, generation) {
+        if (!alive() || !key)
+            throw new Error("No active review page is selected.");
+        const value = record(await request(`/api/session/${sessionId}/render`, {
+            method: "POST", body: JSON.stringify({ key, generation }),
+        }));
+        if (!alive() || state.key !== key || state.generation !== generation)
+            return false;
+        if (typeof value.renderId !== "string" || typeof value.capability !== "string" ||
+            typeof value.path !== "string" || !value.path.startsWith("/artifact/") ||
+            (value.sourceHash != null && typeof value.sourceHash !== "string")) {
+            throw new Error("The review server returned an invalid frame registration.");
+        }
+        state.renderId = value.renderId;
+        state.capability = value.capability;
+        state.sourceHash = typeof value.sourceHash === "string" ? value.sourceHash : null;
+        sourceRevision++;
+        state.phase = { kind: "loading" };
+        initialLoad = true;
+        host.navigate(value.path, state.reloading);
+        publish();
+        readinessTimer = later(() => {
+            if (state.key !== key || state.generation !== generation || !loading())
+                return;
+            if (readinessRetries < 1) {
+                readinessRetries++;
+                rotate();
+            }
+            else
+                fail("The reviewed page did not finish loading. Fix the source or local server, then reload.");
+        }, 5000);
+        return true;
+    }
+    function rotate() {
+        if (!state.key || !alive())
+            return;
+        const key = state.key;
+        const generation = begin();
+        void register(key, generation).catch((error) => {
+            if (state.key === key && state.generation === generation) {
+                fail(error instanceof Error ? error.message : String(error));
+            }
+        });
+    }
+    const stopLoad = host.onLoad(() => {
+        if (!state.renderId || !state.capability)
+            return;
+        if (initialLoad) {
+            initialLoad = false;
+            return;
+        }
+        rotate();
+    });
+    async function ready() {
+        if (!alive() || !state.renderId || !state.capability || readyGeneration === state.generation)
+            return null;
+        cancelTimer(readinessTimer);
+        readinessTimer = null;
+        readinessRetries = 0;
+        readyGeneration = state.generation;
+        state.readyAt = now();
+        state.phase = { kind: "confirming" };
+        const started = identity();
+        const revision = sourceRevision;
+        try {
+            const value = record(await request(`/api/session/${sessionId}/render/${state.renderId}/ready`, {
+                method: "POST",
+                body: JSON.stringify({ capability: state.capability, generation: state.generation, pageKey: state.key }),
+            }));
+            if (!matches(started))
+                return null;
+            if ((value.executionMode !== "static" && value.executionMode !== "interactive" && value.executionMode !== "application") ||
+                (value.savePolicy !== "writable" && value.savePolicy !== "feedback-only") ||
+                (value.sourceHash != null && typeof value.sourceHash !== "string")) {
+                throw new Error("The review could not confirm this document's execution policy. Reload before editing.");
+            }
+            if (revision === sourceRevision) {
+                state.sourceHash = typeof value.sourceHash === "string" ? value.sourceHash : null;
+            }
+            state.execution = {
+                executionMode: value.executionMode, savePolicy: value.savePolicy,
+                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;
+        }
+        catch (error) {
+            if (matches(started)) {
+                const detail = error instanceof Error ? error.message : String(error);
+                const message = "The review could not confirm this document's execution policy. Reload before editing.";
+                fail(detail.startsWith(message) ? detail : `${message} ${detail}`);
+            }
+            return null;
+        }
+    }
+    function configurationTimeout() {
+        if (!host.previous)
+            return;
+        cancelTimer(replacementTimer);
+        const started = identity();
+        replacementTimer = later(() => {
+            if (matches(started) && host.previous) {
+                fail("The page did not confirm its review settings. Reload before continuing.");
+            }
+        }, 5000);
+    }
+    function configure(mode, savePolicy, wait = true) {
+        if (loading() || !state.capability || !state.execution)
+            return Promise.resolve(false);
+        configuration?.settle(false);
+        expectedConfiguration = { mode, savePolicy };
+        configurationTimeout();
+        if (!wait) {
+            send({ type: "eh:configureReview", mode, savePolicy });
+            return Promise.resolve(true);
+        }
+        return new Promise((resolve) => {
+            const timer = later(() => settle(false), 3000);
+            const settle = (applied) => {
+                if (configuration?.settle !== settle)
+                    return;
+                configuration = null;
+                cancelTimer(timer);
+                resolve(applied);
+            };
+            configuration = { mode, savePolicy, settle };
+            send({ type: "eh:configureReview", mode, savePolicy });
+        });
+    }
+    function flush(strict = false) {
+        if (loading() || !state.capability) {
+            return strict ? Promise.reject(new Error("The page is not ready. Wait for it to load, then retry.")) : Promise.resolve();
+        }
+        return new Promise((resolve, reject) => {
+            const requestId = `flush-${++flushSequence}`;
+            const timer = later(() => settle(false), strict ? 6000 : 400);
+            const settle = (confirmed) => {
+                if (!flushes.delete(requestId))
+                    return;
+                cancelTimer(timer);
+                if (!confirmed && strict)
+                    reject(new Error("The page did not finish saving. Wait for it to load, then retry."));
+                else
+                    resolve();
+            };
+            flushes.set(requestId, { strict, settle });
+            send({ type: "eh:flush", requestId });
+        });
+    }
+    return {
+        get state() { return state; },
+        get loading() { return loading(); },
+        identity, matches, begin, register, suspend, ready, configure, flush, send, fail,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => { listeners.delete(listener); };
+        },
+        seedGeneration(generation) {
+            if (Number.isSafeInteger(generation) && state.renderId === null)
+                state.generation = generation;
+        },
+        resetRetries() { readinessRetries = 0; },
+        setPolicy(policy) { state.policy = policy; host.setPolicy(policy); },
+        setSourceHash(hash) { state.sourceHash = hash; sourceRevision++; },
+        startReload() { state.reloading = true; state.pendingReload = false; },
+        restoredScroll() { state.reloading = false; },
+        holdReload() { state.pendingReload = true; publish(); },
+        accepts(event) {
+            if (!alive() || !host.acceptsSource(event.source) || !state.policy ||
+                event.origin !== state.policy.incomingOrigin || !state.capability)
+                return false;
+            const value = event.data;
+            if (!value || typeof value !== "object" || !("capability" in value) ||
+                !("generation" in value) || !("pageKey" in value) || !("type" in value))
+                return false;
+            return value.capability === state.capability && value.generation === state.generation &&
+                value.pageKey === state.key && typeof value.type === "string" &&
+                (!loading() || value.type === "eh:ready");
+        },
+        configured(mode, savePolicy) {
+            if (!expectedConfiguration || expectedConfiguration.mode !== mode ||
+                expectedConfiguration.savePolicy !== savePolicy || loading())
+                return false;
+            state.configurationGeneration = state.generation;
+            if (host.previous)
+                host.afterPaint(() => { if (!loading())
+                    finishReplacement(); });
+            if (configuration && configuration.mode === mode && configuration.savePolicy === savePolicy) {
+                configuration.settle(true);
+            }
+            return true;
+        },
+        flushed(requestId) {
+            if (typeof requestId === "string")
+                flushes.get(requestId)?.settle(true);
+            else
+                for (const request of flushes.values())
+                    if (!request.strict)
+                        request.settle(true);
+        },
+        dispose() {
+            if (!alive())
+                return;
+            suspend();
+            state.phase = { kind: "disposed" };
+            stopLoad();
+            host.dispose();
+            listeners.clear();
+        },
+    };
+}

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();
+        },
+    };
+}