nudge-ui 0.2.4 → 0.2.6

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;
@@ -149,10 +148,7 @@ function applyStaleResults(changes, attempts) {
             continue;
         }
         const routes = evidence.get(i);
-        // A document that does not contain the target says nothing about
-        // staleness. Publish target-missing only when the change matches nowhere;
-        // a Canvas-only match is verified, not a host conflict. When nowhere,
-        // every live document reports the same miss.
+        // Publish target-missing only when no live document matches; a Canvas-only match is verified, not a host conflict.
         if (!routes || routes.length === 0) {
             for (const attempt of attempts.values()) {
                 publishPreviewDiagnostic(attempt, changeKey(change), buildStaleResult(change.selector, getRequestedValue(change)));
@@ -189,22 +185,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 +201,8 @@ export function cancelStaleDetection() {
     }
     pendingChanges = null;
     pendingAttempts = new Map();
-    window.removeEventListener("message", handleFrameReady);
+    stopFrameReady?.();
+    stopFrameReady = null;
     notifyPreviewDiagnostics();
 }
 export function isVerificationPending() {

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

@@ -1,7 +1,4 @@
-/**
- * Keep canvas card controls usable while the board is zoomed out without
- * letting them grow without bound relative to the card.
- */
+/** Keeps card controls usable while the board is zoomed out, without letting them outgrow the card. */
 export declare const CANVAS_TOOLBAR_MAX_SCALE = 2;
 export declare const CANVAS_TOOLBAR_SCALE_CAP_ZOOM: number;
 export declare function getCanvasToolbarScale(zoom: number): number;

package/dist/inspector/canvas/toolbarScale.js

@@ -1,7 +1,4 @@
-/**
- * Keep canvas card controls usable while the board is zoomed out without
- * letting them grow without bound relative to the card.
- */
+/** Keeps card controls usable while the board is zoomed out, without letting them outgrow the card. */
 export const CANVAS_TOOLBAR_MAX_SCALE = 2;
 export const CANVAS_TOOLBAR_SCALE_CAP_ZOOM = 1 / CANVAS_TOOLBAR_MAX_SCALE;
 export function getCanvasToolbarScale(zoom) {

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

@@ -1,5 +1,4 @@
 import { type RefObject } from "react";
 import { type CanvasCard } from "./canvasStore.js";
 import { type CanvasCamera, type CanvasPresentation } from "./viewStore.js";
-/** Animates frame creation and layout changes without delaying direct manipulation. */
 export declare function useCanvasLayoutAnimation(boardRef: RefObject<HTMLDivElement | null>, cards: readonly CanvasCard[], camera: CanvasCamera, presentation: CanvasPresentation): void;

package/dist/inspector/canvas/useCanvasLayoutAnimation.js

@@ -4,7 +4,6 @@ import {} from "./canvasStore.js";
 import { setCanvasLayoutTransitioning } from "./viewStore.js";
 const SLIDE_OPTIONS = { duration: 300, easing: "ease-out" };
 const CAMERA_OPTIONS = { duration: 150, easing: "ease-out" };
-/** Animates frame creation and layout changes without delaying direct manipulation. */
 export function useCanvasLayoutAnimation(boardRef, cards, camera, presentation) {
     const previous = useRef({ cards, camera, presentation });
     const animations = useRef([]);

package/dist/inspector/canvas/viewStore.js

@@ -2,7 +2,7 @@ import { useSyncExternalStore } from "react";
 export const MIN_CAMERA_ZOOM = 0.25;
 export const MAX_CAMERA_ZOOM = 3;
 export const DEFAULT_CAMERA = { x: 0, y: 0, zoom: 1 };
-/** How the canvas is viewed. Frames, groups, and selection live in the canvas store. */
+/** Frames, groups, and selection live in the canvas store. */
 let mode = "inspect";
 let presentation = "focus";
 let presentationTransitioning = false;

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

@@ -1,4 +1,4 @@
-/** Converts wheel units to pixel distances for consistent canvas panning. */
+/** deltaMode 1 is lines (16px) and 2 is pages, so both need converting to pixels. */
 export declare function wheelPanDelta(event: Pick<WheelEvent, "deltaX" | "deltaY" | "deltaMode" | "shiftKey">, viewport: {
     width: number;
     height: number;

package/dist/inspector/canvas/wheelPan.js

@@ -1,4 +1,4 @@
-/** Converts wheel units to pixel distances for consistent canvas panning. */
+/** deltaMode 1 is lines (16px) and 2 is pages, so both need converting to pixels. */
 export function wheelPanDelta(event, viewport) {
     const xUnit = event.deltaMode === 1 ? 16 : event.deltaMode === 2 ? viewport.width : 1;
     const yUnit = event.deltaMode === 1 ? 16 : event.deltaMode === 2 ? viewport.height : 1;

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

@@ -10,11 +10,7 @@ export declare function acquireLease(): boolean;
 export declare function requestTakeover(): boolean;
 /** Enable lease checks for state-changing controller actions in this document. */
 export declare function enableWriteGuard(): void;
-/**
- * Unit-level modules are also used without the browser controller bootstrap.
- * Once the controller enables the guard, only the current lease owner may
- * mutate or persist its canonical workspace state.
- */
+/** Off by default so unit-level modules work without the controller bootstrap. */
 export declare function canWriteWorkspace(): boolean;
 export declare function releaseLease(): void;
 export declare function hasWriteLease(): boolean;

package/dist/inspector/canvas/workspaceLease.js

@@ -49,7 +49,6 @@ function deleteLease() {
         localStorage.removeItem(leaseKey());
     }
     catch {
-        /* ignore */
     }
 }
 export function isLeaseExpired(lease, now = Date.now()) {
@@ -67,7 +66,6 @@ function notifyOwnershipListeners() {
             listener(snapshot);
         }
         catch {
-            /* ignore */
         }
     }
 }
@@ -149,11 +147,7 @@ export function requestTakeover() {
 export function enableWriteGuard() {
     writeGuardEnabled = true;
 }
-/**
- * Unit-level modules are also used without the browser controller bootstrap.
- * Once the controller enables the guard, only the current lease owner may
- * mutate or persist its canonical workspace state.
- */
+/** Off by default so unit-level modules work without the controller bootstrap. */
 export function canWriteWorkspace() {
     return !writeGuardEnabled || hasWriteLease();
 }

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

@@ -34,6 +34,7 @@ export interface SerializableElementChange {
     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", "sourceEvidence", "scope", "instanceOverride", "state",
+            "oldRawValue", "source", "runtimeEvidence", "sourceEvidence", "scope", "sourceInstanceCount", "instanceOverride", "state",
         ])
         || (value.kind !== undefined && value.kind !== "element")
         || typeof value.cid !== "string"
@@ -35,6 +35,8 @@ export function isSerializableElementChangeValue(value) {
         || (value.runtimeEvidence !== undefined && !isRuntimeElementEvidenceValue(value.runtimeEvidence))
         || (value.sourceEvidence !== undefined && !isSourceElementEvidenceValue(value.sourceEvidence))
         || !isEditScopeValue(value.scope)
+        || (value.sourceInstanceCount !== undefined
+            && (!isNonNegativeSafeInteger(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))) {
@@ -118,6 +120,7 @@ export function serializeElementChange(change) {
         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,
     };
@@ -163,6 +166,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] }
                 : {}),
@@ -204,6 +210,7 @@ export function deserializeElementChange(serialized) {
         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,
     };
@@ -248,6 +255,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] }
                 : {}),
@@ -327,18 +337,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"])
+        && hasOnlyKeys(value, ["tagName", "props", "text", "ariaLabel", "domPath", "elementId"])
         && typeof value.tagName === "string"
-        && (typeof value.props === "string" || value.props === null);
+        && (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,7 @@
+import type { DraftChangesSnapshot, DraftProjectionEvent } from "../drafts/draftStore.js";
+export interface DraftPreview {
+    project(snapshot: DraftChangesSnapshot, event: DraftProjectionEvent): void;
+    dispose(): void;
+}
+/** 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,118 @@
+import { getSelectedElement } from "../selection/selectionStore.js";
+import { changeKey } from "./model.js";
+import { beginPreviewAttempt, clearPreviewDiagnostics, getHostPreviewDocument, } from "./previewDiagnostics.js";
+import { verifyPreviewChanges } from "./previewVerification.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";
+/** 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) {
+        if (isOriginalPreviewActive())
+            return;
+        if (!isEditorShellDocument())
+            applyHostDraftProjection(compileDraftProjection(snapshot));
+    }
+    function flushVerification() {
+        handle = null;
+        // Probing the original preview would report held-back changes as conflicts; keep the targets for re-verification on release.
+        if (isOriginalPreviewActive())
+            return;
+        const targets = pendingTargets;
+        pendingTargets = new Map();
+        // The editor shell has no application document to verify; renderer projection reports cover it.
+        if (targets.size === 0 || isEditorShellDocument())
+            return;
+        const current = readActive();
+        const attempt = beginPreviewAttempt(getHostPreviewDocument(), current.revision);
+        if (!attempt)
+            return;
+        const targeted = current.changes.filter((change) => targets.has(changeKey(change)));
+        verifyPreviewChanges({
+            changes: targeted,
+            document,
+            attempt,
+            targetFor: (change) => targets.get(changeKey(change)) ?? null,
+        });
+    }
+    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;
+            // Latest commit context wins for a merged key; the element may live in an iframe, which fixes the verification document.
+            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 markForVerification 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

@@ -1,14 +1,11 @@
 import type { TokenContextWrapper } from "../../css/model/index.js";
 export type EditScope = "source-site" | "rendered-instance";
-/** A JSX instrumentation site. This is stable across documents. */
+/** JSX instrumentation site; stable across documents. */
 export interface SourceSiteRef {
     cid: string;
     src: string;
 }
-/**
- * Serializable identity for one rendered output. It deliberately contains no
- * DOM reference or generated node id: each document resolves it independently.
- */
+/** Deliberately free of DOM references and generated node ids; each document resolves it independently. */
 export interface RenderedInstanceRef {
     sourceSite: SourceSiteRef;
     locator: {
@@ -18,14 +15,14 @@ export interface RenderedInstanceRef {
         text: string | null;
         /** An accessible name can distinguish icon-only repeated controls. */
         ariaLabel?: string | null;
-        /**
-         * The component invocation whose entire output is this element. Present
-         * only when evidence alone cannot tell identical outputs apart.
-         */
+        /** Rendered facts used to reattach generated identities after reload. */
+        tagName?: string;
+        domPath?: string | null;
+        elementId?: string | null;
+        /** 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;
@@ -40,9 +37,7 @@ export interface StyleRuleContext {
 }
 export declare function isRenderedInstanceRef(value: unknown): value is RenderedInstanceRef;
 export declare function isRenderedInstanceOverride(value: unknown): value is RenderedInstanceOverride;
-/** Validates the serializable context carried by a token change. */
 export declare function isStyleRuleContextValue(value: unknown): value is StyleRuleContext;
-/** A source site shared by text and rendered-instance evidence. */
 export type TextProjectionSourceSite = SourceSiteRef;
 export interface TextProjectionTarget {
     sourceSite: TextProjectionSourceSite;
@@ -50,11 +45,14 @@ 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[];
 }
 export type TextProjectionScope = EditScope;
-/** Bounded semantic evidence retained alongside an instance text projection. */
 export interface TextBindingEvidence {
     callsiteId: string;
     componentName: string;

package/dist/inspector/changes/editModel.js

@@ -14,13 +14,16 @@ export function isRenderedInstanceRef(value) {
         || typeof source.cid !== "string"
         || typeof source.src !== "string"
         || !isRecord(locator)
-        || !hasOnlyKeys(locator, ["kind", "occurrence", "props", "text", "ariaLabel", "invocation"]))
+        || !hasOnlyKeys(locator, ["kind", "occurrence", "props", "text", "ariaLabel", "tagName", "domPath", "elementId", "invocation"]))
         return false;
     return locator.kind === "evidence"
-        && Number.isSafeInteger(locator.occurrence) && locator.occurrence >= 0
+        && isNonNegativeSafeInteger(locator.occurrence)
         && (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.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) {
@@ -29,7 +32,6 @@ export function isRenderedInstanceOverride(value) {
         && typeof value.id === "string"
         && isRenderedInstanceRef(value.target);
 }
-/** Validates the serializable context carried by a token change. */
 export function isStyleRuleContextValue(value) {
     if (!isRecord(value) || !hasOnlyKeys(value, ["wrappers"]))
         return false;
@@ -46,7 +48,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;
@@ -58,6 +60,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) {
@@ -59,38 +60,28 @@ export function buildManagedStyleRules(changes) {
             });
         }
     }
-    // Source-site rules remain the default; exact rendered-instance rules are
-    // emitted afterwards so their additional marker specificity wins.
+    // Source-site rules are the default; rendered-instance rules come last so their extra marker specificity wins.
     return [...sourceRules.values(), ...instanceRules.values()];
 }
 export function verifyManagedStyleProjection(change, selectedElement, ownerDocument = document) {
-    // Deferred verification must use the selection that existed when the
-    // projection was committed. Reading the live selection here can make a
-    // host-document change verify against a later canvas selection (or vice
-    // versa) and manufacture a conflict for the wrong document.
+    // Deferred verification must use the selection from commit time; the live selection can belong to the wrong document and manufacture a conflict.
     const selected = selectedElement === undefined
         ? getSelectedElement()?.domElement ?? null
         : selectedElement;
     const requestedValue = requestedStyleValue(change);
-    // A Canvas-only selection belongs to an iframe. The controller stylesheet
-    // cannot verify it synchronously; leave its result unknown until the frame
-    // has received the canonical projection rather than claiming it is stale.
+    // A Canvas-only iframe selection cannot be verified synchronously; leave the result unknown rather than claiming it is stale.
     if (selected && selected.ownerDocument !== ownerDocument) {
         return null;
     }
     let targets = [];
     try {
         const selector = selectorForManagedChange(change);
-        targets = selector ? Array.from(ownerDocument.querySelectorAll(selector)) : [];
+        targets = selector ? Array.from(ownerDocument.querySelectorAll(selectorForInteractionStatePreview(selector))) : [];
     }
     catch {
         targets = [];
     }
-    // Probe targets lazily in DOM order and stop at the first conflicting
-    // preview: the reported result is exactly "first conflict ?? first target",
-    // so probing the remaining instances cannot change the outcome. A
-    // source-site selector matched by many rendered instances (one callsite,
-    // hundreds of nodes) otherwise pays a probe + important-rule scan per match.
+    // Early exit is safe: the result is "first conflict ?? first target", so later probes cannot change it.
     let firstApplied = null;
     let previewResult = null;
     for (const target of targets) {

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

@@ -1,10 +1,5 @@
 import type { TokenEntry } from "../../css/model/index.js";
 import { type ChangeRecord } from "./types.js";
-/**
- * The CSS value a token swap writes into the managed stylesheet and the
- * prompt must describe: an adapter-provided literal when present, otherwise a
- * var() reference on the authored cssName (falling back to the entry name).
- */
 export declare function tokenReference(token: TokenEntry): string;
 export declare function changeKey(change: ChangeRecord): string;
 export declare function mergeChange(current: ChangeRecord[], incoming: ChangeRecord): ChangeRecord[];

package/dist/inspector/changes/model.js

@@ -1,9 +1,4 @@
 import { isComponentChange, isElementChange, isTextContentChange, isTokenChange, } from "./types.js";
-/**
- * The CSS value a token swap writes into the managed stylesheet and the
- * prompt must describe: an adapter-provided literal when present, otherwise a
- * var() reference on the authored cssName (falling back to the entry name).
- */
 export function tokenReference(token) {
     return token.cssValue ?? `var(${token.cssName ?? token.name})`;
 }
@@ -27,9 +22,7 @@ export function changeKey(change) {
         ].join("\u0000");
     }
     if (isTextContentChange(change)) {
-        // The marker id is document-local projection identity. `beforeText` is
-        // part of the durable evidence: two outputs at one source site may have
-        // different initial copy and must remain distinct canonical intents.
+        // Two outputs at one source site may have different initial copy, so beforeText keeps them distinct.
         return [
             "text-content",
             change.target.sourceSite.cid,

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

@@ -14,26 +14,16 @@ export interface PreviewDiagnostic extends PreviewAttempt {
     readonly changeKey: string;
     readonly result: PreviewResult;
 }
-/** Returns the stable host-document identity for this inspector lifetime. */
 export declare function getHostPreviewDocument(): PreviewDocument;
-/** Starts or replaces the live session for one logical document. */
 export declare function startPreviewDocumentSession(document: PreviewDocument): void;
-/** Invalidates a live document session and rejects all of its late results. */
+/** Late results from an invalidated session are rejected. */
 export declare function invalidatePreviewDocumentSession(logicalDocument: string, sessionId?: string): void;
-/** Opens a verification attempt for the currently active document session. */
 export declare function beginPreviewAttempt(document: PreviewDocument, revision?: number): PreviewAttempt | null;
-/** Publishes only a result from the active revision, session, and attempt. */
 export declare function publishPreviewDiagnostic(attempt: PreviewAttempt, changeKey: string, result: PreviewResult): boolean;
-/** Removes diagnostics for the supplied canonical keys across live documents. */
 export declare function clearPreviewDiagnostics(changeKeys?: Iterable<string>): void;
-/** Notifies consumers when verification state changes without a result. */
 export declare function notifyPreviewDiagnostics(): void;
 export declare function getPreviewDiagnostic(changeKey: string, logicalDocument?: string, draftId?: string): PreviewDiagnostic | undefined;
-/**
- * Host-first read across live documents. The per-document store is observable
- * here so a Canvas-only conflict is not write-only; host remains the default
- * for single-document consumers.
- */
+/** Also reads non-host documents so Canvas-only conflicts are not write-only. */
 export declare function getAnyPreviewDiagnostic(changeKey: string): PreviewDiagnostic | undefined;
 export declare function subscribePreviewDiagnostics(listener: () => void): () => void;
 export declare function getPreviewDiagnosticRevision(): number;