nudge-ui 0.2.0

package/dist/inspector/agent/verification.js

@@ -0,0 +1,207 @@
+import { changeKey, tokenReference } from "../changes/model.js";
+import { selectorForManagedChange } from "../changes/managedStyleProjection.js";
+import { getWorkspaceChanges } from "../changes/workspaceChanges.js";
+import { getChangesList, isComponentChange, isTextContentChange, isTokenChange, reconcileVerifiedWorkspaceChanges, } from "../changes/changesLog.js";
+import { verifyPreview } from "../projection/managedStylesheet.js";
+import { resolveRenderedInstance } from "../projection/renderedInstance.js";
+import { getStructuralChanges, } from "../projection/structuralProjection.js";
+import { resolveTextProjectionTarget, resolveTextProjectionTextNode, } from "../projection/textProjection.js";
+import { applyHostWorkspaceProjection, compileWorkspaceProjection, } from "../projection/workspaceProjection.js";
+const dispatches = new Map();
+function stableJsonValue(value) {
+    if (Array.isArray(value))
+        return value.map(stableJsonValue);
+    if (!value || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .filter(([, entry]) => entry !== undefined)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, entry]) => [key, stableJsonValue(entry)]));
+}
+function stableSerialized(value) {
+    return JSON.stringify(stableJsonValue(value));
+}
+/** Stable, preview-metadata-free identity for one prompt handoff record. */
+export function handoffChangeFingerprint(change) {
+    return stableSerialized(change);
+}
+/** Stable identity for one structural record included in a prompt handoff. */
+export function handoffStructuralFingerprint(change) {
+    return stableSerialized(change);
+}
+function requestedStyleValue(change) {
+    if (isTokenChange(change))
+        return change.rawValue;
+    if (change.newToken)
+        return tokenReference(change.newToken);
+    return change.rawValue ?? "";
+}
+function verifyStyle(change, doc) {
+    if (!isTokenChange(change) && (change.state ?? "base") !== "base")
+        return false;
+    const selector = selectorForManagedChange(change);
+    if (!selector)
+        return false;
+    let targets;
+    try {
+        targets = Array.from(doc.querySelectorAll(selector));
+    }
+    catch {
+        return false;
+    }
+    const requested = requestedStyleValue(change);
+    return requested.length > 0
+        && targets.length > 0
+        && targets.every((target) => verifyPreview(target, change.property, requested).status === "applied");
+}
+function verifyText(change, doc) {
+    const resolved = resolveTextProjectionTarget(doc, change.target, change.after);
+    if (resolved.status !== "resolved")
+        return false;
+    const node = resolveTextProjectionTextNode(resolved.element, change.target, change.after);
+    if (node)
+        return node.nodeValue === change.after;
+    return change.target.textNodePath === undefined
+        && change.after.length === 0
+        && (resolved.element.textContent ?? "") === "";
+}
+/**
+ * A delete verifies when its target no longer resolves in the document once
+ * the preview is lifted: the source really removed it. Ambiguous evidence
+ * still means identical elements are present, so only a definitive miss
+ * verifies.
+ */
+function verifyStructuralDelete(change, doc) {
+    return resolveRenderedInstance(doc, change.target).status === "missing";
+}
+/**
+ * A move verifies when the element sits at its recorded destination without
+ * the preview holding it there. The projection rebuild returns a cleanly
+ * applied move preview to its captured origin, so such records conservatively
+ * stay unverified instead of trusting rendered placement alone.
+ */
+function verifyStructuralMove(change, doc) {
+    const target = resolveRenderedInstance(doc, change.target);
+    if (target.status !== "resolved")
+        return false;
+    const parent = resolveRenderedInstance(doc, change.destination.parent);
+    if (parent.status !== "resolved")
+        return false;
+    if (target.element.parentElement !== parent.element)
+        return false;
+    if (!change.destination.before)
+        return target.element.nextElementSibling === null;
+    const before = resolveRenderedInstance(doc, change.destination.before);
+    return before.status === "resolved" && target.element.nextElementSibling === before.element;
+}
+function verifiedStructuralChangeIds(eligible, doc) {
+    const verified = new Set();
+    for (const change of eligible) {
+        const applied = change.kind === "delete"
+            ? verifyStructuralDelete(change, doc)
+            : verifyStructuralMove(change, doc);
+        if (applied)
+            verified.add(change.id);
+    }
+    return verified;
+}
+/**
+ * Positively verifies browser-observable source results after the inspector's
+ * own projections have been removed. Component props and interaction states
+ * intentionally remain unresolved because rendered output alone cannot prove
+ * that their source was updated.
+ */
+export function verifiedChangeKeys(sentChanges, doc = document) {
+    const verified = new Set();
+    for (const change of sentChanges) {
+        if (isComponentChange(change))
+            continue;
+        const applied = isTextContentChange(change)
+            ? verifyText(change, doc)
+            : verifyStyle(change, doc);
+        if (applied)
+            verified.add(changeKey(change));
+    }
+    return verified;
+}
+/** Captures the exact canonical edits associated with one dispatched prompt. */
+export function recordAgentDispatch(revision, changes, structuralChanges = []) {
+    dispatches.set(revision, {
+        changes: changes.map((change) => structuredClone(change)),
+        structuralChanges: structuralChanges.map((change) => structuredClone(change)),
+    });
+}
+/** Drops a captured revision when the bridge rejects its dispatch. */
+export function discardAgentDispatch(revision) {
+    dispatches.delete(revision);
+}
+/** Returns how many canonical edits were in flight for one dispatch. */
+export function getAgentDispatchSize(revision) {
+    const snapshot = dispatches.get(revision);
+    if (!snapshot)
+        return 0;
+    return snapshot.changes.length + snapshot.structuralChanges.length;
+}
+function afterBrowserPaint() {
+    if (typeof requestAnimationFrame !== "function")
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
+    });
+}
+/**
+ * Reconciles only records that still equal the sent snapshot and that remain
+ * observable after removing Nudge's own preview. Newer edits and ambiguous
+ * records are preserved.
+ */
+export async function verifyAndReconcileHandoff(snapshot) {
+    const sentByKey = new Map(snapshot.changes.map((change) => [changeKey(change), handoffChangeFingerprint(change)]));
+    const current = getChangesList();
+    const eligible = current.filter((change) => sentByKey.get(changeKey(change)) === handoffChangeFingerprint(change));
+    const eligibleKeys = new Set(eligible.map(changeKey));
+    const remaining = current.filter((change) => !eligibleKeys.has(changeKey(change)));
+    // The same "still unchanged" rule for structural intent: only canonical
+    // records byte-identical to the dispatched snapshot may be reconciled.
+    const sentStructural = new Map(snapshot.structuralChanges.map((change) => [change.id, handoffStructuralFingerprint(change)]));
+    const currentStructural = getStructuralChanges();
+    const eligibleStructural = currentStructural.filter((change) => sentStructural.get(change.id) === handoffStructuralFingerprint(change));
+    const eligibleStructuralIds = new Set(eligibleStructural.map((change) => change.id));
+    const remainingStructural = currentStructural.filter((change) => !eligibleStructuralIds.has(change.id));
+    try {
+        const currentWorkspace = getWorkspaceChanges();
+        applyHostWorkspaceProjection(compileWorkspaceProjection({
+            revision: currentWorkspace.revision,
+            changes: remaining,
+            structuralChanges: remainingStructural,
+        }));
+        await afterBrowserPaint();
+        const verified = verifiedChangeKeys(eligible);
+        const verifiedStructural = verifiedStructuralChangeIds(eligibleStructural, document);
+        // A user can make another inspector edit while the two-frame verification
+        // window is open. Recheck byte identity immediately before reconciliation
+        // so a newer value at the same key can never be removed.
+        const currentByKey = new Map(getChangesList().map((change) => [changeKey(change), handoffChangeFingerprint(change)]));
+        const stillVerified = new Set([...verified].filter((key) => currentByKey.get(key) === sentByKey.get(key)));
+        const currentStructuralById = new Map(getStructuralChanges().map((change) => [change.id, handoffStructuralFingerprint(change)]));
+        const stillVerifiedStructural = new Set([...verifiedStructural].filter((id) => currentStructuralById.get(id) === sentStructural.get(id)));
+        return reconcileVerifiedWorkspaceChanges(stillVerified, stillVerifiedStructural);
+    }
+    finally {
+        // Reconciliation reapplies the canonical set. If it was unable to write
+        // (for example, a read-only Canvas lease), restore the untouched set here.
+        const canonicalWorkspace = getWorkspaceChanges();
+        applyHostWorkspaceProjection(compileWorkspaceProjection(canonicalWorkspace));
+    }
+}
+/** Reconciles the captured records for one completed connected-agent request. */
+export async function verifyAndReconcileAgentDispatch(revision) {
+    const snapshot = dispatches.get(revision);
+    if (!snapshot)
+        return 0;
+    dispatches.delete(revision);
+    return verifyAndReconcileHandoff(snapshot);
+}
+/** Test/session reset for in-memory dispatch snapshots. */
+export function resetAgentVerification() {
+    dispatches.clear();
+}

package/dist/inspector/canvas/CanvasCard.d.ts

@@ -0,0 +1,10 @@
+import { type ReactElement } from "react";
+import { type CanvasCard } from "./canvasStore.js";
+import type { InspectorSession } from "../session/sessionFactory.js";
+interface CanvasCardProps {
+    card: CanvasCard;
+    onEdit?: (card: CanvasCard) => void;
+    documentOwner?: InspectorSession;
+}
+export declare function CanvasCard({ card, onEdit, documentOwner }: CanvasCardProps): ReactElement;
+export {};

package/dist/inspector/canvas/CanvasCard.js

@@ -0,0 +1,275 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { CANVAS_RENDERER_ATTR } from "./roleDetection.js";
+import { removeCanvasCard, duplicateCard, updateCardTitle, updateCardUrl, resizeCard, setCardPosition, selectCard, getSelectedCardId, useSelectedCardId, useFocusedCardId, useBoardCamera } from "./canvasStore.js";
+import { IconRefresh, IconPlayerPlay, IconCopy, IconArrowsDiagonal } from "@tabler/icons-react";
+import { PROTOCOL_VERSION, isRendererMessageFor, } from "./frameProtocol.js";
+import { registerCardFrame, registerCardFrameSource, unregisterCardFrame, sendProjectionToCard, invalidateCanvasPreviewDocument, PROJECT_ID, WORKSPACE_ID } from "./projection.js";
+import { IconButton } from "../ui/IconButton.js";
+import { Button } from "../ui/Button.js";
+import { setSelectedElement } from "../selection/selectionStore.js";
+import { clearCanvasStructuralProjectionReports } from "../projection/structuralProjection.js";
+import { clearCanvasRenderedInstanceProjectionReports } from "../projection/renderedInstance.js";
+import { clearCanvasTextProjectionReports } from "../projection/textProjection.js";
+import { getCanvasToolbarScale } from "./toolbarScale.js";
+import { getCanvasResizeHandleScale } from "./resizeHandleScale.js";
+import { disposeBrowserCssInspection } from "../inspection/browserCssInspectionRegistry.js";
+import { releaseDocumentProjection } from "../projection/structuralProjection.js";
+const MIN_CARD_WIDTH = 200;
+const MIN_CARD_HEIGHT = 150;
+export function CanvasCard({ card, onEdit, documentOwner }) {
+    const iframeRef = useRef(null);
+    const documentSessionRef = useRef(null);
+    const [loadState, setLoadState] = useState("loading");
+    const [errorMessage, setErrorMessage] = useState(null);
+    const camera = useBoardCamera();
+    const selectedCardId = useSelectedCardId();
+    const focusedCardId = useFocusedCardId();
+    const isSelected = selectedCardId === card.id;
+    const isFocused = focusedCardId === card.id;
+    const toolbarScale = getCanvasToolbarScale(camera.zoom);
+    const resizeHandleScale = getCanvasResizeHandleScale(camera.zoom);
+    const disposeDocumentSession = useCallback(() => {
+        documentSessionRef.current?.session.dispose();
+        documentSessionRef.current = null;
+    }, []);
+    const bindDocumentSession = useCallback(() => {
+        const frameDocument = iframeRef.current?.contentDocument;
+        if (!documentOwner || !frameDocument)
+            return;
+        if (documentSessionRef.current?.document === frameDocument)
+            return;
+        disposeDocumentSession();
+        const session = documentOwner.createDocumentSession(frameDocument);
+        session.registerCleanup(() => disposeBrowserCssInspection(frameDocument));
+        session.registerCleanup(() => releaseDocumentProjection(frameDocument));
+        documentSessionRef.current = { document: frameDocument, session };
+    }, [disposeDocumentSession, documentOwner]);
+    useEffect(() => {
+        const iframe = iframeRef.current;
+        if (!iframe)
+            return;
+        registerCardFrameSource(card.id, iframe);
+        bindDocumentSession();
+        return () => {
+            disposeDocumentSession();
+            unregisterCardFrame(card.id);
+        };
+    }, [bindDocumentSession, card.id, disposeDocumentSession]);
+    function handleReload() {
+        if (iframeRef.current) {
+            if (getSelectedCardId() === card.id)
+                setSelectedElement(null);
+            disposeDocumentSession();
+            invalidateCanvasPreviewDocument(card.id);
+            setLoadState("loading");
+            setErrorMessage(null);
+            const currentSrc = iframeRef.current.src;
+            iframeRef.current.setAttribute("src", currentSrc);
+        }
+    }
+    function handleRemove() {
+        if (getSelectedCardId() === card.id)
+            setSelectedElement(null);
+        removeCanvasCard(card.id);
+    }
+    function handleEdit() {
+        onEdit?.(card);
+    }
+    function handleDuplicate() {
+        duplicateCard(card.id);
+    }
+    /** The controller half of the handshake: announce workspace identity. */
+    function sendParentReady() {
+        iframeRef.current?.contentWindow?.postMessage({
+            type: "parent-ready",
+            protocolVersion: PROTOCOL_VERSION,
+            projectId: PROJECT_ID,
+            workspaceId: WORKSPACE_ID,
+            cardId: card.id,
+        }, window.location.origin);
+    }
+    useEffect(() => {
+        function onMessage(event) {
+            if (event.origin !== window.location.origin)
+                return;
+            if (event.source !== iframeRef.current?.contentWindow)
+                return;
+            const msg = event.data;
+            if (!msg || typeof msg !== "object")
+                return;
+            // A renderer whose runtime finished booting after the iframe load event
+            // asks for the identity announcement it may have missed.
+            // SAFETY: Renderer messages arrive as unvalidated structured clones, so the discriminant must be read structurally.
+            if (msg.type === "renderer-hello") {
+                // SAFETY: The `type === "renderer-hello"` branch above selects exactly the hello payload shape.
+                const hello = msg;
+                if (hello.protocolVersion !== PROTOCOL_VERSION)
+                    return;
+                sendParentReady();
+                return;
+            }
+            if (!isRendererMessageFor(msg, {
+                projectId: PROJECT_ID,
+                workspaceId: WORKSPACE_ID,
+                cardId: card.id,
+            }))
+                return;
+            // SAFETY: isRendererMessageFor validated the frame identity and message shape above.
+            const data = msg;
+            if (data.type === "frame-ready") {
+                setLoadState("ready");
+                setErrorMessage(null);
+                if (data.title)
+                    updateCardTitle(card.id, data.title);
+                if (data.url)
+                    updateCardUrl(card.id, data.url);
+                if (iframeRef.current) {
+                    registerCardFrame(card.id, iframeRef.current);
+                    sendProjectionToCard(card, iframeRef.current);
+                }
+                return;
+            }
+            if (data.type === "frame-metadata") {
+                if (data.title)
+                    updateCardTitle(card.id, data.title);
+                if (data.url)
+                    updateCardUrl(card.id, data.url);
+                return;
+            }
+            if (data.type === "frame-error") {
+                setLoadState("error");
+                setErrorMessage(data.message || "Frame failed to load");
+                return;
+            }
+        }
+        window.addEventListener("message", onMessage);
+        return () => {
+            window.removeEventListener("message", onMessage);
+        };
+    }, [card.id]);
+    useEffect(() => {
+        if (loadState !== "loading")
+            return;
+        const timeout = setTimeout(() => {
+            setLoadState("error");
+            setErrorMessage("Frame load timed out");
+        }, 15000);
+        return () => clearTimeout(timeout);
+    }, [loadState]);
+    // A late handshake still recovers: the message listener stays installed in
+    // the error state, so a slow renderer's eventual frame-ready flips the card
+    // back to "ready" without user action.
+    useEffect(() => {
+        const iframe = iframeRef.current;
+        if (!iframe)
+            return;
+        function onLoad() {
+            if (getSelectedCardId() === card.id)
+                setSelectedElement(null);
+            disposeDocumentSession();
+            // A reload creates a new renderer document; do not show diagnostics
+            // produced by the old frame while its replacement is handshaking.
+            invalidateCanvasPreviewDocument(card.id);
+            clearCanvasStructuralProjectionReports(card.id);
+            clearCanvasRenderedInstanceProjectionReports(card.id);
+            clearCanvasTextProjectionReports(card.id);
+            bindDocumentSession();
+            sendParentReady();
+        }
+        iframe.addEventListener("load", onLoad);
+        return () => iframe.removeEventListener("load", onLoad);
+    }, [bindDocumentSession, card.id, disposeDocumentSession]);
+    const [isDragging, setIsDragging] = useState(false);
+    const dragRef = useRef({ startX: 0, startY: 0, cardX: 0, cardY: 0 });
+    const handleToolbarPointerDown = useCallback((e) => {
+        // SAFETY: pointer events on the card target are HTMLElements in this DOM context.
+        const target = e.target;
+        if (target.closest("button"))
+            return;
+        if (getSelectedCardId() !== card.id)
+            setSelectedElement(null);
+        selectCard(card.id);
+        e.stopPropagation();
+        e.preventDefault();
+        dragRef.current = {
+            startX: e.clientX,
+            startY: e.clientY,
+            cardX: card.x,
+            cardY: card.y,
+        };
+        setIsDragging(true);
+        // SAFETY: pointerdown targets are HTMLElements in the card DOM.
+        e.target.setPointerCapture(e.pointerId);
+        function onMove(ev) {
+            const dx = (ev.clientX - dragRef.current.startX) / camera.zoom;
+            const dy = (ev.clientY - dragRef.current.startY) / camera.zoom;
+            setCardPosition(card.id, dragRef.current.cardX + dx, dragRef.current.cardY + dy);
+        }
+        function onUp() {
+            setIsDragging(false);
+            window.removeEventListener("pointermove", onMove);
+            window.removeEventListener("pointerup", onUp);
+        }
+        window.addEventListener("pointermove", onMove);
+        window.addEventListener("pointerup", onUp);
+    }, [card.id, card.x, card.y, camera.zoom]);
+    const handleCardPointerDown = useCallback(() => {
+        if (getSelectedCardId() !== card.id)
+            setSelectedElement(null);
+        selectCard(card.id);
+    }, [card.id]);
+    const handleResizeStart = useCallback((e) => {
+        e.stopPropagation();
+        e.preventDefault();
+        const startX = e.clientX;
+        const startY = e.clientY;
+        const startWidth = card.width;
+        const startHeight = card.height;
+        // SAFETY: pointerdown targets are HTMLElements in the card DOM.
+        e.target.setPointerCapture(e.pointerId);
+        function onMove(ev) {
+            const dx = (ev.clientX - startX) / camera.zoom;
+            const dy = (ev.clientY - startY) / camera.zoom;
+            const newWidth = Math.max(MIN_CARD_WIDTH, startWidth + dx);
+            const newHeight = Math.max(MIN_CARD_HEIGHT, startHeight + dy);
+            resizeCard(card.id, newWidth, newHeight);
+        }
+        function onUp() {
+            window.removeEventListener("pointermove", onMove);
+            window.removeEventListener("pointerup", onUp);
+        }
+        window.addEventListener("pointermove", onMove);
+        window.addEventListener("pointerup", onUp);
+    }, [card.id, card.width, card.height, camera.zoom]);
+    function handleResizeKeyDown(event) {
+        const step = event.shiftKey ? 40 : 20;
+        if (event.key === "ArrowRight")
+            resizeCard(card.id, card.width + step, card.height);
+        else if (event.key === "ArrowLeft")
+            resizeCard(card.id, Math.max(MIN_CARD_WIDTH, card.width - step), card.height);
+        else if (event.key === "ArrowDown")
+            resizeCard(card.id, card.width, card.height + step);
+        else if (event.key === "ArrowUp")
+            resizeCard(card.id, card.width, Math.max(MIN_CARD_HEIGHT, card.height - step));
+        else
+            return;
+        event.preventDefault();
+    }
+    return (_jsxs("div", { className: `canvas-card${isDragging ? " is-dragging" : ""}${isSelected ? " is-selected" : ""}${isFocused ? " is-focused" : ""}`, "data-card-id": card.id, style: {
+            position: "absolute",
+            left: card.x,
+            top: card.y,
+            width: card.width,
+            height: card.height,
+        }, onPointerDown: handleCardPointerDown, children: [_jsxs("div", { className: "canvas-card__toolbar", onPointerDown: handleToolbarPointerDown, children: [_jsx("div", { className: "canvas-card__drag-surface", "data-test": `canvas-card-drag-${card.id}`, children: _jsxs("span", { className: "canvas-card__dimensions", "data-test": `canvas-card-dimensions-${card.id}`, style: {
+                                transform: `scale(${toolbarScale})`,
+                                transformOrigin: "left bottom",
+                            }, children: [Math.round(card.width), " \u00D7 ", Math.round(card.height), " px"] }) }), _jsxs("div", { className: "canvas-card__actions", style: {
+                            transform: `scale(${toolbarScale})`,
+                            transformOrigin: "right bottom",
+                        }, children: [_jsxs(Button, { variant: "secondary", size: "default", "data-test": `canvas-card-preview-${card.id}`, onClick: handleEdit, children: [_jsx(IconPlayerPlay, { size: 14, stroke: 1.8, "aria-hidden": "true" }), "Page view"] }), _jsx(IconButton, { label: "Duplicate card", variant: "secondary", size: "default", "data-test": `canvas-card-duplicate-${card.id}`, onClick: handleDuplicate, children: _jsx(IconCopy, { size: 14, stroke: 1.8, "aria-hidden": "true" }) }), _jsx(IconButton, { label: "Reload card", variant: "secondary", size: "default", "data-test": `canvas-card-reload-${card.id}`, onClick: handleReload, children: _jsx(IconRefresh, { size: 14, stroke: 1.8, "aria-hidden": "true" }) })] })] }), _jsxs("div", { className: "canvas-card__frame", children: [loadState === "loading" ? (_jsx("div", { className: "canvas-card__loading", "data-test": `canvas-card-loading-${card.id}`, children: "Loading preview..." })) : loadState === "error" ? (_jsxs("div", { className: "canvas-card__error", "data-test": `canvas-card-error-${card.id}`, children: [_jsx("p", { children: errorMessage || "Frame could not be loaded" }), _jsxs("div", { className: "canvas-card__error-actions", children: [_jsx(Button, { size: "compact", variant: "secondary", onClick: handleReload, children: "Retry" }), _jsx(Button, { size: "compact", variant: "danger", onClick: handleRemove, children: "Remove" })] })] })) : null, _jsx("iframe", { ref: iframeRef, className: "canvas-card__iframe", src: card.url, title: card.title || card.url, [CANVAS_RENDERER_ATTR]: "", sandbox: "allow-scripts allow-same-origin allow-forms allow-popups", "data-test": `canvas-card-iframe-${card.id}` })] }), _jsx("div", { className: "canvas-card__resize-handle", "data-test": `canvas-card-resize-${card.id}`, style: {
+                    transform: `scale(${resizeHandleScale})`,
+                    transformOrigin: "right bottom",
+                }, onPointerDown: handleResizeStart, onKeyDown: handleResizeKeyDown, role: "button", "aria-label": "Resize card", tabIndex: 0, children: _jsx(IconArrowsDiagonal, { size: 12, "aria-hidden": "true" }) })] }));
+}

package/dist/inspector/canvas/CanvasElementOverlay.d.ts

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