@erdemtuna/doc-review 0.9.0 → 0.11.0

package/lib/comments-controller.js

@@ -0,0 +1,109 @@
+import { createControllerStore } from "./controller-store.js";
+import { newestComments } from "./chrome-session.js";
+function age(timestamp) {
+    const seconds = Math.max(0, Math.round((Date.now() - (timestamp ?? Date.now())) / 1000));
+    if (seconds < 45)
+        return "just now";
+    const minutes = Math.round(seconds / 60);
+    if (minutes < 60)
+        return `${minutes}m`;
+    const hours = Math.round(minutes / 60);
+    return hours < 24 ? `${hours}h` : `${Math.round(hours / 24)}d`;
+}
+export function createCommentsController(options) {
+    let disposed = false;
+    let sectionOpen = true;
+    const store = createControllerStore(() => {
+        const state = options.read();
+        return {
+            open: state.open && !state.comparing,
+            sectionOpen,
+            sectionLock: state.ui.edit ? "Save or cancel the comment edit to collapse."
+                : state.ui.confirmation ? "Finish or cancel the deletion to collapse." : "",
+            activeId: state.activeId,
+            disabled: state.ended,
+            loading: !state.hasPage && !state.error && !state.ended,
+            error: !state.hasPage ? state.error : null,
+            showEmpty: state.hasPage && state.comments.length === 0 && !state.composeOpen,
+            cards: newestComments(state.comments).map((comment) => ({
+                id: comment.id, quote: comment.quote, feedback: comment.feedback,
+                age: age(comment.updatedAt || comment.createdAt),
+                correction: !!comment.correction, edited: !!comment.updatedAt,
+                orphaned: state.orphans.has(comment.id), active: state.activeId === comment.id,
+            })),
+            others: state.others.map(({ key, filename, count }) => ({ key, filename, count })),
+            ui: state.ui,
+        };
+    });
+    const available = () => !disposed && !options.read().ended && !options.read().comparing;
+    const has = (id) => available() && options.read().comments.some((comment) => comment.id === id);
+    const deleting = () => options.read().ui.confirmation?.status === "deleting";
+    const editable = (id) => has(id) && !deleting() && (!options.read().ui.edit || options.read().ui.edit?.commentId === id);
+    const ownsEdit = (id) => has(id) && options.read().ui.edit?.commentId === id;
+    const publish = () => {
+        if (disposed)
+            return;
+        const state = options.read();
+        if (state.ui.edit || state.ui.confirmation)
+            sectionOpen = true;
+        store.publish();
+    };
+    return {
+        getSnapshot: store.getSnapshot, subscribe: store.subscribe, publish,
+        commands: {
+            setSectionOpen(open) {
+                const state = options.read();
+                if (!available() || (!open && (state.ui.edit || state.ui.confirmation)))
+                    return;
+                sectionOpen = open;
+                publish();
+            },
+            close() { if (available())
+                options.close(); },
+            activate(id, scroll) { if (editable(id))
+                options.activate(id, scroll); },
+            edit(id, surface = "drawer") {
+                if (editable(id)) {
+                    sectionOpen = true;
+                    options.edit(id, surface);
+                    publish();
+                }
+            },
+            dismiss() { if (available())
+                options.dismiss?.(); },
+            updateEdit(id, value) {
+                if (!ownsEdit(id))
+                    return;
+                const edit = options.read().ui.edit;
+                if (!edit || edit.status === "saving")
+                    return;
+                Object.assign(edit, value, { validation: value.draft === edit.draft ? edit.validation : "" });
+                publish();
+            },
+            save(id) { if (ownsEdit(id) && !options.read().ui.edit?.composing)
+                return options.save(); },
+            cancelEdit(id) { if (ownsEdit(id))
+                options.cancelEdit(); },
+            confirm(id, surface = "drawer") {
+                if (has(id) && !options.read().ui.edit && !deleting()) {
+                    sectionOpen = true;
+                    options.confirm(id, surface);
+                    publish();
+                }
+            },
+            cancelDelete(id) {
+                if (has(id) && !deleting() && options.read().ui.confirmation?.commentId === id)
+                    options.cancelDelete();
+            },
+            remove(id) {
+                if (has(id) && options.read().ui.confirmation?.commentId === id)
+                    return options.remove(id);
+            },
+            navigate(key) {
+                if (available() && options.read().others.some((page) => page.key === key))
+                    return options.navigate(key);
+            },
+        },
+        dispose() { disposed = true; store.dispose(); },
+    };
+}

package/lib/contextual-controller.js

@@ -0,0 +1,33 @@
+import { createControllerStore } from "./controller-store.js";
+export function createComposerDraft() {
+    return { text: "", selectionStart: 0, selectionEnd: 0, composing: false, error: "", retry: false };
+}
+export function createContextualController(options) {
+    let disposed = false;
+    const store = createControllerStore(options.read);
+    const available = () => !disposed && options.read().open && !options.read().disabled;
+    return {
+        getSnapshot: store.getSnapshot, subscribe: store.subscribe, publish: store.publish,
+        commands: {
+            update(value) {
+                if (!available() || options.read().submitting)
+                    return;
+                Object.assign(options.read().draft, value);
+                store.publish();
+            },
+            submit() {
+                if (available() && !options.read().draft.composing)
+                    return options.submit();
+            },
+            cancel() { if (available() && !options.read().submitting)
+                return options.cancel(); },
+            reveal() { if (available())
+                options.reveal(); },
+            focus() { if (available())
+                options.focus(); },
+            measure() { if (!disposed)
+                options.measure(); },
+        },
+        dispose() { disposed = true; store.dispose(); },
+    };
+}

package/lib/contracts/feedback.js

@@ -0,0 +1 @@
+export {};

package/lib/contracts/frame.js

@@ -0,0 +1,7 @@
+/** Correlation alone does not validate a message type or its payload. */
+export function isFrameIdentity(value) {
+    return typeof value === "object" && value !== null &&
+        "capability" in value && typeof value.capability === "string" &&
+        "generation" in value && typeof value.generation === "number" &&
+        "pageKey" in value && typeof value.pageKey === "string";
+}

package/lib/contracts/history.js

@@ -0,0 +1 @@
+export {};

package/lib/contracts/index.js

@@ -0,0 +1,2 @@
+export { isFrameIdentity } from "./frame.js";
+export { isExecutionPolicy, isPageResponse, isRenderExecution } from "./page.js";

package/lib/contracts/page.js

@@ -0,0 +1,23 @@
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function isExecutionPolicy(value) {
+    return record(value) &&
+        (value.executionMode === "static" || value.executionMode === "interactive" || value.executionMode === "application") &&
+        (value.savePolicy === "writable" || value.savePolicy === "feedback-only") &&
+        typeof value.feedbackOnly === "boolean";
+}
+export function isPageResponse(value) {
+    return record(value) && isExecutionPolicy(value) &&
+        typeof value.key === "string" && typeof value.file === "string" &&
+        typeof value.filename === "string" && typeof value.markdown === "boolean" &&
+        typeof value.canRevert === "boolean" && typeof value.pollCommand === "string" &&
+        typeof value.historySupported === "boolean" &&
+        (value.executionPreference === undefined || value.executionPreference === "auto" || value.executionPreference === "static") &&
+        ((value.kind === "file" && value.url === undefined) || (value.kind === "url" && typeof value.url === "string")) &&
+        Array.isArray(value.comments) && Array.isArray(value.edits);
+}
+export function isRenderExecution(value) {
+    return record(value) && isExecutionPolicy(value) &&
+        (value.executionNotice === null || typeof value.executionNotice === "string");
+}

package/lib/controller-store.js

@@ -0,0 +1,96 @@
+/**
+ * Capture small controller projections, not entire history/comparison payloads.
+ * Inputs are plain records/arrays/scalars; project mutable maps into entries first.
+ * Only publish reads the owner. Reads and unchanged snapshot branches are cached.
+ * Subscription cleanup does not dispose the owner. Disposal retains the final
+ * snapshot, stops publication, and rejects new subscriptions.
+ */
+export function createControllerStore(read) {
+    const owned = new WeakSet();
+    function capture(value, previous, ancestors = new Set()) {
+        if (value === null || typeof value !== "object") {
+            if (typeof value === "function")
+                throw new TypeError("Controller snapshots cannot contain functions");
+            return value;
+        }
+        if (owned.has(value))
+            return value;
+        const array = Array.isArray(value);
+        const prototype = Object.getPrototypeOf(value);
+        if (!array && prototype !== Object.prototype && prototype !== null) {
+            throw new TypeError("Controller snapshots require plain records and arrays; project mutable collections first");
+        }
+        if (ancestors.has(value))
+            throw new TypeError("Controller snapshots cannot contain cycles");
+        ancestors.add(value);
+        try {
+            const keys = Reflect.ownKeys(value);
+            const prior = previous !== null && typeof previous === "object" &&
+                Array.isArray(previous) === array && Object.getPrototypeOf(previous) === prototype
+                ? previous : undefined;
+            let unchanged = prior !== undefined && Reflect.ownKeys(prior).length === keys.length;
+            const next = array
+                ? [] : Object.create(prototype);
+            for (const key of keys) {
+                const descriptor = Object.getOwnPropertyDescriptor(value, key);
+                if (!("value" in descriptor))
+                    throw new TypeError("Controller snapshots cannot contain accessors");
+                const before = prior && Object.getOwnPropertyDescriptor(prior, key);
+                const child = capture(descriptor.value, before?.value, ancestors);
+                if (!before || !Object.is(child, before.value))
+                    unchanged = false;
+                Object.defineProperty(next, key, {
+                    value: child, enumerable: descriptor.enumerable, writable: true,
+                    configurable: key !== "length" || !array,
+                });
+            }
+            if (unchanged)
+                return prior;
+            Object.freeze(next);
+            owned.add(next);
+            return next;
+        }
+        finally {
+            ancestors.delete(value);
+        }
+    }
+    let snapshot = capture(read(), undefined);
+    let disposed = false;
+    const subscriptions = new Set();
+    return {
+        getSnapshot: () => snapshot,
+        subscribe(listener) {
+            if (disposed)
+                throw new Error("Controller store is disposed");
+            const subscription = { listener };
+            subscriptions.add(subscription);
+            return () => { subscriptions.delete(subscription); };
+        },
+        publish() {
+            if (disposed)
+                return false;
+            const next = capture(read(), snapshot);
+            if (Object.is(next, snapshot))
+                return false;
+            snapshot = next;
+            const errors = [];
+            for (const subscription of [...subscriptions]) {
+                if (!subscriptions.has(subscription))
+                    continue;
+                try {
+                    subscription.listener();
+                }
+                catch (error) {
+                    errors.push(error);
+                }
+            }
+            if (errors.length)
+                throw new AggregateError(errors, "Controller subscription failed");
+            return true;
+        },
+        dispose() {
+            disposed = true;
+            subscriptions.clear();
+        },
+    };
+}

package/lib/document-execution.js

@@ -0,0 +1,115 @@
+import { parse, serialize } from "parse5";
+export const INTERACTIVE_FILE_NOTICE = "Inline page interactions run automatically. Editing is feedback-only. External scripts, application imports, workers, and embedded applications are unsupported; use localhost for those applications. Only the currently visible view is captured.";
+const attr = (node, name) => node.attrs?.find((item) => item.name === name)?.value;
+const javascriptTypes = new Set([
+    "application/ecmascript", "application/javascript", "application/x-ecmascript", "application/x-javascript",
+    "text/ecmascript", "text/javascript", "text/javascript1.0", "text/javascript1.1",
+    "text/javascript1.2", "text/javascript1.3", "text/javascript1.4", "text/javascript1.5",
+    "text/jscript", "text/livescript", "text/x-ecmascript", "text/x-javascript",
+]);
+const urlAttributes = new Set(["href", "src", "action", "formaction", "data", "background"]);
+function dependency(node) {
+    const tag = node.tagName;
+    const source = attr(node, "src") ?? attr(node, "href");
+    if (tag === "script" && source !== undefined)
+        return { kind: "external-script", source };
+    if (tag === "script" && ["importmap", "speculationrules"].includes((attr(node, "type") || "").trim().toLowerCase())) {
+        return { kind: "application-import-map" };
+    }
+    if (["iframe", "frame", "object", "embed"].includes(tag)) {
+        return { kind: "embedded-application", source: attr(node, "src") || attr(node, "data") };
+    }
+    if (tag === "link") {
+        const rel = (attr(node, "rel") || "").toLowerCase().split(/\s+/);
+        if (rel.includes("modulepreload") || (rel.includes("preload") && ["script", "worker"].includes((attr(node, "as") || "").toLowerCase()))) {
+            return { kind: "script-preload", source: attr(node, "href") };
+        }
+    }
+    return null;
+}
+/** Analyze authored source, never an injected SDK or a runtime DOM serialization. */
+export function analyzeDocumentExecution(source) {
+    if (source instanceof Uint8Array)
+        source = Buffer.from(source).toString("utf8");
+    if (typeof source !== "string")
+        throw new TypeError("HTML source bytes or text are required.");
+    const document = parse(source);
+    let active = false;
+    let application = false;
+    const visit = (node, includeTemplates = false) => {
+        if (dependency(node))
+            active = application = true;
+        if (node.tagName === "script") {
+            const type = (attr(node, "type") ?? (attr(node, "language") ? `text/${attr(node, "language")}` : "")).trim().toLowerCase();
+            if (!type || type === "module" || javascriptTypes.has(type))
+                active = true;
+        }
+        for (const attribute of node.attrs || []) {
+            const name = attribute.name.toLowerCase();
+            if (/^on[a-z]/.test(name) || (urlAttributes.has(name) &&
+                /^javascript:/i.test(attribute.value.replace(/[\t\n\r]/g, "").replace(/^[\u0000-\u0020]+/, ""))))
+                active = true;
+        }
+        for (const child of node.childNodes || [])
+            visit(child, includeTemplates);
+        if (includeTemplates && node.content)
+            visit(node.content, true);
+    };
+    visit(document);
+    // Dormant template content cannot instantiate itself. Once authored execution
+    // exists, include its dependencies in the same bounded application policy.
+    if (active)
+        visit(document, true);
+    return {
+        executionMode: application ? "application" : active ? "interactive" : "static",
+        savePolicy: active ? "feedback-only" : "writable",
+        feedbackOnly: active,
+    };
+}
+export function documentExecutionPolicy(page, source, preference = "auto") {
+    if (page.kind === "url")
+        return { executionMode: "application", savePolicy: "feedback-only", feedbackOnly: true };
+    if (page.markdown)
+        return { executionMode: "static", savePolicy: "feedback-only", feedbackOnly: true };
+    const policy = analyzeDocumentExecution(source);
+    return { ...policy, executionMode: preference === "static" ? "static" : policy.executionMode };
+}
+/** Keep inline interactions; the response CSP bounds dynamically created dependencies. */
+export function transformInteractiveHtml(html) {
+    const document = parse(String(html));
+    const unsupportedDependencies = [];
+    let omitted = 0;
+    const visit = (parent) => {
+        parent.childNodes = (parent.childNodes || []).filter((node) => {
+            const unsupported = dependency(node);
+            if (unsupported) {
+                if (unsupportedDependencies.length < 100) {
+                    unsupportedDependencies.push({ ...unsupported, source: String(unsupported.source || "").slice(0, 512) });
+                }
+                else
+                    omitted += 1;
+                return false;
+            }
+            if (node.tagName === "base")
+                return false;
+            if (node.tagName === "meta" && ["content-security-policy", "refresh"].includes((attr(node, "http-equiv") || "").trim().toLowerCase()))
+                return false;
+            if (node.childNodes)
+                visit(node);
+            if (node.content)
+                visit(node.content);
+            return true;
+        });
+    };
+    visit(document);
+    if (omitted)
+        unsupportedDependencies.push({ kind: "additional-dependencies", count: omitted });
+    const notice = INTERACTIVE_FILE_NOTICE + (unsupportedDependencies.length ? " Unsupported dependency elements were removed." : "");
+    const root = document.childNodes.find((node) => node.tagName === "html");
+    if (!root.childNodes.some((node) => node.tagName === "body")) {
+        const body = { nodeName: "body", tagName: "body", attrs: [], namespaceURI: "http://www.w3.org/1999/xhtml", childNodes: [], parentNode: root };
+        root.childNodes = root.childNodes.filter((node) => node.tagName !== "frameset");
+        root.childNodes.push(body);
+    }
+    return { html: serialize(document), unsupportedDependencies, notice };
+}

package/lib/edit-limits.js

@@ -0,0 +1,24 @@
+export const MAX_EDIT_CHARACTERS = 200_000;
+const EDIT_FIELDS = ["before", "after", "before_html", "after_html", "moved_after", "moved_before"];
+export function limitEditFields(input) {
+    const fields = {};
+    const truncatedFields = [];
+    for (const field of EDIT_FIELDS) {
+        const value = input[field];
+        if (typeof value !== "string")
+            continue;
+        let end = 0;
+        let count = 0;
+        // Count Unicode code points, not UTF-16 halves of an astral character.
+        for (const character of value) {
+            if (count === MAX_EDIT_CHARACTERS)
+                break;
+            end += character.length;
+            count += 1;
+        }
+        fields[field] = value.slice(0, end);
+        if (end < value.length)
+            truncatedFields.push(field);
+    }
+    return { fields, truncated: truncatedFields.length > 0, truncated_fields: truncatedFields };
+}

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,19 @@
+/** UI policy 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(" "),
+    };
+}

package/lib/feedback-controller.js

@@ -0,0 +1,113 @@
+import { record } from "./chrome-api.js";
+import { createControllerStore } from "./controller-store.js";
+import { deliverFeedback } from "./history-coordinator.js";
+export function createFeedbackController(options) {
+    let state = { phase: "idle" };
+    let disposed = false;
+    let inFlight = false;
+    let sent = false;
+    const store = createControllerStore(() => ({ ...state, sending: inFlight, sent }));
+    const busy = () => inFlight;
+    const publish = () => { if (!disposed)
+        store.publish(); };
+    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; },
+        getSnapshot: store.getSnapshot,
+        subscribe: store.subscribe,
+        clearSent() { sent = false; if (!busy())
+            state = { phase: "idle" }; publish(); },
+        async send() {
+            if (busy() || disposed || sent)
+                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);
+                        publish();
+                    },
+                    refresh: () => disposed ? Promise.resolve(false) : options.refresh(),
+                });
+                if (disposed)
+                    return;
+                if (outcome.refreshFailure) {
+                    const notice = "Feedback sent. History could not be refreshed; your feedback does not need to be sent again.";
+                    if (sent)
+                        state = { phase: "delivered", notice };
+                    options.warning(notice);
+                }
+                else if (outcome.captureFailure) {
+                    const notice = "Feedback sent. Content comparison may be incomplete.";
+                    if (sent)
+                        state = { phase: "delivered", notice };
+                    options.announce(notice);
+                }
+            }
+            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; store.dispose(); },
+    };
+}