nudge-ui 0.2.3 → 0.2.5

package/dist/inspector/pageInspector.js

@@ -0,0 +1,342 @@
+/**
+ * Entry for loading the inspector into any page without a host Adapter.
+ *
+ * Everything a host normally supplies is derived from the live document:
+ * runtime identity is assigned lazily under the pointer, and tokens come from
+ * readable stylesheets plus the root's computed custom properties. Source
+ * locations, component semantics, iterations, and the agent bridge are
+ * unavailable. In editor mode the application runs in Canvas frames;
+ * otherwise the page itself is the only Canvas card.
+ */
+import { bootstrapNudgeUi, configureNudgeUiRuntime, getNudgeUiRuntimeConfig, isCanvasRenderer, readNudgeUiEditorTarget, setInspectorOpen, unmountInspector, } from "./index.js";
+import { CANVAS_RENDERER_ATTR } from "./canvas/roleDetection.js";
+import { releaseLease } from "./canvas/workspaceLease.js";
+import { enablePageSurface } from "./canvas/pageSurface.js";
+import { setNudgeUiHostDevFlag } from "./runtime/devFlag.js";
+import { configureInspectorStorage } from "./runtime/inspectorStorage.js";
+import { configureSketchStorage } from "./sketch/persistence.js";
+import { preferAdoptedStylesheets } from "./runtime/ownedStylesheets.js";
+import { enableInspectionPerformanceDiagnostics } from "./inspection/performanceDiagnostics.js";
+import { installLazyRuntimeIdentity } from "./runtime/staticHtmlRuntimeIdentity.js";
+import { createTokenInventory } from "../css/token-inventory/inventory.js";
+export { createMirroredStorage } from "./runtime/inspectorStorage.js";
+const MOUNT_ID = "nudge-ui-root";
+const LOADED_FLAG = "__NUDGE_UI_PAGE_INSPECTOR__";
+const COMPUTED_ROOT_ID = "computed:root";
+function isNudgeOwnedSheet(sheet) {
+    const owner = sheet.ownerNode;
+    return owner instanceof Element && owner.hasAttribute("data-nudge-ui");
+}
+function sheetId(sheet, index, base) {
+    const owner = sheet.ownerNode;
+    const viteId = owner instanceof HTMLElement ? owner.dataset.viteDevId : undefined;
+    if (viteId)
+        return viteId;
+    if (sheet.href) {
+        const url = new URL(sheet.href, base);
+        return url.origin === new URL(base).origin ? url.pathname : url.href;
+    }
+    return `inline-style-${index + 1}`;
+}
+function serializeRules(sheet) {
+    return Array.from(sheet.cssRules, (rule) => rule.cssText).join("\n");
+}
+async function collectSheet(sheet, index, base) {
+    const id = sheetId(sheet, index, base);
+    try {
+        return { id, content: serializeRules(sheet) };
+    }
+    catch {
+        if (!sheet.href)
+            return { id, readError: "stylesheet rules are not readable" };
+    }
+    try {
+        const response = await fetch(sheet.href, { mode: "cors", credentials: "omit" });
+        if (!response.ok)
+            return { id, readError: `HTTP ${response.status}` };
+        return { id, content: await response.text() };
+    }
+    catch {
+        return { id, readError: "cross-origin stylesheet without CORS access" };
+    }
+}
+/**
+ * Custom properties visible on the root element but absent from readable
+ * stylesheets: definitions in cross-origin sheets without CORS, scoped theme
+ * rules the inventory rejects, or variables set from JavaScript.
+ */
+function computedRootDeclarations(doc, definedNames) {
+    const declarations = [];
+    const view = doc.defaultView ?? window;
+    for (const element of [doc.documentElement, doc.body]) {
+        if (!element)
+            continue;
+        const style = view.getComputedStyle(element);
+        for (let index = 0; index < style.length; index += 1) {
+            const name = style.item(index);
+            if (!name.startsWith("--") || definedNames.has(name))
+                continue;
+            const value = style.getPropertyValue(name).trim();
+            if (!value)
+                continue;
+            definedNames.add(name);
+            declarations.push(`  ${name}: ${value};`);
+        }
+    }
+    return declarations.length > 0 ? `:root {\n${declarations.join("\n")}\n}` : null;
+}
+function mapDiagnostic(diagnostic) {
+    return {
+        code: diagnostic.code,
+        message: diagnostic.message,
+        module: diagnostic.module ?? diagnostic.artifact ?? "document",
+        ...(diagnostic.exportName !== undefined ? { exportName: diagnostic.exportName } : {}),
+    };
+}
+async function collectDocumentTokens(doc) {
+    const sheets = Array.from(doc.styleSheets).filter((sheet) => !isNudgeOwnedSheet(sheet));
+    const collected = await Promise.all(sheets.map((sheet, index) => collectSheet(sheet, index, doc.location.href)));
+    const inventory = createTokenInventory();
+    for (const [order, sheet] of collected.entries()) {
+        const artifact = {
+            buildTool: "browser",
+            id: sheet.id,
+            stage: "authored",
+            provenance: "project",
+            order,
+            ...(sheet.content !== undefined ? { content: sheet.content } : {}),
+            ...(sheet.readError ? {
+                diagnostics: [{
+                        code: "stylesheet-unreadable",
+                        message: `Stylesheet "${sheet.id}" could not be read: ${sheet.readError}`,
+                        module: sheet.id,
+                    }],
+            } : {}),
+        };
+        inventory.apply(artifact);
+    }
+    const definedNames = new Set(inventory.snapshot().definitions.map((definition) => definition.cssName));
+    const computed = computedRootDeclarations(doc, definedNames);
+    if (computed) {
+        inventory.apply({
+            buildTool: "browser",
+            id: COMPUTED_ROOT_ID,
+            stage: "authored",
+            provenance: "project",
+            order: -1,
+            content: computed,
+        });
+    }
+    const snapshot = inventory.snapshot();
+    return {
+        tokenCatalog: snapshot.definitions.map((definition) => ({
+            ...definition,
+            declarations: definition.declarations.map((declaration) => ({
+                id: declaration.id,
+                order: declaration.order,
+                value: declaration.value,
+                source: declaration.source,
+                important: declaration.important,
+                context: declaration.context,
+            })),
+        })),
+        tokens: snapshot.tokens,
+        tokenDiagnostics: snapshot.diagnostics.map(mapDiagnostic),
+        tokenGeneration: `browser:${snapshot.generation}`,
+    };
+}
+const NO_TOKENS = { tokenCatalog: [], tokens: [], tokenDiagnostics: [], tokenGeneration: "" };
+function runtimeConfig(tokens, unavailableReason) {
+    return {
+        projectId: `page:${location.origin}`,
+        host: "static-html",
+        framework: "HTML",
+        stylingSystem: "CSS custom properties",
+        capabilities: { canvas: !unavailableReason, componentSemantics: false, domNavigation: !unavailableReason },
+        features: { canvasIterations: false, ...(unavailableReason ? { sketch: false } : {}) },
+        ...(unavailableReason ? { inspectionUnavailableReason: unavailableReason } : {}),
+        componentContracts: [],
+        ...tokens,
+    };
+}
+function createMount() {
+    const mount = document.createElement("div");
+    mount.id = MOUNT_ID;
+    document.body.append(mount);
+    return mount;
+}
+/** Mounts the inspector and returns a toggle that fully unmounts and remounts it. */
+function mountPageInspector() {
+    let mount = null;
+    let removeIdentityListeners = null;
+    const enable = () => {
+        setNudgeUiHostDevFlag(true);
+        removeIdentityListeners = installLazyRuntimeIdentity(document);
+        mount = createMount();
+        bootstrapNudgeUi(mount);
+        setInspectorOpen(true);
+    };
+    const disable = (target) => {
+        unmountInspector();
+        removeIdentityListeners?.();
+        removeIdentityListeners = null;
+        releaseLease();
+        setInspectorOpen(false);
+        setNudgeUiHostDevFlag(false);
+        target.remove();
+        mount = null;
+    };
+    enable();
+    return () => {
+        if (mount)
+            disable(mount);
+        else
+            enable();
+    };
+}
+/**
+ * Replaces the page's content with the iframe editor. The application runs in
+ * Canvas renderer frames, which the caller loads the inspector into.
+ */
+function mountEditor(onRendererFrameLoad) {
+    document.head.replaceChildren();
+    document.body.replaceChildren();
+    for (const element of [document.documentElement, document.body]) {
+        element.removeAttribute("style");
+        element.removeAttribute("hidden");
+        element.removeAttribute("inert");
+    }
+    document.title = "Nudge UI";
+    const layout = new CSSStyleSheet();
+    layout.replaceSync(`html, body, #${MOUNT_ID} { display: block; width: 100%; height: 100%; margin: 0; overflow: hidden; }`);
+    document.adoptedStyleSheets = [layout];
+    // A parsed meta policy remains active even after the original head is removed.
+    document.addEventListener("securitypolicyviolation", (event) => {
+        if (event.disposition !== "enforce" || event.effectiveDirective !== "frame-src")
+            return;
+        if (getNudgeUiRuntimeConfig().inspectionUnavailableReason)
+            return;
+        configureNudgeUiRuntime(runtimeConfig(NO_TOKENS, "its security policy"));
+    });
+    setNudgeUiHostDevFlag(true);
+    const mount = createMount();
+    bootstrapNudgeUi(mount);
+    setInspectorOpen(true);
+    // Storage hydration can delay the controller mount; watch its host now.
+    const root = mount.shadowRoot ?? mount.attachShadow({ mode: "open" });
+    const frames = () => root.querySelectorAll(`iframe[${CANVAS_RENDERER_ATTR}]`);
+    const applicationDocument = (frame) => {
+        const frameDocument = frame.contentDocument;
+        return frameDocument && frameDocument.location.href !== "about:blank" ? frameDocument : null;
+    };
+    // A frame's `load` waits for every image, so renderers start once the DOM is ready.
+    const announced = new WeakSet();
+    const announceReadyDocuments = () => {
+        for (const frame of frames()) {
+            const frameDocument = applicationDocument(frame);
+            if (!frameDocument || frameDocument.readyState === "loading" || announced.has(frameDocument))
+                continue;
+            announced.add(frameDocument);
+            onRendererFrameLoad?.();
+        }
+    };
+    window.setInterval(announceReadyDocuments, 100);
+    // Script-built styles exist only in the application frames, not in this document.
+    const collectFrameTokens = (frame) => {
+        const frameDocument = applicationDocument(frame);
+        if (!frameDocument)
+            return;
+        void collectDocumentTokens(frameDocument).then((tokens) => {
+            if (getNudgeUiRuntimeConfig().inspectionUnavailableReason)
+                return;
+            if (tokens.tokenGeneration !== getNudgeUiRuntimeConfig().tokenGeneration) {
+                configureNudgeUiRuntime(runtimeConfig(tokens));
+            }
+        });
+    };
+    const watched = new WeakSet();
+    const watch = () => {
+        for (const frame of frames()) {
+            if (watched.has(frame))
+                continue;
+            watched.add(frame);
+            frame.addEventListener("load", () => collectFrameTokens(frame));
+            collectFrameTokens(frame);
+        }
+    };
+    new MutationObserver(watch).observe(root, { childList: true, subtree: true });
+    watch();
+}
+/** Leaves the editor by loading the application URL it frames. */
+function exitEditor() {
+    location.replace(readNudgeUiEditorTarget(location.href) ?? location.href);
+}
+/**
+ * Starts the inspector on the current page. Running a second bundle copy in
+ * the same window toggles the first instance instead, because only the first
+ * copy's stores drive the UI.
+ */
+export async function startPageInspector(options = {}) {
+    const target = window;
+    const loaded = target[LOADED_FLAG];
+    if (loaded) {
+        loaded.toggle();
+        return;
+    }
+    const editor = options.surface === "editor" && readNudgeUiEditorTarget(location.href) !== null;
+    let toggle = editor ? exitEditor : null;
+    target[LOADED_FLAG] = {
+        surface: editor ? "editor" : "page",
+        toggle: () => toggle?.(),
+        enablePerformanceDiagnostics: () => enableInspectionPerformanceDiagnostics(document),
+    };
+    if (options.storage)
+        configureInspectorStorage(options.storage);
+    if (options.sketchStorage)
+        configureSketchStorage(options.sketchStorage);
+    if (options.adoptStylesheets)
+        preferAdoptedStylesheets();
+    const tokens = options.unavailableReason ? NO_TOKENS : await collectDocumentTokens(document);
+    configureNudgeUiRuntime(runtimeConfig(tokens, options.unavailableReason));
+    if (editor) {
+        mountEditor(options.onRendererFrameLoad);
+    }
+    else {
+        if (!options.unavailableReason)
+            enablePageSurface();
+        toggle = mountPageInspector();
+    }
+    console.info(`[nudge-ui] Inspector loaded in ${editor ? "editor" : "page"} mode with ${tokens.tokenCatalog.length} tokens`
+        + (tokens.tokenDiagnostics.length > 0 ? ` and ${tokens.tokenDiagnostics.length} stylesheet diagnostics.` : "."), tokens.tokenDiagnostics);
+}
+/**
+ * Starts the renderer in an editor's Canvas frame. Does nothing in any other
+ * document, or when the frame already runs one.
+ */
+export function startCanvasRenderer(options = {}) {
+    const target = window;
+    if (!isCanvasRenderer() || target[LOADED_FLAG])
+        return;
+    target[LOADED_FLAG] = {
+        surface: "renderer",
+        toggle: () => undefined,
+        enablePerformanceDiagnostics: () => enableInspectionPerformanceDiagnostics(document),
+    };
+    if (options.adoptStylesheets)
+        preferAdoptedStylesheets();
+    setNudgeUiHostDevFlag(true);
+    installLazyRuntimeIdentity(document);
+    configureNudgeUiRuntime(runtimeConfig(NO_TOKENS));
+    bootstrapNudgeUi(createMount());
+    // Renderers inspect their own elements, so they need this document's tokens.
+    const collectTokens = () => {
+        void collectDocumentTokens(document).then((tokens) => {
+            if (tokens.tokenGeneration !== getNudgeUiRuntimeConfig().tokenGeneration) {
+                configureNudgeUiRuntime(runtimeConfig(tokens));
+            }
+        });
+    };
+    collectTokens();
+    if (document.readyState !== "complete")
+        window.addEventListener("load", collectTokens, { once: true });
+}

package/dist/inspector/projection/draftProjection.d.ts

@@ -3,7 +3,8 @@ import type { RenderedInstanceOverride } from "../changes/editModel.js";
 import { type StructuralChange } from "./structuralProjection.js";
 import type { ComponentOverride } from "../componentSemantics/types.js";
 import { type TextContentChangeRecord } from "../changes/types.js";
-import type { DraftContents } from "../changes/draftChanges.js";
+import type { DraftContents } from "../drafts/model.js";
+import { type RuntimeIdentityClaim } from "../runtime/runtimeIdentityClaims.js";
 export interface DraftProjectionSource extends DraftContents {
     readonly revision: number;
 }
@@ -22,9 +23,15 @@ export interface DraftProjectionPlan<ManagedStyles> {
     readonly structuralChanges: readonly StructuralChange[];
     readonly textContentChanges: readonly TextContentChangeRecord[];
     readonly componentOverrides: readonly ComponentOverride[];
+    /**
+     * Generated identities the saved edits refer to. Omitted by plans that
+     * only hide edits (hold-to-view-original), which keep the attached ones.
+     */
+    readonly runtimeIdentities?: readonly RuntimeIdentityClaim[];
 }
 /** Applies every projection dimension to one document-local runtime. */
 export interface DocumentProjectionAdapter<ManagedStyles> {
+    applyRuntimeIdentities(claims: readonly RuntimeIdentityClaim[]): void;
     applyStructural(changes: readonly StructuralChange[]): void;
     applyRenderedInstances(overrides: readonly RenderedInstanceOverride[]): void;
     applyText(changes: readonly TextContentChangeRecord[]): void;
@@ -35,7 +42,8 @@ export declare function compileDraftProjection(snapshot: DraftProjectionSource):
 /**
  * Replaces one document projection in the required order.
  *
- * Structural intent is applied first because later rendered-instance evidence
+ * Generated identities are attached first: every selector and resolver below
+ * looks elements up by them. Structural intent follows because later rendered-instance evidence
  * can depend on the restored element order. Managed CSS is applied last so
  * selectors can use the document-local instance markers installed above.
  */

package/dist/inspector/projection/draftProjection.js

@@ -6,6 +6,7 @@ import { replaceComponentOverrideProjection } from "../componentSemantics/index.
 import { componentChangeToOverride } from "../componentSemantics/changeModel.js";
 import { isComponentChange } from "../changes/types.js";
 import { buildManagedStyleRules } from "../changes/managedStyleProjection.js";
+import { applyRuntimeIdentityClaims, collectRuntimeIdentityClaims, } from "../runtime/runtimeIdentityClaims.js";
 export function compileDraftProjection(snapshot) {
     const changes = [...snapshot.changes];
     const rules = buildManagedStyleRules(changes);
@@ -22,16 +23,20 @@ export function compileDraftProjection(snapshot) {
             .filter(isComponentChange)
             .map(componentChangeToOverride)
             .filter((override) => override !== null),
+        runtimeIdentities: collectRuntimeIdentityClaims(snapshot),
     };
 }
 /**
  * Replaces one document projection in the required order.
  *
- * Structural intent is applied first because later rendered-instance evidence
+ * Generated identities are attached first: every selector and resolver below
+ * looks elements up by them. Structural intent follows because later rendered-instance evidence
  * can depend on the restored element order. Managed CSS is applied last so
  * selectors can use the document-local instance markers installed above.
  */
 export function applyDraftProjection(adapter, plan) {
+    if (plan.runtimeIdentities)
+        adapter.applyRuntimeIdentities(plan.runtimeIdentities);
     adapter.applyStructural(plan.structuralChanges);
     adapter.applyRenderedInstances(plan.instanceOverrides);
     adapter.applyText(plan.textContentChanges);
@@ -39,6 +44,9 @@ export function applyDraftProjection(adapter, plan) {
     adapter.applyManagedStyles(plan.managedStyles);
 }
 const hostDocumentProjectionAdapter = {
+    applyRuntimeIdentities: (claims) => {
+        applyRuntimeIdentityClaims(document, claims);
+    },
     applyStructural: (changes) => {
         applyStructuralProjection(document, changes);
     },

package/dist/inspector/projection/managedStylesheet.js

@@ -2,6 +2,7 @@ import { getElementComputedStyle } from "../runtime/domRealm.js";
 import { notifyBrowserStylesheetChange } from "../inspection/browserCssInspectionRegistry.js";
 import { escapeAttrValue, escapeCssString } from "./cssEscapes.js";
 import { isNudgeUiDev } from "../runtime/devFlag.js";
+import { adoptStylesheet, allowsStyleElements, releaseAdoptedStylesheet } from "../runtime/ownedStylesheets.js";
 export { escapeAttrValue, escapeCssString } from "./cssEscapes.js";
 const SHEET_ID = "nudge-ui-styles";
 let managedHeadGuardDocument = null;
@@ -25,6 +26,12 @@ function installManagedHeadGuard(doc) {
 }
 export function ensureManagedSheet() {
     const doc = document;
+    if (!allowsStyleElements(doc)) {
+        // Adopted sheets already cascade after every document stylesheet.
+        adoptStylesheet(doc, SHEET_ID, rulesToCssText(managedRules));
+        exposeManagedSheetText(doc);
+        return;
+    }
     // SAFETY: getElementById returns an Element; the managed style element is created as HTMLStyleElement when missing.
     let el = doc.getElementById(SHEET_ID);
     if (!el) {
@@ -53,6 +60,9 @@ export function ensureManagedSheet() {
         rehydrateManagedSheet(doc, el);
     }
     installManagedHeadGuard(doc);
+    exposeManagedSheetText(doc);
+}
+function exposeManagedSheetText(doc) {
     if (isNudgeUiDev() && doc.defaultView) {
         // Keep the canonical CSS available to dev diagnostics.
         doc.defaultView.__nudgeUiGetManagedSheetText = getManagedSheetText;
@@ -125,15 +135,24 @@ function rehydrateManagedSheet(doc, el) {
  * copy for rehydration if a framework moves or reparses that element.
  */
 function rebuildSheetText(rules) {
-    // SAFETY: getElementById returns an Element; the managed style element is created as HTMLStyleElement when missing.
-    const el = document.getElementById(SHEET_ID);
-    if (!el)
-        return;
     const desired = rules.map((rule) => ({
         ...rule,
         declarations: { ...rule.declarations },
     }));
     const cssText = rulesToCssText(desired);
+    if (!allowsStyleElements(document)) {
+        const rulesChanged = rulesToCssText(managedRules) !== cssText;
+        managedRules = desired;
+        if (!rulesChanged)
+            return;
+        adoptStylesheet(document, SHEET_ID, cssText);
+        notifyBrowserStylesheetChange(document);
+        return;
+    }
+    // SAFETY: getElementById returns an Element; the managed style element is created as HTMLStyleElement when missing.
+    const el = document.getElementById(SHEET_ID);
+    if (!el)
+        return;
     const rulesChanged = rulesToCssText(managedRules) !== cssText;
     const shouldRetryDroppedRules = el.sheet !== null
         && el.sheet.cssRules.length !== desired.length
@@ -237,6 +256,7 @@ export function removeManagedSheet() {
     const el = document.getElementById(SHEET_ID);
     if (el)
         el.remove();
+    releaseAdoptedStylesheet(document, SHEET_ID);
     managedRules = [];
     failedRehydrationCssText = null;
     notifyBrowserStylesheetChange(document);

package/dist/inspector/projection/renderedInstance.d.ts

@@ -23,10 +23,23 @@ export declare function captureRenderedInstance(el: HTMLElement): RenderedInstan
 /**
  * Resolves exactly one element, or declines to apply. Occurrence documents the
  * captured placement, but structural previews can legitimately change it.
- * Evidence must therefore identify one current candidate before an edit can
- * be applied.
+ * Evidence, narrowed by a recorded invocation when present, must therefore
+ * identify one current candidate before an edit can be applied.
  */
 export declare function resolveRenderedInstance(doc: Document, ref: RenderedInstanceRef): ResolutionResult;
+/**
+ * Resolves a reference whose source position may have moved since capture.
+ * A relocated site still renders matching authored evidence, so an evidence
+ * miss there is reported as ambiguous rather than as proof of absence.
+ */
+export declare function resolveMovedRenderedInstance(doc: Document, ref: RenderedInstanceRef): ResolutionResult;
+/**
+ * Captures identity for a structural target. When evidence matches several
+ * identical outputs, the nearest component invocation whose entire output is
+ * this element can still identify it. Otherwise the evidence-only reference
+ * is returned and resolves as ambiguous.
+ */
+export declare function captureStructuralTarget(el: HTMLElement): RenderedInstanceRef | null;
 /** Checks stable source/evidence fields without treating a post-move ordinal as identity. */
 export declare function matchesRenderedInstanceEvidence(el: HTMLElement, ref: RenderedInstanceRef): boolean;
 /** Builds an instance override without changing the element's transient edit scope. */

package/dist/inspector/projection/renderedInstance.js

@@ -1,8 +1,10 @@
-import { getActiveDraftChanges, getDraftChanges } from "../changes/draftChanges.js";
+import { getActiveDraftChanges, getDraftChanges } from "../drafts/store.js";
+import { inspectRootInvocations } from "../componentSemantics/adapterRegistry.js";
 import { escapeAttrValue } from "./cssEscapes.js";
 import { isNudgeUiDev } from "../runtime/devFlag.js";
-import { sourceSiteSelector } from "../selection/sourceSite.js";
+import { relocateSourceSite, sourceSiteSelector } from "../selection/sourceSite.js";
 import { isRenderedInstanceOverride } from "../changes/editModel.js";
+import { boundRuntimeEvidence, isRuntimeGeneratedSource, normalizeRuntimeTag, runtimeDomPath } from "../runtime/staticHtmlRuntimeIdentity.js";
 export { isRenderedInstanceOverride, isRenderedInstanceRef } from "../changes/editModel.js";
 const PROJECTION_ATTR = "data-projection-instance";
 let nextOverrideId = 1;
@@ -44,25 +46,42 @@ export function captureRenderedInstance(el) {
             props: el.getAttribute("data-cprops"),
             text: normalizedText(el),
             ariaLabel: el.getAttribute("aria-label"),
+            ...(isRuntimeGeneratedSource(src) ? {
+                tagName: normalizeRuntimeTag(el.tagName),
+                domPath: runtimeDomPath(el),
+                elementId: boundRuntimeEvidence(el.id || null),
+            } : {}),
         },
     };
 }
 /**
  * Resolves exactly one element, or declines to apply. Occurrence documents the
  * captured placement, but structural previews can legitimately change it.
- * Evidence must therefore identify one current candidate before an edit can
- * be applied.
+ * Evidence, narrowed by a recorded invocation when present, must therefore
+ * identify one current candidate before an edit can be applied.
  */
 export function resolveRenderedInstance(doc, ref) {
     const sourceCandidates = candidates(doc, ref.sourceSite);
-    const { props, text, ariaLabel = null } = ref.locator;
+    const { props, text, ariaLabel = null, invocation } = ref.locator;
     // An ordinal alone is not an identity for a repeated source site.
-    if (sourceCandidates.length > 1 && props === null && text === null && ariaLabel === null) {
+    if (!invocation && sourceCandidates.length > 1 && props === null && text === null && ariaLabel === null) {
         return { status: "ambiguous" };
     }
-    const matchingEvidence = sourceCandidates.filter((element) => element.getAttribute("data-cprops") === props
+    let matchingEvidence = sourceCandidates.filter((element) => element.getAttribute("data-cprops") === props
         && normalizedText(element) === text
         && element.getAttribute("aria-label") === ariaLabel);
+    if (invocation) {
+        const scoped = [];
+        for (const element of matchingEvidence) {
+            const invocations = inspectRootInvocations(element);
+            // Without readable ancestry, absence of the invocation proves nothing.
+            if (invocations === null)
+                return { status: "ambiguous" };
+            if (invocations.some((candidate) => candidate.callsiteId === invocation.callsiteId))
+                scoped.push(element);
+        }
+        matchingEvidence = scoped;
+    }
     if (matchingEvidence.length === 0)
         return { status: "missing" };
     // Evidence alone is never enough to choose between two identical rendered
@@ -72,6 +91,40 @@ export function resolveRenderedInstance(doc, ref) {
         return { status: "ambiguous" };
     return { status: "resolved", element: matchingEvidence[0] };
 }
+/**
+ * Resolves a reference whose source position may have moved since capture.
+ * A relocated site still renders matching authored evidence, so an evidence
+ * miss there is reported as ambiguous rather than as proof of absence.
+ */
+export function resolveMovedRenderedInstance(doc, ref) {
+    const exact = resolveRenderedInstance(doc, ref);
+    if (exact.status !== "missing")
+        return exact;
+    const { props, ariaLabel = null } = ref.locator;
+    const sourceSite = relocateSourceSite(doc, ref.sourceSite, (element) => element.getAttribute("data-cprops") === props && element.getAttribute("aria-label") === ariaLabel);
+    if (!sourceSite)
+        return exact;
+    const moved = resolveRenderedInstance(doc, { ...ref, sourceSite });
+    return moved.status === "missing" ? { status: "ambiguous" } : moved;
+}
+/**
+ * Captures identity for a structural target. When evidence matches several
+ * identical outputs, the nearest component invocation whose entire output is
+ * this element can still identify it. Otherwise the evidence-only reference
+ * is returned and resolves as ambiguous.
+ */
+export function captureStructuralTarget(el) {
+    const ref = captureRenderedInstance(el);
+    if (!ref || resolveRenderedInstance(el.ownerDocument, ref).status !== "ambiguous")
+        return ref;
+    for (const invocation of inspectRootInvocations(el) ?? []) {
+        const scoped = { ...ref, locator: { ...ref.locator, invocation } };
+        const resolved = resolveRenderedInstance(el.ownerDocument, scoped);
+        if (resolved.status === "resolved" && resolved.element === el)
+            return scoped;
+    }
+    return ref;
+}
 /** Checks stable source/evidence fields without treating a post-move ordinal as identity. */
 export function matchesRenderedInstanceEvidence(el, ref) {
     const { props, text, ariaLabel = null } = ref.locator;

package/dist/inspector/projection/structuralProjection.d.ts

@@ -47,15 +47,6 @@ export declare function getStructuralChanges(): readonly StructuralChange[];
 export declare function getStructuralDeletes(): readonly StructuralDelete[];
 /** Revert removes one canonical intent and leaves every other intent intact. */
 export declare function revertStructuralChange(changeId: string): boolean;
-/**
- * Removes source-verified structural intents without leaving an undo path that
- * can recreate their browser-only previews.
- *
- * Agent completion can verify a subset of one dispatched snapshot. The
- * remaining records and their useful history stay intact while every verified
- * ID is pruned from canonical state, undo/redo snapshots, and Canvas reports.
- */
-export declare function reconcileVerifiedStructuralChanges(verifiedIds: ReadonlySet<string>): number;
 /** State changes drive controller-to-renderer projection. Diagnostics do not. */
 export declare function subscribeStructuralChanges(listener: () => void): () => void;
 /** Compatibility name retained while the controller moved to a full union. */