@erdemtuna/doc-review 0.9.0 → 0.11.0

package/lib/poll-transport.js

@@ -0,0 +1,220 @@
+import http from "node:http";
+import { performance } from "node:perf_hooks";
+export const DEFAULT_POLL_SECONDS = 12 * 60 * 60;
+const MAX_TIMER_MS = 2 ** 31 - 1;
+const clock = {
+    now: () => performance.now(),
+    setTimeout: (fn, ms) => setTimeout(fn, ms),
+    clearTimeout: (timer) => clearTimeout(timer),
+};
+function codedError(message, code) {
+    return Object.assign(new Error(message), { code });
+}
+export function createDeadline(seconds = DEFAULT_POLL_SECONDS, time = clock) {
+    const end = time.now() + seconds * 1000;
+    const remaining = () => Math.max(0, end - time.now());
+    const check = () => {
+        if (remaining() <= 0)
+            throw codedError("Polling deadline reached.", "POLL_DEADLINE");
+    };
+    return {
+        seconds,
+        time,
+        remaining,
+        check,
+        async sleep(ms) {
+            check();
+            await new Promise((resolve) => time.setTimeout(resolve, Math.min(ms, remaining(), MAX_TIMER_MS)));
+            check();
+        },
+    };
+}
+export function isRecoverableTransportError(err) {
+    return new Set([
+        "ECONNRESET", "ECONNREFUSED", "EPIPE", "ETIMEDOUT", "EHOSTUNREACH",
+        "ENETUNREACH", "ENETDOWN", "ECONNABORTED", "ERR_STREAM_PREMATURE_CLOSE",
+        "SERVER_START_PENDING",
+    ]).has(err?.code);
+}
+/**
+ * An absolute response deadline, not a socket-idle timeout: heartbeats and
+ * partially received JSON must not extend the caller's waiting budget.
+ */
+export function requestRaw(server, options, body, { timeoutMs = options.timeout, time = clock, signal, timeoutCode = "ETIMEDOUT", makeRequest = http.request, } = {}) {
+    return new Promise((resolve, reject) => {
+        let req;
+        let res;
+        let timer;
+        let done = false;
+        let ended = false;
+        let raw = "";
+        const expires = timeoutMs == null ? null : time.now() + timeoutMs;
+        const premature = () => codedError("The server closed an incomplete response.", "ERR_STREAM_PREMATURE_CLOSE");
+        const cleanupResponse = () => {
+            res?.removeListener("data", onData);
+            res?.removeListener("end", onEnd);
+            res?.removeListener("aborted", onAborted);
+        };
+        const settle = (err, value) => {
+            if (done)
+                return;
+            done = true;
+            time.clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+            cleanupResponse();
+            // Keep error handlers until close: destroying a socket may emit one last
+            // error asynchronously. Close removes the remaining owned listeners.
+            res?.destroy();
+            req?.destroy();
+            if (err)
+                reject(err);
+            else
+                resolve(value);
+        };
+        const onError = (err) => settle(err);
+        const onData = (chunk) => { raw += chunk; };
+        const onEnd = () => {
+            ended = true;
+            if (!res.complete)
+                return settle(premature());
+            settle(null, { status: res.statusCode, raw });
+        };
+        const onAborted = () => settle(premature());
+        const onResponseClose = () => {
+            if (!ended)
+                settle(premature());
+            cleanupResponse();
+            res.removeListener("error", onError);
+            res.removeListener("close", onResponseClose);
+        };
+        const onRequestClose = () => {
+            if (!done)
+                settle(premature());
+            req.removeListener("error", onError);
+            req.removeListener("close", onRequestClose);
+            req.removeListener("response", onResponse);
+        };
+        const onAbort = () => settle(codedError("Polling cancelled.", "ABORT_ERR"));
+        const armTimer = () => {
+            const left = expires - time.now();
+            if (left <= 0)
+                return settle(codedError("Polling request timed out.", timeoutCode));
+            timer = time.setTimeout(armTimer, Math.min(left, MAX_TIMER_MS));
+        };
+        const onResponse = (response) => {
+            res = response;
+            if (done) {
+                res.destroy();
+                return;
+            }
+            res.setEncoding("utf8");
+            res.on("data", onData);
+            res.on("end", onEnd);
+            res.on("error", onError);
+            res.on("aborted", onAborted);
+            res.on("close", onResponseClose);
+        };
+        try {
+            if (signal?.aborted)
+                return onAbort();
+            const port = typeof server === "number" ? server : server.port;
+            const token = typeof server === "number" ? "" : server.token || "";
+            const { timeout: _timeout, ...requestOptions } = options;
+            req = makeRequest({
+                host: "127.0.0.1",
+                port,
+                ...requestOptions,
+                headers: { ...(token ? { "x-doc-review-token": token } : {}), ...(options.headers || {}) },
+            });
+            req.on("response", onResponse);
+            req.on("error", onError);
+            req.on("close", onRequestClose);
+            signal?.addEventListener("abort", onAbort, { once: true });
+            if (expires !== null)
+                armTimer();
+            if (done)
+                return;
+            if (body)
+                req.write(JSON.stringify(body));
+            req.end();
+        }
+        catch (err) {
+            settle(err);
+        }
+    });
+}
+export function parseServerResponse(response) {
+    if (response.status !== 200) {
+        let detail = "";
+        try {
+            detail = JSON.parse(response.raw).error || "";
+        }
+        catch { /* HTTP status is sufficient. */ }
+        throw codedError(`Doc-review server returned HTTP ${response.status}${detail ? `: ${detail}` : "."}`, "SERVER_RESPONSE_ERROR");
+    }
+    try {
+        const parsed = JSON.parse(response.raw);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            throw new Error();
+        return parsed;
+    }
+    catch {
+        throw codedError("Malformed response from the doc-review server. End the review and restart the server.", "SERVER_RESPONSE_INVALID");
+    }
+}
+export async function pollOnce(server, target, ackId, deadline) {
+    deadline.check();
+    const query = `target=${encodeURIComponent(target)}${ackId ? `&ack=${encodeURIComponent(ackId)}` : ""}`;
+    const response = await requestRaw(server, {
+        method: "GET",
+        path: `/api/poll?${query}`,
+    }, undefined, {
+        timeoutMs: deadline.remaining(),
+        time: deadline.time,
+        timeoutCode: "POLL_DEADLINE",
+    });
+    // Graceful server disposal ends the space heartbeats without a JSON payload.
+    // HTTP is complete, but this poll was interrupted just like a dropped socket.
+    if (response.status === 200 && /^ +$/.test(response.raw)) {
+        throw codedError("The server ended the poll before sending feedback.", "ERR_STREAM_PREMATURE_CLOSE");
+    }
+    const batch = parseServerResponse(response);
+    if (!["feedback", "closed", "timeout"].includes(batch.status) ||
+        (batch.status === "feedback" && (typeof batch.batch_id !== "string" || !batch.batch_id || !Array.isArray(batch.pages)))) {
+        throw codedError("Malformed polling response from the doc-review server.", "SERVER_RESPONSE_INVALID");
+    }
+    return batch;
+}
+export async function pollUntilDeadline({ target, ackId = "", deadline = createDeadline(), discover, poll = pollOnce, diagnostic = () => { }, }) {
+    let failures = 0;
+    for (;;) {
+        try {
+            deadline.check();
+            const server = await discover(deadline);
+            deadline.check();
+            // An uncertain send must repeat the supplied receipt, never a newer ID.
+            const batch = await poll(server, target, ackId, deadline);
+            deadline.check();
+            return batch;
+        }
+        catch (err) {
+            if (err.code === "POLL_DEADLINE" || deadline.remaining() <= 0) {
+                return {
+                    status: "timeout",
+                    waited_seconds: deadline.seconds,
+                    next_step: "No feedback yet. Run the same poll command again to keep waiting, or `doc-review status <target>` to check without blocking.",
+                };
+            }
+            if (!isRecoverableTransportError(err))
+                throw err;
+            diagnostic(`Lost the connection (${err.message}); retrying.\n`);
+            try {
+                await deadline.sleep(Math.min(250 * 2 ** Math.min(failures++, 5), 5000));
+            }
+            catch (sleepError) {
+                if (sleepError.code !== "POLL_DEADLINE")
+                    throw sleepError;
+            }
+        }
+    }
+}

package/lib/positioning.js

@@ -0,0 +1,97 @@
+const GAP = 12;
+export function visibleViewport(win = window) {
+    const viewport = win.visualViewport;
+    return viewport
+        ? { left: viewport.offsetLeft, top: viewport.offsetTop, width: viewport.width, height: viewport.height }
+        : { left: 0, top: 0, width: win.innerWidth, height: win.innerHeight };
+}
+export function lastVisibleRect(rects) {
+    if (!Array.isArray(rects))
+        return null;
+    for (let index = rects.length - 1; index >= 0; index -= 1) {
+        const rect = rects[index];
+        if (rect && rect.width >= 0 && rect.height >= 0)
+            return rect;
+    }
+    return null;
+}
+const clamp = (value, min, max) => Math.max(min, Math.min(max, value));
+function frameRectToChrome(rect, frameRect) {
+    return {
+        left: frameRect.left + rect.left,
+        right: frameRect.left + rect.right,
+        top: frameRect.top + rect.top,
+        bottom: frameRect.top + rect.bottom,
+    };
+}
+export function placeContextualSurface(geometry, options) {
+    const { frameRect, viewport, surfaceWidth = 340, surfaceHeight = 220, narrow = false, toolbarHeight = 48, } = options;
+    const bottomSheet = () => ({
+        kind: "sheet",
+        left: viewport.left,
+        top: viewport.top + viewport.height - Math.min(surfaceHeight, viewport.height),
+        width: viewport.width,
+    });
+    if (!geometry || geometry.relation === "unavailable" || !geometry.clip)
+        return { kind: "hidden" };
+    if (narrow)
+        return bottomSheet();
+    const clip = frameRectToChrome(geometry.clip, frameRect);
+    const minLeft = viewport.left + GAP;
+    const maxLeft = viewport.left + viewport.width - surfaceWidth - GAP;
+    const viewportMinTop = viewport.top + toolbarHeight + GAP;
+    const minTop = Math.max(viewportMinTop, clip.top + GAP);
+    const maxTop = viewport.top + viewport.height - surfaceHeight - GAP;
+    const clipBottomTop = clip.bottom - surfaceHeight - GAP;
+    const horizontal = Number.isFinite(geometry.horizontal)
+        ? frameRect.left + geometry.horizontal
+        : clip.left;
+    const edgeLeft = clamp(horizontal + GAP, minLeft, maxLeft);
+    if (geometry.relation === "above") {
+        return { kind: "edge-top", left: edgeLeft, top: minTop, width: surfaceWidth };
+    }
+    if (geometry.relation === "below") {
+        return {
+            kind: "edge-bottom",
+            left: edgeLeft,
+            top: Math.max(viewportMinTop, Math.min(maxTop, clipBottomTop)),
+            width: surfaceWidth,
+        };
+    }
+    const target = lastVisibleRect(geometry.rects);
+    if (!target)
+        return { kind: "hidden" };
+    const rect = frameRectToChrome(target, frameRect);
+    const attachedMaxTop = Math.min(maxTop, clipBottomTop);
+    const clampTop = (top) => clamp(top, minTop, Math.max(minTop, attachedMaxTop));
+    const candidates = [
+        { left: rect.right + GAP, top: clampTop(rect.bottom - surfaceHeight) },
+        { left: rect.left - surfaceWidth - GAP, top: clampTop(rect.bottom - surfaceHeight) },
+        { left: clamp(rect.left, minLeft, maxLeft), top: rect.bottom + GAP },
+        { left: clamp(rect.left, minLeft, maxLeft), top: rect.top - surfaceHeight - GAP },
+    ];
+    const fit = candidates.find((candidate) => candidate.left >= minLeft &&
+        candidate.left <= maxLeft &&
+        candidate.top >= minTop &&
+        candidate.top <= attachedMaxTop &&
+        candidate.left + surfaceWidth <= Math.min(viewport.left + viewport.width - GAP, clip.right) &&
+        candidate.top + surfaceHeight <= clip.bottom);
+    const fallback = fit || {
+        left: clamp(rect.right + GAP, minLeft, maxLeft),
+        top: clampTop(rect.top),
+    };
+    return { kind: "attached", ...fallback, width: surfaceWidth };
+}
+export function alignedCardPosition(rects, { frameRect, viewport, width = 300, height = 180 }) {
+    const target = lastVisibleRect(rects);
+    if (!target)
+        return null;
+    const top = frameRect.top + target.top;
+    const right = frameRect.left + target.right;
+    if (top < frameRect.top || top > frameRect.bottom || right < frameRect.left || right > frameRect.right)
+        return null;
+    return {
+        left: Math.max(viewport.left + 12, Math.min(viewport.left + viewport.width - width - 12, right + 12)),
+        top: Math.max(viewport.top + 12, Math.min(viewport.top + viewport.height - height - 12, top)),
+    };
+}

package/lib/recovery-controller.js

@@ -0,0 +1,123 @@
+import { createControllerStore } from "./controller-store.js";
+import { decodePage, record } from "./chrome-api.js";
+import { executionPresentation } from "./execution-client.js";
+export function createRecoveryController(options) {
+    let disposed = false;
+    let busy = false;
+    let reloadBusy = false;
+    let menuOpen = false;
+    let restoreMenuFocus = true;
+    let failure = null;
+    const lifetime = new AbortController();
+    const matches = (a, b) => a.key === b.key && a.generation === b.generation && a.renderId === b.renderId;
+    function project() {
+        const context = options.read();
+        const view = executionPresentation(context.page, context.rendered, {
+            loading: context.loading, pendingReload: context.pendingReload, error: context.frameError,
+        });
+        const visible = !context.ended && !context.comparing;
+        const menuVisible = visible && (view.eligible || !!view.detail);
+        const error = failure && matches(failure.identity, context.identity) ? failure.message : null;
+        return {
+            menuVisible, menuOpen: menuVisible && menuOpen, restoreMenuFocus,
+            busy, canRecover: !disposed && !context.ended && !context.comparing && !busy && view.eligible && !!context.identity.key,
+            preference: view.preference, eligible: view.eligible, detail: view.detail,
+            reloadVisible: visible && context.reload.visible,
+            reloadMessage: context.reload.message, reloadError: context.reload.error,
+            canReload: !disposed && visible && context.reload.visible && !!context.identity.key && (!context.loading || !!context.frameError) && !reloadBusy,
+            reloadBusy,
+            status: visible && !context.reload.visible ? (context.frameError || error || view.status || (busy ? "Updating page recovery settings…" : "")) : "",
+            statusError: !!context.frameError || !!error,
+        };
+    }
+    const store = createControllerStore(project);
+    function setMenuOpen(open, { restoreFocus = true } = {}) {
+        if (disposed || (open && !project().menuVisible))
+            return;
+        if (menuOpen === open) {
+            // The iframe's interaction message can arrive after native dismissal.
+            if (!open && !restoreFocus) {
+                restoreMenuFocus = false;
+                store.publish();
+            }
+            return;
+        }
+        menuOpen = open;
+        restoreMenuFocus = restoreFocus;
+        store.publish();
+        options.menuChanged(open);
+    }
+    function publish() {
+        if (!project().menuVisible)
+            setMenuOpen(false, { restoreFocus: false });
+        return store.publish();
+    }
+    async function recover(preference) {
+        if (!project().canRecover)
+            return;
+        const identity = { ...options.read().identity };
+        busy = true;
+        failure = null;
+        setMenuOpen(false);
+        publish();
+        try {
+            const response = record(await options.request(`/api/session/${options.sessionId}/execution`, {
+                method: "POST", body: JSON.stringify({ key: identity.key, preference }), signal: lifetime.signal,
+            }));
+            const page = decodePage(response.page);
+            if (!disposed && matches(identity, options.read().identity)) {
+                if (page.key !== identity.key)
+                    throw new Error("The recovery response belongs to a different page.");
+                options.changed(page);
+            }
+            // The server event remains the only owner of draft-safe frame replacement.
+        }
+        catch (error) {
+            if (!disposed && matches(identity, options.read().identity)) {
+                const message = error instanceof Error ? error.message : String(error);
+                failure = { identity, message: `Recovery could not be updated: ${message}. Retry from More.` };
+                options.failed(message);
+            }
+        }
+        finally {
+            busy = false;
+            publish();
+        }
+    }
+    async function reload() {
+        if (!project().canReload)
+            return;
+        reloadBusy = true;
+        publish();
+        try {
+            await options.reload();
+        }
+        catch (error) {
+            if (!disposed)
+                options.failed(error instanceof Error ? error.message : String(error));
+        }
+        finally {
+            reloadBusy = false;
+            publish();
+        }
+    }
+    return {
+        getSnapshot: store.getSnapshot, subscribe: store.subscribe, publish,
+        commands: {
+            setMenuOpen, recover, reload,
+            keepCurrent() {
+                if (disposed || !project().reloadVisible || reloadBusy)
+                    return;
+                options.keepCurrent();
+                publish();
+            },
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            lifetime.abort();
+            store.dispose();
+        },
+    };
+}

package/lib/review-controller.js

@@ -0,0 +1,93 @@
+import { decodePage, record } from "./chrome-api.js";
+export function createReviewController(options) {
+    let source = null;
+    let revision = 0;
+    let navigationRevision = 0;
+    let disposed = false;
+    const cleanup = new Set();
+    const invalidate = () => { revision++; };
+    const report = (error) => { if (!disposed)
+        options.failed(error); };
+    async function refresh() {
+        const started = ++revision;
+        const key = options.key();
+        const generation = options.generation();
+        options.beforeRefresh();
+        const page = await options.request(`/api/page/${key}?session=${encodeURIComponent(options.sessionId)}`);
+        if (disposed || started !== revision || key !== options.key() || generation !== options.generation())
+            return;
+        options.refreshPage(decodePage(page), true);
+    }
+    function connect() {
+        if (disposed || source)
+            return;
+        source = (options.eventSource || ((url) => new EventSource(url)))(`/events/${options.sessionId}`);
+        source.addEventListener("ended", () => { if (!disposed)
+            options.ended(); });
+        source.addEventListener("reload", () => {
+            if (disposed)
+                return;
+            invalidate();
+            void options.reload().catch(report);
+        });
+        source.addEventListener("history", () => { if (!disposed)
+            void options.history().catch(report); });
+        source.addEventListener("agent", (event) => {
+            if (disposed)
+                return;
+            try {
+                const value = record(JSON.parse(event.data));
+                if (typeof value.state !== "string")
+                    throw new Error("Invalid agent state event.");
+                options.agent(value.state);
+            }
+            catch (error) {
+                report(error);
+            }
+        });
+        source.addEventListener("refresh", () => { if (!disposed)
+            void refresh().catch(report); });
+        // EventSource owns reconnect/backoff; reconnect errors are not failed mutations.
+        source.onerror = () => { };
+    }
+    async function navigate(body) {
+        if (disposed)
+            throw new Error("Review ended");
+        if (options.hasDrafts())
+            throw new Error("Save or cancel open comment drafts before changing pages");
+        const started = ++navigationRevision;
+        invalidate();
+        const key = options.key();
+        const generation = options.generation();
+        await options.save();
+        if (disposed || started !== navigationRevision || key !== options.key() || generation !== options.generation()) {
+            throw new Error("The page changed before navigating. Retry on the current page.");
+        }
+        if ("key" in body)
+            options.suspend();
+        const result = record(await options.request(`/api/session/${options.sessionId}/${"key" in body ? "goto" : "navigate"}`, { method: "POST", body: JSON.stringify(body) }));
+        // A source reload does not undo a navigation already accepted by the server.
+        if (disposed || started !== navigationRevision)
+            return;
+        const next = "key" in body ? body.key : result.key;
+        if (typeof next !== "string")
+            throw new Error("The server returned an invalid navigation target.");
+        await options.load(next);
+    }
+    return {
+        connect, refresh, navigate, invalidate,
+        own(stop) { cleanup.add(stop); return stop; },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            revision++;
+            navigationRevision++;
+            source?.close();
+            source = null;
+            for (const stop of cleanup)
+                stop();
+            cleanup.clear();
+        },
+    };
+}

package/lib/review-mode.js

@@ -0,0 +1,66 @@
+export const REVIEW_MODES = Object.freeze(["view", "edit"]);
+export function normalizeReviewMode(mode) {
+    return mode === "edit" ? "edit" : "view";
+}
+export function savePolicyForPage(page) {
+    return page && ((typeof page === "object" || typeof page === "function") &&
+        (("savePolicy" in page && page.savePolicy === "feedback-only") ||
+            ("kind" in page && page.kind === "url") ||
+            ("markdown" in page && page.markdown) || ("feedbackOnly" in page && page.feedbackOnly)))
+        ? "feedback-only"
+        : "writable";
+}
+export function reviewConfiguration(page, mode) {
+    return {
+        mode: normalizeReviewMode(mode),
+        savePolicy: savePolicyForPage(page),
+    };
+}
+export function applyBodyReviewMode(body, mode) {
+    const normalized = normalizeReviewMode(mode);
+    if (normalized === "edit") {
+        if (body.getAttribute("contenteditable") !== "true")
+            body.setAttribute("contenteditable", "true");
+        if (body.getAttribute("spellcheck") !== "false")
+            body.setAttribute("spellcheck", "false");
+    }
+    else {
+        if (body.hasAttribute("contenteditable"))
+            body.removeAttribute("contenteditable");
+        if (body.hasAttribute("spellcheck"))
+            body.removeAttribute("spellcheck");
+    }
+    return normalized;
+}
+/** Keep the active mode intact when an application hydrates and rewrites body attributes. */
+export function keepBodyInReviewMode(body, initialMode = "view") {
+    let mode = normalizeReviewMode(initialMode);
+    let applying = false;
+    const enforce = () => {
+        if (applying)
+            return;
+        applying = true;
+        applyBodyReviewMode(body, mode);
+        applying = false;
+    };
+    const view = body.ownerDocument.defaultView;
+    if (!view)
+        throw new TypeError("The review body must belong to a window.");
+    const Observer = view.MutationObserver;
+    const observer = new Observer(enforce);
+    observer.observe(body, { attributes: true, attributeFilter: ["contenteditable", "spellcheck"] });
+    enforce();
+    return {
+        get mode() {
+            return mode;
+        },
+        setMode(nextMode) {
+            mode = normalizeReviewMode(nextMode);
+            enforce();
+            return mode;
+        },
+        disconnect() {
+            observer.disconnect();
+        },
+    };
+}