@erdemtuna/doc-review 0.9.0 → 0.10.0

package/lib/editing.js

@@ -0,0 +1,107 @@
+/**
+ * Pure editing helpers, shared by the in-page SDK and Node tests.
+ *
+ * Everything here is deliberately DOM-free: the SDK feeds in strings and
+ * computed-style snapshots, and gets back decisions it can apply.
+ */
+/**
+ * The list command for a marker typed at the start of a line, or null.
+ * `lead` is everything between the start of the block and the caret, so a
+ * marker typed mid-sentence never converts.
+ */
+export function listCommandFor(lead) {
+    const marker = String(lead || "").replace(/\u00a0/g, " ").trim();
+    if (/^[-*]$/.test(marker))
+        return "insertUnorderedList";
+    if (/^\d{1,3}[.)]$/.test(marker))
+        return "insertOrderedList";
+    return null;
+}
+/**
+ * Style properties a fresh list needs when the page's CSS reset hides it.
+ * Tailwind preflight and similar resets set `list-style: none` and zero the
+ * indent, so a just-created list looks like nothing happened. Returns only
+ * the properties that are actually broken, so styled pages stay untouched.
+ */
+export function listStyleFixup(tagName, computed) {
+    const patch = {};
+    if (computed.listStyleType === "none") {
+        patch.listStyleType = /^ol$/i.test(tagName) ? "decimal" : "disc";
+    }
+    const inset = (parseFloat(computed.paddingLeft) || 0) + (parseFloat(computed.marginLeft) || 0);
+    if (inset < 16)
+        patch.paddingLeft = "1.5em";
+    return patch;
+}
+/**
+ * Style a fresh link needs when the page can't distinguish it from prose.
+ * Reset stylesheets (`a { color: inherit; text-decoration: inherit }`) make a
+ * just-created link invisible; underline it only when neither color nor
+ * decoration sets it apart.
+ */
+export function linkStyleFixup(anchorComputed, parentComputed) {
+    const decorated = String(anchorComputed.textDecorationLine || "").includes("underline");
+    const recolored = !!parentComputed && anchorComputed.color !== parentComputed.color;
+    return decorated || recolored ? {} : { textDecoration: "underline" };
+}
+/**
+ * A typed link, made openable and safe. Bare domains get https://, in-page
+ * and relative references pass through, and anything with an executable or
+ * unknown scheme (javascript:, data:, …) is rejected outright.
+ */
+export function normalizeHref(raw) {
+    const href = String(raw || "").replace(/[\u0000-\u001f\u007f]/g, "").trim();
+    if (!href)
+        return "";
+    let candidate = href;
+    if (!/^(https?:|mailto:|tel:|#|\/|\.)/i.test(href)) {
+        const head = href.split(/[/?#]/)[0];
+        if (/^([\w-]+\.)+[\w-]+(:\d+)?$/.test(head) || /^localhost(:\d+)?$/i.test(head)) {
+            // A bare domain — "example.com", "localhost:3000/wiki" — gets a scheme.
+            candidate = `https://${href}`;
+        }
+        else if (/^[a-z][a-z0-9+.-]*:/i.test(href)) {
+            return "";
+        }
+    }
+    try {
+        const parsed = new URL(candidate, "https://relative.invalid");
+        if (!/^(https?:|mailto:|tel:)$/i.test(parsed.protocol))
+            return "";
+    }
+    catch {
+        return "";
+    }
+    return candidate;
+}
+/**
+ * Classify an authored navigation target. Relative references stay under
+ * controlled source-relative navigation; only explicitly safe external
+ * schemes leave the review.
+ */
+export function classifyHref(raw) {
+    const href = String(raw || "").replace(/[\u0000-\u001f\u007f]/g, "").trim();
+    if (!href)
+        return "invalid";
+    if (href.startsWith("#"))
+        return "hash";
+    if (/^\/\//.test(href) || /^https?:/i.test(href) || /^(?:mailto|tel):/i.test(href))
+        return "external";
+    if (/^[a-z][a-z0-9+.-]*:/i.test(href))
+        return "invalid";
+    return "navigate";
+}
+export function externalHref(raw, baseHref = "https://relative.invalid/") {
+    const href = String(raw || "").replace(/[\u0000-\u001f\u007f]/g, "").trim();
+    if (classifyHref(href) !== "external")
+        return "";
+    if (/^(?:mailto|tel):/i.test(href))
+        return href;
+    try {
+        const parsed = new URL(href, baseHref);
+        return /^https?:$/i.test(parsed.protocol) ? parsed.href : "";
+    }
+    catch {
+        return "";
+    }
+}

package/lib/execution-client.js

@@ -0,0 +1,69 @@
+/** UI policy always describes the visible frame, not a newer on-disk source. */
+export function executionPresentation(page, rendered, { loading = false, pendingReload = false, error = null } = {}) {
+    const eligible = page?.kind === "file" && !page.markdown;
+    const policy = rendered?.savePolicy;
+    return {
+        eligible,
+        preference: page?.executionPreference || "auto",
+        editDescription: policy === "writable" ? "Edits save directly to this file"
+            : policy === "feedback-only" ? "Edits are feedback for the agent to apply"
+                : "Waiting for the page's editing policy",
+        status: error || (pendingReload ? "Showing the previous page while reload is pending."
+            : loading ? "Loading page…" : ""),
+        detail: [
+            rendered?.executionNotice,
+            rendered?.executionMode === "static" && policy === "feedback-only" && eligible
+                ? "Scripts are disabled for recovery. Edits still go to the agent; the source is not overwritten." : null,
+        ].filter(Boolean).join(" "),
+    };
+}
+export function createExecutionControls({ api, sessionId, elements, changed, failed }) {
+    let busy = false;
+    let currentPage = null;
+    async function recover(preference) {
+        if (busy || !currentPage)
+            return;
+        const key = currentPage.key;
+        busy = true;
+        if (elements.menu) {
+            elements.menu.open = false;
+            elements.menu.querySelector("summary")?.focus({ preventScroll: true });
+        }
+        elements.static.disabled = elements.auto.disabled = true;
+        try {
+            const result = await api(`/api/session/${sessionId}/execution`, {
+                method: "POST", body: JSON.stringify({ key, preference }),
+            });
+            if (currentPage?.key === key)
+                changed(result.page);
+            // The server's reload event owns draft-safe frame replacement.
+        }
+        catch (error) {
+            failed(error);
+        }
+        finally {
+            busy = false;
+            elements.static.disabled = elements.auto.disabled = false;
+        }
+    }
+    elements.static.addEventListener("click", () => void recover("static"));
+    elements.auto.addEventListener("click", () => void recover("auto"));
+    return {
+        render(page, rendered, options) {
+            currentPage = page;
+            const view = executionPresentation(page, rendered, options);
+            elements.static.hidden = !view.eligible || view.preference === "static";
+            elements.auto.hidden = !view.eligible || view.preference !== "static";
+            if (elements.menu)
+                elements.menu.hidden = !view.eligible && !view.detail;
+            elements.status.textContent = view.status;
+            elements.status.hidden = !view.status;
+            if (elements.details) {
+                elements.details.textContent = view.detail;
+                elements.details.hidden = !view.detail;
+            }
+            if (elements.editDescription)
+                elements.editDescription.textContent = view.editDescription;
+        },
+    };
+}

package/lib/feedback-controller.js

@@ -0,0 +1,106 @@
+import { record } from "./chrome-api.js";
+import { deliverFeedback } from "./history-coordinator.js";
+export function createFeedbackController(options) {
+    const listeners = new Set();
+    let state = { phase: "idle" };
+    let disposed = false;
+    let inFlight = false;
+    let sent = false;
+    const busy = () => inFlight;
+    const publish = () => { if (!disposed)
+        for (const listener of listeners)
+            listener(); };
+    const current = (identity) => !disposed && !!identity.renderId &&
+        identity.key === options.current().key && identity.generation === options.current().generation &&
+        identity.renderId === options.current().renderId;
+    return {
+        get state() { return state; },
+        get sending() { return busy(); },
+        get sent() { return sent; },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => { listeners.delete(listener); };
+        },
+        clearSent() { sent = false; if (!busy())
+            state = { phase: "idle" }; },
+        async send() {
+            if (busy() || disposed)
+                return;
+            const identity = options.current();
+            const sentNote = options.note();
+            inFlight = true;
+            state = { phase: "saving" };
+            options.pauseCapture();
+            publish();
+            let delivering = false;
+            let delivered = false;
+            try {
+                const outcome = await deliverFeedback({
+                    save: () => options.save.barrier(),
+                    capture: () => options.capture(),
+                    deliver: async (snapshot) => {
+                        await options.save.settled();
+                        await options.save.settleEdits(identity.key);
+                        if (!current(identity))
+                            throw new Error("The page changed before sending. Retry on the current page.");
+                        if (options.save.state.conflict || options.save.state.status === "failed" ||
+                            (options.policy() === "writable" && !options.save.state.dynamic && options.save.state.dirty)) {
+                            throw new Error("Your page edits have not finished saving.");
+                        }
+                        delivering = true;
+                        state = { phase: "delivering" };
+                        publish();
+                        const result = record(await options.request(`/api/page/${identity.key}/send`, {
+                            method: "POST",
+                            body: JSON.stringify({
+                                sessionId: options.sessionId, note: sentNote.trim(),
+                                history: {
+                                    renderId: identity.renderId, generation: identity.generation,
+                                    semantic: snapshot?.semantic || null,
+                                    semanticCapturedAt: snapshot?.semanticCapturedAt, view: snapshot?.view,
+                                    expectedSourceHash: snapshot?.sourceHash || options.save.state.baseHash || options.sourceHash(),
+                                    allowUnavailable: true,
+                                },
+                            }),
+                        }));
+                        if (result.ok === false) {
+                            throw new Error(typeof result.error === "string" ? result.error : "Feedback delivery was not confirmed");
+                        }
+                    },
+                    committed() {
+                        delivered = true;
+                        sent = true;
+                        state = { phase: "delivered" };
+                        if (!disposed)
+                            options.clearNote(sentNote);
+                    },
+                    refresh: () => disposed ? Promise.resolve(false) : options.refresh(),
+                });
+                if (disposed)
+                    return;
+                if (outcome.refreshFailure)
+                    options.warning("Feedback sent. History could not be refreshed; your feedback does not need to be sent again.");
+                else if (outcome.captureFailure)
+                    options.announce("Feedback sent. Content comparison may be incomplete.");
+            }
+            catch (error) {
+                if (disposed)
+                    return;
+                const detail = error instanceof Error ? error.message : String(error);
+                const message = delivered ? "Feedback sent. History is temporarily unavailable; do not send it again."
+                    : !delivering ? `Feedback not sent: ${detail} Your feedback and drafts are still here.`
+                        : `Feedback delivery was not confirmed: ${detail} No automatic retry was made. Check the agent before sending again.`;
+                state = delivered ? { phase: "delivered" }
+                    : { phase: delivering ? "uncertain" : "failed", message };
+                options.failed(message);
+            }
+            finally {
+                inFlight = false;
+                publish();
+                if (!disposed)
+                    options.resumeCapture();
+            }
+        },
+        dispose() { disposed = true; listeners.clear(); },
+    };
+}

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