nudge-ui 0.2.0

package/dist/inspector/componentSemantics/changeModel.js

@@ -0,0 +1,60 @@
+import { componentPropBaseline } from "./boundaries.js";
+export function formatComponentPropValue(value) {
+    return String(value);
+}
+export function formatComponentPropBaseline(baseline) {
+    return baseline.kind === "default"
+        ? "(default)"
+        : formatComponentPropValue(baseline.value);
+}
+export function createComponentPropChange(target, prop, after, options = {}) {
+    const authoredAs = target.meta.authoredProps[prop.name]
+        ?? (target.meta.authoredProps["..."] ? "spread" : "default");
+    return {
+        kind: "component-prop",
+        target: {
+            framework: target.framework,
+            componentId: target.contract.componentId,
+            callsiteId: target.meta.callsiteId,
+            componentName: target.meta.componentName,
+            file: target.meta.file,
+            line: target.meta.line,
+            column: target.meta.column,
+        },
+        property: prop.name,
+        before: componentPropBaseline(target.props[prop.name]),
+        after,
+        authoredAs,
+        scope: options.scope ?? "source-site",
+        evidence: options.evidence,
+    };
+}
+export function componentChangeToOverride(change) {
+    if (change.authoredAs !== "literal"
+        && change.authoredAs !== "expression"
+        && change.authoredAs !== "spread"
+        && change.authoredAs !== "default")
+        return null;
+    const mountedCount = change.evidence?.mountedCount;
+    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.
+    if (mountedCount !== undefined && mountedCount > 1) {
+        if (change.scope !== "source-site")
+            return null;
+        if (change.authoredAs === "expression" || change.authoredAs === "spread")
+            return null;
+    }
+    if (change.scope === "rendered-instance")
+        return null;
+    return {
+        framework: change.target.framework,
+        callsiteId: change.target.callsiteId,
+        prop: change.property,
+        value: change.after,
+    };
+}

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

@@ -0,0 +1,4 @@
+export { editableComponentTargets, inspectComponentTargets, registerComponentRuntimeAdapter, replaceComponentOverrideProjection, } from "./adapterRegistry.js";
+export type { AuthoredPropKind, ComponentChangeRecord, ComponentChangeTarget, ComponentContract, ComponentFramework, ComponentInvocationMeta, ComponentOverride, ComponentPropBaseline, ComponentPropContract, ComponentPropValue, EditableComponentTarget, RuntimeComponentTarget, } from "./types.js";
+export { resolveTextBinding, VISIBLE_TEXT_PROP_PRIORITY, } from "./textBinding.js";
+export type { TextBindingCandidate, TextEditBinding, TextEditRejection, TextEditRejectionReason, } from "./textBinding.js";

package/dist/inspector/componentSemantics/index.js

@@ -0,0 +1,2 @@
+export { editableComponentTargets, inspectComponentTargets, registerComponentRuntimeAdapter, replaceComponentOverrideProjection, } from "./adapterRegistry.js";
+export { resolveTextBinding, VISIBLE_TEXT_PROP_PRIORITY, } from "./textBinding.js";

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

@@ -0,0 +1,10 @@
+import { type ReactElement } from "react";
+import type { ComponentInvocationMeta, ComponentOverride, ComponentRuntimeAdapter, RuntimeComponentTarget } from "./types.js";
+/** Returns null when this runtime has no mounted boundary for the callsite. */
+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;
+export declare function inspectReactComponentTargets(element: HTMLElement): RuntimeComponentTarget[];
+export declare function replaceReactComponentOverrides(overrides: ComponentOverride[]): void;
+export declare const reactComponentRuntimeAdapter: ComponentRuntimeAdapter;

package/dist/inspector/componentSemantics/reactRuntime.js

@@ -0,0 +1,186 @@
+import { cloneElement, createElement, forwardRef, useEffect, useMemo, useSyncExternalStore, version as reactVersion, } from "react";
+import { registerHostRuntimeAdapter } from "./runtimeBridge.js";
+import { getNudgeUiRuntimeConfig } from "../runtime/runtimeConfig.js";
+const BOUNDARY_MARKER = Symbol.for("nudge-ui.react-component-boundary");
+const EMPTY_OVERRIDE = Object.freeze({});
+const REACT_MAJOR_VERSION = Number.parseInt(reactVersion, 10);
+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.
+ */
+const mountedCallsites = new Map();
+function registerMountedCallsite(callsiteId) {
+    mountedCallsites.set(callsiteId, (mountedCallsites.get(callsiteId) ?? 0) + 1);
+    let active = true;
+    return () => {
+        if (!active)
+            return;
+        active = false;
+        const count = (mountedCallsites.get(callsiteId) ?? 1) - 1;
+        if (count > 0)
+            mountedCallsites.set(callsiteId, count);
+        else
+            mountedCallsites.delete(callsiteId);
+    };
+}
+/** Returns null when this runtime has no mounted boundary for the callsite. */
+export function getReactCallsiteMultiplicity(callsiteId) {
+    return mountedCallsites.get(callsiteId) ?? null;
+}
+/** Test/runtime teardown hook; canonical changes never depend on this state. */
+export function resetReactComponentRuntime() {
+    mountedCallsites.clear();
+    overridesByCallsite = new Map();
+    listeners.clear();
+}
+function subscribe(listener) {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+}
+function overrideFor(callsiteId) {
+    return overridesByCallsite.get(callsiteId) ?? EMPTY_OVERRIDE;
+}
+function sameOverrideProjection(next) {
+    if (next.size !== overridesByCallsite.size)
+        return false;
+    for (const [callsiteId, nextProps] of next) {
+        const currentProps = overridesByCallsite.get(callsiteId);
+        if (!currentProps)
+            return false;
+        const nextKeys = Object.keys(nextProps);
+        const currentKeys = Object.keys(currentProps);
+        if (nextKeys.length !== currentKeys.length)
+            return false;
+        if (nextKeys.some((property) => !Object.hasOwn(currentProps, property)
+            || !Object.is(currentProps[property], nextProps[property]))) {
+            return false;
+        }
+    }
+    return true;
+}
+function getReactElementRef(element) {
+    // React 19 exposes ref as a regular prop and warns when element.ref is read.
+    if (Number.isFinite(REACT_MAJOR_VERSION) && REACT_MAJOR_VERSION >= 19) {
+        return element.props.ref ?? null;
+    }
+    return element.ref ?? null;
+}
+function mergeRefs(...refs) {
+    if (refs.every((ref) => ref === null))
+        return null;
+    let cleanup = null;
+    return (instance) => {
+        cleanup?.();
+        cleanup = null;
+        if (instance === null)
+            return;
+        const cleanupCallbacks = refs.map((ref) => {
+            if (typeof ref === "function") {
+                const result = ref(instance);
+                return typeof result === "function" ? result : null;
+            }
+            if (ref !== null) {
+                ref.current = instance;
+            }
+            return null;
+        });
+        cleanup = () => {
+            refs.forEach((ref, index) => {
+                if (typeof ref === "function") {
+                    const cleanupCallback = cleanupCallbacks[index];
+                    if (cleanupCallback)
+                        cleanupCallback();
+                    else
+                        ref(null);
+                }
+                else if (ref !== null) {
+                    ref.current = null;
+                }
+            });
+        };
+    };
+}
+const ReactComponentOverride = forwardRef(function ReactComponentOverride({ element, meta, ...injectedProps }, forwardedRef) {
+    useEffect(() => registerMountedCallsite(meta.callsiteId), [meta.callsiteId]);
+    const override = useSyncExternalStore(subscribe, () => overrideFor(meta.callsiteId), () => EMPTY_OVERRIDE);
+    const elementRef = getReactElementRef(element);
+    const mergedRef = useMemo(() => mergeRefs(elementRef, forwardedRef), [elementRef, forwardedRef]);
+    const hasInjectedProps = Object.keys(injectedProps).length > 0;
+    const hasOverride = Object.keys(override).length > 0;
+    if (!hasInjectedProps && !hasOverride && forwardedRef === null)
+        return element;
+    const props = {
+        ...injectedProps,
+        ...override,
+    };
+    if (forwardedRef !== null)
+        props.ref = mergedRef;
+    return cloneElement(element, props);
+});
+ReactComponentOverride[BOUNDARY_MARKER] = true;
+ReactComponentOverride.displayName = "NudgeUiComponentOverride";
+function isBoundaryType(value) {
+    if (value === null || (typeof value !== "function" && typeof value !== "object"))
+        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 });
+}
+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({
+                framework: "react",
+                meta,
+                props: {
+                    ...sourceElement.props,
+                    ...overrideFor(meta.callsiteId),
+                },
+                mountedCount: getReactCallsiteMultiplicity(meta.callsiteId) ?? undefined,
+            });
+        }
+        fiber = fiber.return ?? null;
+    }
+    return targets;
+}
+export function replaceReactComponentOverrides(overrides) {
+    if (!getNudgeUiRuntimeConfig().capabilities.componentSemantics)
+        return;
+    const next = new Map();
+    for (const override of overrides) {
+        if (override.framework !== "react")
+            continue;
+        const props = next.get(override.callsiteId) ?? {};
+        props[override.prop] = override.value;
+        next.set(override.callsiteId, props);
+    }
+    if (sameOverrideProjection(next))
+        return;
+    overridesByCallsite = next;
+    listeners.forEach((listener) => listener());
+}
+export const reactComponentRuntimeAdapter = {
+    framework: "react",
+    inspect: inspectReactComponentTargets,
+    replaceOverrides: replaceReactComponentOverrides,
+    getCallsiteMultiplicity: getReactCallsiteMultiplicity,
+};
+registerHostRuntimeAdapter(reactComponentRuntimeAdapter);

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

@@ -0,0 +1,25 @@
+import type { ComponentOverride, ComponentRuntimeAdapter, RuntimeComponentTarget } from "./types.js";
+export type { ComponentFramework, ComponentInvocationMeta, ComponentOverride, 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.
+ */
+export declare function registerHostRuntimeAdapter(adapter: ComponentRuntimeAdapter): () => void;
+/** Returns the active host runtime Adapters for this browser realm. */
+export declare function getHostRuntimeAdapters(): 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.
+ */
+export declare function copyRuntimeTarget(target: RuntimeComponentTarget): RuntimeComponentTarget;
+/** Copies override commands before dispatching them into a host Adapter. */
+export declare function copyComponentOverrides(overrides: readonly ComponentOverride[]): ComponentOverride[];

package/dist/inspector/componentSemantics/runtimeBridge.js

@@ -0,0 +1,161 @@
+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() {
+    // SAFETY: this module exclusively owns the versioned symbol property and
+    // validates its initialization before returning the registry.
+    const target = globalThis;
+    const current = target[HOST_RUNTIME_KEY];
+    if (current !== undefined) {
+        if (!isHostRuntimeRegistry(current)) {
+            throw new Error(`Nudge UI host runtime is incompatible with version ${NUDGE_UI_HOST_RUNTIME_VERSION}.`);
+        }
+        return current;
+    }
+    const created = {
+        version: NUDGE_UI_HOST_RUNTIME_VERSION,
+        adapters: new Map(),
+        overrides: new Map(),
+    };
+    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.
+ */
+export function registerHostRuntimeAdapter(adapter) {
+    assertRuntimeAdapter(adapter);
+    const hostRegistry = registry();
+    hostRegistry.adapters.set(adapter.framework, adapter);
+    const overrides = hostRegistry.overrides.get(adapter.framework);
+    if (overrides)
+        adapter.replaceOverrides(copyComponentOverrides(overrides));
+    return () => {
+        if (hostRegistry.adapters.get(adapter.framework) === adapter) {
+            hostRegistry.adapters.delete(adapter.framework);
+        }
+    };
+}
+/** Returns the active host runtime Adapters for this browser realm. */
+export function getHostRuntimeAdapters() {
+    return [...registry().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([
+        ...hostRegistry.adapters.keys(),
+        ...hostRegistry.overrides.keys(),
+    ]);
+    for (const override of overrides) {
+        assertComponentOverride(override);
+        frameworks.add(override.framework);
+    }
+    for (const framework of frameworks) {
+        const projection = copyComponentOverrides(overrides.filter((override) => override.framework === framework));
+        hostRegistry.overrides.set(framework, projection);
+        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.
+ */
+export function copyRuntimeTarget(target) {
+    assertRuntimeTarget(target);
+    const props = {};
+    for (const [name, value] of Object.entries(target.props)) {
+        if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+            props[name] = value;
+        }
+    }
+    return {
+        framework: target.framework,
+        meta: {
+            callsiteId: target.meta.callsiteId,
+            componentId: target.meta.componentId,
+            componentName: target.meta.componentName,
+            file: target.meta.file,
+            line: target.meta.line,
+            column: target.meta.column,
+            authoredProps: { ...target.meta.authoredProps },
+        },
+        props,
+        ...(target.mountedCount === undefined ? {} : { mountedCount: target.mountedCount }),
+    };
+}
+/** Copies override commands before dispatching them into a host Adapter. */
+export function copyComponentOverrides(overrides) {
+    return overrides.map((override) => {
+        assertComponentOverride(override);
+        return { ...override };
+    });
+}
+function isHostRuntimeRegistry(
+// The page-global value comes from a separately bundled host Adapter.
+// oxlint-disable-next-line anti-slop/no-unknown-parameters
+value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    // SAFETY: the object check above makes reading these optional candidate fields safe.
+    const candidate = value;
+    return candidate.version === NUDGE_UI_HOST_RUNTIME_VERSION
+        && candidate.adapters instanceof Map
+        && candidate.overrides instanceof Map;
+}
+function assertRuntimeAdapter(adapter) {
+    if (adapter === null
+        || typeof adapter !== "object"
+        || !isComponentFramework(adapter.framework)
+        || typeof adapter.inspect !== "function"
+        || typeof adapter.replaceOverrides !== "function") {
+        throw new TypeError("Nudge UI received an invalid host runtime Adapter.");
+    }
+}
+function assertRuntimeTarget(target) {
+    if (target === null
+        || typeof target !== "object"
+        || !isComponentFramework(target.framework)
+        || target.meta === null
+        || typeof target.meta !== "object"
+        || target.props === null
+        || typeof target.props !== "object"
+        || Array.isArray(target.props)) {
+        throw new TypeError("Nudge UI received an invalid component target from a host Adapter.");
+    }
+    const meta = target.meta;
+    if (typeof meta.callsiteId !== "string"
+        || meta.callsiteId.length === 0
+        || typeof meta.componentId !== "string"
+        || meta.componentId.length === 0
+        || typeof meta.componentName !== "string"
+        || meta.componentName.length === 0
+        || typeof meta.file !== "string"
+        || meta.file.length === 0
+        || typeof meta.line !== "number"
+        || typeof meta.column !== "number"
+        || meta.authoredProps === null
+        || typeof meta.authoredProps !== "object"
+        || Array.isArray(meta.authoredProps)) {
+        throw new TypeError("Nudge UI received invalid component metadata from a host Adapter.");
+    }
+}
+function assertComponentOverride(override) {
+    if (override === null
+        || typeof override !== "object"
+        || !isComponentFramework(override.framework)
+        || typeof override.callsiteId !== "string"
+        || override.callsiteId.length === 0
+        || typeof override.prop !== "string"
+        || override.prop.length === 0
+        || !["string", "number", "boolean"].includes(typeof override.value)) {
+        throw new TypeError("Nudge UI received an invalid component override.");
+    }
+}

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

@@ -0,0 +1,2 @@
+/** React runtime props are untrusted external input until inspected. */
+export type RuntimeProps = Record<string, unknown>;

package/dist/inspector/componentSemantics/runtimeTypes.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,69 @@
+import type { ComponentChangeTarget, EditableComponentTarget } from "./types.js";
+import type { TextProjectionTarget } from "../inline-text/textChangeBoundary.js";
+import type { TextBindingEvidence, TextProjectionScope } from "../inline-text/textChangeBoundary.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";
+export interface TextEditRejection {
+    kind: "rejected";
+    reason: TextEditRejectionReason;
+    message: string;
+}
+export type TextEditBinding = {
+    kind: "component-prop";
+    property: string;
+    target: ComponentChangeTarget;
+} | {
+    kind: "rendered-text";
+    target: TextProjectionTarget;
+};
+export interface ComponentTextEditBinding {
+    kind: "component-prop";
+    property: string;
+    target: ComponentChangeTarget;
+}
+export interface TextBindingRenderedSource {
+    file: string;
+    line: number;
+    column: number;
+    component: string;
+    selector: string;
+    authoredAs: "literal" | "expression" | "unknown";
+    evidence?: TextBindingEvidence;
+}
+export interface TextBindingChoice {
+    binding: ComponentTextEditBinding;
+    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;
+    renderedTarget?: TextProjectionTarget;
+    renderedSource?: TextBindingRenderedSource;
+    /** 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.
+ */
+export declare function resolveTextBinding(element: HTMLElement, point?: {
+    x: number;
+    y: number;
+}): TextBindingCandidate | TextEditRejection;