nudge-ui 0.2.4 → 0.2.6

package/dist/inspector/runtime/runtimeIdentityClaims.js

@@ -0,0 +1,178 @@
+import { boundRuntimeEvidence, isRuntimeGeneratedSource, normalizeRuntimeTag, normalizeRuntimeText, RUNTIME_ELEMENT_CID_PREFIX, runtimeDomPath, } from "./staticHtmlRuntimeIdentity.js";
+const states = new WeakMap();
+function isGeneratedCid(cid) {
+    return typeof cid === "string" && cid.startsWith(RUNTIME_ELEMENT_CID_PREFIX);
+}
+/** Generated values contain no characters that selector escaping rewrites. */
+function generatedSourceFromSelector(selector) {
+    const match = /\[data-src="([^"\\]*)"\]/.exec(selector);
+    return match && isRuntimeGeneratedSource(match[1]) ? match[1] : null;
+}
+function claimFromEvidence(cid, src, evidence) {
+    return {
+        cid,
+        src,
+        tagName: evidence.tagName,
+        text: evidence.text,
+        props: evidence.props,
+        ariaLabel: evidence.ariaLabel,
+        domPath: evidence.domPath ?? null,
+        elementId: evidence.elementId ?? null,
+    };
+}
+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.
+    const originalText = new Map();
+    for (const change of changes) {
+        if (change.kind === "text-content") {
+            const { sourceSite, beforeText } = change.target;
+            if (isGeneratedCid(sourceSite.cid))
+                originalText.set(sourceSite.cid, normalizeRuntimeText(beforeText));
+            if (!isGeneratedCid(sourceSite.cid) || claims.has(sourceSite.cid))
+                continue;
+            claims.set(sourceSite.cid, {
+                cid: sourceSite.cid,
+                src: sourceSite.src || null,
+                tagName: change.target.tagName ?? "",
+                text: null,
+                props: change.target.props,
+                ariaLabel: change.target.ariaLabel,
+                domPath: change.target.domPath ?? null,
+                elementId: change.target.elementId ?? null,
+            });
+            continue;
+        }
+        if (change.kind !== undefined && change.kind !== "element")
+            continue;
+        if (!isGeneratedCid(change.cid) || !change.runtimeEvidence || claims.has(change.cid))
+            continue;
+        claims.set(change.cid, claimFromEvidence(change.cid, generatedSourceFromSelector(change.selector), change.runtimeEvidence));
+    }
+    for (const change of structuralChanges) {
+        const targets = change.kind === "move"
+            ? [change.target, change.source.parent, change.destination.parent, ...(change.destination.before ? [change.destination.before] : [])]
+            : [change.target];
+        for (const { sourceSite, locator } of targets) {
+            if (!isGeneratedCid(sourceSite.cid) || claims.has(sourceSite.cid))
+                continue;
+            claims.set(sourceSite.cid, {
+                cid: sourceSite.cid,
+                src: isRuntimeGeneratedSource(sourceSite.src) ? sourceSite.src : null,
+                tagName: locator.tagName ?? "",
+                text: locator.text,
+                props: boundRuntimeEvidence(locator.props),
+                ariaLabel: boundRuntimeEvidence(locator.ariaLabel ?? null),
+                domPath: locator.domPath ?? null,
+                elementId: locator.elementId ?? null,
+            });
+        }
+    }
+    return [...claims.values()].map((claim) => (originalText.has(claim.cid) ? { ...claim, text: originalText.get(claim.cid) } : claim));
+}
+function hasStructuralMatch(element, claim) {
+    return normalizeRuntimeTag(element.tagName) === claim.tagName
+        && boundRuntimeEvidence(element.id || null) === claim.elementId
+        && boundRuntimeEvidence(element.getAttribute("aria-label")) === claim.ariaLabel
+        && boundRuntimeEvidence(element.getAttribute("data-cprops")) === claim.props
+        && (claim.domPath === null || runtimeDomPath(element) === claim.domPath);
+}
+/** Never takes an element that holds authored identity or another claim's identity. */
+function findClaimedElement(doc, claim, claimed) {
+    if (!claim.tagName)
+        return null;
+    let elements;
+    try {
+        elements = Array.from(doc.getElementsByTagName(claim.tagName));
+    }
+    catch {
+        return null;
+    }
+    const candidates = elements.filter((element) => {
+        const cid = element.getAttribute("data-cid");
+        if (cid !== null && (!isGeneratedCid(cid) || claimed.has(cid)))
+            return false;
+        return hasStructuralMatch(element, claim);
+    });
+    const byText = candidates.filter((element) => normalizeRuntimeText(element.textContent) === claim.text);
+    if (byText.length === 1)
+        return byText[0];
+    return null;
+}
+function hasIdentity(doc, cid) {
+    for (const element of Array.from(doc.querySelectorAll("[data-cid]"))) {
+        if (element.getAttribute("data-cid") === cid)
+            return true;
+    }
+    return false;
+}
+function attachClaims(doc, state) {
+    const claimed = new Set(state.claims.keys());
+    for (const claim of state.claims.values()) {
+        if (hasIdentity(doc, claim.cid))
+            continue;
+        const element = findClaimedElement(doc, claim, claimed);
+        if (!element)
+            continue;
+        element.setAttribute("data-cid", claim.cid);
+        if (claim.src !== null)
+            element.setAttribute("data-src", claim.src);
+    }
+}
+function observe(doc, state) {
+    if (state.observer || state.claims.size === 0)
+        return;
+    const Observer = doc.defaultView?.MutationObserver;
+    if (!Observer || !doc.documentElement)
+        return;
+    // 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;
+        state.queued = true;
+        queueMicrotask(() => {
+            if (states.get(doc) !== state)
+                return;
+            state.queued = false;
+            attachClaims(doc, state);
+        });
+    });
+    state.observer.observe(doc.documentElement, { childList: true, subtree: true });
+}
+/** Unmatched claims stay pending; their edits simply do not apply. */
+export function applyRuntimeIdentityClaims(doc, claims) {
+    if (claims.length === 0) {
+        disposeRuntimeIdentityClaims(doc);
+        return;
+    }
+    let state = states.get(doc);
+    if (!state) {
+        state = { claims: new Map(), observer: null, queued: false };
+        states.set(doc, state);
+    }
+    state.claims = new Map(claims.map((claim) => [claim.cid, claim]));
+    attachClaims(doc, state);
+    observe(doc, state);
+}
+/** Stops reattachment for a document session, including queued work. */
+export function disposeRuntimeIdentityClaims(doc) {
+    states.get(doc)?.observer?.disconnect();
+    states.delete(doc);
+}
+/** Runtime validation for claims received from another window. */
+export function isRuntimeIdentityClaim(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const claim = value;
+    const nullableString = (field) => field === null || typeof field === "string";
+    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)
+        && nullableString(claim.ariaLabel)
+        && nullableString(claim.domPath)
+        && nullableString(claim.elementId);
+}

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

@@ -1,32 +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;
-/** Normalizes rendered text before it becomes durable runtime evidence. */
+/** Ancestor description so a prompt without source locations still carries searchable ids, classes, and test ids. */
+export declare function runtimeDomPath(element: Element): string | null;
 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;
+/** Install before the inspector so its capture listeners run first. */
+export declare function installLazyRuntimeIdentity(doc?: Document): () => void;

package/dist/inspector/runtime/staticHtmlRuntimeIdentity.js

@@ -1,26 +1,47 @@
-/**
- * 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);
 }
-/** Normalizes rendered text before it becomes durable runtime evidence. */
+const DOM_PATH_MAX_LENGTH = 240;
+const DOM_PATH_MAX_DEPTH = 4;
+const DOM_PATH_MAX_CLASSES = 3;
+const TEST_ID_ATTRIBUTES = ["data-testid", "data-test", "data-qa"];
+function domPathSegment(element) {
+    let segment = element.localName;
+    if (element.id)
+        segment += `#${element.id}`;
+    const testAttribute = TEST_ID_ATTRIBUTES.find((name) => element.hasAttribute(name));
+    if (testAttribute)
+        segment += `[${testAttribute}="${element.getAttribute(testAttribute)}"]`;
+    const classes = Array.from(element.classList).slice(0, DOM_PATH_MAX_CLASSES);
+    if (classes.length > 0)
+        segment += `.${classes.join(".")}`;
+    return segment;
+}
+/** 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;
+    while (current && segments.length < DOM_PATH_MAX_DEPTH && !DOCUMENT_STRUCTURE_TAGS.has(current.tagName)) {
+        segments.unshift(domPathSegment(current));
+        if (current.id)
+            break;
+        current = current.parentElement;
+    }
+    if (segments.length === 0)
+        return null;
+    const path = segments.join(" > ");
+    return path.length > DOM_PATH_MAX_LENGTH ? `…${path.slice(-DOM_PATH_MAX_LENGTH)}` : path;
+}
 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, "")) ?? "";
 }
@@ -33,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);
 }
@@ -66,47 +85,10 @@ 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 usedCids = existingAttributeValues(doc, "data-cid");
-    const usedSources = existingAttributeValues(doc, "data-src");
-    let nextId = 1;
+    const ensureIdentity = createIdentityAllocator(doc);
     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;
@@ -147,3 +129,72 @@ export function installStaticHtmlRuntimeIdentity(doc = document) {
         observer.disconnect();
     };
 }
+const LAZY_IDENTITY_EVENTS = ["pointerover", "pointerdown", "mousedown", "click", "dblclick"];
+const LAZY_DESCENDANT_DEPTH = 2;
+/** Install before the inspector so its capture listeners run first. */
+export function installLazyRuntimeIdentity(doc = document) {
+    // 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)
+            return;
+        for (const child of Array.from(element.children)) {
+            ensureIdentity(child);
+            tagDescendants(child, depth - 1);
+        }
+    }
+    function onPointer(event) {
+        const target = event.target;
+        if (!(target instanceof Element) || !isEligibleElement(target))
+            return;
+        for (let current = target; current; current = current.parentElement) {
+            // Ancestors of a tagged element were tagged with it.
+            if (current.hasAttribute("data-cid") && current !== target)
+                break;
+            ensureIdentity(current);
+        }
+        tagDescendants(target, LAZY_DESCENDANT_DEPTH);
+        if (target.parentElement)
+            tagDescendants(target.parentElement, 1);
+    }
+    for (const type of LAZY_IDENTITY_EVENTS)
+        doc.addEventListener(type, onPointer, true);
+    return () => {
+        for (const type of LAZY_IDENTITY_EVENTS)
+            doc.removeEventListener(type, onPointer, true);
+    };
+}
+function createIdentityAllocator(doc, scope = "") {
+    const usedCids = existingAttributeValues(doc, "data-cid");
+    const usedSources = existingAttributeValues(doc, "data-src");
+    let nextId = 1;
+    function nextIdentity() {
+        while (true) {
+            const id = nextId++;
+            const cid = `${RUNTIME_ELEMENT_CID_PREFIX}${scope}${id}`;
+            const src = `${RUNTIME_UNKNOWN_SOURCE_PREFIX}${scope}${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);
+    }
+    return ensureIdentity;
+}

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,21 +10,16 @@ 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;
 export declare function getEditScope(el: HTMLElement): EditScope;
 export interface BatchScopeFields {
     scope: EditScope;
+    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;
 }
@@ -118,13 +108,24 @@ export function planBatchEditScopes(selectedElements) {
     if (!decisions)
         return null;
     const plan = new Map();
+    const sourceCounts = new WeakMap();
     for (const [element, decision] of decisions) {
-        plan.set(element, decision.scope === "new-rendered-instance"
+        const selector = selectorForElement(element);
+        let counts = sourceCounts.get(element.ownerDocument);
+        if (!counts) {
+            counts = new Map();
+            sourceCounts.set(element.ownerDocument, counts);
+        }
+        const count = selector ? counts.get(selector) ?? querySourceSiteMatches(element) : 0;
+        if (selector)
+            counts.set(selector, count);
+        const fields = decision.scope === "new-rendered-instance"
             ? {
                 scope: "rendered-instance",
                 instanceOverride: buildRenderedInstanceOverrideForTarget(decision.target),
             }
-            : decision);
+            : decision;
+        plan.set(element, count > 0 ? { ...fields, sourceInstanceCount: count } : fields);
     }
     return plan;
 }

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[];

package/dist/inspector/selection/hierarchy.js

@@ -21,30 +21,48 @@ export function computeHierarchy(el) {
     }
     return chain;
 }
-/** Returns the nearest tracked descendants, breadth-first and document-ordered. */
-export function computeDescendants(el, maxDepth = 2, maxNodes = 2) {
-    if (maxDepth < 1 || maxNodes < 1)
-        return [];
-    const descendants = Array.from(el.querySelectorAll('[data-cid]'))
-        .map((element, order) => {
-        let depth = 1;
-        let ancestor = element.parentElement;
-        while (ancestor && ancestor !== el) {
-            if (ancestor.hasAttribute('data-cid'))
-                depth += 1;
-            ancestor = ancestor.parentElement;
+/** Direct children listed in the DOM navigator before the rest collapse into a count. */
+export const NAVIGATOR_CHILD_LIMIT = 50;
+function htmlElementConstructor(el) {
+    return el.ownerDocument.defaultView?.HTMLElement ?? null;
+}
+/** The nearest tracked elements below `el` in document order, looking through untracked wrappers. */
+export function computeTrackedChildren(el, limit = NAVIGATOR_CHILD_LIMIT) {
+    const constructor = htmlElementConstructor(el);
+    const result = { elements: [], hidden: 0 };
+    if (!constructor)
+        return result;
+    const visit = (parent) => {
+        for (const child of parent.children) {
+            if (!(child instanceof constructor))
+                continue;
+            if (!child.hasAttribute("data-cid"))
+                visit(child);
+            else if (result.elements.length < limit)
+                result.elements.push(child);
+            else
+                result.hidden += 1;
+        }
+    };
+    visit(el);
+    return result;
+}
+export function hasTrackedChildren(el) {
+    const constructor = htmlElementConstructor(el);
+    if (!constructor)
+        return false;
+    const visit = (parent) => {
+        for (const child of parent.children) {
+            if (!(child instanceof constructor))
+                continue;
+            if (child.hasAttribute("data-cid") || visit(child))
+                return true;
         }
-        return ancestor === el ? { element, depth, order } : null;
-    })
-        .filter((node) => node !== null && node.depth <= maxDepth)
-        .sort((left, right) => left.depth - right.depth || left.order - right.order);
-    return descendants.slice(0, maxNodes).map(({ element, depth }) => ({ element, depth }));
+        return false;
+    };
+    return visit(el);
 }
-export function computeNavigationNodes(el, hierarchy = computeHierarchy(el)) {
-    const children = computeDescendants(el, 2, 2);
-    const parents = hierarchy.slice(1, (children.length > 0 ? 2 : 4) + 1);
-    return [
-        ...parents.map((element, index) => ({ element, direction: "up", depth: index + 1 })),
-        ...children.map(({ element, depth }) => ({ element, direction: "down", depth })),
-    ];
+/** Nearest tracked ancestors, fewer when children also fill the menu. */
+export function computeNavigationParents(hierarchy, hasChildren) {
+    return hierarchy.slice(1, (hasChildren ? 2 : 4) + 1);
 }

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

@@ -10,7 +10,6 @@ export interface SelectedElement {
     fiber?: unknown;
     componentTargets: RuntimeComponentTarget[];
 }
-/** The ordered selection presented to the inspector. */
 export interface Selection {
     elements: readonly SelectedElement[];
     primary: SelectedElement;
@@ -22,11 +21,9 @@ declare function getSelection(): Selection | null;
 declare function getHierarchy(): HTMLElement[];
 declare function getHierarchyIndex(): number;
 export declare function setSelectedElement(el: SelectedElement | null): void;
-/** Replaces the selection with one or more ordered targets. */
 export declare function setSelectedElements(elements: readonly SelectedElement[]): void;
 /** Adds or removes one target while keeping the toggled target primary. */
 export declare function toggleSelectedElement(el: SelectedElement): void;
-/** Removes one rendered node from the group, preserving the remaining order. */
 export declare function removeSelectedElement(el: HTMLElement): void;
 /** Refreshes metadata for one selected DOM node without collapsing a group. */
 export declare function refreshSelectedElement(el: SelectedElement): void;