nudge-ui 0.2.1 → 0.2.3

package/dist/inspector/changes/previewDiagnostics.js

@@ -1,16 +1,15 @@
-import { getWorkspaceChanges, subscribeWorkspaceChanges } from "./workspaceChanges.js";
+import { getActiveDraftChanges, getDraftChanges } from "./draftChanges.js";
 const HOST_DOCUMENT = {
     logicalDocument: "host",
     sessionId: "host-document",
 };
-let workspaceRevision = getWorkspaceChanges().revision;
 let activeSessions = new Map([[HOST_DOCUMENT.logicalDocument, HOST_DOCUMENT.sessionId]]);
 let attemptsBySession = new Map();
 let diagnostics = new Map();
 let diagnosticRevision = 0;
 const listeners = new Set();
 function storageKey(document, changeKey) {
-    return `${document.logicalDocument}\u0000${document.sessionId}\u0000${changeKey}`;
+    return `${document.draftId ?? getActiveDraftChanges().draftId}\u0000${document.logicalDocument}\u0000${document.sessionId}\u0000${changeKey}`;
 }
 function sessionKey(document) {
     return `${document.logicalDocument}\u0000${document.sessionId}`;
@@ -26,23 +25,12 @@ function notify() {
     for (const listener of listeners)
         listener();
 }
-function syncWorkspaceRevision() {
-    const nextRevision = getWorkspaceChanges().revision;
-    if (nextRevision === workspaceRevision)
-        return;
-    // Track the revision so late publishes are rejected per key. Do not clear
-    // here: a new commit must preserve earlier diagnostics until they are
-    // re-verified, otherwise every edit deletes every other change's status.
-    workspaceRevision = nextRevision;
-}
-subscribeWorkspaceChanges(syncWorkspaceRevision);
 /** Returns the stable host-document identity for this inspector lifetime. */
 export function getHostPreviewDocument() {
-    return HOST_DOCUMENT;
+    return { ...HOST_DOCUMENT, draftId: getActiveDraftChanges().draftId };
 }
 /** Starts or replaces the live session for one logical document. */
 export function startPreviewDocumentSession(document) {
-    syncWorkspaceRevision();
     const previousSession = activeSessions.get(document.logicalDocument);
     if (previousSession === document.sessionId)
         return;
@@ -76,9 +64,9 @@ export function invalidatePreviewDocumentSession(logicalDocument, sessionId) {
         notify();
 }
 /** Opens a verification attempt for the currently active document session. */
-export function beginPreviewAttempt(document, revision = getWorkspaceChanges().revision) {
-    syncWorkspaceRevision();
-    if (revision !== workspaceRevision || activeSessions.get(document.logicalDocument) !== document.sessionId) {
+export function beginPreviewAttempt(document, revision = getDraftChanges(document.draftId ?? getActiveDraftChanges().draftId).revision) {
+    const draftId = document.draftId ?? getActiveDraftChanges().draftId;
+    if (revision !== getDraftChanges(draftId).revision || activeSessions.get(document.logicalDocument) !== document.sessionId) {
         return null;
     }
     const attempt = (attemptsBySession.get(sessionKey(document)) ?? 0) + 1;
@@ -87,12 +75,11 @@ export function beginPreviewAttempt(document, revision = getWorkspaceChanges().r
     // rejects late publishes per key; wiping would drop every other change's
     // status before it is re-verified (and drop all host status when Canvas
     // verification returns null).
-    return { ...document, workspaceRevision: revision, attempt };
+    return { ...document, draftId, draftRevision: revision, attempt };
 }
 /** Publishes only a result from the active revision, session, and attempt. */
 export function publishPreviewDiagnostic(attempt, changeKey, result) {
-    syncWorkspaceRevision();
-    if (attempt.workspaceRevision !== workspaceRevision
+    if (attempt.draftRevision !== getDraftChanges(attempt.draftId).revision
         || activeSessions.get(attempt.logicalDocument) !== attempt.sessionId
         || attemptsBySession.get(sessionKey(attempt)) !== attempt.attempt) {
         return false;
@@ -101,7 +88,7 @@ export function publishPreviewDiagnostic(attempt, changeKey, result) {
     const previous = diagnostics.get(key);
     if (previous
         && previous.changeKey === changeKey
-        && previous.workspaceRevision === attempt.workspaceRevision
+        && previous.draftRevision === attempt.draftRevision
         && previous.attempt === attempt.attempt
         && sameResult(previous.result, result)) {
         return true;
@@ -127,7 +114,7 @@ export function clearPreviewDiagnostics(changeKeys) {
 export function notifyPreviewDiagnostics() {
     notify();
 }
-export function getPreviewDiagnostic(changeKey, logicalDocument = HOST_DOCUMENT.logicalDocument) {
+export function getPreviewDiagnostic(changeKey, logicalDocument = HOST_DOCUMENT.logicalDocument, draftId = getActiveDraftChanges().draftId) {
     // Pure getter: never sync or notify. It runs on the React render path via
     // StaleChangeIndicator, so side effects here would clear state mid-render.
     // Diagnostics survive workspace revisions until overwritten or explicitly
@@ -135,7 +122,7 @@ export function getPreviewDiagnostic(changeKey, logicalDocument = HOST_DOCUMENT.
     const sessionId = activeSessions.get(logicalDocument);
     if (!sessionId)
         return undefined;
-    return diagnostics.get(storageKey({ logicalDocument, sessionId }, changeKey));
+    return diagnostics.get(storageKey({ logicalDocument, sessionId, draftId }, changeKey));
 }
 /**
  * Host-first read across live documents. The per-document store is observable
@@ -164,7 +151,6 @@ export function getPreviewDiagnosticRevision() {
 }
 /** Test and teardown reset; it does not alter canonical workspace state. */
 export function resetPreviewDiagnostics() {
-    workspaceRevision = getWorkspaceChanges().revision;
     activeSessions = new Map([[HOST_DOCUMENT.logicalDocument, HOST_DOCUMENT.sessionId]]);
     attemptsBySession = new Map();
     diagnostics = new Map();

package/dist/inspector/clientManifest.d.ts

@@ -1,5 +1,5 @@
 import { type NudgeUiRuntimeConfig } from "./runtime/runtimeConfig.js";
-export type { NudgeUiRuntimeConfig } from "./runtime/runtimeConfig.js";
+export type { NudgeUiRuntimeConfig, NudgeUiRuntimeFeatures } from "./runtime/runtimeConfig.js";
 export { detectStylingSystem } from "./runtime/runtimeConfig.js";
 /** Version of the host-to-inspector runtime manifest Interface. */
 export declare const NUDGE_UI_CLIENT_MANIFEST_VERSION = 1;
@@ -24,6 +24,8 @@ export interface NudgeUiClientManifest {
         readonly strategy: "refresh-manifest" | "reload-document";
         readonly events?: readonly string[];
     };
+    /** Set by `NUDGE_UI=1`: automated browsers open the editor instead of the plain app. */
+    readonly inspectAutomatedBrowsers?: true;
 }
 /** Parses and normalizes an external manifest before it replaces inspector state. */
 export declare function parseNudgeUiClientManifest(value: unknown): NudgeUiClientManifest | null;

package/dist/inspector/clientManifest.js

@@ -23,6 +23,7 @@ value) {
             ...(isAgentBridge(value.agentBridge) ? { agentBridge: value.agentBridge } : {}),
             ...(value.document === undefined ? {} : { document: value.document }),
             ...(value.reload === undefined ? {} : { reload: value.reload }),
+            ...(value.inspectAutomatedBrowsers === true ? { inspectAutomatedBrowsers: true } : {}),
         };
     }
     catch {

package/dist/inspector/comments/CommentsOverlay.d.ts

@@ -0,0 +1,2 @@
+import { type ReactElement } from "react";
+export declare function CommentsOverlay(): ReactElement | null;

package/dist/inspector/comments/CommentsOverlay.js

@@ -0,0 +1,250 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from "react";
+import { IconCheck, IconTrash } from "@tabler/icons-react";
+import { useCanvasMode } from "../canvas/viewStore.js";
+import { getRegisteredFrames } from "../canvas/projection.js";
+import { subscribeCanvasRendererMessages } from "../canvas/rendererMessageRouter.js";
+import { RENDERER_ELEMENT_ID_ATTR } from "../canvas/rendererCidIndex.js";
+import { captureRenderedInstance } from "../projection/renderedInstance.js";
+import { IconButton } from "../ui/IconButton.js";
+import { TextInput } from "../ui/TextInput.js";
+import { commentFingerprint, commentViewport, resolveCommentElement } from "./element.js";
+import { commentRoute, getCommentClearRevision, isCommentToolActive, removeComment, saveComment, subscribeComments, useComments, useCommentToolActive } from "./store.js";
+import { isReadingCommentSource, readCommentSource, reconcileComments } from "./verification.js";
+const styles = ".comment-pin {\n  position: fixed;\n  z-index: 10;\n  display: grid;\n  place-items: center;\n  width: var(--icon-size-large);\n  height: var(--icon-size-large);\n  padding: 0;\n  border: 2px solid var(--surface-raised-2x);\n  border-radius: 50%;\n  background: var(--accent);\n  box-shadow: var(--shadow-popup);\n  cursor: pointer;\n  pointer-events: auto;\n}\n\n.comment-editor-backdrop {\n  position: fixed;\n  inset: 0;\n  z-index: 11;\n  pointer-events: auto;\n}\n\n.comment-editor {\n  position: fixed;\n  z-index: 12;\n  display: flex;\n  align-items: center;\n  gap: var(--space-4);\n  width: min(384px, calc(100vw - 16px));\n  box-sizing: border-box;\n  padding: var(--space-8);\n  border-radius: var(--radius-12);\n  background: var(--surface-raised-2x);\n  box-shadow: var(--shadow-popup);\n  pointer-events: auto;\n}\n\n.comment-editor .text-input { flex: 1; min-width: 0; padding-inline: var(--space-8); }\n.comment-editor__error { position: absolute; top: 100%; left: 0; padding: var(--space-8); background: var(--surface-raised-2x); color: var(--text-primary); border-radius: var(--radius-control); }\n";
+function sameAnchor(left, right) {
+    return left?.left === right?.left && left?.top === right?.top;
+}
+function anchorFor(iframe, element) {
+    if (!element.isConnected || iframe.contentDocument !== element.ownerDocument)
+        return null;
+    // Focus view keeps other frames mounted, but their pins must stay hidden.
+    if (getComputedStyle(iframe).visibility !== "visible")
+        return null;
+    const frame = iframe.getBoundingClientRect();
+    const rect = element.getBoundingClientRect();
+    const scale = frame.width / (iframe.clientWidth || frame.width);
+    const left = frame.left + rect.right * scale;
+    const top = frame.top + rect.top * scale;
+    if (top < frame.top || top > frame.bottom || left < frame.left || left > frame.right)
+        return null;
+    return { left, top };
+}
+export function CommentsOverlay() {
+    const mode = useCanvasMode();
+    const comments = useComments();
+    const commentActive = useCommentToolActive();
+    const [draft, setDraft] = useState(null);
+    const [note, setNote] = useState("");
+    const [saving, setSaving] = useState(false);
+    const [error, setError] = useState(null);
+    const [anchors, setAnchors] = useState(new Map());
+    const [draftAnchor, setDraftAnchor] = useState(null);
+    const draftRef = useRef(draft);
+    draftRef.current = draft;
+    const bindings = useRef(new Map());
+    const observations = useRef(new Map());
+    function openDraft(next) {
+        setDraft(next);
+        setNote(next.existing?.note ?? "");
+        setError(null);
+    }
+    useEffect(() => {
+        if (!commentActive)
+            setDraft(null);
+    }, [commentActive]);
+    useEffect(() => {
+        let revision = getCommentClearRevision();
+        return subscribeComments(() => {
+            if (revision === getCommentClearRevision())
+                return;
+            revision = getCommentClearRevision();
+            setDraft(null);
+        });
+    }, []);
+    useEffect(() => {
+        if (!draft)
+            return;
+        function dismissOnEscape(event) {
+            if (event.key !== "Escape")
+                return;
+            event.preventDefault();
+            event.stopPropagation();
+            setDraft(null);
+        }
+        window.addEventListener("keydown", dismissOnEscape, true);
+        return () => window.removeEventListener("keydown", dismissOnEscape, true);
+    }, [draft]);
+    useEffect(() => subscribeCanvasRendererMessages(({ iframe, message }) => {
+        if (message.type === "element-click" && isCommentToolActive()) {
+            const element = iframe.contentDocument?.querySelector(`[${RENDERER_ELEMENT_ID_ATTR}="${message.elementId}"]`);
+            if (element && element.getAttribute("data-cid") === message.cid && (element.getAttribute("data-src") ?? "") === message.src) {
+                openDraft({ element, iframe });
+            }
+        }
+        if (message.type === "element-deselect")
+            setDraft(null);
+        if (message.type === "frame-ready" && iframe.contentDocument) {
+            void reconcileComments(iframe.contentDocument).catch(() => undefined);
+        }
+    }), []);
+    useEffect(() => {
+        if (comments.length === 0 && !draft) {
+            setAnchors(new Map());
+            setDraftAnchor(null);
+            bindings.current.clear();
+            return;
+        }
+        let animationFrame = 0;
+        let previousAnchors = null;
+        let previousDraftAnchor;
+        const refresh = () => {
+            const next = new Map();
+            const offsets = new Map();
+            for (const key of bindings.current.keys()) {
+                if (!comments.some((comment) => key.startsWith(`${comment.id}:`)))
+                    bindings.current.delete(key);
+            }
+            for (const comment of comments) {
+                for (const [cardId, iframe] of getRegisteredFrames()) {
+                    const doc = iframe.contentDocument;
+                    if (!doc || commentRoute(doc) !== comment.route)
+                        continue;
+                    const key = `${comment.id}:${cardId}`;
+                    const bound = bindings.current.get(key);
+                    const element = bound?.iframe === iframe && bound.element.isConnected && bound.element.ownerDocument === doc
+                        ? bound.element : resolveCommentElement(doc, comment.target);
+                    if (!element)
+                        continue;
+                    bindings.current.set(key, { element, iframe });
+                    const anchor = anchorFor(iframe, element);
+                    if (anchor) {
+                        const positionKey = `${cardId}:${anchor.left}:${anchor.top}`;
+                        const offset = offsets.get(positionKey) ?? 0;
+                        next.set(key, { ...anchor, top: anchor.top + offset });
+                        offsets.set(positionKey, offset + 30);
+                    }
+                }
+            }
+            if (!previousAnchors || previousAnchors.size !== next.size
+                || [...next].some(([key, anchor]) => !sameAnchor(previousAnchors?.get(key), anchor))) {
+                previousAnchors = next;
+                setAnchors(next);
+            }
+            const current = draftRef.current;
+            const nextDraftAnchor = current ? anchorFor(current.iframe, current.element) : null;
+            if (previousDraftAnchor === undefined || !sameAnchor(previousDraftAnchor, nextDraftAnchor)) {
+                previousDraftAnchor = nextDraftAnchor;
+                setDraftAnchor(nextDraftAnchor);
+            }
+            if (current && (!current.element.isConnected || current.iframe.contentDocument !== current.element.ownerDocument))
+                setDraft(null);
+            animationFrame = requestAnimationFrame(refresh);
+        };
+        refresh();
+        return () => cancelAnimationFrame(animationFrame);
+    }, [comments, draft]);
+    useEffect(() => {
+        if (!comments.some((comment) => comment.handedOff))
+            return;
+        const refresh = () => {
+            const documents = new Set([...getRegisteredFrames()].map(([, iframe]) => iframe.contentDocument).filter((doc) => doc !== null));
+            for (const [doc, observation] of observations.current) {
+                if (documents.has(doc))
+                    continue;
+                observation.observer.disconnect();
+                if (observation.timer)
+                    clearTimeout(observation.timer);
+                observations.current.delete(doc);
+            }
+            for (const doc of documents) {
+                if (observations.current.has(doc) || !comments.some((item) => item.handedOff && item.route === commentRoute(doc)))
+                    continue;
+                const observation = { observer: new MutationObserver((records) => {
+                        if (isReadingCommentSource(doc))
+                            return;
+                        const sourceChanged = records.some((record) => {
+                            const element = record.target.nodeType === 1 ? record.target : record.target.parentElement;
+                            if (element?.closest('[data-nudge-ui], #nudge-ui-root'))
+                                return false;
+                            if (record.type === "attributes" && (record.attributeName?.startsWith("data-nudge") || record.attributeName?.startsWith("data-projection") || record.attributeName === "data-renderer-id"))
+                                return false;
+                            return true;
+                        });
+                        if (!sourceChanged)
+                            return;
+                        if (observation.timer)
+                            clearTimeout(observation.timer);
+                        observation.timer = setTimeout(() => { void reconcileComments(doc).catch(() => undefined); }, 200);
+                    }), timer: null };
+                observation.observer.observe(doc.documentElement, { subtree: true, childList: true, characterData: true, attributes: true });
+                observations.current.set(doc, observation);
+                void reconcileComments(doc).catch(() => undefined);
+            }
+        };
+        refresh();
+        const timer = setInterval(refresh, 500);
+        return () => {
+            clearInterval(timer);
+            for (const observation of observations.current.values()) {
+                observation.observer.disconnect();
+                if (observation.timer)
+                    clearTimeout(observation.timer);
+            }
+            observations.current.clear();
+        };
+    }, [comments]);
+    async function confirm() {
+        if (!draft || saving || !note.trim())
+            return;
+        const currentDraft = draft;
+        const clearRevision = getCommentClearRevision();
+        const text = note.trim();
+        setSaving(true);
+        setError(null);
+        try {
+            const comment = await readCommentSource(draft.element.ownerDocument, () => {
+                if (!draft.element.isConnected)
+                    return null;
+                const target = captureRenderedInstance(draft.element);
+                if (!target)
+                    return null;
+                return {
+                    id: draft.existing?.id ?? crypto.randomUUID(),
+                    route: commentRoute(draft.element.ownerDocument),
+                    target,
+                    tag: draft.element.tagName.toLowerCase(),
+                    note: text,
+                    baseline: commentFingerprint(draft.element),
+                    viewport: commentViewport(draft.element.ownerDocument),
+                    handedOff: false,
+                };
+            });
+            if (getCommentClearRevision() !== clearRevision)
+                return;
+            if (!comment) {
+                setError("The element changed. Select it again to save your comment.");
+                return;
+            }
+            saveComment(comment);
+            if (draftRef.current === currentDraft)
+                setDraft(null);
+        }
+        catch {
+            setError("Couldn't save this comment. Try again.");
+        }
+        finally {
+            setSaving(false);
+        }
+    }
+    if (mode !== "canvas")
+        return null;
+    return _jsxs(_Fragment, { children: [_jsx("style", { children: styles }), comments.flatMap((comment) => [...anchors].filter(([key]) => key.startsWith(`${comment.id}:`)).map(([key, anchor]) => (_jsx("button", { type: "button", className: "comment-pin", "data-test": "comment-pin", "aria-label": `Comment: ${comment.note}`, title: comment.note, style: anchor, onClick: () => {
+                    const bound = bindings.current.get(key);
+                    if (bound)
+                        openDraft({ ...bound, existing: comment });
+                } }, key)))), draft && draftAnchor ? _jsx("div", { className: "comment-editor-backdrop", "aria-hidden": "true", onClick: () => setDraft(null) }) : null, draft && draftAnchor ? _jsxs("form", { className: "comment-editor", "data-test": "comment-editor", role: "dialog", "aria-label": "Element comment", style: { left: Math.max(8, Math.min(draftAnchor.left + 12, window.innerWidth - 400)), top: Math.max(8, Math.min(draftAnchor.top, window.innerHeight - 90)) }, onSubmit: (event) => { event.preventDefault(); void confirm(); }, children: [_jsx(TextInput, { appearance: "embedded", autoFocus: true, "aria-label": "Comment", "data-test": "comment-input", placeholder: "Leave a comment", maxLength: 2000, value: note, disabled: saving, onChange: (event) => setNote(event.target.value) }), _jsx(IconButton, { label: "Confirm comment", variant: "primary", type: "submit", disabled: saving || !note.trim(), "data-test": "comment-confirm", children: _jsx(IconCheck, { size: 18 }) }), draft.existing ? _jsx(IconButton, { label: "Delete comment", variant: "quiet", disabled: saving, onClick: () => {
+                            removeComment(draft.existing.id);
+                            setDraft(null);
+                        }, children: _jsx(IconTrash, { size: 16 }) }) : null, error ? _jsx("span", { className: "comment-editor__error", role: "alert", children: error }) : null] }) : null] });
+}

package/dist/inspector/comments/element.d.ts

@@ -0,0 +1,6 @@
+import type { RenderedInstanceRef } from "../changes/editModel.js";
+/** Retains a changed target only when its source site still identifies one output. */
+export declare function resolveCommentElement(doc: Document, target: RenderedInstanceRef): HTMLElement | null;
+export declare function commentViewport(doc: Document): string;
+/** Captures rendered content and appearance, excluding inspector identity and transient cursors. */
+export declare function commentFingerprint(element: HTMLElement): string;

package/dist/inspector/comments/element.js

@@ -0,0 +1,47 @@
+import { resolveRenderedInstance } from "../projection/renderedInstance.js";
+import { sourceSiteSelector } from "../selection/sourceSite.js";
+/** Retains a changed target only when its source site still identifies one output. */
+export function resolveCommentElement(doc, target) {
+    const exact = resolveRenderedInstance(doc, target);
+    if (exact.status === "resolved")
+        return exact.element;
+    const selector = sourceSiteSelector(target.sourceSite.cid, target.sourceSite.src);
+    if (!selector)
+        return null;
+    const candidates = Array.from(doc.querySelectorAll(selector));
+    if (candidates.length === 1)
+        return candidates[0];
+    const { props, ariaLabel } = target.locator;
+    if (!props && !ariaLabel)
+        return null;
+    const matching = candidates.filter((element) => element.getAttribute("data-cprops") === props
+        && element.getAttribute("aria-label") === (ariaLabel ?? null));
+    return matching.length === 1 ? matching[0] : null;
+}
+export function commentViewport(doc) {
+    return `${doc.defaultView?.innerWidth}:${doc.defaultView?.innerHeight}`;
+}
+/** Captures rendered content and appearance, excluding inspector identity and transient cursors. */
+export function commentFingerprint(element) {
+    const clone = element.cloneNode(true);
+    for (const node of [clone, ...clone.querySelectorAll("*")]) {
+        for (const attribute of [...node.attributes]) {
+            if (attribute.name.startsWith("data-nudge") || attribute.name.startsWith("data-projection")
+                || ["data-cid", "data-src", "data-cprops", "data-renderer-id"].includes(attribute.name))
+                node.removeAttribute(attribute.name);
+        }
+        if (node instanceof element.ownerDocument.defaultView.HTMLElement) {
+            node.style.removeProperty("cursor");
+            if (node.getAttribute("style") === "")
+                node.removeAttribute("style");
+        }
+    }
+    const style = element.ownerDocument.defaultView?.getComputedStyle(element);
+    const properties = ["color", "background-color", "font-family", "font-size", "font-weight", "line-height",
+        "padding", "margin", "gap", "display", "border", "border-radius", "box-shadow", "opacity", "width", "height"];
+    const value = JSON.stringify([clone.outerHTML, properties.map((property) => style?.getPropertyValue(property) ?? "")]);
+    let hash = 2166136261;
+    for (let index = 0; index < value.length; index += 1)
+        hash = Math.imul(hash ^ value.charCodeAt(index), 16777619);
+    return (hash >>> 0).toString(16);
+}

package/dist/inspector/comments/store.d.ts

@@ -0,0 +1,29 @@
+import { type RenderedInstanceRef } from "../changes/editModel.js";
+import { type DraftTarget } from "../drafts/model.js";
+export interface ElementComment {
+    readonly id: string;
+    readonly route: string;
+    readonly target: RenderedInstanceRef;
+    readonly tag: string;
+    readonly note: string;
+    readonly baseline: string;
+    readonly viewport: string;
+    readonly handedOff: boolean;
+}
+export declare function getComments(): readonly ElementComment[];
+export declare function loadComments(): void;
+export declare function subscribeComments(listener: () => void): () => void;
+export declare function useComments(): readonly ElementComment[];
+export declare function getCommentsForTarget(target: DraftTarget): readonly ElementComment[];
+export declare function useFrameComments(): readonly ElementComment[];
+export declare function saveComment(comment: ElementComment): void;
+export declare function removeComment(id: string): void;
+export declare function getCommentClearRevision(): number;
+/** Clears saved notes and invalidates any open or saving comment draft. */
+export declare function clearComments(target?: DraftTarget): void;
+/** Arms only the exact notes successfully copied or accepted by an agent. */
+export declare function markCommentsHandedOff(sent: readonly ElementComment[]): void;
+export declare function setCommentToolActive(active: boolean): void;
+export declare function isCommentToolActive(): boolean;
+export declare function useCommentToolActive(): boolean;
+export declare function commentRoute(doc: Document): string;

package/dist/inspector/comments/store.js

@@ -0,0 +1,121 @@
+import { useSyncExternalStore } from "react";
+import { isRenderedInstanceRef } from "../changes/editModel.js";
+import { useCanvasCards, useFocusedCardId, useSelectedCardId } from "../canvas/canvasStore.js";
+import { canWriteWorkspace } from "../canvas/workspaceLease.js";
+import { contentEditTarget } from "../canvas/frameContent.js";
+import { documentTarget, targetKey } from "../drafts/model.js";
+import { getNudgeUiRuntimeConfig } from "../runtime/runtimeConfig.js";
+let comments = [];
+let loadedKey = null;
+let loadedDemo = false;
+const listeners = new Set();
+const toolListeners = new Set();
+let commentToolActive = false;
+let clearRevision = 0;
+function storageKey() {
+    return `nudge-ui:${getNudgeUiRuntimeConfig().projectId}:comments:v1`;
+}
+function isComment(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const item = value;
+    return ["id", "route", "tag", "note", "baseline", "viewport"].every((key) => typeof item[key] === "string")
+        && typeof item.handedOff === "boolean" && isRenderedInstanceRef(item.target);
+}
+export function getComments() {
+    const key = storageKey();
+    const demo = getNudgeUiRuntimeConfig().demo === true;
+    if (loadedKey !== key || loadedDemo !== demo) {
+        loadedKey = key;
+        loadedDemo = demo;
+        try {
+            const saved = demo ? [] : JSON.parse(localStorage.getItem(key) ?? "[]");
+            comments = Array.isArray(saved) ? saved.filter(isComment) : [];
+        }
+        catch {
+            comments = [];
+        }
+    }
+    return comments;
+}
+export function loadComments() {
+    loadedKey = null;
+    clearRevision += 1;
+    getComments();
+    for (const listener of listeners)
+        listener();
+}
+function publish(next) {
+    if (!canWriteWorkspace())
+        return;
+    comments = next;
+    if (getNudgeUiRuntimeConfig().demo !== true) {
+        try {
+            localStorage.setItem(storageKey(), JSON.stringify(next));
+        }
+        catch { }
+    }
+    for (const listener of listeners)
+        listener();
+}
+export function subscribeComments(listener) {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+}
+export function useComments() {
+    return useSyncExternalStore(subscribeComments, getComments, getComments);
+}
+export function getCommentsForTarget(target) {
+    return getComments().filter((comment) => targetKey(documentTarget(comment.route)) === targetKey(target));
+}
+export function useFrameComments() {
+    useComments();
+    const cards = useCanvasCards();
+    const selected = useSelectedCardId();
+    const focused = useFocusedCardId();
+    const card = cards.find((card) => card.id === selected) ?? cards.find((card) => card.id === focused) ?? cards[0];
+    return getCommentsForTarget(card ? contentEditTarget(card.content) : documentTarget(window.location.href));
+}
+export function saveComment(comment) {
+    const current = getComments();
+    publish([...current.filter((item) => item.id !== comment.id), comment]);
+}
+export function removeComment(id) {
+    publish(getComments().filter((item) => item.id !== id));
+}
+export function getCommentClearRevision() { return clearRevision; }
+/** Clears saved notes and invalidates any open or saving comment draft. */
+export function clearComments(target) {
+    if (!canWriteWorkspace())
+        return;
+    getComments();
+    clearRevision += 1;
+    const cleared = new Set((target ? getCommentsForTarget(target) : getComments()).map((comment) => comment.id));
+    publish(getComments().filter((comment) => !cleared.has(comment.id)));
+}
+/** Arms only the exact notes successfully copied or accepted by an agent. */
+export function markCommentsHandedOff(sent) {
+    publish(getComments().map((item) => sent.some((candidate) => candidate.id === item.id && candidate.note === item.note)
+        ? { ...item, handedOff: true } : item));
+}
+export function setCommentToolActive(active) {
+    if (commentToolActive === active)
+        return;
+    commentToolActive = active;
+    for (const listener of toolListeners)
+        listener();
+}
+export function isCommentToolActive() { return commentToolActive; }
+export function useCommentToolActive() {
+    return useSyncExternalStore((listener) => {
+        toolListeners.add(listener);
+        return () => toolListeners.delete(listener);
+    }, isCommentToolActive, isCommentToolActive);
+}
+export function commentRoute(doc) {
+    const url = new URL(doc.location.href);
+    url.hash = "";
+    url.searchParams.delete("nudge-ui");
+    url.searchParams.sort();
+    return url.href;
+}

package/dist/inspector/comments/verification.d.ts

@@ -0,0 +1,5 @@
+export declare function isReadingCommentSource(doc: Document): boolean;
+/** Serializes clean reads and restores the latest previews even if the read fails. */
+export declare function readCommentSource<T>(doc: Document, read: () => T): Promise<T | null>;
+/** Changed, uniquely located elements resolve after handoff; missing and ambiguous targets remain. */
+export declare function reconcileComments(doc: Document): Promise<void>;

package/dist/inspector/comments/verification.js

@@ -0,0 +1,52 @@
+import { getDraftChanges } from "../changes/draftChanges.js";
+import { documentTarget, targetKey } from "../drafts/model.js";
+import { isCanvasProjectionRevisionCurrent, projectDraftToDocument } from "../canvas/projection.js";
+import { commentFingerprint, commentViewport, resolveCommentElement } from "./element.js";
+import { commentRoute, getCommentClearRevision, getComments, removeComment } from "./store.js";
+const documentReads = new WeakMap();
+const readingDocuments = new WeakSet();
+export function isReadingCommentSource(doc) { return readingDocuments.has(doc); }
+/** Serializes clean reads and restores the latest previews even if the read fails. */
+export function readCommentSource(doc, read) {
+    const previous = documentReads.get(doc) ?? Promise.resolve();
+    const operation = previous.catch(() => undefined).then(async () => {
+        readingDocuments.add(doc);
+        try {
+            const revision = await projectDraftToDocument(doc, { changes: [], structuralChanges: [] });
+            if (revision === null || !isCanvasProjectionRevisionCurrent(doc, revision))
+                return null;
+            return read();
+        }
+        finally {
+            try {
+                await projectDraftToDocument(doc, getDraftChanges(targetKey(documentTarget(doc.location.href))));
+                // Deliver projection mutation records before accepting another source signal.
+                await new Promise((resolve) => setTimeout(resolve, 0));
+            }
+            finally {
+                readingDocuments.delete(doc);
+            }
+        }
+    });
+    documentReads.set(doc, operation);
+    return operation;
+}
+/** Changed, uniquely located elements resolve after handoff; missing and ambiguous targets remain. */
+export async function reconcileComments(doc) {
+    const revision = getCommentClearRevision();
+    const sent = getComments().filter((item) => item.handedOff && item.route === commentRoute(doc));
+    if (sent.length === 0)
+        return;
+    const resolved = await readCommentSource(doc, () => sent.filter((item) => {
+        if (item.viewport !== commentViewport(doc))
+            return false;
+        const element = resolveCommentElement(doc, item.target);
+        return element !== null && commentFingerprint(element) !== item.baseline;
+    }));
+    if (revision !== getCommentClearRevision())
+        return;
+    for (const item of resolved ?? []) {
+        if (getComments().some((current) => current.id === item.id && current.note === item.note && current.handedOff))
+            removeComment(item.id);
+    }
+}