nudge-ui 0.2.4 → 0.2.6

package/dist/inspector/componentSemantics/ComponentPropsSection.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { isComponentChange, useChanges } from "../changes/changesLog.js";
+import { isComponentChange } from "../changes/types.js";
+import { useChanges } from "../drafts/store.js";
 import { FieldRow } from "../ui/FieldRow.js";
 import { Select } from "../ui/Select.js";
 import { SegmentedControl } from "../ui/SegmentedControl.js";
@@ -20,18 +21,21 @@ function pendingValue(target, prop, changes) {
 function valueFromOption(prop, serialized) {
     return prop.options.find((option) => String(option) === serialized) ?? serialized;
 }
-export function ComponentPropsSection({ selected }) {
+export function useComponentProps(selected) {
     const changes = useChanges();
-    const target = editableComponentTargets(selected.componentTargets)[0];
+    const target = selected ? editableComponentTargets(selected.componentTargets)[0] : undefined;
     if (!target)
         return null;
-    // Text contracts are owned by the scoped inline editor in this slice. A
-    // panel input would turn every keystroke into an independent history entry;
-    // a single-commit panel transaction belongs to a later interaction design.
+    // Text props are owned by the scoped inline editor, not this panel.
     const visibleProps = target.contract.props.filter((prop) => prop.control !== "text" && pendingValue(target, prop, changes) !== undefined);
-    if (visibleProps.length === 0)
+    return visibleProps.length === 0 ? null : { target, visibleProps, changes };
+}
+export function ComponentPropsSection({ selected }) {
+    const view = useComponentProps(selected);
+    if (!view)
         return null;
-    return (_jsxs("section", { className: "editor component-props", "data-test": "component-props-section", "data-component": target.meta.componentName, children: [_jsx("div", { className: "editor__title-row", children: _jsx("div", { className: "editor__title", children: target.meta.componentName }) }), visibleProps.map((prop) => {
+    const { target, visibleProps, changes } = view;
+    return (_jsxs("section", { className: "editor component-props", "data-test": "component-props-section", "data-component": target.meta.componentName, children: [target.livePreview === false ? (_jsx("div", { className: "component-props__hint", "data-test": "component-props-prompt-only", children: "Live preview isn't available here. Changes are added to the prompt." })) : null, visibleProps.map((prop) => {
                 const current = pendingValue(target, prop, changes);
                 return (_jsx(FieldRow, { label: prop.name, property: prop.name, "data-test": "component-prop", children: prop.control === "boolean" ? (_jsx(SegmentedControl, { "aria-label": `${prop.name} component prop`, "data-test": "component-prop-boolean", "data-property": prop.name, value: current ? "true" : "false", options: [
                             { value: "false", label: "Off" },

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

@@ -1,16 +1,9 @@
 import type { ComponentOverride, ComponentRootInvocation, ComponentRuntimeAdapter, EditableComponentTarget, RuntimeComponentTarget } from "./types.js";
-/** Register a framework adapter without coupling semantic resolution to React. */
 export declare function registerComponentRuntimeAdapter(adapter: ComponentRuntimeAdapter): () => void;
 export declare function inspectComponentTargets(element: HTMLElement): RuntimeComponentTarget[];
-/**
- * Returns the invocations, nearest first, whose entire rendered output is this
- * element. Null means no enabled runtime could read the element's ancestry.
- */
+/** Nearest first; null means no enabled runtime could read the element's ancestry. */
 export declare function inspectRootInvocations(element: HTMLElement): ComponentRootInvocation[] | null;
-/**
- * Resolve multiplicity through the owning runtime Adapter. The inspector does
- * not infer it from DOM order or retain a React fiber as durable identity.
- */
+/** Multiplicity is never inferred from DOM order. */
 export declare function callsiteMultiplicity(target: RuntimeComponentTarget): number | null;
 export declare function editableComponentTargets(targets: RuntimeComponentTarget[]): EditableComponentTarget[];
 export declare function replaceComponentOverrideProjection(overrides: ComponentOverride[]): void;

package/dist/inspector/componentSemantics/adapterRegistry.js

@@ -6,7 +6,6 @@ function enabledRuntimeAdapters(ownerGlobal) {
         return [];
     return [...getHostRuntimeAdapters(ownerGlobal)];
 }
-/** Register a framework adapter without coupling semantic resolution to React. */
 export function registerComponentRuntimeAdapter(adapter) {
     return registerHostRuntimeAdapter(adapter);
 }
@@ -42,10 +41,7 @@ export function inspectComponentTargets(element) {
     }
     return targets;
 }
-/**
- * Returns the invocations, nearest first, whose entire rendered output is this
- * element. Null means no enabled runtime could read the element's ancestry.
- */
+/** Nearest first; null means no enabled runtime could read the element's ancestry. */
 export function inspectRootInvocations(element) {
     let invocations = null;
     const ownerGlobal = element.ownerDocument.defaultView ?? globalThis;
@@ -70,10 +66,7 @@ function diagnoseAdapter(adapter, detail) {
     diagnosedAdapters.add(adapter);
     console.warn(`[nudge-ui] Ignored invalid ${adapter.framework} Adapter inspection: ${detail}`);
 }
-/**
- * Resolve multiplicity through the owning runtime Adapter. The inspector does
- * not infer it from DOM order or retain a React fiber as durable identity.
- */
+/** Multiplicity is never inferred from DOM order. */
 export function callsiteMultiplicity(target) {
     return target.mountedCount === undefined ? null : target.mountedCount;
 }

package/dist/inspector/componentSemantics/changeAction.js

@@ -1,4 +1,4 @@
-import { appendChange } from "../changes/changesLog.js";
+import { appendChange } from "../drafts/store.js";
 import { createComponentPropChange } from "./changeModel.js";
 export { createComponentPropChange } from "./changeModel.js";
 export function setComponentProp(target, prop, value) {

package/dist/inspector/componentSemantics/changeModel.js

@@ -39,10 +39,8 @@ export function componentChangeToOverride(change) {
     if (mountedCount !== undefined
         && (!Number.isSafeInteger(mountedCount) || mountedCount < 0))
         return null;
-    // A rendered-instance semantic record is intentionally never projected as a
-    // callsite override. Repeated expression/spread props are equally unsafe to
-    // broaden, even when a malformed/internal record asks for source-site scope.
-    // Repeated literals remain explicitly source-editable.
+    // Rendered-instance records and repeated expression/spread props must never
+    // broaden to a callsite override; repeated literals stay source-editable.
     if (mountedCount !== undefined && mountedCount > 1) {
         if (change.scope !== "source-site")
             return null;

package/dist/inspector/componentSemantics/react/callsites.d.ts

@@ -0,0 +1,28 @@
+import type { ComponentInvocationMeta, ComponentRootInvocation } from "../types.js";
+import { type Fiber, type FiberProps } from "./fibers.js";
+import { type FiberRoot } from "./devtoolsHook.js";
+export interface TaggedInvocation {
+    meta: ComponentInvocationMeta;
+    fiber: Fiber;
+    /** Distance above the inspected host fiber, for ordering against boundaries. */
+    depth: number;
+    root: FiberRoot | null;
+}
+/** Called from transformed modules before any of their JSX renders. */
+export declare function registerReactCallsites(metas: readonly ComponentInvocationMeta[]): void;
+export declare function invocationProps(fiber: Fiber): FiberProps;
+/**
+ * Nearest invocation first. One callsite can span several fibers (memo/forwardRef
+ * layers, or a component spreading props onward): with no host output between
+ * them they are one invocation owned by the outermost layer; a repeat above is recursive.
+ */
+export declare function taggedInvocationsAbove(host: Fiber): TaggedInvocation[];
+export declare function taggedRootInvocations(host: Fiber): Array<ComponentRootInvocation & {
+    depth: number;
+}>;
+export declare function taggedCallsiteMultiplicity(callsiteId: string, root?: FiberRoot | null): number | null;
+export declare function canPreviewLive(root: FiberRoot | null): boolean;
+/** Overrides for registered callsites only; wrapped callsites keep their boundary. */
+export declare function replaceTaggedOverrides(next: ReadonlyMap<string, FiberProps>): void;
+/** Test/runtime teardown hook. */
+export declare function resetTaggedCallsites(): void;

package/dist/inspector/componentSemantics/react/callsites.js

@@ -0,0 +1,261 @@
+import { IDENTITY_ATTRIBUTES } from "../../../compiler/identityAttributes.js";
+import { HOST_ROOT_TAG, hostOutputCount, isHostOutput } from "./fibers.js";
+import { commitGeneration, onCommit, propEditingRenderer, rememberRoot, trackedRoots, trackedRootsAvailable, } from "./devtoolsHook.js";
+// React keeps `data-src` on a component's fiber whether or not the component forwards it to the DOM.
+const IDENTITY_PROPS = new Set(IDENTITY_ATTRIBUTES);
+const callsites = new Map();
+let overridesByCallsite = new Map();
+/** Called from transformed modules before any of their JSX renders. */
+export function registerReactCallsites(metas) {
+    for (const meta of metas)
+        callsites.set(meta.callsiteId, meta);
+    registrations += 1;
+    observeCommits();
+}
+function taggedCallsite(fiber) {
+    if (isHostOutput(fiber))
+        return null;
+    const src = fiber.memoizedProps?.["data-src"];
+    return typeof src === "string" ? callsites.get(src) ?? null : null;
+}
+export function invocationProps(fiber) {
+    const props = {};
+    for (const [name, value] of Object.entries(fiber.memoizedProps ?? {})) {
+        if (!IDENTITY_PROPS.has(name))
+            props[name] = value;
+    }
+    return props;
+}
+function resolveRoot(host) {
+    let top = host;
+    while (top.return)
+        top = top.return;
+    if (top.tag !== HOST_ROOT_TAG)
+        return { root: null, onCurrentTree: true };
+    // SAFETY: a HostRoot fiber's stateNode is its FiberRoot; it is checked to be an object below.
+    const root = top.stateNode;
+    if (!root || typeof root !== "object")
+        return { root: null, onCurrentTree: true };
+    rememberRoot(root);
+    return { root, onCurrentTree: root.current === top };
+}
+function displayedFiber(fiber, onCurrentTree) {
+    return onCurrentTree ? fiber : fiber.alternate ?? fiber;
+}
+/**
+ * Nearest invocation first. One callsite can span several fibers (memo/forwardRef
+ * layers, or a component spreading props onward): with no host output between
+ * them they are one invocation owned by the outermost layer; a repeat above is recursive.
+ */
+export function taggedInvocationsAbove(host) {
+    if (callsites.size === 0)
+        return [];
+    const { root, onCurrentTree } = resolveRoot(host);
+    const found = new Map();
+    let chain = null;
+    let depth = 0;
+    for (let fiber = host.return ?? null; fiber; fiber = fiber.return ?? null) {
+        depth += 1;
+        if (isHostOutput(fiber)) {
+            chain = null;
+            continue;
+        }
+        const meta = taggedCallsite(fiber);
+        if (!meta)
+            continue;
+        const existing = found.get(meta.callsiteId);
+        if (existing && chain === meta.callsiteId) {
+            existing.fiber = displayedFiber(fiber, onCurrentTree);
+        }
+        else if (!existing) {
+            found.set(meta.callsiteId, { meta, fiber: displayedFiber(fiber, onCurrentTree), depth, root });
+            chain = meta.callsiteId;
+        }
+        else {
+            chain = null;
+        }
+    }
+    return [...found.values()];
+}
+export function taggedRootInvocations(host) {
+    if (callsites.size === 0)
+        return [];
+    const invocations = [];
+    const seen = new Set();
+    let depth = 0;
+    for (let fiber = host.return ?? null; fiber && !isHostOutput(fiber); fiber = fiber.return ?? null) {
+        depth += 1;
+        const meta = taggedCallsite(fiber);
+        if (!meta || seen.has(meta.callsiteId))
+            continue;
+        if (hostOutputCount(fiber) !== 1)
+            break;
+        seen.add(meta.callsiteId);
+        invocations.push({ callsiteId: meta.callsiteId, componentName: meta.componentName, depth });
+    }
+    return invocations;
+}
+// A mounted tree only changes at a commit, so one walk per root serves every inspection
+// until the next commit; without an observer there is no signal, so nothing is cached.
+let registrations = 0;
+const walkedRoots = new WeakMap();
+function mountedInvocations(roots) {
+    const merged = new Map();
+    const commits = commitGeneration();
+    const version = commits === null ? null : `${commits}:${registrations}`;
+    for (const root of roots) {
+        const cached = walkedRoots.get(root);
+        const invocations = version !== null && cached?.version === version
+            ? cached.invocations
+            : walkRoot(root);
+        if (version !== null)
+            walkedRoots.set(root, { version, invocations });
+        for (const [callsiteId, fibers] of invocations) {
+            merged.set(callsiteId, [...(merged.get(callsiteId) ?? []), ...fibers]);
+        }
+    }
+    return merged;
+}
+function walkRoot(root) {
+    const invocations = new Map();
+    const top = root.current;
+    if (!top)
+        return invocations;
+    const stack = [[top, null]];
+    while (stack.length > 0) {
+        const [fiber, chain] = stack.pop();
+        let next = chain;
+        if (isHostOutput(fiber)) {
+            next = null;
+        }
+        else {
+            const meta = taggedCallsite(fiber);
+            if (meta && meta.callsiteId !== chain) {
+                const list = invocations.get(meta.callsiteId) ?? [];
+                list.push(fiber);
+                invocations.set(meta.callsiteId, list);
+                next = meta.callsiteId;
+            }
+        }
+        for (let child = fiber.child ?? null; child; child = child.sibling ?? null) {
+            stack.push([child, next]);
+        }
+    }
+    return invocations;
+}
+function rootsIncluding(root) {
+    const roots = trackedRoots();
+    return root && !roots.includes(root) ? [...roots, root] : roots;
+}
+export function taggedCallsiteMultiplicity(callsiteId, root = null) {
+    if (!callsites.has(callsiteId))
+        return null;
+    const count = mountedInvocations(rootsIncluding(root)).get(callsiteId)?.length ?? 0;
+    return count > 0 ? count : null;
+}
+export function canPreviewLive(root) {
+    return propEditingRenderer(root ?? undefined) !== null;
+}
+/**
+ * The authored value a prop had before its override. A rendered value that is not
+ * the last applied override came from a parent render and replaces the record;
+ * both fibers of an invocation share the record because React alternates between them.
+ */
+const authoredValues = new WeakMap();
+function authoredFor(fiber) {
+    const existing = authoredValues.get(fiber) ?? (fiber.alternate ? authoredValues.get(fiber.alternate) : undefined);
+    const record = existing ?? new Map();
+    authoredValues.set(fiber, record);
+    if (fiber.alternate)
+        authoredValues.set(fiber.alternate, record);
+    return record;
+}
+/** React's override starts from the last rendered props, so two calls before a render would lose the first. */
+function editInvocation(renderer, fiber, overrides, restoring) {
+    const rendered = fiber.memoizedProps ?? {};
+    const next = { ...rendered };
+    const authored = authoredFor(fiber);
+    let changed = false;
+    for (const prop of restoring ?? []) {
+        const original = authored.get(prop);
+        if (!original)
+            continue;
+        authored.delete(prop);
+        if (original.present)
+            next[prop] = original.value;
+        else
+            delete next[prop];
+        changed = true;
+    }
+    for (const [prop, value] of Object.entries(overrides ?? {})) {
+        if (Object.is(rendered[prop], value))
+            continue;
+        const record = authored.get(prop);
+        if (record && Object.is(rendered[prop], record.applied)) {
+            record.applied = value;
+        }
+        else {
+            authored.set(prop, { present: Object.hasOwn(rendered, prop), value: rendered[prop], applied: value });
+        }
+        next[prop] = value;
+        changed = true;
+    }
+    if (changed)
+        renderer.overrideProps?.(fiber, [], next);
+}
+function applyOverrides(restoring = new Map()) {
+    if (overridesByCallsite.size === 0 && restoring.size === 0)
+        return;
+    const callsiteIds = new Set([...overridesByCallsite.keys(), ...restoring.keys()]);
+    for (const root of trackedRoots()) {
+        const renderer = propEditingRenderer(root);
+        if (!renderer?.overrideProps)
+            continue;
+        const invocations = mountedInvocations([root]);
+        for (const callsiteId of callsiteIds) {
+            for (const fiber of invocations.get(callsiteId) ?? []) {
+                editInvocation(renderer, fiber, overridesByCallsite.get(callsiteId), restoring.get(callsiteId));
+            }
+        }
+    }
+}
+/** Overrides for registered callsites only; wrapped callsites keep their boundary. */
+export function replaceTaggedOverrides(next) {
+    const registered = new Map([...next].filter(([callsiteId]) => callsites.has(callsiteId)));
+    const restoring = new Map();
+    for (const [callsiteId, props] of overridesByCallsite) {
+        const following = registered.get(callsiteId);
+        const dropped = Object.keys(props).filter((prop) => !following || !Object.hasOwn(following, prop));
+        if (dropped.length > 0)
+            restoring.set(callsiteId, new Set(dropped));
+    }
+    overridesByCallsite = registered;
+    observeCommits();
+    applyOverrides(restoring);
+}
+// Overrides are reapplied after every commit because a parent render hands an
+// invocation its authored props again; skipping unchanged values ends the cycle.
+let reapplyQueued = false;
+let stopObserving = null;
+function observeCommits() {
+    if (stopObserving)
+        return;
+    const stop = onCommit(() => {
+        if (overridesByCallsite.size === 0 || reapplyQueued)
+            return;
+        reapplyQueued = true;
+        queueMicrotask(() => {
+            reapplyQueued = false;
+            applyOverrides();
+        });
+    });
+    if (trackedRootsAvailable())
+        stopObserving = stop;
+}
+/** Test/runtime teardown hook. */
+export function resetTaggedCallsites() {
+    callsites.clear();
+    overridesByCallsite = new Map();
+    stopObserving?.();
+    stopObserving = null;
+}

package/dist/inspector/componentSemantics/react/devtoolsHook.d.ts

@@ -0,0 +1,23 @@
+import type { Fiber, FiberProps } from "./fibers.js";
+/** The private seam React DevTools edits props through; read defensively because it is not public API. */
+export interface ReactRendererInternals {
+    /** An empty path replaces the whole props object, which is the only form used here. */
+    overrideProps?: (fiber: Fiber, path: [], value: FiberProps) => void;
+}
+export interface FiberRoot {
+    current?: Fiber | null;
+}
+/**
+ * A fiber must only be edited by its own renderer: a known owner without the toolkit
+ * (a production build) answers null rather than borrowing another copy's; an unknown
+ * owner resolves only when exactly one capable renderer exists.
+ */
+export declare function propEditingRenderer(root?: FiberRoot): ReactRendererInternals | null;
+/** Commits seen so far, or null when commits cannot be observed. */
+export declare function commitGeneration(): number | null;
+/** True once commits are observable, which needs a hook on the page. */
+export declare function trackedRootsAvailable(): boolean;
+export declare function trackedRoots(): FiberRoot[];
+/** Records a root found from the DOM, for trees that committed before observation began. */
+export declare function rememberRoot(root: FiberRoot): void;
+export declare function onCommit(listener: (root: FiberRoot) => void): () => void;

package/dist/inspector/componentSemantics/react/devtoolsHook.js

@@ -0,0 +1,71 @@
+const COMMIT_OBSERVER = Symbol.for("nudge-ui.react-commit-observer");
+function hook() {
+    // SAFETY: the global is absent or a hook object installed by React Refresh,
+    // React DevTools, or the capture script; members are checked before use.
+    const value = globalThis.__REACT_DEVTOOLS_GLOBAL_HOOK__;
+    return typeof value === "object" && value !== null ? value : null;
+}
+/**
+ * A fiber must only be edited by its own renderer: a known owner without the toolkit
+ * (a production build) answers null rather than borrowing another copy's; an unknown
+ * owner resolves only when exactly one capable renderer exists.
+ */
+export function propEditingRenderer(root) {
+    const renderers = hook()?.renderers;
+    if (!(renderers instanceof Map))
+        return null;
+    const rendererId = root ? commitObserver()?.roots.get(root) : undefined;
+    if (rendererId !== undefined && rendererId >= 0) {
+        const owner = renderers.get(rendererId);
+        return typeof owner?.overrideProps === "function" ? owner : null;
+    }
+    const capable = [...renderers.values()].filter((renderer) => typeof renderer?.overrideProps === "function");
+    return capable.length === 1 ? capable[0] : null;
+}
+/** Observes commits through the hook once per realm; roots are recorded so the runtime can walk mounted trees without a DOM query. */
+function commitObserver() {
+    const target = hook();
+    if (!target)
+        return null;
+    const existing = target[COMMIT_OBSERVER];
+    if (existing)
+        return existing;
+    const observer = { roots: new Map(), listeners: new Set(), generation: 0 };
+    const previous = target.onCommitFiberRoot;
+    target.onCommitFiberRoot = function onCommitFiberRoot(rendererId, root, ...details) {
+        if (typeof previous === "function")
+            previous.call(this, rendererId, root, ...details);
+        observer.generation += 1;
+        if (root && typeof root === "object") {
+            observer.roots.set(root, rendererId);
+            for (const listener of observer.listeners)
+                listener(root);
+        }
+    };
+    target[COMMIT_OBSERVER] = observer;
+    return observer;
+}
+/** Commits seen so far, or null when commits cannot be observed. */
+export function commitGeneration() {
+    return commitObserver()?.generation ?? null;
+}
+/** True once commits are observable, which needs a hook on the page. */
+export function trackedRootsAvailable() {
+    return commitObserver() !== null;
+}
+export function trackedRoots() {
+    return [...(commitObserver()?.roots.keys() ?? [])];
+}
+/** Records a root found from the DOM, for trees that committed before observation began. */
+export function rememberRoot(root) {
+    const observer = commitObserver();
+    if (observer && !observer.roots.has(root))
+        observer.roots.set(root, -1);
+}
+export function onCommit(listener) {
+    const observer = commitObserver();
+    if (!observer)
+        return () => undefined;
+    observer.listeners.add(listener);
+    return () => observer.listeners.delete(listener);
+}

package/dist/inspector/componentSemantics/react/fibers.d.ts

@@ -0,0 +1,17 @@
+/** Props exactly as the application passed them; values are read and checked individually. */
+export type FiberProps = Readonly<Record<string, unknown>>;
+export interface Fiber {
+    type?: unknown;
+    tag?: number;
+    memoizedProps?: FiberProps | null;
+    return?: Fiber | null;
+    child?: Fiber | null;
+    sibling?: Fiber | null;
+    alternate?: Fiber | null;
+    stateNode?: unknown;
+}
+export declare const HOST_ROOT_TAG = 3;
+export declare function findFiber(element: Element): Fiber | null;
+export declare function isHostOutput(fiber: Fiber): boolean;
+/** Counts top-level host outputs below a fiber, stopping once there are two. */
+export declare function hostOutputCount(fiber: Fiber): number;

package/dist/inspector/componentSemantics/react/fibers.js

@@ -0,0 +1,30 @@
+/** React work tags for host output that has no string element type. */
+const HOST_PORTAL_TAG = 4;
+const HOST_TEXT_TAG = 6;
+export const HOST_ROOT_TAG = 3;
+export function findFiber(element) {
+    for (const key of Object.keys(element)) {
+        if (key.startsWith("__reactFiber$") || key.startsWith("__reactInternalInstance$")) {
+            // SAFETY: React DOM stores the node's fiber under this generated key; every field is read defensively.
+            return element[key] ?? null;
+        }
+    }
+    return null;
+}
+export 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. */
+export 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;
+}

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

@@ -1,10 +1,11 @@
 import { type ReactElement } from "react";
-import type { ComponentInvocationMeta, ComponentOverride, ComponentRootInvocation, ComponentRuntimeAdapter, RuntimeComponentTarget } from "./types.js";
-/** Returns null when this runtime has no mounted boundary for the callsite. */
+import type { ComponentInvocationMeta, ComponentOverride, ComponentRootInvocation, ComponentRuntimeAdapter, RuntimeComponentTarget } from "../types.js";
+export { registerReactCallsites } from "./callsites.js";
 export declare function getReactCallsiteMultiplicity(callsiteId: string): number | null;
 /** Test/runtime teardown hook; canonical changes never depend on this state. */
 export declare function resetReactComponentRuntime(): void;
 export declare function instrumentReactComponent(element: ReactElement<Record<string, unknown>>, meta: ComponentInvocationMeta): ReactElement;
+/** Wrapped callsites answer through their boundary, others through their fiber's identity tag; both merge nearest first. */
 export declare function inspectReactComponentTargets(element: HTMLElement): RuntimeComponentTarget[];
 export declare function inspectReactRootInvocations(element: HTMLElement): ComponentRootInvocation[] | null;
 export declare function replaceReactComponentOverrides(overrides: ComponentOverride[]): void;