nudge-ui 0.2.2 → 0.2.3

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

package/dist/inspector/drafts/model.d.ts

@@ -0,0 +1,35 @@
+import type { DraftContents } from "../changes/draftChanges.js";
+export type DraftTarget = {
+    readonly kind: "application";
+    readonly route: string;
+} | {
+    readonly kind: "html";
+    readonly artifactId: string;
+    readonly path: string;
+};
+/** A draft's ID is its target key, so every frame showing the same page or iteration edits one draft. */
+export interface Draft {
+    readonly id: string;
+    readonly target: DraftTarget;
+    readonly revision: number;
+    readonly contents: DraftContents;
+    readonly sketchIds: readonly string[];
+}
+export interface DraftSnapshot {
+    readonly projectId: string;
+    readonly drafts: readonly Draft[];
+}
+export declare function applicationTarget(url?: string): {
+    kind: "application";
+    route: string;
+};
+export declare function htmlTarget(artifactId: string): {
+    kind: "html";
+    artifactId: string;
+    path: string;
+};
+/** Maps a captured document URL to the draft that owns it: an iteration preview or an application page. */
+export declare function documentTarget(url: string): DraftTarget;
+export declare function targetKey(target: DraftTarget): string;
+export declare function targetFromKey(key: string): DraftTarget | null;
+export declare function isDraftTarget(value: unknown): value is DraftTarget;

package/dist/inspector/drafts/model.js

@@ -0,0 +1,45 @@
+import { normalizeUrl, normalizedUrlKey } from "../canvas/normalizeUrl.js";
+const ARTIFACT_PATH = /^\/__nudge_ui__\/artifacts\/([a-f0-9-]{36})\//i;
+export function applicationTarget(url = window.location.href) {
+    const page = new URL(url, window.location.href);
+    page.searchParams.delete("nudge-ui");
+    page.searchParams.sort();
+    const normalized = normalizeUrl(page.href);
+    return { kind: "application", route: normalizedUrlKey(normalized) };
+}
+export function htmlTarget(artifactId) {
+    return { kind: "html", artifactId, path: `.nudge/artifacts/${artifactId}/document.html` };
+}
+/** Maps a captured document URL to the draft that owns it: an iteration preview or an application page. */
+export function documentTarget(url) {
+    const artifactId = ARTIFACT_PATH.exec(new URL(url, window.location.href).pathname)?.[1];
+    return artifactId ? htmlTarget(artifactId) : applicationTarget(url);
+}
+export function targetKey(target) {
+    return target.kind === "application" ? `application:${target.route}` : `html:${target.artifactId}`;
+}
+export function targetFromKey(key) {
+    if (key.startsWith("html:"))
+        return htmlTarget(key.slice("html:".length));
+    if (!key.startsWith("application:"))
+        return null;
+    const target = { kind: "application", route: key.slice("application:".length) };
+    return isDraftTarget(target) ? target : null;
+}
+export function isDraftTarget(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const target = value;
+    if (target.kind === "application") {
+        if (typeof target.route !== "string")
+            return false;
+        try {
+            return applicationTarget(target.route).route === target.route;
+        }
+        catch {
+            return false;
+        }
+    }
+    return target.kind === "html" && typeof target.artifactId === "string"
+        && target.path === `.nudge/artifacts/${target.artifactId}/document.html`;
+}

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

@@ -0,0 +1,28 @@
+import { type FrameContent } from "../canvas/frameContent.js";
+import { type DraftContents } from "../changes/draftChanges.js";
+import type { SketchDocument } from "../sketch/model.js";
+import { type Draft, type DraftSnapshot } from "./model.js";
+export declare function draftIdForContent(content: FrameContent): string;
+export declare function draftIdForCard(cardId: string): string | null;
+export declare function sketchOwner(document: SketchDocument): string | null;
+export declare function getDraft(id: string): Draft | null;
+export declare function getDraftForCard(cardId: string): Draft | null;
+export declare function getDraftContentsForCard(cardId: string): DraftContents | null;
+export declare function persistDrafts(): void;
+/** Replaces every in-memory draft with the stored drafts, so a tab that takes over never writes stale edits. */
+export declare function loadDrafts(nextProjectId: string, options?: {
+    persistent?: boolean;
+}): void;
+export declare function activateDraftForCard(cardId: string): void;
+export declare function activateDraft(draftId: string, preferredCardId?: string): void;
+export declare function clearSavedIterationDraft(cardId: string, expectedRevision?: number): boolean;
+/** Returns the first preferred frame that exists, then the first frame. */
+export declare function getEditableCardId(...preferredCardIds: readonly (string | null | undefined)[]): string | null;
+export declare function assignSketchToDraft(draftId: string, sketchId: string): void;
+export declare function sketchBelongsToCard(document: SketchDocument, cardId: string | null): boolean;
+export declare function subscribeDrafts(listener: () => void): () => void;
+export declare function getDraftsSnapshot(): DraftSnapshot;
+export declare function useDrafts(): DraftSnapshot;
+/** Discards stored and in-memory drafts for the current project. */
+export declare function clearDrafts(): void;
+export declare function resetDrafts(): void;