nudge-ui 0.2.0

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

@@ -0,0 +1,76 @@
+import type { TokenEntry } from "../../css/model/index.js";
+import type { ComponentChangeRecord } from "../componentSemantics/types.js";
+import type { EditScope, RenderedInstanceOverride, StyleRuleContext, TextContentChangeRecord } from "./editModel.js";
+/** Bounded rendered facts retained for one element without an authored source location. */
+export interface RuntimeElementEvidence {
+    /**
+     * Why the location is unknown; prompts phrase their guidance accordingly.
+     * Omitted by legacy records, which are all runtime-created DOM.
+     */
+    reason?: "runtime-created" | "unannotated";
+    tagName: string;
+    text: string | null;
+    props: string | null;
+    ariaLabel: string | null;
+}
+export interface ElementChangeRecord {
+    kind?: "element";
+    cid: string;
+    file: string;
+    line: number;
+    /** Exact source column for static HTML; omitted by legacy React records. */
+    column?: number;
+    selector: string;
+    property: string;
+    /** CSSOM-declared source context that the inspector projection came from. */
+    sourceProperty?: string;
+    /** Best-effort CSSOM serialization; not an exact source-text quote. */
+    sourceAuthoredValue?: string;
+    oldToken: TokenEntry | null;
+    newToken: TokenEntry | null;
+    rawValue?: string;
+    oldRawValue?: string;
+    source: {
+        file: string;
+        line: number;
+        component: string;
+    };
+    /** Present when the selected element has a document-local runtime identity. */
+    runtimeEvidence?: RuntimeElementEvidence;
+    scope?: EditScope;
+    /** Durable, controller-owned target for one rendered output. */
+    instanceOverride?: RenderedInstanceOverride;
+    state?: "base" | "hover" | "active" | "focus" | "focus-visible" | "disabled";
+}
+export interface TokenChangeRecord {
+    kind: "token";
+    tokenName: string;
+    file: string;
+    line: number;
+    selector: string;
+    property: string;
+    rawValue: string;
+    oldRawValue: string;
+    important: boolean;
+    context: StyleRuleContext;
+    contextLabel: string;
+    source: {
+        file: string;
+        line: number;
+        component: string;
+    };
+    cid?: undefined;
+    oldToken?: null;
+    newToken?: null;
+    scope?: undefined;
+}
+export type ChangeRecord = ElementChangeRecord | TokenChangeRecord | ComponentChangeRecord | TextContentChangeRecord;
+export type PreviewableChangeRecord = ElementChangeRecord | TokenChangeRecord;
+export declare function isTokenChange(change: ChangeRecord): change is TokenChangeRecord;
+export declare function isComponentChange(change: ChangeRecord): change is ComponentChangeRecord;
+export declare function isTextContentChange(change: ChangeRecord): change is TextContentChangeRecord;
+export declare function isElementChange(change: ChangeRecord): change is ElementChangeRecord;
+export declare function isPreviewableChange(change: ChangeRecord): change is PreviewableChangeRecord;
+export type { ComponentChangeRecord } from "../componentSemantics/types.js";
+export type { TextBindingEvidence, TextContentChangeRecord, TextProjectionScope, TextProjectionSourceSite, TextProjectionTarget, } from "./editModel.js";
+export { isTextContentChangeListValue, isTextContentChangeValue, isTextProjectionTargetValue, } from "./editModel.js";

package/dist/inspector/changes/types.js

@@ -0,0 +1,16 @@
+export function isTokenChange(change) {
+    return change.kind === "token";
+}
+export function isComponentChange(change) {
+    return change.kind === "component-prop";
+}
+export function isTextContentChange(change) {
+    return change.kind === "text-content";
+}
+export function isElementChange(change) {
+    return !isTokenChange(change) && !isComponentChange(change) && !isTextContentChange(change);
+}
+export function isPreviewableChange(change) {
+    return isElementChange(change) || isTokenChange(change);
+}
+export { isTextContentChangeListValue, isTextContentChangeValue, isTextProjectionTargetValue, } from "./editModel.js";

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

@@ -0,0 +1,43 @@
+import type { ChangeRecord } from "./types.js";
+import type { StructuralChange } from "./structuralTypes.js";
+export interface WorkspaceContents {
+    readonly changes: readonly ChangeRecord[];
+    readonly structuralChanges: readonly StructuralChange[];
+}
+export interface WorkspaceChangesSnapshot extends WorkspaceContents {
+    readonly revision: number;
+    readonly canUndo: boolean;
+    readonly canRedo: boolean;
+}
+export type WorkspaceProjector = (snapshot: WorkspaceChangesSnapshot) => void;
+export type CommitResult = "applied" | "unchanged" | "blocked";
+export interface WorkspaceChangeStore {
+    getSnapshot(): WorkspaceChangesSnapshot;
+    subscribe(listener: () => void): () => void;
+    commitChangeRecords(incoming: readonly ChangeRecord[]): CommitResult;
+    revertChangeRecord(change: ChangeRecord): boolean;
+    discardChangeRecords(target: {
+        kind: "selector";
+        selector: string;
+    } | {
+        kind: "instance-override";
+        id: string;
+    }): boolean;
+    commitStructuralChange(change: StructuralChange): boolean;
+    revertStructuralChangeRecord(changeId: string): boolean;
+    reconcileWorkspaceChanges(verifiedKeys: ReadonlySet<string>, verifiedStructuralIds: ReadonlySet<string>): number;
+    undoWorkspaceChange(): boolean;
+    redoWorkspaceChange(): boolean;
+    restoreWorkspaceChanges(next: WorkspaceContents): void;
+    clearWorkspaceChanges(): void;
+}
+export declare const workspaceChangeStore: WorkspaceChangeStore;
+/** Compatibility accessors retained for callers that have not adopted the store seam. */
+export declare function getWorkspaceChanges(): WorkspaceChangesSnapshot;
+export declare function subscribeWorkspaceChanges(listener: () => void): () => void;
+export declare function commitChangeRecords(incoming: readonly ChangeRecord[], project: WorkspaceProjector): CommitResult;
+export declare function commitStructuralChange(change: StructuralChange, project: WorkspaceProjector): boolean;
+export declare function undoWorkspaceChange(project: WorkspaceProjector): boolean;
+export declare function redoWorkspaceChange(project: WorkspaceProjector): boolean;
+export declare function restoreWorkspaceChanges(next: WorkspaceContents, project: WorkspaceProjector): void;
+export declare function resetWorkspaceChanges(): void;

package/dist/inspector/changes/workspaceChanges.js

@@ -0,0 +1,239 @@
+import { canWriteWorkspace } from "../canvas/workspaceLease.js";
+import { changeKey, mergeChange, sameEffectiveChanges, selectorForChange } from "./model.js";
+import { isElementChange } from "./types.js";
+let contents = { changes: [], structuralChanges: [] };
+let revision = 0;
+let undoStack = [];
+let redoStack = [];
+let snapshot = createSnapshot();
+const listeners = new Set();
+function cloneContents(value) {
+    return {
+        changes: value.changes.map((change) => cloneValue(change)),
+        structuralChanges: value.structuralChanges.map((change) => cloneValue(change)),
+    };
+}
+function cloneValue(value, key) {
+    // Token entries belong to the shared catalog. Preserve their identity so
+    // callers can continue to correlate a change with its catalog entry.
+    if (key === "oldToken" || key === "newToken")
+        return value;
+    if (Array.isArray(value))
+        return value.map((item) => cloneValue(item));
+    if (value !== null && typeof value === "object") {
+        const clone = {};
+        for (const [key, child] of Object.entries(value)) {
+            clone[key] = cloneValue(child, key);
+        }
+        return clone;
+    }
+    return value;
+}
+function freezeValue(value, key) {
+    if (key === "oldToken" || key === "newToken")
+        return value;
+    if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
+        for (const [childKey, child] of Object.entries(value))
+            freezeValue(child, childKey);
+        Object.freeze(value);
+    }
+    return value;
+}
+function createSnapshot() {
+    const snapshotContents = freezeValue(cloneContents(contents));
+    return Object.freeze({
+        revision,
+        changes: snapshotContents.changes,
+        structuralChanges: snapshotContents.structuralChanges,
+        canUndo: undoStack.length > 0,
+        canRedo: redoStack.length > 0,
+    });
+}
+function publish() {
+    revision += 1;
+    snapshot = createSnapshot();
+    for (const listener of listeners)
+        listener();
+}
+function commit(next) {
+    if (!canWriteWorkspace())
+        return false;
+    const before = cloneContents(contents);
+    contents = cloneContents(next);
+    undoStack.push({ before, after: cloneContents(contents) });
+    redoStack = [];
+    publish();
+    return true;
+}
+function getSnapshot() {
+    return snapshot;
+}
+function subscribe(listener) {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+}
+function commitChangeRecordsImpl(incoming) {
+    if (incoming.length === 0)
+        return "unchanged";
+    const nextChanges = incoming.reduce((current, change) => mergeChange(current, change), [...contents.changes]);
+    if (sameEffectiveChanges([...contents.changes], nextChanges))
+        return "unchanged";
+    return commit({ ...contents, changes: nextChanges }) ? "applied" : "blocked";
+}
+function revertChangeRecordImpl(change) {
+    const key = changeKey(change);
+    const changes = contents.changes.filter((candidate) => changeKey(candidate) !== key);
+    if (changes.length === contents.changes.length)
+        return false;
+    return commit({ ...contents, changes });
+}
+function discardChangeRecordsImpl(target) {
+    const changes = contents.changes.filter((change) => target.kind === "selector"
+        ? selectorForChange(change) !== target.selector
+        : !isElementChange(change) || change.instanceOverride?.id !== target.id);
+    if (changes.length === contents.changes.length)
+        return false;
+    return commit({ ...contents, changes });
+}
+function commitStructuralChangeImpl(change) {
+    if (contents.structuralChanges.some((candidate) => candidate.id === change.id))
+        return false;
+    return commit({
+        ...contents,
+        structuralChanges: [...contents.structuralChanges, change],
+    });
+}
+function revertStructuralChangeRecordImpl(changeId) {
+    const structuralChanges = contents.structuralChanges.filter((change) => change.id !== changeId);
+    if (structuralChanges.length === contents.structuralChanges.length)
+        return false;
+    return commit({ ...contents, structuralChanges });
+}
+function reconcileWorkspaceChangesImpl(verifiedKeys, verifiedStructuralIds) {
+    if (!canWriteWorkspace())
+        return 0;
+    const retain = (value) => ({
+        changes: value.changes.filter((change) => !verifiedKeys.has(changeKey(change))),
+        structuralChanges: value.structuralChanges.filter((change) => !verifiedStructuralIds.has(change.id)),
+    });
+    const next = retain(contents);
+    const removed = contents.changes.length - next.changes.length
+        + contents.structuralChanges.length - next.structuralChanges.length;
+    if (removed === 0)
+        return 0;
+    contents = next;
+    const prune = (entries) => entries
+        .map((entry) => ({ before: retain(entry.before), after: retain(entry.after) }))
+        .filter((entry) => !sameWorkspaceContents(entry.before, entry.after));
+    undoStack = prune(undoStack);
+    redoStack = prune(redoStack);
+    publish();
+    return removed;
+}
+function sameWorkspaceContents(left, right) {
+    return sameEffectiveChanges([...left.changes], [...right.changes])
+        && sameStructuralChanges(left.structuralChanges, right.structuralChanges);
+}
+function sameStructuralChanges(left, right) {
+    // Structural intent is an ordered list of small, immutable JSON records.
+    // Equality must include operation order and the complete target payload.
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+function undoWorkspaceChangeImpl() {
+    if (!canWriteWorkspace())
+        return false;
+    const entry = undoStack.at(-1);
+    if (!entry)
+        return false;
+    undoStack.pop();
+    contents = cloneContents(entry.before);
+    redoStack.push(entry);
+    publish();
+    return true;
+}
+function redoWorkspaceChangeImpl() {
+    if (!canWriteWorkspace())
+        return false;
+    const entry = redoStack.at(-1);
+    if (!entry)
+        return false;
+    redoStack.pop();
+    contents = cloneContents(entry.after);
+    undoStack.push(entry);
+    publish();
+    return true;
+}
+function restoreWorkspaceChangesImpl(next) {
+    contents = cloneContents(next);
+    undoStack = [];
+    redoStack = [];
+    publish();
+}
+function clearWorkspaceChangesImpl() {
+    contents = { changes: [], structuralChanges: [] };
+    undoStack = [];
+    redoStack = [];
+    publish();
+}
+/** Resets controller state for teardown and tests without requiring a lease. */
+function resetWorkspaceChangesImpl() {
+    contents = { changes: [], structuralChanges: [] };
+    undoStack = [];
+    redoStack = [];
+    revision = 0;
+    snapshot = createSnapshot();
+    for (const listener of listeners)
+        listener();
+}
+export const workspaceChangeStore = {
+    getSnapshot,
+    subscribe,
+    commitChangeRecords: commitChangeRecordsImpl,
+    revertChangeRecord: revertChangeRecordImpl,
+    discardChangeRecords: discardChangeRecordsImpl,
+    commitStructuralChange: commitStructuralChangeImpl,
+    revertStructuralChangeRecord: revertStructuralChangeRecordImpl,
+    reconcileWorkspaceChanges: reconcileWorkspaceChangesImpl,
+    undoWorkspaceChange: undoWorkspaceChangeImpl,
+    redoWorkspaceChange: redoWorkspaceChangeImpl,
+    restoreWorkspaceChanges: restoreWorkspaceChangesImpl,
+    clearWorkspaceChanges: clearWorkspaceChangesImpl,
+};
+/** Compatibility accessors retained for callers that have not adopted the store seam. */
+export function getWorkspaceChanges() {
+    return workspaceChangeStore.getSnapshot();
+}
+export function subscribeWorkspaceChanges(listener) {
+    return workspaceChangeStore.subscribe(listener);
+}
+export function commitChangeRecords(incoming, project) {
+    const result = workspaceChangeStore.commitChangeRecords(incoming);
+    if (result === "applied")
+        project(workspaceChangeStore.getSnapshot());
+    return result;
+}
+export function commitStructuralChange(change, project) {
+    const changed = workspaceChangeStore.commitStructuralChange(change);
+    if (changed)
+        project(workspaceChangeStore.getSnapshot());
+    return changed;
+}
+export function undoWorkspaceChange(project) {
+    const changed = workspaceChangeStore.undoWorkspaceChange();
+    if (changed)
+        project(workspaceChangeStore.getSnapshot());
+    return changed;
+}
+export function redoWorkspaceChange(project) {
+    const changed = workspaceChangeStore.redoWorkspaceChange();
+    if (changed)
+        project(workspaceChangeStore.getSnapshot());
+    return changed;
+}
+export function restoreWorkspaceChanges(next, project) {
+    workspaceChangeStore.restoreWorkspaceChanges(next);
+    project(workspaceChangeStore.getSnapshot());
+}
+export function resetWorkspaceChanges() {
+    resetWorkspaceChangesImpl();
+}

package/dist/inspector/clientManifest.d.ts

@@ -0,0 +1,24 @@
+import { type NudgeUiRuntimeConfig } from "./runtime/runtimeConfig.js";
+export type { NudgeUiRuntimeConfig } from "./runtime/runtimeConfig.js";
+export { detectStylingSystem } from "./runtime/runtimeConfig.js";
+/** Version of the host-to-inspector runtime manifest Interface. */
+export declare const NUDGE_UI_CLIENT_MANIFEST_VERSION = 1;
+/** Runtime document consumed by the self-contained inspector client. */
+export interface NudgeUiClientManifest {
+    readonly version: typeof NUDGE_UI_CLIENT_MANIFEST_VERSION;
+    readonly revision: number;
+    readonly runtime: NudgeUiRuntimeConfig;
+    /** Optional document preparation requested by the host Adapter. */
+    readonly document?: {
+        readonly runtimeIdentity?: "static-html";
+        readonly stylesheetOrder?: "browser";
+    };
+    /** Optional development reload transport owned by the host Adapter. */
+    readonly reload?: {
+        readonly endpoint: string;
+        readonly strategy: "refresh-manifest" | "reload-document";
+        readonly events?: readonly string[];
+    };
+}
+/** Parses and normalizes an external manifest before it replaces inspector state. */
+export declare function parseNudgeUiClientManifest(value: unknown): NudgeUiClientManifest | null;

package/dist/inspector/clientManifest.js

@@ -0,0 +1,69 @@
+import { normalizeNudgeUiRuntimeConfig, } from "./runtime/runtimeConfig.js";
+export { detectStylingSystem } from "./runtime/runtimeConfig.js";
+/** Version of the host-to-inspector runtime manifest Interface. */
+export const NUDGE_UI_CLIENT_MANIFEST_VERSION = 1;
+/** Parses and normalizes an external manifest before it replaces inspector state. */
+export function parseNudgeUiClientManifest(
+// JSON is untrusted at this I/O boundary and is narrowed below.
+// oxlint-disable-next-line anti-slop/no-unknown-parameters
+value) {
+    if (!isRecord(value)
+        || value.version !== NUDGE_UI_CLIENT_MANIFEST_VERSION
+        || typeof value.revision !== "number"
+        || !Number.isInteger(value.revision)
+        || value.revision < 0
+        || !isDocumentOptions(value.document)
+        || !isReloadOptions(value.reload))
+        return null;
+    try {
+        return {
+            version: NUDGE_UI_CLIENT_MANIFEST_VERSION,
+            revision: value.revision,
+            runtime: normalizeNudgeUiRuntimeConfig(value.runtime),
+            ...(value.document === undefined ? {} : { document: value.document }),
+            ...(value.reload === undefined ? {} : { reload: value.reload }),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function isDocumentOptions(
+// Optional manifest capability is parsed before use.
+// oxlint-disable-next-line anti-slop/no-unknown-parameters
+value) {
+    if (value === undefined)
+        return true;
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    // SAFETY: the object check above makes reading optional candidate fields safe.
+    const candidate = value;
+    return (candidate.runtimeIdentity === undefined || candidate.runtimeIdentity === "static-html")
+        && (candidate.stylesheetOrder === undefined || candidate.stylesheetOrder === "browser");
+}
+function isReloadOptions(
+// Optional manifest capability is parsed before use.
+// oxlint-disable-next-line anti-slop/no-unknown-parameters
+value) {
+    if (value === undefined)
+        return true;
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    // SAFETY: the object check above makes reading optional candidate fields safe.
+    const candidate = value;
+    if (typeof candidate.endpoint !== "string"
+        || !candidate.endpoint.startsWith("/__nudge_ui__/")
+        || (candidate.strategy !== "refresh-manifest" && candidate.strategy !== "reload-document")) {
+        return false;
+    }
+    return candidate.events === undefined
+        || (Array.isArray(candidate.events)
+            && candidate.events.length > 0
+            && candidate.events.every((event) => typeof event === "string" && event.trim().length > 0));
+}
+function isRecord(
+// This is the first structural parser for the untrusted JSON value.
+// oxlint-disable-next-line anti-slop/no-unknown-parameters
+value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

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

@@ -0,0 +1,5 @@
+import type { ReactElement } from "react";
+import type { SelectedElement } from "../selection/selectionStore.js";
+export declare function ComponentPropsSection({ selected }: {
+    selected: SelectedElement;
+}): ReactElement | null;

package/dist/inspector/componentSemantics/ComponentPropsSection.js

@@ -0,0 +1,44 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { isComponentChange, useChanges } from "../changes/changesLog.js";
+import { FieldRow } from "../ui/FieldRow.js";
+import { Select } from "../ui/Select.js";
+import { SegmentedControl } from "../ui/SegmentedControl.js";
+import { editableComponentTargets } from "./index.js";
+import { setComponentProp } from "./changeAction.js";
+function pendingValue(target, prop, changes) {
+    const pending = changes.find((change) => isComponentChange(change)
+        && change.target.framework === target.framework
+        && change.target.callsiteId === target.meta.callsiteId
+        && change.property === prop.name);
+    if (pending && isComponentChange(pending))
+        return pending.after;
+    const current = target.props[prop.name];
+    return typeof current === "string" || typeof current === "number" || typeof current === "boolean"
+        ? current
+        : undefined;
+}
+function valueFromOption(prop, serialized) {
+    return prop.options.find((option) => String(option) === serialized) ?? serialized;
+}
+export function ComponentPropsSection({ selected }) {
+    const changes = useChanges();
+    const target = editableComponentTargets(selected.componentTargets)[0];
+    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.
+    const visibleProps = target.contract.props.filter((prop) => prop.control !== "text" && pendingValue(target, prop, changes) !== undefined);
+    if (visibleProps.length === 0)
+        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 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" },
+                            { value: "true", label: "On" },
+                        ], onChange: (value) => setComponentProp(target, prop, value === "true") })) : (_jsx(Select, { "data-test": `component-prop-${prop.name}`, value: String(current), options: prop.options.map((option) => ({
+                            value: String(option),
+                            label: String(option),
+                        })), onValueChange: (value) => setComponentProp(target, prop, valueFromOption(prop, value)) })) }, prop.name));
+            })] }));
+}

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

@@ -0,0 +1,11 @@
+import type { ComponentOverride, 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[];
+/**
+ * Resolve multiplicity through the owning runtime Adapter. The inspector does
+ * not infer it from DOM order or retain a React fiber as durable identity.
+ */
+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

@@ -0,0 +1,75 @@
+import { getNudgeUiRuntimeConfig } from "../runtime/runtimeConfig.js";
+import { copyComponentOverrides, copyRuntimeTarget, getHostRuntimeAdapters, registerHostRuntimeAdapter, replaceHostRuntimeAdapterOverrides, } from "./runtimeBridge.js";
+const diagnosedAdapters = new WeakSet();
+function enabledRuntimeAdapters() {
+    if (!getNudgeUiRuntimeConfig().capabilities.componentSemantics)
+        return [];
+    return [...getHostRuntimeAdapters()];
+}
+/** Register a framework adapter without coupling semantic resolution to React. */
+export function registerComponentRuntimeAdapter(adapter) {
+    return registerHostRuntimeAdapter(adapter);
+}
+export function inspectComponentTargets(element) {
+    const targets = [];
+    for (const adapter of enabledRuntimeAdapters()) {
+        let inspected;
+        try {
+            inspected = adapter.inspect(element);
+            if (!Array.isArray(inspected)) {
+                throw new TypeError("A host runtime Adapter returned a non-array inspection result.");
+            }
+        }
+        catch (error) {
+            diagnoseAdapter(adapter, error instanceof Error ? error.message : String(error));
+            continue;
+        }
+        for (const value of inspected) {
+            try {
+                const target = copyRuntimeTarget(value);
+                targets.push({
+                    ...target,
+                    mountedCount: target.mountedCount
+                        ?? adapter.getCallsiteMultiplicity?.(target.meta.callsiteId)
+                        ?? undefined,
+                });
+            }
+            catch (error) {
+                diagnoseAdapter(adapter, error instanceof Error ? error.message : String(error));
+            }
+        }
+    }
+    return targets;
+}
+function diagnoseAdapter(adapter, detail) {
+    if (diagnosedAdapters.has(adapter))
+        return;
+    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.
+ */
+export function callsiteMultiplicity(target) {
+    return target.mountedCount === undefined ? null : target.mountedCount;
+}
+export function editableComponentTargets(targets) {
+    if (!getNudgeUiRuntimeConfig().capabilities.componentSemantics)
+        return [];
+    const { componentContracts } = getNudgeUiRuntimeConfig();
+    return targets.flatMap((target) => {
+        const exact = componentContracts.filter((contract) => contract.componentId === target.meta.componentId);
+        const matches = exact.length > 0
+            ? exact
+            : componentContracts.filter((contract) => contract.name === target.meta.componentName);
+        if (matches.length !== 1)
+            return [];
+        return [{ ...target, contract: matches[0] }];
+    });
+}
+export function replaceComponentOverrideProjection(overrides) {
+    if (!getNudgeUiRuntimeConfig().capabilities.componentSemantics)
+        return;
+    replaceHostRuntimeAdapterOverrides(copyComponentOverrides(overrides));
+}

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

@@ -0,0 +1,2 @@
+import type { ComponentPropBaseline } from "./types.js";
+export declare function componentPropBaseline(value: unknown): ComponentPropBaseline;

package/dist/inspector/componentSemantics/boundaries.js

@@ -0,0 +1,10 @@
+function isPropValue(value) {
+    return typeof value === "string"
+        || typeof value === "number"
+        || typeof value === "boolean";
+}
+export function componentPropBaseline(value) {
+    return isPropValue(value)
+        ? { kind: "value", value }
+        : { kind: "default" };
+}

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

@@ -0,0 +1,3 @@
+import type { ComponentPropContract, ComponentPropValue, EditableComponentTarget } from "./types.js";
+export { createComponentPropChange } from "./changeModel.js";
+export declare function setComponentProp(target: EditableComponentTarget, prop: ComponentPropContract, value: ComponentPropValue): void;

package/dist/inspector/componentSemantics/changeAction.js

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

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

@@ -0,0 +1,8 @@
+import type { ComponentChangeRecord, ComponentOverride, ComponentPropBaseline, ComponentPropContract, ComponentPropValue, ComponentChangeScope, ComponentInvocationEvidence, EditableComponentTarget } from "./types.js";
+export declare function formatComponentPropValue(value: ComponentPropValue): string;
+export declare function formatComponentPropBaseline(baseline: ComponentPropBaseline): string;
+export declare function createComponentPropChange(target: EditableComponentTarget, prop: ComponentPropContract, after: ComponentPropValue, options?: {
+    scope?: ComponentChangeScope;
+    evidence?: ComponentInvocationEvidence;
+}): ComponentChangeRecord;
+export declare function componentChangeToOverride(change: ComponentChangeRecord): ComponentOverride | null;