nudge-ui 0.2.5 → 0.2.6

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

@@ -1,136 +1,62 @@
 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 DOM navigator overlay is available. */
     readonly domNavigation?: boolean;
-    /**
-     * Source-coordinate precision policy for prompts; every source site is
-     * exact when the host omits it.
-     */
+    /** Precision policy for prompt source coordinates; every source site is exact when omitted. */
     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.
-     */
+    /** Regex for this host's scoping markers; stripped from selector labels, kept in change records. Omitted means no stripping. */
     readonly scopingSelectorPattern?: string;
 }
-/** Product features that a host can selectively expose in its inspector UI. */
 export interface NudgeUiRuntimeFeatures {
-    /** Whether the annotation sketch tool is available in the Canvas UI. */
     readonly sketch?: boolean;
-    /** Whether Canvas can create filesystem-backed HTML iterations. */
     readonly canvasIterations?: boolean;
+    /** The MCP settings section; hosts that cannot reach an MCP server turn it off. */
+    readonly mcp?: boolean;
 }
-/**
- * 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;
-    /** Product-level feature switches; omitted features remain enabled. */
+    /** Omitted features remain enabled. */
     readonly features?: NudgeUiRuntimeFeatures;
     readonly tokenCatalog: readonly TokenDefinition[];
     readonly tokens: readonly TokenEntry[];
     readonly tokenDiagnostics: readonly TokenCatalogDiagnostic[];
     readonly tokenGeneration: string;
     readonly componentContracts: readonly ComponentContract[];
-    /** Why this page cannot be inspected; replaces the selection empty state. */
+    /** Replaces the selection empty state when the page cannot be inspected. */
     readonly inspectionUnavailableReason?: string;
-    /** Whether this runtime is the explicit public landing-page demo. */
     readonly demo?: boolean;
-    /** Additional same-origin pages seeded into the public demo canvas. */
+    /** Additional same-origin pages seeded into the demo canvas. */
     readonly demoPages?: readonly string[];
-    /** Labels for demo cards in display order, including the primary card. */
+    /** In display order, including the primary card. */
     readonly demoCardLabels?: readonly string[];
 }
-/**
- * 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.
- */
+/** Throws TypeError on invalid input; optional fields receive safe defaults. */
 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;
-/** Returns whether a product feature is enabled; omitted flags default to enabled. */
 export declare function isNudgeUiFeatureEnabled(features: NudgeUiRuntimeFeatures | undefined, feature: keyof NudgeUiRuntimeFeatures): boolean;
-/**
- * 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.
- */
+/** The demo boundary is this flag, never a 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.
- */
+/** Null when the host declares none; an invalid pattern degrades to no stripping. */
 export declare function getScopingSelectorPattern(): RegExp | null;
-/**
- * Subscribes to complete runtime replacements, such as Vite HMR updates.
- * Listeners run after the new snapshot is installed.
- */
+/** 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

@@ -5,9 +5,8 @@ function cloneAndFreeze(value, seen = new WeakMap()) {
     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.
+    // Frozen subtrees are reused by reference so repeated configuration with the
+    // same frozen payload keeps array identity for identity-keyed caches.
     if (Object.isFrozen(value)) {
         seen.set(source, value);
         return value;
@@ -159,11 +158,13 @@ function normalizeFeatures(input) {
     }
     const sketch = optionalFeatureBoolean(input, "sketch");
     const canvasIterations = optionalFeatureBoolean(input, "canvasIterations");
-    if (sketch === undefined && canvasIterations === undefined)
+    const mcp = optionalFeatureBoolean(input, "mcp");
+    if (sketch === undefined && canvasIterations === undefined && mcp === undefined)
         return {};
     return {
         ...(sketch === undefined ? {} : { sketch }),
         ...(canvasIterations === undefined ? {} : { canvasIterations }),
+        ...(mcp === undefined ? {} : { mcp }),
     };
 }
 function optionalDemoFlag(input) {
@@ -175,18 +176,7 @@ function optionalDemoFlag(input) {
     }
     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.
- */
+/** Throws TypeError on invalid input; optional fields receive safe defaults. */
 export function normalizeNudgeUiRuntimeConfig(input) {
     if (!isPlainRecord(input)) {
         throw new TypeError("Nudge UI runtime configuration must be an object.");
@@ -221,16 +211,6 @@ export function normalizeNudgeUiRuntimeConfig(input) {
 }
 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) {
@@ -242,37 +222,21 @@ export function configureNudgeUiRuntime(config) {
         }
     }
 }
-/** Returns the immutable runtime snapshot used by shared inspector Modules. */
 export function getNudgeUiRuntimeConfig() {
     return activeRuntimeConfig;
 }
-/** Returns whether a product feature is enabled; omitted flags default to enabled. */
 export function isNudgeUiFeatureEnabled(features, feature) {
     return features?.[feature] !== false;
 }
-/**
- * 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.
- */
+/** The demo boundary is this flag, never a 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.
- */
+/** Null when the host declares none; an invalid pattern degrades to no stripping. */
 export function getScopingSelectorPattern() {
     const source = activeRuntimeConfig.capabilities.scopingSelectorPattern;
     if (source === undefined)
@@ -287,15 +251,11 @@ export function getScopingSelectorPattern() {
     }
     return compiledScopingPattern.pattern;
 }
-/**
- * Subscribes to complete runtime replacements, such as Vite HMR updates.
- * Listeners run after the new snapshot is installed.
- */
+/** 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")
@@ -307,7 +267,6 @@ export function detectStylingSystem(tokens) {
     }
     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/runtimeIdentityClaims.d.ts

@@ -1,10 +1,5 @@
 import type { DraftContents } from "../drafts/model.js";
-/**
- * A generated identity that a saved edit refers to, plus the rendered facts
- * captured with it. Generated identities are document-local: after a reload
- * no element carries them until the claim is re-attached to the one element
- * whose rendered facts still match.
- */
+/** Document-local identity that survives a reload only by re-attaching to the element whose rendered facts match. */
 export interface RuntimeIdentityClaim {
     readonly cid: string;
     readonly src: string | null;
@@ -15,15 +10,10 @@ export interface RuntimeIdentityClaim {
     readonly domPath: string | null;
     readonly elementId: string | null;
 }
-/** Collects one claim per generated identity referenced by saved edits. */
 export declare function collectRuntimeIdentityClaims({ changes, structuralChanges }: DraftContents): RuntimeIdentityClaim[];
-/**
- * Replaces the generated identities saved edits refer to in one document and
- * attaches each to its element, now and whenever the document's elements are
- * replaced. Unmatched claims stay pending; their edits simply do not apply.
- */
+/** Unmatched claims stay pending; their edits simply do not apply. */
 export declare function applyRuntimeIdentityClaims(doc: Document, claims: readonly RuntimeIdentityClaim[]): void;
-/** Stops reattachment for a disposed document session, including queued work. */
+/** Stops reattachment for a document session, including queued work. */
 export declare function disposeRuntimeIdentityClaims(doc: Document): void;
 /** Runtime validation for claims received from another window. */
 export declare function isRuntimeIdentityClaim(value: unknown): value is RuntimeIdentityClaim;

package/dist/inspector/runtime/runtimeIdentityClaims.js

@@ -20,11 +20,10 @@ function claimFromEvidence(cid, src, evidence) {
         elementId: evidence.elementId ?? null,
     };
 }
-/** Collects one claim per generated identity referenced by saved edits. */
 export function collectRuntimeIdentityClaims({ changes, structuralChanges }) {
     const claims = new Map();
-    // The page still renders the text from before an inline text edit, so a
-    // text edit's original text wins over evidence captured after the preview.
+    // The page still renders the text from before an inline text edit, so a text
+    // edit's original text wins over evidence captured after the preview.
     const originalText = new Map();
     for (const change of changes) {
         if (change.kind === "text-content") {
@@ -79,11 +78,7 @@ function hasStructuralMatch(element, claim) {
         && boundRuntimeEvidence(element.getAttribute("data-cprops")) === claim.props
         && (claim.domPath === null || runtimeDomPath(element) === claim.domPath);
 }
-/**
- * Finds the single element a claim describes, or null when none or several
- * match. Elements holding authored identity, or another claim's identity,
- * are never taken. Conflicting text evidence leaves the claim unattached.
- */
+/** Never takes an element that holds authored identity or another claim's identity. */
 function findClaimedElement(doc, claim, claimed) {
     if (!claim.tagName)
         return null;
@@ -131,9 +126,8 @@ function observe(doc, state) {
     const Observer = doc.defaultView?.MutationObserver;
     if (!Observer || !doc.documentElement)
         return;
-    // Frameworks replace server-rendered elements during hydration and route
-    // changes. Re-attach once per mutation batch; attaching only writes to an
-    // element that lacks the identity, so it cannot feed itself.
+    // Attaching only writes to an element that lacks the identity, so hydration and route
+    // changes cannot feed the observer its own writes.
     state.observer = new Observer(() => {
         if (state.queued)
             return;
@@ -147,11 +141,7 @@ function observe(doc, state) {
     });
     state.observer.observe(doc.documentElement, { childList: true, subtree: true });
 }
-/**
- * Replaces the generated identities saved edits refer to in one document and
- * attaches each to its element, now and whenever the document's elements are
- * replaced. Unmatched claims stay pending; their edits simply do not apply.
- */
+/** Unmatched claims stay pending; their edits simply do not apply. */
 export function applyRuntimeIdentityClaims(doc, claims) {
     if (claims.length === 0) {
         disposeRuntimeIdentityClaims(doc);
@@ -166,7 +156,7 @@ export function applyRuntimeIdentityClaims(doc, claims) {
     attachClaims(doc, state);
     observe(doc, state);
 }
-/** Stops reattachment for a disposed document session, including queued work. */
+/** Stops reattachment for a document session, including queued work. */
 export function disposeRuntimeIdentityClaims(doc) {
     states.get(doc)?.observer?.disconnect();
     states.delete(doc);
@@ -177,8 +167,8 @@ export function isRuntimeIdentityClaim(value) {
         return false;
     const claim = value;
     const nullableString = (field) => field === null || typeof field === "string";
-    return isGeneratedCid(claim.cid)
-        && (claim.src === null || isRuntimeGeneratedSource(claim.src))
+    return typeof claim.cid === "string" && isGeneratedCid(claim.cid)
+        && (claim.src === null || (typeof claim.src === "string" && isRuntimeGeneratedSource(claim.src)))
         && typeof claim.tagName === "string"
         && nullableString(claim.text)
         && nullableString(claim.props)

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

@@ -1,47 +1,15 @@
-/**
- * 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.
- */
+/** Document-local identity for runtime-created elements; intentionally not a file:line:column source claim. */
 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;
-/**
- * Describes an element by its nearest ancestors so a prompt without source
- * locations still carries searchable class names, ids, and test ids.
- */
+/** Ancestor description so a prompt without source locations still carries searchable ids, classes, and test ids. */
 export declare function runtimeDomPath(element: Element): 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.
- */
+/** Fills only missing identity attributes and observes added subtrees; the returned function disconnects the observer. */
 export declare function installStaticHtmlRuntimeIdentity(doc?: Document): () => void;
-/**
- * Assigns runtime identity only to elements the pointer reaches: the target,
- * its ancestors, two levels of descendants for the DOM navigator, and its
- * siblings, which structural moves capture as anchors.
- *
- * Unlike `installStaticHtmlRuntimeIdentity`, nothing observes DOM mutations,
- * so a busy application pays no cost for subtrees nobody inspects. Install it
- * before the inspector so its capture listeners run first.
- */
+/** Install before the inspector so its capture listeners run first. */
 export declare function installLazyRuntimeIdentity(doc?: Document): () => void;

package/dist/inspector/runtime/staticHtmlRuntimeIdentity.js

@@ -1,15 +1,7 @@
-/**
- * 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.
- */
+/** Document-local identity for runtime-created elements; intentionally not a file:line:column source claim. */
 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);
 }
@@ -29,10 +21,7 @@ function domPathSegment(element) {
         segment += `.${classes.join(".")}`;
     return segment;
 }
-/**
- * Describes an element by its nearest ancestors so a prompt without source
- * locations still carries searchable class names, ids, and test ids.
- */
+/** Ancestor description so a prompt without source locations still carries searchable ids, classes, and test ids. */
 export function runtimeDomPath(element) {
     const segments = [];
     let current = element;
@@ -47,14 +36,12 @@ export function runtimeDomPath(element) {
     const path = segments.join(" > ");
     return path.length > DOM_PATH_MAX_LENGTH ? `…${path.slice(-DOM_PATH_MAX_LENGTH)}` : path;
 }
-/** 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, "")) ?? "";
 }
@@ -67,11 +54,9 @@ const EXCLUDED_SUBTREE_TAGS = new Set([
     "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);
 }
@@ -100,16 +85,7 @@ function existingAttributeValues(doc, 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.
- */
+/** Fills only missing identity attributes and observes added subtrees; the returned function disconnects the observer. */
 export function installStaticHtmlRuntimeIdentity(doc = document) {
     const ensureIdentity = createIdentityAllocator(doc);
     let disposed = false;
@@ -155,20 +131,11 @@ export function installStaticHtmlRuntimeIdentity(doc = document) {
 }
 const LAZY_IDENTITY_EVENTS = ["pointerover", "pointerdown", "mousedown", "click", "dblclick"];
 const LAZY_DESCENDANT_DEPTH = 2;
-/**
- * Assigns runtime identity only to elements the pointer reaches: the target,
- * its ancestors, two levels of descendants for the DOM navigator, and its
- * siblings, which structural moves capture as anchors.
- *
- * Unlike `installStaticHtmlRuntimeIdentity`, nothing observes DOM mutations,
- * so a busy application pays no cost for subtrees nobody inspects. Install it
- * before the inspector so its capture listeners run first.
- */
+/** Install before the inspector so its capture listeners run first. */
 export function installLazyRuntimeIdentity(doc = document) {
-    // Pointer order differs between page loads, so sequential numbers would
-    // hand a saved edit's identity to whichever element is hovered first after
-    // a reload. A per-install scope keeps fresh identities distinct from saved
-    // ones; `runtimeIdentityClaims` re-attaches the saved ones by evidence.
+    // Pointer order differs between page loads, so sequential numbers could hand a saved
+    // edit's identity to a different element; a per-install scope keeps fresh identities
+    // distinct from saved ones, which `runtimeIdentityClaims` re-attaches by evidence.
     const ensureIdentity = createIdentityAllocator(doc, `${Math.random().toString(36).slice(2, 8)}-`);
     function tagDescendants(element, depth) {
         if (depth === 0)

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

@@ -1,10 +1,3 @@
 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.
- */
+/** Components rendering runtime-derived UI must subscribe here, not through the plain getter. */
 export declare function useNudgeUiRuntimeConfig(): NudgeUiRuntimeConfig;

package/dist/inspector/runtime/useRuntimeConfig.js

@@ -1,13 +1,6 @@
 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.
- */
+/** Components rendering runtime-derived UI must subscribe here, not through the plain getter. */
 export function useNudgeUiRuntimeConfig() {
     return useSyncExternalStore(subscribeNudgeUiRuntime, getNudgeUiRuntimeConfig);
 }

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

@@ -10,12 +10,7 @@ export interface InstanceEvidence {
 }
 /** 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.
- */
+/** Memoized per element and scope revision so the render path avoids repeated full-document queries. */
 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;
@@ -25,7 +20,6 @@ export interface BatchScopeFields {
     sourceInstanceCount?: number;
     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;

package/dist/inspector/selection/editScope.js

@@ -20,12 +20,7 @@ function querySourceSiteMatches(el) {
         return 0;
     }
 }
-/**
- * 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.
- */
+/** Memoized per element and scope revision so the render path avoids repeated full-document queries. */
 export function countSourceSiteMatches(el, revision = 0) {
     const cid = el.getAttribute("data-cid") ?? "";
     const src = el.getAttribute("data-src") ?? "";
@@ -59,11 +54,7 @@ export function relinkElement(el) {
 export function getEditScope(el) {
     return getRenderedInstanceOverride(el) ? "rendered-instance" : "source-site";
 }
-/**
- * Plans the scope for every target in a batch edit without mutating the DOM or
- * transient instance state. A partial repeated-source group is editable only
- * when each selected output has evidence that resolves uniquely.
- */
+/** A partial repeated-source group is editable only when each selected output resolves uniquely. */
 function analyzeBatchEditScopes(selectedElements) {
     const plan = new Map();
     if (selectedElements.length <= 1) {
@@ -108,7 +99,6 @@ function analyzeBatchEditScopes(selectedElements) {
     }
     return plan;
 }
-/** Returns whether every element can be addressed safely by one batch edit. */
 export function canPlanBatchEditScopes(selectedElements) {
     return analyzeBatchEditScopes(selectedElements) !== null;
 }

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

@@ -1,8 +1,4 @@
-/**
- * A style edit target is deliberately smaller than the selection model. The
- * editor only needs the rendered DOM nodes that will receive one declaration;
- * source metadata and selection ordering stay inside the selection module.
- */
+/** Deliberately just the DOM nodes receiving a declaration; source metadata stays in the selection module. */
 export type EditTarget = HTMLElement | readonly HTMLElement[];
 export declare function targetElements(target: EditTarget): readonly HTMLElement[];
 export declare function isMultiTarget(target: EditTarget): boolean;

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

@@ -1,13 +1,13 @@
 export declare function computeHierarchy(el: HTMLElement): HTMLElement[];
-export interface DescendantNode {
-    element: HTMLElement;
-    depth: number;
+/** Direct children listed in the DOM navigator before the rest collapse into a count. */
+export declare const NAVIGATOR_CHILD_LIMIT = 50;
+export interface TrackedChildren {
+    elements: HTMLElement[];
+    /** Tracked children past the limit. */
+    hidden: number;
 }
-export interface NavigationNode {
-    element: HTMLElement;
-    direction: "up" | "down";
-    depth: number;
-}
-/** Returns the nearest tracked descendants, breadth-first and document-ordered. */
-export declare function computeDescendants(el: HTMLElement, maxDepth?: number, maxNodes?: number): DescendantNode[];
-export declare function computeNavigationNodes(el: HTMLElement, hierarchy?: HTMLElement[]): NavigationNode[];
+/** The nearest tracked elements below `el` in document order, looking through untracked wrappers. */
+export declare function computeTrackedChildren(el: HTMLElement, limit?: number): TrackedChildren;
+export declare function hasTrackedChildren(el: HTMLElement): boolean;
+/** Nearest tracked ancestors, fewer when children also fill the menu. */
+export declare function computeNavigationParents(hierarchy: readonly HTMLElement[], hasChildren: boolean): HTMLElement[];