nudge-ui 0.2.0

package/dist/inspector/runtime/runtimeConfig.d.ts

@@ -0,0 +1,119 @@
+import type { TokenCatalogDiagnostic, TokenDefinition, TokenEntry } from "../../css/model/index.js";
+import type { ComponentContract } from "../componentSemantics/types.js";
+/** The host Adapter that supplied the active inspector runtime. */
+export type NudgeUiRuntimeHost = "vite-react" | "static-html" | "nextjs-react" | "astro";
+/** The framework semantics enabled for the active inspector runtime. */
+export type NudgeUiRuntimeFramework = "React" | "HTML" | "Astro";
+/**
+ * Which identity origins carry exact authored coordinates in prompts
+ * (ADR-0011 Stage 5).
+ *
+ * A host whose pipeline captures `data-src` positions from anything other
+ * than the authored source declares the exact subset. Hosts that omit the
+ * policy state that every source site is exact.
+ */
+export interface SourceCoordinatePolicy {
+    /** Cid prefixes whose `data-src` line:column point at authored source. */
+    readonly exactCidPrefixes: readonly string[];
+    /** File extensions whose `data-src` line:column point at authored source. */
+    readonly exactFileExtensions: readonly string[];
+}
+/** Capabilities exposed by the active host Adapter. */
+export interface NudgeUiRuntimeCapabilities {
+    /** Whether the multi-page Canvas workspace is available. */
+    readonly canvas: boolean;
+    /** Whether framework component inspection and prop overrides are available. */
+    readonly componentSemantics: boolean;
+    /** Whether the experimental DOM navigation section is available. */
+    readonly domNavigation?: boolean;
+    /**
+     * Source-coordinate precision policy for prompts; every source site is
+     * exact when the host omits it.
+     */
+    readonly sourceCoordinates?: SourceCoordinatePolicy;
+    /**
+     * Regex source matching this host's structural scoping markers, stripped
+     * from human-facing selector labels (ADR-0011). The raw selector stays in
+     * change records so managed-rule targeting keeps matching the rendered
+     * DOM. No stripping when the host omits it.
+     */
+    readonly scopingSelectorPattern?: string;
+}
+/**
+ * Browser knowledge supplied by a host Adapter before the inspector mounts.
+ *
+ * A host replaces the complete configuration when its document is replaced or
+ * its development transport is refreshed. Shared inspector Modules read the
+ * current snapshot through `getNudgeUiRuntimeConfig()` and never import a
+ * host-specific transport directly.
+ */
+export interface NudgeUiRuntimeConfig {
+    readonly projectId: string;
+    readonly host: NudgeUiRuntimeHost;
+    readonly framework: NudgeUiRuntimeFramework;
+    readonly stylingSystem: string;
+    readonly capabilities: NudgeUiRuntimeCapabilities;
+    readonly tokenCatalog: readonly TokenDefinition[];
+    readonly tokens: readonly TokenEntry[];
+    readonly tokenDiagnostics: readonly TokenCatalogDiagnostic[];
+    readonly tokenGeneration: string;
+    readonly componentContracts: readonly ComponentContract[];
+    /** Whether this runtime is the explicit public landing-page demo. */
+    readonly demo?: boolean;
+}
+/**
+ * Validates a host-supplied configuration and fills safe defaults.
+ *
+ * `projectId`, `host`, and `framework` are required identity fields; wrong
+ * types or values fail fast at the host seam instead of leaking `undefined`
+ * into storage keys or capability checks. Token arrays, the styling-system
+ * label, generation string, and capabilities are optional and default to
+ * empty/false values so a minimal host still bootstraps honestly.
+ *
+ * @param input The configuration supplied by a host Adapter.
+ * @returns A complete plain-data configuration ready to snapshot.
+ */
+export declare function normalizeNudgeUiRuntimeConfig(input: unknown): NudgeUiRuntimeConfig;
+/**
+ * Replaces the complete runtime configuration for the active document.
+ *
+ * The input is validated and incomplete optional fields receive safe defaults
+ * (see `normalizeNudgeUiRuntimeConfig`). Replacement is atomic from the
+ * inspector's perspective. The returned snapshot owns recursively cloned and
+ * frozen plain data, so a host can safely replace its virtual module values
+ * during HMR without leaving shared Modules bound to an old transport object
+ * or freezing caller-owned values.
+ */
+export declare function configureNudgeUiRuntime(config: NudgeUiRuntimeConfig): void;
+/** Returns the immutable runtime snapshot used by shared inspector Modules. */
+export declare function getNudgeUiRuntimeConfig(): NudgeUiRuntimeConfig;
+/**
+ * Whether this document runs the explicit public landing demo (ADR-0014 and
+ * ADR-0016). The plugin emits `demo: true` for the flagged demo route and for
+ * the explicit landing root in development and `nudge-demo` builds, so this is
+ * the precise runtime boundary of the demo — narrower than any build-mode
+ * name.
+ */
+export declare function isDemoRuntime(): boolean;
+/**
+ * Returns the active host's source-coordinate policy, or null when the host
+ * declares none — every source site is exact in that case.
+ */
+export declare function getSourceCoordinatePolicy(): SourceCoordinatePolicy | null;
+/**
+ * Returns the active host's structural scoping-marker pattern compiled for
+ * global replacement, or null when the host declares none. An invalid regex
+ * source degrades to no stripping rather than breaking labeling.
+ */
+export declare function getScopingSelectorPattern(): RegExp | null;
+/**
+ * Subscribes to complete runtime replacements, such as Vite HMR updates.
+ * Listeners run after the new snapshot is installed.
+ */
+export declare function subscribeNudgeUiRuntime(listener: () => void): () => void;
+/** Returns the styling-system label represented by a token inventory. */
+export declare function detectStylingSystem(tokens: readonly TokenEntry[]): string;
+/** Returns a mutable container for UI controls that require array props. */
+export declare function getNudgeUiTokenEntries(): TokenEntry[];
+export type { TokenCatalogDiagnostic, TokenDefinition, TokenEntry } from "../../css/model/index.js";
+export type { ComponentContract } from "../componentSemantics/types.js";

package/dist/inspector/runtime/runtimeConfig.js

@@ -0,0 +1,276 @@
+function cloneAndFreeze(value, seen = new WeakMap()) {
+    if (value === null || typeof value !== "object")
+        return value;
+    const source = value;
+    const existing = seen.get(source);
+    if (existing)
+        return existing;
+    // An already-frozen subtree is immutable, so it can be reused by reference.
+    // Repeated configuration with the same frozen payload (HMR re-runs, stub
+    // spread patterns) keeps array identity stable for identity-keyed caches.
+    if (Object.isFrozen(value)) {
+        seen.set(source, value);
+        return value;
+    }
+    if (Array.isArray(value)) {
+        const copy = [];
+        seen.set(source, copy);
+        for (const item of value)
+            copy.push(cloneAndFreeze(item, seen));
+        return Object.freeze(copy);
+    }
+    const copy = {};
+    seen.set(source, copy);
+    for (const [key, child] of Object.entries(value)) {
+        copy[key] = cloneAndFreeze(child, seen);
+    }
+    return Object.freeze(copy);
+}
+const DEFAULT_RUNTIME_CONFIG = cloneAndFreeze({
+    projectId: "/stub/project",
+    host: "vite-react",
+    framework: "React",
+    stylingSystem: "CSS custom properties",
+    capabilities: { canvas: true, componentSemantics: true, domNavigation: false },
+    tokenCatalog: [],
+    tokens: [],
+    tokenDiagnostics: [],
+    tokenGeneration: "",
+    componentContracts: [],
+});
+const RUNTIME_HOSTS = [
+    "vite-react",
+    "static-html",
+    "nextjs-react",
+    "astro",
+];
+const RUNTIME_FRAMEWORKS = [
+    "React",
+    "HTML",
+    "Astro",
+];
+const normalizedRuntimeConfigs = new WeakSet();
+function isNormalizedRuntimeConfig(
+// Callers first narrow this value to a non-null object at the runtime boundary.
+// oxlint-disable-next-line anti-slop/no-object-parameters
+value) {
+    return normalizedRuntimeConfigs.has(value);
+}
+function isPlainRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireString(input, field) {
+    const value = input[field];
+    if (typeof value === "string" && value.length > 0)
+        return value;
+    throw new TypeError(`Nudge UI runtime configuration requires a non-empty string "${field}"; received ${value === undefined ? "undefined" : JSON.stringify(value)}.`);
+}
+function requireEnum(input, field, allowed) {
+    const value = input[field];
+    if (typeof value === "string" && allowed.includes(value))
+        return value;
+    throw new TypeError(`Nudge UI runtime configuration requires "${field}" to be one of ${allowed.map((candidate) => JSON.stringify(candidate)).join(", ")}; received ${value === undefined ? "undefined" : JSON.stringify(value)}.`);
+}
+function optionalString(input, field) {
+    const value = input[field];
+    if (value === undefined)
+        return "";
+    if (typeof value !== "string") {
+        throw new TypeError(`Nudge UI runtime configuration field "${field}" must be a string.`);
+    }
+    return value;
+}
+function optionalArray(input, field) {
+    const value = input[field];
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value)) {
+        throw new TypeError(`Nudge UI runtime configuration field "${field}" must be an array.`);
+    }
+    return value;
+}
+function optionalBoolean(input, field) {
+    const value = input[field];
+    if (value === undefined)
+        return false;
+    if (typeof value !== "boolean") {
+        throw new TypeError(`Nudge UI runtime capability "${field}" must be a boolean; received ${JSON.stringify(value)}.`);
+    }
+    return value;
+}
+function optionalNonEmptyString(input, field) {
+    const value = input[field];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string" || value.length === 0) {
+        throw new TypeError(`Nudge UI runtime configuration field "${field}" must be a non-empty string.`);
+    }
+    return value;
+}
+function optionalStringArray(input, field) {
+    const value = input[field];
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+        throw new TypeError(`Nudge UI runtime configuration field "${field}" must be an array of strings.`);
+    }
+    return value;
+}
+function normalizeSourceCoordinatePolicy(input) {
+    const policy = input.sourceCoordinates;
+    if (policy === undefined)
+        return undefined;
+    if (!isPlainRecord(policy)) {
+        throw new TypeError('Nudge UI runtime capability "sourceCoordinates" must be an object.');
+    }
+    return {
+        exactCidPrefixes: optionalStringArray(policy, "exactCidPrefixes") ?? [],
+        exactFileExtensions: optionalStringArray(policy, "exactFileExtensions") ?? [],
+    };
+}
+function normalizeCapabilities(input) {
+    if (input === undefined)
+        return { canvas: false, componentSemantics: false, domNavigation: false };
+    if (!isPlainRecord(input)) {
+        throw new TypeError('Nudge UI runtime configuration field "capabilities" must be an object.');
+    }
+    return {
+        canvas: optionalBoolean(input, "canvas"),
+        componentSemantics: optionalBoolean(input, "componentSemantics"),
+        domNavigation: optionalBoolean(input, "domNavigation"),
+        sourceCoordinates: normalizeSourceCoordinatePolicy(input),
+        scopingSelectorPattern: optionalNonEmptyString(input, "scopingSelectorPattern"),
+    };
+}
+function optionalDemoFlag(input) {
+    const value = input.demo;
+    if (value === undefined || value === false)
+        return undefined;
+    if (value !== true) {
+        throw new TypeError(`Nudge UI runtime configuration field "demo" must be a boolean; received ${JSON.stringify(value)}.`);
+    }
+    return true;
+}
+/**
+ * Validates a host-supplied configuration and fills safe defaults.
+ *
+ * `projectId`, `host`, and `framework` are required identity fields; wrong
+ * types or values fail fast at the host seam instead of leaking `undefined`
+ * into storage keys or capability checks. Token arrays, the styling-system
+ * label, generation string, and capabilities are optional and default to
+ * empty/false values so a minimal host still bootstraps honestly.
+ *
+ * @param input The configuration supplied by a host Adapter.
+ * @returns A complete plain-data configuration ready to snapshot.
+ */
+export function normalizeNudgeUiRuntimeConfig(input) {
+    if (!isPlainRecord(input)) {
+        throw new TypeError("Nudge UI runtime configuration must be an object.");
+    }
+    if (isNormalizedRuntimeConfig(input))
+        return input;
+    const demo = optionalDemoFlag(input);
+    const normalized = cloneAndFreeze({
+        projectId: requireString(input, "projectId"),
+        host: requireEnum(input, "host", RUNTIME_HOSTS),
+        framework: requireEnum(input, "framework", RUNTIME_FRAMEWORKS),
+        stylingSystem: optionalString(input, "stylingSystem"),
+        capabilities: normalizeCapabilities(input.capabilities),
+        tokenCatalog: optionalArray(input, "tokenCatalog"),
+        tokens: optionalArray(input, "tokens"),
+        tokenDiagnostics: optionalArray(input, "tokenDiagnostics"),
+        tokenGeneration: optionalString(input, "tokenGeneration"),
+        componentContracts: optionalArray(input, "componentContracts"),
+        ...(demo === true ? { demo: true } : {}),
+    });
+    normalizedRuntimeConfigs.add(normalized);
+    return normalized;
+}
+let activeRuntimeConfig = DEFAULT_RUNTIME_CONFIG;
+const runtimeListeners = new Set();
+/**
+ * Replaces the complete runtime configuration for the active document.
+ *
+ * The input is validated and incomplete optional fields receive safe defaults
+ * (see `normalizeNudgeUiRuntimeConfig`). Replacement is atomic from the
+ * inspector's perspective. The returned snapshot owns recursively cloned and
+ * frozen plain data, so a host can safely replace its virtual module values
+ * during HMR without leaving shared Modules bound to an old transport object
+ * or freezing caller-owned values.
+ */
+export function configureNudgeUiRuntime(config) {
+    activeRuntimeConfig = normalizeNudgeUiRuntimeConfig(config);
+    for (const listener of runtimeListeners) {
+        try {
+            listener();
+        }
+        catch {
+            // A runtime listener must not prevent the host from replacing config.
+        }
+    }
+}
+/** Returns the immutable runtime snapshot used by shared inspector Modules. */
+export function getNudgeUiRuntimeConfig() {
+    return activeRuntimeConfig;
+}
+/**
+ * Whether this document runs the explicit public landing demo (ADR-0014 and
+ * ADR-0016). The plugin emits `demo: true` for the flagged demo route and for
+ * the explicit landing root in development and `nudge-demo` builds, so this is
+ * the precise runtime boundary of the demo — narrower than any build-mode
+ * name.
+ */
+export function isDemoRuntime() {
+    return getNudgeUiRuntimeConfig().demo === true;
+}
+/**
+ * Returns the active host's source-coordinate policy, or null when the host
+ * declares none — every source site is exact in that case.
+ */
+export function getSourceCoordinatePolicy() {
+    return activeRuntimeConfig.capabilities.sourceCoordinates ?? null;
+}
+let compiledScopingPattern = null;
+/**
+ * Returns the active host's structural scoping-marker pattern compiled for
+ * global replacement, or null when the host declares none. An invalid regex
+ * source degrades to no stripping rather than breaking labeling.
+ */
+export function getScopingSelectorPattern() {
+    const source = activeRuntimeConfig.capabilities.scopingSelectorPattern;
+    if (source === undefined)
+        return null;
+    if (compiledScopingPattern?.source !== source) {
+        try {
+            compiledScopingPattern = { source, pattern: new RegExp(source, "g") };
+        }
+        catch {
+            compiledScopingPattern = { source, pattern: null };
+        }
+    }
+    return compiledScopingPattern.pattern;
+}
+/**
+ * Subscribes to complete runtime replacements, such as Vite HMR updates.
+ * Listeners run after the new snapshot is installed.
+ */
+export function subscribeNudgeUiRuntime(listener) {
+    runtimeListeners.add(listener);
+    return () => runtimeListeners.delete(listener);
+}
+/** Returns the styling-system label represented by a token inventory. */
+export function detectStylingSystem(tokens) {
+    for (const token of tokens) {
+        if (token.adapter === "vanilla-extract")
+            return "vanilla-extract (sprinkles)";
+        if (token.adapter === "tailwind-v3")
+            return "Tailwind v3";
+        if (token.adapter === "tailwind-v4")
+            return "Tailwind v4";
+    }
+    return "CSS custom properties";
+}
+/** Returns a mutable container for UI controls that require array props. */
+export function getNudgeUiTokenEntries() {
+    return [...activeRuntimeConfig.tokens];
+}

package/dist/inspector/runtime/staticHtmlRuntimeIdentity.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Source identity reserved for elements created by a static HTML page after
+ * the server's source-preserving pass has completed.
+ *
+ * The value intentionally does not match `file:line:column`. It is a
+ * document-local selector identity, not a claim about source location.
+ */
+export declare const RUNTIME_UNKNOWN_SOURCE_PREFIX = "nudge-ui:unknown:";
+export declare const RUNTIME_ELEMENT_CID_PREFIX = "nudge-ui-runtime-";
+/** Maximum length retained for any runtime DOM evidence field. */
+export declare const RUNTIME_EVIDENCE_MAX_LENGTH = 120;
+/** Bounds an untrusted runtime evidence string without changing its content. */
+export declare function boundRuntimeEvidence(value: string | null): string | null;
+/** Normalizes rendered text before it becomes durable runtime evidence. */
+export declare function normalizeRuntimeText(value: string | null): string | null;
+/** Keeps a runtime tag suitable for the prompt's inline element notation. */
+export declare function normalizeRuntimeTag(value: string): string;
+/** Returns true for the source values generated for runtime DOM. */
+export declare function isRuntimeGeneratedSource(src: string | null | undefined): boolean;
+/** Returns whether this document-local element received generated identity. */
+export declare function isRuntimeCreatedElement(element: Element | null | undefined): boolean;
+/**
+ * Installs document-local identity for eligible elements that a static HTML
+ * application creates at runtime.
+ *
+ * The server owns source locations for the initial response. This Adapter
+ * only fills missing attributes, observes added subtrees, and leaves the
+ * author document untouched on disk. The returned function disconnects the
+ * observer; generated attributes remain available to managed CSS until the
+ * page is replaced.
+ */
+export declare function installStaticHtmlRuntimeIdentity(doc?: Document): () => void;

package/dist/inspector/runtime/staticHtmlRuntimeIdentity.js

@@ -0,0 +1,149 @@
+/**
+ * Source identity reserved for elements created by a static HTML page after
+ * the server's source-preserving pass has completed.
+ *
+ * The value intentionally does not match `file:line:column`. It is a
+ * document-local selector identity, not a claim about source location.
+ */
+export const RUNTIME_UNKNOWN_SOURCE_PREFIX = "nudge-ui:unknown:";
+export const RUNTIME_ELEMENT_CID_PREFIX = "nudge-ui-runtime-";
+/** Maximum length retained for any runtime DOM evidence field. */
+export const RUNTIME_EVIDENCE_MAX_LENGTH = 120;
+/** Bounds an untrusted runtime evidence string without changing its content. */
+export function boundRuntimeEvidence(value) {
+    return value === null ? null : value.slice(0, RUNTIME_EVIDENCE_MAX_LENGTH);
+}
+/** Normalizes rendered text before it becomes durable runtime evidence. */
+export function normalizeRuntimeText(value) {
+    if (value === null)
+        return null;
+    const normalized = value.replace(/\s+/g, " ").trim();
+    return normalized ? boundRuntimeEvidence(normalized) : null;
+}
+/** Keeps a runtime tag suitable for the prompt's inline element notation. */
+export function normalizeRuntimeTag(value) {
+    return boundRuntimeEvidence(value.trim().toLowerCase().replace(/[^a-z0-9-]+/g, "")) ?? "";
+}
+const HTML_NAMESPACE = "http://www.w3.org/1999/xhtml";
+const DOCUMENT_STRUCTURE_TAGS = new Set(["HTML", "HEAD", "BODY"]);
+const EXCLUDED_SUBTREE_TAGS = new Set([
+    "SCRIPT",
+    "STYLE",
+    "TEMPLATE",
+    "NOSCRIPT",
+]);
+const runtimeCreatedElements = new WeakSet();
+/** Returns true for the source values generated for runtime DOM. */
+export function isRuntimeGeneratedSource(src) {
+    return typeof src === "string" && src.startsWith(RUNTIME_UNKNOWN_SOURCE_PREFIX);
+}
+/** Returns whether this document-local element received generated identity. */
+export function isRuntimeCreatedElement(element) {
+    return element !== null && element !== undefined && runtimeCreatedElements.has(element);
+}
+function isElement(node) {
+    return node.nodeType === 1;
+}
+function isEligibleElement(element) {
+    if (element.namespaceURI !== HTML_NAMESPACE)
+        return false;
+    if (DOCUMENT_STRUCTURE_TAGS.has(element.tagName))
+        return false;
+    let current = element;
+    while (current) {
+        if (current.namespaceURI !== HTML_NAMESPACE)
+            return false;
+        if (EXCLUDED_SUBTREE_TAGS.has(current.tagName))
+            return false;
+        if (current.id === "nudge-ui-root")
+            return false;
+        current = current.parentElement;
+    }
+    return true;
+}
+function existingAttributeValues(doc, name) {
+    return new Set(Array.from(doc.querySelectorAll(`[${name}]`))
+        .map((element) => element.getAttribute(name))
+        .filter((value) => value !== null));
+}
+/**
+ * Installs document-local identity for eligible elements that a static HTML
+ * application creates at runtime.
+ *
+ * The server owns source locations for the initial response. This Adapter
+ * only fills missing attributes, observes added subtrees, and leaves the
+ * author document untouched on disk. The returned function disconnects the
+ * observer; generated attributes remain available to managed CSS until the
+ * page is replaced.
+ */
+export function installStaticHtmlRuntimeIdentity(doc = document) {
+    const usedCids = existingAttributeValues(doc, "data-cid");
+    const usedSources = existingAttributeValues(doc, "data-src");
+    let nextId = 1;
+    let disposed = false;
+    function nextIdentity() {
+        while (true) {
+            const id = nextId++;
+            const cid = `${RUNTIME_ELEMENT_CID_PREFIX}${id}`;
+            const src = `${RUNTIME_UNKNOWN_SOURCE_PREFIX}${id}`;
+            if (usedCids.has(cid) || usedSources.has(src))
+                continue;
+            usedCids.add(cid);
+            usedSources.add(src);
+            return { cid, src };
+        }
+    }
+    function ensureIdentity(element) {
+        if (!isEligibleElement(element))
+            return;
+        const needsCid = element.getAttribute("data-cid") === null;
+        const needsSource = element.getAttribute("data-src") === null;
+        if (!needsCid && !needsSource)
+            return;
+        const identity = nextIdentity();
+        if (needsCid)
+            element.setAttribute("data-cid", identity.cid);
+        if (needsSource)
+            element.setAttribute("data-src", identity.src);
+        runtimeCreatedElements.add(element);
+    }
+    function scanSubtree(node) {
+        if (disposed)
+            return;
+        if (isElement(node)) {
+            ensureIdentity(node);
+            for (const descendant of Array.from(node.querySelectorAll("*"))) {
+                ensureIdentity(descendant);
+            }
+            return;
+        }
+        if (node.nodeType === 11) {
+            // SAFETY: nodeType 11 is DOCUMENT_FRAGMENT_NODE, so the node is a DocumentFragment by the DOM spec.
+            for (const descendant of Array.from(node.querySelectorAll("*"))) {
+                ensureIdentity(descendant);
+            }
+        }
+    }
+    const scanRoot = doc.body ?? doc.documentElement;
+    if (scanRoot)
+        scanSubtree(scanRoot);
+    const MutationObserverConstructor = doc.defaultView?.MutationObserver ?? globalThis.MutationObserver;
+    if (!MutationObserverConstructor || !doc.documentElement) {
+        return () => {
+            disposed = true;
+        };
+    }
+    const observer = new MutationObserverConstructor((records) => {
+        for (const record of records) {
+            for (const node of Array.from(record.addedNodes))
+                scanSubtree(node);
+        }
+    });
+    observer.observe(doc.documentElement, { childList: true, subtree: true });
+    return () => {
+        if (disposed)
+            return;
+        disposed = true;
+        observer.disconnect();
+    };
+}

package/dist/inspector/runtime/useRuntimeConfig.d.ts

@@ -0,0 +1,10 @@
+import type { NudgeUiRuntimeConfig } from "./runtimeConfig.js";
+/**
+ * Reads the immutable runtime snapshot reactively.
+ *
+ * Components that render runtime-derived UI (token catalogs, capability
+ * gating) must use this hook instead of the plain getter, so a host that
+ * atomically replaces the configuration during HMR or a dev-transport
+ * refresh re-renders the subscribed tree with the new snapshot.
+ */
+export declare function useNudgeUiRuntimeConfig(): NudgeUiRuntimeConfig;

package/dist/inspector/runtime/useRuntimeConfig.js

@@ -0,0 +1,13 @@
+import { useSyncExternalStore } from "react";
+import { getNudgeUiRuntimeConfig, subscribeNudgeUiRuntime, } from "./runtimeConfig.js";
+/**
+ * Reads the immutable runtime snapshot reactively.
+ *
+ * Components that render runtime-derived UI (token catalogs, capability
+ * gating) must use this hook instead of the plain getter, so a host that
+ * atomically replaces the configuration during HMR or a dev-transport
+ * refresh re-renders the subscribed tree with the new snapshot.
+ */
+export function useNudgeUiRuntimeConfig() {
+    return useSyncExternalStore(subscribeNudgeUiRuntime, getNudgeUiRuntimeConfig);
+}

package/dist/inspector/selection/editScope.d.ts

@@ -0,0 +1,32 @@
+import type { EditScope } from "../editScope.js";
+import type { RenderedInstanceOverride } from "../changes/editModel.js";
+export { sourceSiteSelector } from "./sourceSite.js";
+export type { EditScope };
+export interface InstanceEvidence {
+    renderedIndex: number;
+    props: string | null;
+    text: string | null;
+    ariaLabel: string | null;
+}
+/** Test hook: clears the memoized source-site match counts. */
+export declare function resetSourceSiteMatchCounts(): void;
+/**
+ * Counts the rendered elements matching a source site. The result is memoized
+ * per (element identity, scope revision) so the selection render path no longer
+ * runs a full-document querySelectorAll on every render; it only recomputes
+ * when the caller's scope revision changes.
+ */
+export declare function countSourceSiteMatches(el: HTMLElement, revision?: number): number;
+export declare function unlinkElement(el: HTMLElement): string | null;
+export declare function relinkElement(el: HTMLElement): string | null;
+export declare function getEditScope(el: HTMLElement): EditScope;
+export interface BatchScopeFields {
+    scope: EditScope;
+    instanceOverride?: RenderedInstanceOverride;
+}
+/** Returns whether every element can be addressed safely by one batch edit. */
+export declare function canPlanBatchEditScopes(selectedElements: readonly HTMLElement[]): boolean;
+/** Resolves safe scopes immediately before a write is committed. */
+export declare function planBatchEditScopes(selectedElements: readonly HTMLElement[]): ReadonlyMap<HTMLElement, BatchScopeFields> | null;
+export declare function selectorForElement(el: HTMLElement): string | null;
+export declare function getInstanceEvidence(el: HTMLElement): InstanceEvidence;