nudge-ui 0.2.4 → 0.2.6

package/dist/inspector/componentSemantics/{reactRuntime.js → react/runtime.js}

@@ -1,19 +1,18 @@
 import { cloneElement, createElement, forwardRef, useEffect, useMemo, useSyncExternalStore, version as reactVersion, } from "react";
-import { registerHostRuntimeAdapter } from "./runtimeBridge.js";
-import { getNudgeUiRuntimeConfig } from "../runtime/runtimeConfig.js";
+import { registerHostRuntimeAdapter } from "../runtimeBridge.js";
+import { getNudgeUiRuntimeConfig } from "../../runtime/runtimeConfig.js";
+import { findFiber, hostOutputCount, isHostOutput } from "./fibers.js";
+import { canPreviewLive, invocationProps, replaceTaggedOverrides, resetTaggedCallsites, taggedCallsiteMultiplicity, taggedInvocationsAbove, taggedRootInvocations, } from "./callsites.js";
+export { registerReactCallsites } from "./callsites.js";
 const BOUNDARY_MARKER = Symbol.for("nudge-ui.react-component-boundary");
 const EMPTY_OVERRIDE = Object.freeze({});
 const REACT_MAJOR_VERSION = Number.parseInt(reactVersion, 10);
-/** React work tags for host output that has no string element type. */
-const HOST_PORTAL_TAG = 4;
-const HOST_TEXT_TAG = 6;
 let overridesByCallsite = new Map();
 const listeners = new Set();
 /**
- * Mounted invocation accounting is runtime state, not canonical identity. A
- * boundary registers by its stable transformed callsite and unregisters on
- * unmount. This survives rerenders and React Strict Mode's effect probe, and
- * each Canvas iframe owns an independent registry/module instance.
+ * Mounted invocation accounting is runtime state, not canonical identity: a boundary
+ * registers by its stable transformed callsite and unregisters on unmount, surviving
+ * rerenders and React Strict Mode's effect probe.
  */
 const mountedCallsites = new Map();
 function registerMountedCallsite(callsiteId) {
@@ -30,7 +29,6 @@ function registerMountedCallsite(callsiteId) {
             mountedCallsites.delete(callsiteId);
     };
 }
-/** Returns null when this runtime has no mounted boundary for the callsite. */
 export function getReactCallsiteMultiplicity(callsiteId) {
     return mountedCallsites.get(callsiteId) ?? null;
 }
@@ -39,6 +37,7 @@ export function resetReactComponentRuntime() {
     mountedCallsites.clear();
     overridesByCallsite = new Map();
     listeners.clear();
+    resetTaggedCallsites();
 }
 function subscribe(listener) {
     listeners.add(listener);
@@ -119,9 +118,8 @@ const ReactComponentOverride = forwardRef(function ReactComponentOverride({ elem
     const props = {
         ...injectedProps,
         ...override,
+        ...(forwardedRef === null ? {} : { ref: mergedRef }),
     };
-    if (forwardedRef !== null)
-        props.ref = mergedRef;
     return cloneElement(element, props);
 });
 ReactComponentOverride[BOUNDARY_MARKER] = true;
@@ -131,26 +129,40 @@ function isBoundaryType(value) {
         return false;
     return Reflect.get(value, BOUNDARY_MARKER) === true;
 }
-function findFiber(element) {
-    for (const key of Object.keys(element)) {
-        if (/^__reactFiber\$/.test(key) || /^__reactInternalInstance\$/.test(key)) {
-            return Reflect.get(element, key) ?? null;
-        }
-    }
-    return null;
-}
 export function instrumentReactComponent(element, meta) {
     return createElement(ReactComponentOverride, { key: element.key ?? undefined, element, meta });
 }
+function boundaryOf(fiber) {
+    if (!isBoundaryType(fiber.type))
+        return null;
+    // SAFETY: a boundary fiber's props are the `{ element, meta }` it was created with; both are checked below.
+    const props = (fiber.memoizedProps ?? {});
+    return props.meta && props.element ? { meta: props.meta, element: props.element } : null;
+}
+function nearestFirst(boundaries, tagged) {
+    const wrapped = new Set(boundaries.map((entry) => entry.callsiteId));
+    return [...boundaries, ...tagged.filter((entry) => !wrapped.has(entry.callsiteId))]
+        .sort((left, right) => left.depth - right.depth)
+        .map((entry) => entry.value);
+}
+/** Wrapped callsites answer through their boundary, others through their fiber's identity tag; both merge nearest first. */
 export function inspectReactComponentTargets(element) {
     if (!getNudgeUiRuntimeConfig().capabilities.componentSemantics)
         return [];
-    const targets = [];
-    let fiber = findFiber(element);
-    while (fiber) {
-        if (isBoundaryType(fiber.type) && fiber.memoizedProps?.meta && fiber.memoizedProps.element) {
-            const { meta, element: sourceElement } = fiber.memoizedProps;
-            targets.push({
+    const host = findFiber(element);
+    if (!host)
+        return [];
+    const boundaries = [];
+    let depth = 0;
+    for (let fiber = host; fiber; fiber = fiber.return ?? null, depth += 1) {
+        const boundary = boundaryOf(fiber);
+        if (!boundary)
+            continue;
+        const { meta, element: sourceElement } = boundary;
+        boundaries.push({
+            depth,
+            callsiteId: meta.callsiteId,
+            value: {
                 framework: "react",
                 meta,
                 props: {
@@ -158,28 +170,21 @@ export function inspectReactComponentTargets(element) {
                     ...overrideFor(meta.callsiteId),
                 },
                 mountedCount: getReactCallsiteMultiplicity(meta.callsiteId) ?? undefined,
-            });
-        }
-        fiber = fiber.return ?? null;
+            },
+        });
     }
-    return targets;
-}
-function isHostOutput(fiber) {
-    return typeof fiber.type === "string" || fiber.tag === HOST_TEXT_TAG || fiber.tag === HOST_PORTAL_TAG;
-}
-/** Counts top-level host outputs below a fiber, stopping once there are two. */
-function hostOutputCount(fiber) {
-    let count = 0;
-    const visit = (parent) => {
-        for (let child = parent.child ?? null; child && count < 2; child = child.sibling ?? null) {
-            if (isHostOutput(child))
-                count += 1;
-            else
-                visit(child);
-        }
-    };
-    visit(fiber);
-    return count;
+    const tagged = taggedInvocationsAbove(host).map((invocation) => ({
+        depth: invocation.depth,
+        callsiteId: invocation.meta.callsiteId,
+        value: {
+            framework: "react",
+            meta: invocation.meta,
+            props: invocationProps(invocation.fiber),
+            mountedCount: taggedCallsiteMultiplicity(invocation.meta.callsiteId, invocation.root) ?? undefined,
+            ...(canPreviewLive(invocation.root) ? {} : { livePreview: false }),
+        },
+    }));
+    return nearestFirst(boundaries, tagged);
 }
 export function inspectReactRootInvocations(element) {
     if (!getNudgeUiRuntimeConfig().capabilities.componentSemantics)
@@ -187,16 +192,27 @@ export function inspectReactRootInvocations(element) {
     const host = findFiber(element);
     if (!host)
         return null;
-    const invocations = [];
+    const boundaries = [];
+    let depth = 0;
     for (let fiber = host.return ?? null; fiber && !isHostOutput(fiber); fiber = fiber.return ?? null) {
-        if (!isBoundaryType(fiber.type) || !fiber.memoizedProps?.meta)
+        depth += 1;
+        const boundary = boundaryOf(fiber);
+        if (!boundary)
             continue;
         if (hostOutputCount(fiber) !== 1)
             break;
-        const { callsiteId, componentName } = fiber.memoizedProps.meta;
-        invocations.push({ callsiteId, componentName });
+        const { callsiteId, componentName } = boundary.meta;
+        boundaries.push({ depth, callsiteId, value: { callsiteId, componentName } });
     }
-    return invocations;
+    const tagged = taggedRootInvocations(host).map(({ depth: taggedDepth, callsiteId, componentName }) => ({
+        depth: taggedDepth,
+        callsiteId,
+        value: { callsiteId, componentName },
+    }));
+    return nearestFirst(boundaries, tagged);
+}
+function callsiteMultiplicity(callsiteId) {
+    return getReactCallsiteMultiplicity(callsiteId) ?? taggedCallsiteMultiplicity(callsiteId);
 }
 export function replaceReactComponentOverrides(overrides) {
     if (!getNudgeUiRuntimeConfig().capabilities.componentSemantics)
@@ -209,6 +225,7 @@ export function replaceReactComponentOverrides(overrides) {
         props[override.prop] = override.value;
         next.set(override.callsiteId, props);
     }
+    replaceTaggedOverrides(next);
     if (sameOverrideProjection(next))
         return;
     overridesByCallsite = next;
@@ -218,7 +235,7 @@ export const reactComponentRuntimeAdapter = {
     framework: "react",
     inspect: inspectReactComponentTargets,
     replaceOverrides: replaceReactComponentOverrides,
-    getCallsiteMultiplicity: getReactCallsiteMultiplicity,
+    getCallsiteMultiplicity: callsiteMultiplicity,
     rootInvocations: inspectReactRootInvocations,
 };
 registerHostRuntimeAdapter(reactComponentRuntimeAdapter);

package/dist/inspector/componentSemantics/runtimeBridge.d.ts

@@ -1,27 +1,11 @@
 import type { ComponentOverride, ComponentRootInvocation, ComponentRuntimeAdapter, RuntimeComponentTarget } from "./types.js";
 export type { ComponentFramework, ComponentInvocationMeta, ComponentOverride, ComponentRootInvocation, ComponentRuntimeAdapter, RuntimeComponentTarget, } from "./types.js";
-/** Version of the page-global host runtime Adapter Interface. */
 export declare const NUDGE_UI_HOST_RUNTIME_VERSION = 1;
-/**
- * Registers a framework runtime Adapter in the host application's module graph.
- *
- * The registry lives on the page global because the self-contained inspector
- * client and the host Adapter intentionally have separate dependency graphs.
- * Registration replaces an older Adapter for the same framework so HMR does
- * not accumulate stale implementations.
- */
+/** The registry lives on the page global because the inspector client and the host Adapter have separate dependency graphs. */
 export declare function registerHostRuntimeAdapter(adapter: ComponentRuntimeAdapter): () => void;
-/** Returns the active host runtime Adapters for the requested browser realm. */
 export declare function getHostRuntimeAdapters(ownerGlobal?: typeof globalThis): readonly ComponentRuntimeAdapter[];
-/** Stores the latest projection and sends it to every registered host Adapter. */
 export declare function replaceHostRuntimeAdapterOverrides(overrides: readonly ComponentOverride[]): void;
-/**
- * Copies a host Adapter result into the protocol's plain-data value space.
- * React elements, functions, and other reconciler-owned values never cross
- * the host/client seam.
- */
+/** Reconciler-owned values never cross the host/client seam. */
 export declare function copyRuntimeTarget(target: RuntimeComponentTarget): RuntimeComponentTarget;
-/** Copies a host Adapter's root invocations into plain protocol data. */
 export declare function copyRootInvocations(invocations: readonly ComponentRootInvocation[]): ComponentRootInvocation[];
-/** Copies override commands before dispatching them into a host Adapter. */
 export declare function copyComponentOverrides(overrides: readonly ComponentOverride[]): ComponentOverride[];

package/dist/inspector/componentSemantics/runtimeBridge.js

@@ -1,5 +1,4 @@
 import { isComponentFramework } from "./types.js";
-/** Version of the page-global host runtime Adapter Interface. */
 export const NUDGE_UI_HOST_RUNTIME_VERSION = 1;
 const HOST_RUNTIME_KEY = Symbol.for("nudge-ui.host-runtime.v1");
 function registry() {
@@ -21,14 +20,7 @@ function registry() {
     target[HOST_RUNTIME_KEY] = created;
     return created;
 }
-/**
- * Registers a framework runtime Adapter in the host application's module graph.
- *
- * The registry lives on the page global because the self-contained inspector
- * client and the host Adapter intentionally have separate dependency graphs.
- * Registration replaces an older Adapter for the same framework so HMR does
- * not accumulate stale implementations.
- */
+/** The registry lives on the page global because the inspector client and the host Adapter have separate dependency graphs. */
 export function registerHostRuntimeAdapter(adapter) {
     assertRuntimeAdapter(adapter);
     const hostRegistry = registry();
@@ -42,14 +34,14 @@ export function registerHostRuntimeAdapter(adapter) {
         }
     };
 }
-/** Returns the active host runtime Adapters for the requested browser realm. */
 export function getHostRuntimeAdapters(ownerGlobal = globalThis) {
     if (ownerGlobal === globalThis)
         return [...registry().adapters.values()];
+    // SAFETY: the symbol key is this module's private registry slot; symbol lookup works across realms.
     const current = ownerGlobal[HOST_RUNTIME_KEY];
     if (current === undefined)
         return [];
-    const mapConstructor = Reflect.get(ownerGlobal, "Map");
+    const mapConstructor = ownerGlobal.Map;
     if (!mapConstructor
         || typeof current !== "object"
         || current === null
@@ -59,7 +51,6 @@ export function getHostRuntimeAdapters(ownerGlobal = globalThis) {
     }
     return [...(current.adapters.values())];
 }
-/** Stores the latest projection and sends it to every registered host Adapter. */
 export function replaceHostRuntimeAdapterOverrides(overrides) {
     const hostRegistry = registry();
     const frameworks = new Set([
@@ -76,11 +67,7 @@ export function replaceHostRuntimeAdapterOverrides(overrides) {
         hostRegistry.adapters.get(framework)?.replaceOverrides(copyComponentOverrides(projection));
     }
 }
-/**
- * Copies a host Adapter result into the protocol's plain-data value space.
- * React elements, functions, and other reconciler-owned values never cross
- * the host/client seam.
- */
+/** Reconciler-owned values never cross the host/client seam. */
 export function copyRuntimeTarget(target) {
     assertRuntimeTarget(target);
     const props = {};
@@ -102,9 +89,9 @@ export function copyRuntimeTarget(target) {
         },
         props,
         ...(target.mountedCount === undefined ? {} : { mountedCount: target.mountedCount }),
+        ...(target.livePreview === false ? { livePreview: false } : {}),
     };
 }
-/** Copies a host Adapter's root invocations into plain protocol data. */
 export function copyRootInvocations(invocations) {
     if (!Array.isArray(invocations)) {
         throw new TypeError("Nudge UI received invalid root invocations from a host Adapter.");
@@ -121,7 +108,6 @@ export function copyRootInvocations(invocations) {
         return { callsiteId: invocation.callsiteId, componentName: invocation.componentName };
     });
 }
-/** Copies override commands before dispatching them into a host Adapter. */
 export function copyComponentOverrides(overrides) {
     return overrides.map((override) => {
         assertComponentOverride(override);

package/dist/inspector/componentSemantics/textBinding.d.ts

@@ -1,6 +1,5 @@
 import type { ComponentChangeTarget, EditableComponentTarget } from "./types.js";
-import type { TextProjectionTarget } from "../inline-text/textChangeBoundary.js";
-import type { TextBindingEvidence, TextProjectionScope } from "../inline-text/textChangeBoundary.js";
+import type { TextBindingEvidence, TextProjectionScope, TextProjectionTarget } from "../changes/editModel.js";
 /** The order used when more than one visible prop has the same value. */
 export declare const VISIBLE_TEXT_PROP_PRIORITY: readonly ["children", "label", "text", "caption", "description", "title"];
 export type TextEditRejectionReason = "no-text" | "no-binding" | "ambiguous-binding" | "editing-active" | "unsafe-target";
@@ -36,20 +35,16 @@ export interface TextBindingChoice {
     editableTarget: EditableComponentTarget;
     mountedCount: number;
     authoredAs: "literal" | "expression" | "spread" | "default";
-    /** Durable target/source evidence for an item-only commit. */
     renderedTarget: TextProjectionTarget | null;
     renderedSource?: TextBindingRenderedSource;
 }
 export interface TextBindingCandidate {
     binding: TextEditBinding;
-    /** Runtime target retained privately for semantic canonical records. */
     editableTarget?: EditableComponentTarget;
     element: HTMLElement;
     textNode: Text;
     before: string;
-    /** Equal-priority semantic candidates are selected by the inline chooser. */
     bindingChoices?: TextBindingChoice[];
-    /** Repeated literal invocations expose this scope choice before commit. */
     scope?: TextProjectionScope;
     scopeChoices?: TextProjectionScope[];
     mountedCount?: number;
@@ -58,11 +53,7 @@ export interface TextBindingCandidate {
     /** Existing inspector affordance hidden while its empty node is edited. */
     emptyProjectionMarker?: HTMLElement;
 }
-/**
- * Resolves only a confidently matched semantic string binding. Text nodes and
- * the temporary editor host are not identity: the returned component target is
- * the durable callsite used by the canonical component-prop record.
- */
+/** Text nodes and the temporary editor host are not identity; the returned callsite is the durable one. */
 export declare function resolveTextBinding(element: HTMLElement, point?: {
     x: number;
     y: number;

package/dist/inspector/componentSemantics/textBinding.js

@@ -1,5 +1,5 @@
 import { callsiteMultiplicity, editableComponentTargets, inspectComponentTargets, } from "./adapterRegistry.js";
-import { captureTextProjectionTarget, resolveTextProjectionTextNode, textProjectionSelector, } from "../projection/textProjection.js";
+import { captureTextProjectionTarget, hasSafeMixedDescendants, isInApplicationEditingHost, isUnsafeTextHost, resolveTextProjectionTextNode, textProjectionSelector, } from "../projection/textProjection.js";
 /** The order used when more than one visible prop has the same value. */
 export const VISIBLE_TEXT_PROP_PRIORITY = [
     "children",
@@ -17,24 +17,6 @@ const STRUCTURAL_TEXT_PROPS = new Set([
     "role",
     "style",
 ]);
-const UNSAFE_TEXT_TAGS = new Set(["SCRIPT", "STYLE", "TEXTAREA", "OPTION"]);
-const UNSAFE_MIXED_DESCENDANT_TAGS = new Set([
-    ...UNSAFE_TEXT_TAGS,
-    "INPUT",
-    "SELECT",
-    "BUTTON",
-    "A",
-    "B",
-    "STRONG",
-    "I",
-    "EM",
-    "U",
-    "MARK",
-    "CODE",
-    "S",
-    "DEL",
-    "INS",
-]);
 function isStructuralTextProp(name) {
     return STRUCTURAL_TEXT_PROPS.has(name)
         || name.startsWith("data")
@@ -52,9 +34,8 @@ function isApplicationEditingHost(element) {
         && host.getAttribute("contenteditable") !== "false";
 }
 function isApplicationEditingTextNode(element, textNode) {
-    // `element.closest()` only checks the selected root. A tracked root can
-    // contain an application-owned editing island, so inspect the text node's
-    // complete ancestor chain as well.
+    // `element.closest()` only checks the selected root; an editing island can
+    // live deeper, so inspect the text node's own chain as well.
     const editingHost = textNode.parentElement?.closest("[contenteditable]");
     if (!editingHost)
         return false;
@@ -62,9 +43,6 @@ function isApplicationEditingTextNode(element, textNode) {
         && editingHost.getAttribute("contenteditable") !== "false"
         && (editingHost === element || element.contains(editingHost) || editingHost.contains(element));
 }
-function isUnsafeSemanticHost(element) {
-    return UNSAFE_TEXT_TAGS.has(element.tagName);
-}
 function isVisibleTextProp(name) {
     return VISIBLE_TEXT_PROP_PRIORITY.some((candidate) => candidate === name);
 }
@@ -107,33 +85,13 @@ function textNodesFor(element) {
     return nodes;
 }
 function isSafeRenderedTextHost(element, textNode) {
-    if (UNSAFE_TEXT_TAGS.has(element.tagName))
-        return false;
-    const editingHost = element.closest("[contenteditable]");
-    if (editingHost
-        && editingHost.getAttribute("data-inline-editor") !== "true"
-        && editingHost.getAttribute("contenteditable") !== "false")
+    if (isUnsafeTextHost(element) || isInApplicationEditingHost(element))
         return false;
     if (element.children.length === 0) {
         const directTextNodes = Array.from(element.childNodes).filter((node) => node.nodeType === 3);
         return directTextNodes.length === 1 && directTextNodes[0] === textNode;
     }
-    if (!element.contains(textNode))
-        return false;
-    // A line break is layout structure, not rich text content. When the exact
-    // text node is captured, wrapping that node leaves the <br> in place and
-    // preserves both lines. Other inline formatting remains rejected because
-    // replacing text inside it would silently flatten authored markup.
-    for (const descendant of Array.from(element.querySelectorAll("*"))) {
-        if (UNSAFE_MIXED_DESCENDANT_TAGS.has(descendant.tagName))
-            return false;
-        const descendantEditingHost = descendant.closest("[contenteditable]");
-        if (descendantEditingHost
-            && descendantEditingHost.getAttribute("data-inline-editor") !== "true"
-            && descendantEditingHost.getAttribute("contenteditable") !== "false")
-            return false;
-    }
-    return true;
+    return element.contains(textNode) && hasSafeMixedDescendants(element);
 }
 function textNodeAtPoint(element, point) {
     const nodes = textNodesFor(element);
@@ -177,9 +135,8 @@ function mountedCountFor(element, target) {
     const mountedCount = callsiteMultiplicity(target);
     if (mountedCount !== null)
         return mountedCount;
-    // Adapters written before multiplicity was introduced may still provide a
-    // marker-backed inspection. Keep that compatibility fallback conservative:
-    // it can prove one root, but it can never prove an arbitrary count.
+    // Compatibility fallback for adapters predating multiplicity: it can prove
+    // one root, never an arbitrary count.
     return hasUniqueInvocationEvidence(element, target.meta.callsiteId) ? 1 : null;
 }
 function candidatesForText(element, renderedText) {
@@ -229,10 +186,8 @@ function renderedTextCandidate(element, textNode, before, semantic, requireUniqu
     }
     const componentTarget = semantic?.target ?? inspectComponentTargets(element)[0];
     const semanticProperty = semantic?.property;
-    // A component target is only source evidence when it is the callsite that
-    // produced this exact DOM root. For text inside a child host element, the
-    // nearest boundary is the enclosing component invocation, so the element's
-    // own data-src must remain the prompt/change source.
+    // A component target is source evidence only when its callsite produced this
+    // exact DOM root; otherwise the element's own data-src remains the source.
     const elementDataSrc = element.getAttribute("data-src");
     const elementSource = parseRenderedSource(elementDataSrc ?? "");
     const matchingComponentTarget = componentTarget
@@ -280,7 +235,6 @@ function renderedTextCandidate(element, textNode, before, semantic, requireUniqu
         element,
         textNode,
         before,
-        // Keep this private metadata on the candidate for canonical source data.
         renderedSource: {
             file: source.file,
             line: source.line,
@@ -331,11 +285,6 @@ function parseRenderedSource(src) {
         return { file: src, line: 0, column: 0 };
     return { file: match[1] ?? src, line: Number(match[2]), column: Number(match[3]) };
 }
-/**
- * Compatibility evidence for adapters that predate the mounted-count seam.
- * React itself reports multiplicity through the runtime Adapter registry; this
- * fallback is only a one-root proof and is never used to pick an occurrence.
- */
 function hasUniqueInvocationEvidence(element, callsiteId) {
     const nodes = Array.from(element.ownerDocument.querySelectorAll("[data-cid]"));
     const matches = new Set();
@@ -366,11 +315,7 @@ function hasUniqueInvocationEvidence(element, callsiteId) {
     }
     return roots === 1;
 }
-/**
- * Resolves only a confidently matched semantic string binding. Text nodes and
- * the temporary editor host are not identity: the returned component target is
- * the durable callsite used by the canonical component-prop record.
- */
+/** Text nodes and the temporary editor host are not identity; the returned callsite is the durable one. */
 export function resolveTextBinding(element, point) {
     if (isApplicationEditingHost(element)) {
         return {
@@ -379,11 +324,9 @@ export function resolveTextBinding(element, point) {
             message: "Application-owned editing surfaces are not managed by the inspector.",
         };
     }
-    // Hard-dangerous hosts are rejected before adapter inspection. Descendant
-    // markup is intentionally not included: a confident semantic component
-    // binding may still own a nested text node, while rendered fallback keeps
-    // its stricter direct-leaf requirement.
-    if (isUnsafeSemanticHost(element)) {
+    // Descendant markup is intentionally not included: a semantic binding may still own a
+    // nested text node, while the rendered fallback keeps its stricter direct-leaf rule.
+    if (isUnsafeTextHost(element)) {
         return {
             kind: "rejected",
             reason: "unsafe-target",
@@ -439,9 +382,7 @@ export function resolveTextBinding(element, point) {
             renderedSource: rendered?.source,
         };
     });
-    // Multiple equal-priority candidates are not rejected or guessed. The
-    // session exposes these choices to the inline chooser and blocks commit
-    // until the user picks one.
+    // Equal-priority candidates are handed to the inline chooser, never guessed.
     if (choices.length > 1) {
         return {
             binding: firstBinding,
@@ -463,16 +404,13 @@ export function resolveTextBinding(element, point) {
     const authoredAs = authoredAsFor(match.target, match.property);
     const binding = targetBinding(match.target, match.property);
     if (match.mountedCount > 1 && authoredAs !== "literal") {
-        // Expressions/spreads are source-logic intent. A semantic callsite
-        // override would fan out to every item, so retain one durable text target
-        // and tell the prompt to update the data/source logic.
+        // Expressions/spreads are source-logic intent; a callsite override would
+        // fan out to every item, so keep one durable text target instead.
         return renderedTextCandidate(element, textNode, before, match);
     }
     if (match.mountedCount > 1 && authoredAs === "literal") {
-        // Validate the selected output with the same bounded before-text evidence
-        // used by the durable projection. The source-site option remains safe even
-        // when identical outputs make an instance impossible to distinguish, but
-        // an item-only session is never allowed to guess.
+        // Item-only scope must validate against the same bounded before-text
+        // evidence as the durable projection; source-site stays safe either way.
         const rendered = renderedTextCandidate(element, textNode, before, match, false);
         if (!("kind" in rendered)) {
             return {
@@ -484,10 +422,8 @@ export function resolveTextBinding(element, point) {
                 scopeChoices: ["rendered-instance", "source-site"],
             };
         }
-        // An unsafe/missing rendered-text projection only removes the item-scoped
-        // option. The explicit all-output source-site edit is still a safe
-        // canonical component-prop change and must not be rejected because the
-        // DOM fallback cannot capture bounded instance evidence.
+        // A missing rendered projection only removes the item-scoped option; the
+        // all-output source-site edit is still a safe canonical change.
         return {
             binding,
             editableTarget: match.target,
@@ -499,9 +435,6 @@ export function resolveTextBinding(element, point) {
             scopeChoices: ["source-site"],
         };
     }
-    // Unique invocation (mountedCount === 1): the callsite is unambiguous, so
-    // the source-site edit is always safe and no scope choice is offered. The
-    // mountedCount > 1 cases all returned above.
     return {
         binding,
         editableTarget: match.target,

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

@@ -1,16 +1,13 @@
 import type { RuntimeProps } from "./runtimeTypes.js";
 import type { EditScope } from "../editScope.js";
+import type { ComponentInvocationMeta } from "../../compiler/componentContractTypes.js";
 export type ComponentPropValue = string | number | boolean;
 export type AuthoredPropKind = "literal" | "expression" | "spread" | "default";
 export declare const COMPONENT_FRAMEWORKS: readonly ["react"];
 export type ComponentFramework = (typeof COMPONENT_FRAMEWORKS)[number];
 export type ComponentChangeScope = EditScope;
-/** Returns whether a host value names a supported component framework. */
 export declare function isComponentFramework(value: string): value is ComponentFramework;
-/**
- * Bounded evidence for the rendered invocation that a text edit started from.
- * This is deliberately JSON data, never a DOM node or a React fiber.
- */
+/** Deliberately JSON data, never a DOM node or a React fiber. */
 export interface ComponentInvocationEvidence {
     occurrence: number;
     props: string | null;
@@ -40,26 +37,18 @@ export interface ComponentChangeRecord {
     before: ComponentPropBaseline;
     after: ComponentPropValue;
     authoredAs: AuthoredPropKind;
-    /** `source-site` is the historical/default semantic projection scope. */
     scope?: ComponentChangeScope;
-    /** Present when an inline scope decision was made from one rendered item. */
     evidence?: ComponentInvocationEvidence;
 }
-export interface ComponentInvocationMeta {
-    callsiteId: string;
-    componentId: string;
-    componentName: string;
-    file: string;
-    line: number;
-    column: number;
-    authoredProps: Record<string, Exclude<AuthoredPropKind, "default">>;
-}
+/** The compiler owns this wire format; the runtime only reads it. */
+export type { ComponentInvocationMeta };
 export interface RuntimeComponentTarget {
     framework: ComponentFramework;
     meta: ComponentInvocationMeta;
     props: RuntimeProps;
-    /** Adapter-reported mounted invocation count for this callsite. */
     mountedCount?: number;
+    /** False when the runtime cannot render a prop change (the change still reaches the prompt); absent means live. */
+    livePreview?: boolean;
 }
 /** A component invocation whose entire rendered output is one DOM element. */
 export interface ComponentRootInvocation {
@@ -92,16 +81,8 @@ export interface ComponentRuntimeAdapter {
     framework: ComponentFramework;
     inspect(element: HTMLElement): RuntimeComponentTarget[];
     replaceOverrides(overrides: ComponentOverride[]): void;
-    /**
-     * Return the number of currently mounted invocations for a callsite. A
-     * runtime that cannot prove this must return null/undefined so callers can
-     * fail closed instead of broadening a semantic override.
-     */
+    /** A runtime that cannot prove the count must return null so callers fail closed. */
     getCallsiteMultiplicity?(callsiteId: string): number | null | undefined;
-    /**
-     * Return, nearest first, the invocations whose entire rendered output is
-     * this element. A runtime that cannot read the element's ancestry must
-     * return null so structural identity fails closed.
-     */
+    /** Nearest first; null when the runtime cannot read the element's ancestry, so structural identity fails closed. */
     rootInvocations?(element: HTMLElement): ComponentRootInvocation[] | null;
 }

package/dist/inspector/componentSemantics/types.js

@@ -1,5 +1,4 @@
 export const COMPONENT_FRAMEWORKS = ["react"];
-/** Returns whether a host value names a supported component framework. */
 export function isComponentFramework(value) {
     return COMPONENT_FRAMEWORKS.some((framework) => framework === value);
 }

package/dist/inspector/conformance/borderCases.d.ts

@@ -1,7 +1,2 @@
 import type { ConformanceFixture } from "./fixture.js";
-/**
- * Framework-neutral border corpus. Covers shorthand decomposition into width,
- * style, and color longhands (including omitted CSS initials), side-specific
- * shorthands, token attribution, border-radius, and true raw fallbacks.
- */
 export declare const BORDER_CASES: ConformanceFixture[];