nudge-ui 0.2.3 → 0.2.5

package/dist/inspector/canvas/sessionStore.js

@@ -1,11 +1,12 @@
+import { inspectorStorage } from "../runtime/inspectorStorage.js";
 import { isFrameContent } from "./frameContent.js";
 import { clearComments } from "../comments/store.js";
+import { clearSketchesForProject } from "../sketch/store.js";
+import { clearSketchClipboardHandoff } from "../sketch/handoff.js";
 import { documentTarget, targetFromKey } from "../drafts/model.js";
-import { canEditDraft, getActiveDraftChanges, isDraftLocked } from "../changes/draftChanges.js";
 import { getFrameGroups, isFrameGroup, getCanvasCards, getFocusedCardId, getSelectedCardId, hydrateCanvasStore, removeCanvasCard, } from "./canvasStore.js";
 import { getCanvasMode, getCanvasPresentation, getBoardCamera, setBoardCamera, } from "./viewStore.js";
 import { applyRules } from "../projection/managedStylesheet.js";
-import { clearActiveDraft } from "../changes/changesLog.js";
 import { removeManagedSheet } from "../projection/managedStylesheet.js";
 import { setSelectedElement } from "../selection/selectionStore.js";
 import { canWriteWorkspace } from "./workspaceLease.js";
@@ -13,7 +14,7 @@ import { resetStructuralDeleteProjection, } from "../projection/structuralProjec
 import { projectToAllReadyCards } from "./projection.js";
 import { getNudgeUiRuntimeConfig } from "../runtime/runtimeConfig.js";
 import { clearClipboardHandoff, getClipboardHandoffSnapshot, hydrateClipboardHandoff, isClipboardHandoffSnapshot, } from "../prompt/clipboardHandoff.js";
-import { activateDraftForCard, clearDrafts, persistDrafts } from "../drafts/store.js";
+import { activateDraftForCard, canEditDraft, clearActiveDraft, clearDrafts, getActiveDraftChanges, isDraftLocked, persistDrafts, } from "../drafts/store.js";
 const SCHEMA_VERSION = 17;
 const STORAGE_PREFIX = "nudge-ui";
 function projectId() {
@@ -79,7 +80,7 @@ function persistSessionUnchecked() {
     try {
         persistDrafts();
         const session = buildSession();
-        localStorage.setItem(storageKey(projectId()), JSON.stringify(session));
+        inspectorStorage()?.setItem(storageKey(projectId()), JSON.stringify(session));
         return true;
     }
     catch {
@@ -92,7 +93,7 @@ export function hydrateSession() {
         return { restored: false, changeCount: 0 };
     let raw = null;
     try {
-        raw = localStorage.getItem(storageKey(projectId()));
+        raw = inspectorStorage()?.getItem(storageKey(projectId())) ?? null;
     }
     catch {
         return { restored: false, changeCount: 0 };
@@ -211,24 +212,26 @@ export function hydrateSession() {
 }
 function safeDiscard() {
     try {
-        localStorage.removeItem(storageKey(projectId()));
+        inspectorStorage()?.removeItem(storageKey(projectId()));
     }
     catch {
         // ignore
     }
 }
-/** Clears the active frame's edit draft while preserving canvas geometry and other drafts. */
+/** Clears the active draft, its comments, and project sketches while preserving canvas geometry and other drafts. */
 export function clearSelectedFrameChanges() {
     if (!canEditDraft())
-        return;
+        return Promise.resolve();
     const cardId = getSelectedCardId() ?? getFocusedCardId();
     if (cardId)
         activateDraftForCard(cardId);
     clearComments(targetFromKey(getActiveDraftChanges().draftId) ?? documentTarget(window.location.href));
     clearActiveDraft();
+    clearSketchClipboardHandoff();
     setSelectedElement(null);
     projectToAllReadyCards();
     scheduleAutoSave();
+    return clearSketchesForProject();
 }
 export function clearSession() {
     if (isDraftLocked())
@@ -236,7 +239,7 @@ export function clearSession() {
     if (!canWriteWorkspace())
         return;
     try {
-        localStorage.removeItem(storageKey(projectId()));
+        inspectorStorage()?.removeItem(storageKey(projectId()));
     }
     catch {
         // ignore

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

@@ -1,4 +1,4 @@
-import type { ChangeRecord } from "../changes/changesLog.js";
+import { type ChangeRecord } from "../changes/types.js";
 export type StaleChangeStatus = "unverified" | "verified" | "stale" | "token-drift";
 export interface StaleChangeInfo {
     index: number;

package/dist/inspector/canvas/staleChangeDetector.js

@@ -1,13 +1,11 @@
-import { draftIdForCard } from "../drafts/store.js";
-import { isPreviewableChange, isTokenChange, } from "../changes/changesLog.js";
+import { draftIdForCard, getActiveDraftChanges } from "../drafts/store.js";
+import { isPreviewableChange, isTokenChange, } from "../changes/types.js";
 import { changeKey } from "../changes/model.js";
 import { beginPreviewAttempt, clearPreviewDiagnostics, getHostPreviewDocument, notifyPreviewDiagnostics, publishPreviewDiagnostic, } from "../changes/previewDiagnostics.js";
-import { getActiveDraftChanges } from "../changes/draftChanges.js";
 import { getCanvasPreviewDocument, getRegisteredFrames } from "./projection.js";
-import { findCanvasFrameBySource, PROJECT_ID, WORKSPACE_ID } from "./projection.js";
+import { subscribeCanvasRendererMessages } from "./rendererMessageRouter.js";
 import { getCanvasCards } from "./canvasStore.js";
 import { getCanvasMode } from "./viewStore.js";
-import { isRendererMessageFor } from "./frameProtocol.js";
 import { getNudgeUiRuntimeConfig } from "../runtime/runtimeConfig.js";
 const VERIFICATION_TIMEOUT_MS = 5000;
 const STALE_CHECK_DEBOUNCE_MS = 100;
@@ -15,6 +13,7 @@ let verificationTimer = null;
 let debounceTimer = null;
 let pendingChanges = null;
 let pendingAttempts = new Map();
+let stopFrameReady = null;
 function checkSelectorInDocument(doc, selector) {
     try {
         return doc.querySelectorAll(selector).length > 0;
@@ -189,22 +188,10 @@ export function startStaleDetection(changes) {
         verificationTimer = null;
         notifyPreviewDiagnostics();
     }, VERIFICATION_TIMEOUT_MS);
-    window.addEventListener("message", handleFrameReady);
-}
-function handleFrameReady(event) {
-    if (event.origin !== window.location.origin)
-        return;
-    const msg = event.data;
-    const frame = findCanvasFrameBySource(event.source);
-    if (!frame || !isRendererMessageFor(msg, {
-        projectId: PROJECT_ID,
-        workspaceId: WORKSPACE_ID,
-        cardId: frame.cardId,
-    }) || msg.type !== "frame-ready")
-        return;
-    if (!pendingChanges)
-        return;
-    scheduleStaleCheck();
+    stopFrameReady ??= subscribeCanvasRendererMessages(({ message }) => {
+        if (message.type === "frame-ready" && pendingChanges)
+            scheduleStaleCheck();
+    });
 }
 export function cancelStaleDetection() {
     if (verificationTimer) {
@@ -217,7 +204,8 @@ export function cancelStaleDetection() {
     }
     pendingChanges = null;
     pendingAttempts = new Map();
-    window.removeEventListener("message", handleFrameReady);
+    stopFrameReady?.();
+    stopFrameReady = null;
     notifyPreviewDiagnostics();
 }
 export function isVerificationPending() {

package/dist/inspector/changes/codecs.d.ts

@@ -32,7 +32,9 @@ export interface SerializableElementChange {
         component: string;
     };
     runtimeEvidence?: NonNullable<ElementChangeRecord["runtimeEvidence"]>;
+    sourceEvidence?: NonNullable<ElementChangeRecord["sourceEvidence"]>;
     scope?: EditScope;
+    sourceInstanceCount?: number;
     instanceOverride?: RenderedInstanceOverride;
     state?: NonNullable<ElementChangeRecord["state"]>;
 }

package/dist/inspector/changes/codecs.js

@@ -16,7 +16,7 @@ export function isSerializableElementChangeValue(value) {
         || !hasOnlyKeys(value, [
             "kind", "cid", "file", "line", "column", "selector", "property",
             "sourceProperty", "sourceAuthoredValue", "oldToken", "newToken", "rawValue",
-            "oldRawValue", "source", "runtimeEvidence", "scope", "instanceOverride", "state",
+            "oldRawValue", "source", "runtimeEvidence", "sourceEvidence", "scope", "sourceInstanceCount", "instanceOverride", "state",
         ])
         || (value.kind !== undefined && value.kind !== "element")
         || typeof value.cid !== "string"
@@ -33,7 +33,9 @@ export function isSerializableElementChangeValue(value) {
         || (value.rawValue !== undefined && typeof value.rawValue !== "string")
         || (value.oldRawValue !== undefined && typeof value.oldRawValue !== "string")
         || (value.runtimeEvidence !== undefined && !isRuntimeElementEvidenceValue(value.runtimeEvidence))
+        || (value.sourceEvidence !== undefined && !isSourceElementEvidenceValue(value.sourceEvidence))
         || !isEditScopeValue(value.scope)
+        || (value.sourceInstanceCount !== undefined && (!Number.isSafeInteger(value.sourceInstanceCount) || value.sourceInstanceCount < 1))
         || (value.instanceOverride !== undefined && value.scope !== "rendered-instance")
         || (value.scope === "rendered-instance" && !isRenderedInstanceOverride(value.instanceOverride))
         || (value.state !== undefined && !isElementStateValue(value.state))) {
@@ -115,7 +117,9 @@ export function serializeElementChange(change) {
         oldRawValue: change.oldRawValue,
         source: change.source,
         runtimeEvidence: change.runtimeEvidence ? { ...change.runtimeEvidence } : undefined,
+        sourceEvidence: change.sourceEvidence ? { ...change.sourceEvidence } : undefined,
         scope: change.scope === "rendered-instance" ? "rendered-instance" : "source-site",
+        ...(change.sourceInstanceCount !== undefined ? { sourceInstanceCount: change.sourceInstanceCount } : {}),
         instanceOverride: change.scope === "rendered-instance" ? change.instanceOverride : undefined,
         state: change.state,
     };
@@ -161,6 +165,9 @@ export function serializeTextContentChange(change) {
             props: change.target.props,
             ariaLabel: change.target.ariaLabel,
             beforeText: change.target.beforeText,
+            ...(change.target.tagName !== undefined ? { tagName: change.target.tagName } : {}),
+            ...(change.target.elementId !== undefined ? { elementId: change.target.elementId } : {}),
+            ...(change.target.domPath !== undefined ? { domPath: change.target.domPath } : {}),
             ...(change.target.textNodePath?.length
                 ? { textNodePath: [...change.target.textNodePath] }
                 : {}),
@@ -200,7 +207,9 @@ export function deserializeElementChange(serialized) {
         oldRawValue: serialized.oldRawValue,
         source: serialized.source,
         runtimeEvidence: serialized.runtimeEvidence ? { ...serialized.runtimeEvidence } : undefined,
+        sourceEvidence: serialized.sourceEvidence ? { ...serialized.sourceEvidence } : undefined,
         scope: serialized.scope ?? "source-site",
+        ...(serialized.sourceInstanceCount !== undefined ? { sourceInstanceCount: serialized.sourceInstanceCount } : {}),
         instanceOverride: serialized.scope === "rendered-instance" ? serialized.instanceOverride : undefined,
         state: serialized.state,
     };
@@ -245,6 +254,9 @@ export function deserializeTextContentChange(serialized) {
             props: serialized.target.props,
             ariaLabel: serialized.target.ariaLabel,
             beforeText: serialized.target.beforeText,
+            ...(serialized.target.tagName !== undefined ? { tagName: serialized.target.tagName } : {}),
+            ...(serialized.target.elementId !== undefined ? { elementId: serialized.target.elementId } : {}),
+            ...(serialized.target.domPath !== undefined ? { domPath: serialized.target.domPath } : {}),
             ...(serialized.target.textNodePath?.length
                 ? { textNodePath: [...serialized.target.textNodePath] }
                 : {}),
@@ -324,12 +336,24 @@ function isComponentInvocationEvidenceValue(value) {
 }
 function isRuntimeElementEvidenceValue(value) {
     return isRecord(value)
-        && hasOnlyKeys(value, ["reason", "tagName", "text", "props", "ariaLabel"])
+        && hasOnlyKeys(value, ["reason", "tagName", "text", "props", "ariaLabel", "domPath", "elementId"])
         && (value.reason === undefined || value.reason === "runtime-created" || value.reason === "unannotated")
         && typeof value.tagName === "string"
         && (typeof value.text === "string" || value.text === null)
         && (typeof value.props === "string" || value.props === null)
-        && (typeof value.ariaLabel === "string" || value.ariaLabel === null);
+        && (typeof value.ariaLabel === "string" || value.ariaLabel === null)
+        && (value.domPath === undefined || typeof value.domPath === "string" || value.domPath === null)
+        && (value.elementId === undefined || typeof value.elementId === "string" || value.elementId === null);
+}
+function isSourceElementEvidenceValue(value) {
+    return isRecord(value)
+        && hasOnlyKeys(value, ["tagName", "props", "text", "ariaLabel", "domPath", "elementId"])
+        && typeof value.tagName === "string"
+        && (typeof value.props === "string" || value.props === null)
+        && (value.text === undefined || typeof value.text === "string" || value.text === null)
+        && (value.ariaLabel === undefined || typeof value.ariaLabel === "string" || value.ariaLabel === null)
+        && (value.domPath === undefined || typeof value.domPath === "string" || value.domPath === null)
+        && (value.elementId === undefined || typeof value.elementId === "string" || value.elementId === null);
 }
 function isTokenRefValue(value) {
     if (value === null)

package/dist/inspector/changes/draftPreview.d.ts

@@ -0,0 +1,12 @@
+import type { DraftChangesSnapshot, DraftProjectionEvent } from "../drafts/draftStore.js";
+/** The host document's preview of the active draft. */
+export interface DraftPreview {
+    project(snapshot: DraftChangesSnapshot, event: DraftProjectionEvent): void;
+    dispose(): void;
+}
+/**
+ * Projects the active draft into the host document and verifies the managed
+ * CSS off the commit path (0044). Verification re-checks the full surviving
+ * set: a new rule can change cascade or specificity for earlier changes.
+ */
+export declare function createDraftPreview(readActive: () => DraftChangesSnapshot): DraftPreview;

package/dist/inspector/changes/draftPreview.js

@@ -0,0 +1,133 @@
+import { getSelectedElement } from "../selection/selectionStore.js";
+import { changeKey } from "./model.js";
+import { verifyManagedStyleProjection } from "./managedStyleProjection.js";
+import { isPreviewableChange } from "./types.js";
+import { beginPreviewAttempt, clearPreviewDiagnostics, getHostPreviewDocument, publishPreviewDiagnostic, } from "./previewDiagnostics.js";
+import { clearStructuralProjectionReports, pruneStructuralProjectionReports } from "../projection/structuralProjection.js";
+import { applyHostDraftProjection, compileDraftProjection } from "../projection/draftProjection.js";
+import { isEditorShellDocument } from "../runtime/editorShell.js";
+import { isOriginalPreviewActive, subscribeOriginalPreview } from "../shell/originalPreview.js";
+/**
+ * Projects the active draft into the host document and verifies the managed
+ * CSS off the commit path (0044). Verification re-checks the full surviving
+ * set: a new rule can change cascade or specificity for earlier changes.
+ */
+export function createDraftPreview(readActive) {
+    let pendingTargets = new Map();
+    let handle = null;
+    function reapply(snapshot) {
+        // While hold-to-view-original is active the host document intentionally
+        // shows the page without inspector changes. Releasing re-projects.
+        if (isOriginalPreviewActive())
+            return;
+        if (!isEditorShellDocument())
+            applyHostDraftProjection(compileDraftProjection(snapshot));
+    }
+    function flushVerification() {
+        handle = null;
+        // Probing the original preview would report the held-back changes as
+        // conflicts. Keep the pending targets; releasing re-verifies them.
+        if (isOriginalPreviewActive())
+            return;
+        const targets = pendingTargets;
+        pendingTargets = new Map();
+        // The editor shell has no application document. Renderer diagnostics are
+        // owned by renderer projection reports.
+        if (targets.size === 0 || isEditorShellDocument())
+            return;
+        const current = readActive();
+        const attempt = beginPreviewAttempt(getHostPreviewDocument(), current.revision);
+        if (!attempt)
+            return;
+        for (const change of current.changes) {
+            if (!isPreviewableChange(change))
+                continue;
+            const key = changeKey(change);
+            if (!targets.has(key))
+                continue;
+            const result = verifyManagedStyleProjection(change, targets.get(key) ?? null);
+            if (result)
+                publishPreviewDiagnostic(attempt, key, result);
+        }
+    }
+    function scheduleVerification() {
+        if (handle !== null)
+            return;
+        const view = typeof window !== "undefined" ? window : undefined;
+        if (view && typeof view.requestIdleCallback === "function") {
+            handle = view.requestIdleCallback(flushVerification, { timeout: 200 });
+        }
+        else if (view && typeof view.requestAnimationFrame === "function") {
+            handle = view.requestAnimationFrame(flushVerification);
+        }
+        else {
+            handle = setTimeout(flushVerification, 0);
+        }
+    }
+    function markForVerification(snapshot, verificationTargets) {
+        const selectedElement = getSelectedElement()?.domElement ?? null;
+        let added = false;
+        for (const key of snapshot.changes.map(changeKey)) {
+            if (!pendingTargets.has(key))
+                added = true;
+            // Keep the latest commit context for a merged key. The element may be in
+            // an iframe, so this is also the document for verification.
+            pendingTargets.set(key, verificationTargets?.get(key) ?? selectedElement);
+        }
+        if (added)
+            scheduleVerification();
+    }
+    const stopOriginalPreview = subscribeOriginalPreview(() => {
+        if (isEditorShellDocument())
+            return;
+        const snapshot = readActive();
+        if (isOriginalPreviewActive()) {
+            applyHostDraftProjection({
+                sourceRevision: snapshot.revision,
+                managedStyles: { rules: [], css: "" },
+                instanceOverrides: [],
+                structuralChanges: [],
+                textContentChanges: [],
+                componentOverrides: [],
+            });
+            return;
+        }
+        reapply(snapshot);
+        // A flush during the hold kept its targets without scheduling, so marking
+        // alone would find every key present and schedule nothing.
+        markForVerification(snapshot);
+        if (pendingTargets.size > 0)
+            scheduleVerification();
+    });
+    return {
+        project(snapshot, event) {
+            switch (event.kind) {
+                case "edit":
+                    reapply(snapshot);
+                    markForVerification(snapshot, event.verificationTargets);
+                    return;
+                case "reconcile":
+                    reapply(snapshot);
+                    pruneStructuralProjectionReports(event.structuralIds);
+                    markForVerification(snapshot);
+                    return;
+                case "switch":
+                    pendingTargets.clear();
+                    reapply(snapshot);
+                    markForVerification(snapshot);
+                    return;
+                case "reset":
+                    // A deferred verification must not inspect a new record with the
+                    // selection context of the cleared one.
+                    pendingTargets.clear();
+                    clearPreviewDiagnostics();
+                    clearStructuralProjectionReports();
+                    reapply(snapshot);
+            }
+        },
+        dispose() {
+            stopOriginalPreview();
+            pendingTargets.clear();
+        },
+    };
+}

package/dist/inspector/changes/editModel.d.ts

@@ -18,8 +18,22 @@ export interface RenderedInstanceRef {
         text: string | null;
         /** An accessible name can distinguish icon-only repeated controls. */
         ariaLabel?: string | null;
+        /** Rendered facts used to reattach generated identities after reload. */
+        tagName?: string;
+        domPath?: string | null;
+        elementId?: string | null;
+        /**
+         * The component invocation whose entire output is this element. Present
+         * only when evidence alone cannot tell identical outputs apart.
+         */
+        invocation?: InvocationRef;
     };
 }
+/** A component callsite, as stamped by the compiler, and its component name. */
+export interface InvocationRef {
+    callsiteId: string;
+    componentName: string;
+}
 export interface RenderedInstanceOverride {
     id: string;
     target: RenderedInstanceRef;
@@ -40,6 +54,10 @@ export interface TextProjectionTarget {
     props: string | null;
     ariaLabel: string | null;
     beforeText: string;
+    /** Optional prompt details; never used to resolve or group text targets. */
+    tagName?: string;
+    elementId?: string | null;
+    domPath?: string | null;
     /** Document-local evidence for a text node inside safe mixed markup. */
     textNodePath?: readonly number[];
 }

package/dist/inspector/changes/editModel.js

@@ -1,3 +1,9 @@
+function isInvocationRef(value) {
+    return isRecord(value)
+        && hasOnlyKeys(value, ["callsiteId", "componentName"])
+        && typeof value.callsiteId === "string" && value.callsiteId.length > 0 && value.callsiteId.length <= 1024
+        && typeof value.componentName === "string" && value.componentName.length > 0 && value.componentName.length <= 256;
+}
 export function isRenderedInstanceRef(value) {
     if (!isRecord(value) || !hasOnlyKeys(value, ["sourceSite", "locator"]))
         return false;
@@ -8,13 +14,17 @@ export function isRenderedInstanceRef(value) {
         || typeof source.cid !== "string"
         || typeof source.src !== "string"
         || !isRecord(locator)
-        || !hasOnlyKeys(locator, ["kind", "occurrence", "props", "text", "ariaLabel"]))
+        || !hasOnlyKeys(locator, ["kind", "occurrence", "props", "text", "ariaLabel", "tagName", "domPath", "elementId", "invocation"]))
         return false;
     return locator.kind === "evidence"
         && Number.isSafeInteger(locator.occurrence) && locator.occurrence >= 0
         && (typeof locator.props === "string" || locator.props === null)
         && (typeof locator.text === "string" || locator.text === null)
-        && (locator.ariaLabel === undefined || typeof locator.ariaLabel === "string" || locator.ariaLabel === null);
+        && (locator.ariaLabel === undefined || typeof locator.ariaLabel === "string" || locator.ariaLabel === null)
+        && (locator.tagName === undefined || typeof locator.tagName === "string")
+        && (locator.domPath === undefined || typeof locator.domPath === "string" || locator.domPath === null)
+        && (locator.elementId === undefined || typeof locator.elementId === "string" || locator.elementId === null)
+        && (locator.invocation === undefined || isInvocationRef(locator.invocation));
 }
 export function isRenderedInstanceOverride(value) {
     return isRecord(value)
@@ -39,7 +49,7 @@ export function isStyleRuleContextValue(value) {
 }
 export function isTextProjectionTargetValue(value) {
     if (!isRecord(value)
-        || !hasOnlyKeys(value, ["sourceSite", "occurrence", "props", "ariaLabel", "beforeText", "textNodePath"])) {
+        || !hasOnlyKeys(value, ["sourceSite", "occurrence", "props", "ariaLabel", "beforeText", "textNodePath", "tagName", "elementId", "domPath"])) {
         return false;
     }
     const occurrence = value.occurrence;
@@ -51,6 +61,9 @@ export function isTextProjectionTargetValue(value) {
         || (typeof props !== "string" && props !== null)
         || (typeof ariaLabel !== "string" && ariaLabel !== null)
         || typeof beforeText !== "string"
+        || (value.tagName !== undefined && typeof value.tagName !== "string")
+        || (value.elementId !== undefined && value.elementId !== null && typeof value.elementId !== "string")
+        || (value.domPath !== undefined && value.domPath !== null && typeof value.domPath !== "string")
         || (textNodePath !== undefined
             && (!Array.isArray(textNodePath)
                 || textNodePath.length === 0

package/dist/inspector/changes/managedStyleProjection.js

@@ -2,6 +2,7 @@ import { verifyPreview } from "../projection/managedStylesheet.js";
 import { getSelectedElement } from "../selection/selectionStore.js";
 import { instanceSelector } from "../projection/renderedInstance.js";
 import { selectorForInteractionState } from "../shell/styleState.js";
+import { selectorForInteractionStatePreview } from "../shell/interactionStatePreview.js";
 import { isComponentChange, isTextContentChange, isTokenChange, } from "./types.js";
 import { tokenReference } from "./model.js";
 function requestedStyleValue(change) {
@@ -81,7 +82,7 @@ export function verifyManagedStyleProjection(change, selectedElement, ownerDocum
     let targets = [];
     try {
         const selector = selectorForManagedChange(change);
-        targets = selector ? Array.from(ownerDocument.querySelectorAll(selector)) : [];
+        targets = selector ? Array.from(ownerDocument.querySelectorAll(selectorForInteractionStatePreview(selector))) : [];
     }
     catch {
         targets = [];

package/dist/inspector/changes/previewDiagnostics.js

@@ -1,4 +1,4 @@
-import { getActiveDraftChanges, getDraftChanges } from "./draftChanges.js";
+import { getActiveDraftChanges, getDraftChanges } from "../drafts/store.js";
 const HOST_DOCUMENT = {
     logicalDocument: "host",
     sessionId: "host-document",

package/dist/inspector/changes/types.d.ts

@@ -4,7 +4,7 @@ import type { EditScope, RenderedInstanceOverride, StyleRuleContext, TextContent
 /** Bounded rendered facts retained for one element without an authored source location. */
 export interface RuntimeElementEvidence {
     /**
-     * Why the location is unknown; prompts phrase their guidance accordingly.
+     * Why the element has no authored source location.
      * Omitted by legacy records, which are all runtime-created DOM.
      */
     reason?: "runtime-created" | "unannotated";
@@ -12,6 +12,19 @@ export interface RuntimeElementEvidence {
     text: string | null;
     props: string | null;
     ariaLabel: string | null;
+    /** Nearest-ancestor selector path; omitted by records captured before it existed. */
+    domPath?: string | null;
+    elementId?: string | null;
+}
+/** Bounded authored facts for one annotated element. */
+export interface SourceElementEvidence {
+    tagName: string;
+    props: string | null;
+    /** Rendered identification details; omitted by older saved changes. */
+    text?: string | null;
+    ariaLabel?: string | null;
+    domPath?: string | null;
+    elementId?: string | null;
 }
 export interface ElementChangeRecord {
     kind?: "element";
@@ -37,7 +50,11 @@ export interface ElementChangeRecord {
     };
     /** Present when the selected element has a document-local runtime identity. */
     runtimeEvidence?: RuntimeElementEvidence;
+    /** Authored facts that relocate the source site after its position shifts. */
+    sourceEvidence?: SourceElementEvidence;
     scope?: EditScope;
+    /** Matching rendered items when captured; presentation only, absent in older edits. */
+    sourceInstanceCount?: number;
     /** Durable, controller-owned target for one rendered output. */
     instanceOverride?: RenderedInstanceOverride;
     state?: "base" | "hover" | "active" | "focus" | "focus-visible" | "disabled";

package/dist/inspector/comments/CommentsOverlay.js

@@ -4,7 +4,9 @@ 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 { measureFrameViewport, toViewportPoint } from "../canvas/frameConnection.js";
+import { canvasFrameElement } from "../canvas/canvasFrame.js";
+import { getElementComputedStyle } from "../runtime/domRealm.js";
 import { captureRenderedInstance } from "../projection/renderedInstance.js";
 import { IconButton } from "../ui/IconButton.js";
 import { TextInput } from "../ui/TextInput.js";
@@ -12,21 +14,21 @@ import { commentFingerprint, commentViewport, resolveCommentElement } from "./el
 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";
+import { InspectorStyle } from "../ui/InspectorStyle.js";
 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")
+    // Focus view keeps real frames mounted, but their pins must stay hidden.
+    const frameElement = canvasFrameElement(iframe);
+    if (frameElement && getElementComputedStyle(frameElement).visibility !== "visible")
         return null;
-    const frame = iframe.getBoundingClientRect();
+    const frame = measureFrameViewport(iframe);
     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)
+    const { x: left, y: top } = toViewportPoint(frame, { x: rect.right, y: rect.top });
+    if (top < frame.top || top > frame.top + frame.height || left < frame.left || left > frame.left + frame.width)
         return null;
     return { left, top };
 }
@@ -75,17 +77,17 @@ export function CommentsOverlay() {
         window.addEventListener("keydown", dismissOnEscape, true);
         return () => window.removeEventListener("keydown", dismissOnEscape, true);
     }, [draft]);
-    useEffect(() => subscribeCanvasRendererMessages(({ iframe, message }) => {
+    useEffect(() => subscribeCanvasRendererMessages(({ frame, 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 });
-            }
+            const element = frame.element(message);
+            if (element)
+                openDraft({ element, iframe: frame.iframe });
         }
         if (message.type === "element-deselect")
             setDraft(null);
-        if (message.type === "frame-ready" && iframe.contentDocument) {
-            void reconcileComments(iframe.contentDocument).catch(() => undefined);
+        const frameDocument = frame.document();
+        if (message.type === "frame-ready" && frameDocument) {
+            void reconcileComments(frameDocument).catch(() => undefined);
         }
     }), []);
     useEffect(() => {
@@ -239,7 +241,7 @@ export function CommentsOverlay() {
     }
     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: () => {
+    return _jsxs(_Fragment, { children: [_jsx(InspectorStyle, { css: 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 });

package/dist/inspector/comments/element.js

@@ -1,17 +1,24 @@
 import { resolveRenderedInstance } from "../projection/renderedInstance.js";
-import { sourceSiteSelector } from "../selection/sourceSite.js";
+import { relocateSourceSite, 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);
+    const { props, ariaLabel } = target.locator;
+    const sourceSite = relocateSourceSite(doc, target.sourceSite, (element) => element.getAttribute("data-cprops") === props && element.getAttribute("aria-label") === (ariaLabel ?? null));
+    if (sourceSite) {
+        const moved = resolveRenderedInstance(doc, { ...target, sourceSite });
+        if (moved.status === "resolved")
+            return moved.element;
+    }
+    const site = sourceSite ?? target.sourceSite;
+    const selector = sourceSiteSelector(site.cid, site.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