nudge-ui 0.2.4 → 0.2.6

package/dist/inspector/inspection/bridge.d.ts

@@ -1,5 +1,5 @@
 import type { TokenDefinition, TokenEntry } from "../../css/model/index.js";
-import { getChangesList, getPendingRules } from "../changes/changesLog.js";
+import { getChangesList, getPendingRules } from "../drafts/store.js";
 import type { InspectorProjection } from "../spacing/projection.js";
 import type { ResolvedProperty } from "../../css/model/index.js";
 export declare const NUDGE_UI_INSPECTION_VERSION: 1;
@@ -53,11 +53,7 @@ export interface InspectElementOptions {
     catalog?: readonly TokenDefinition[];
     tokens?: readonly TokenEntry[];
 }
-/**
- * Returns the inspector's stable, read-only facts for one rendered element.
- * Compatibility tests and the React UI cross the same resolver/projection seam;
- * this function deliberately performs no selection or edit side effects.
- */
+/** Deliberately performs no selection or edit side effects. */
 export declare function inspectElement(element: HTMLElement, options?: InspectElementOptions): ElementInspection;
 export interface NudgeUiInspectionBridge {
     version: typeof NUDGE_UI_INSPECTION_VERSION;
@@ -68,5 +64,5 @@ declare global {
         __nudgeUi?: NudgeUiInspectionBridge;
     }
 }
-/** Installs the dev-only browser seam used by compatibility applications. */
+/** Dev-only seam used by compatibility applications. */
 export declare function installInspectionBridge(target?: Window): () => void;

package/dist/inspector/inspection/bridge.js

@@ -1,4 +1,5 @@
-import { getChangesList, getPendingRules, isPreviewableChange } from "../changes/changesLog.js";
+import { getChangesList, getPendingRules } from "../drafts/store.js";
+import { isPreviewableChange } from "../changes/types.js";
 import { changeKey } from "../changes/model.js";
 import { getAnyPreviewDiagnostic } from "../changes/previewDiagnostics.js";
 import { detectFramework } from "../prompt/detectFramework.js";
@@ -20,9 +21,7 @@ function inspectBrowserFacts(element, definitions, entries) {
             tokens: session.inspectTokens(element),
         };
     }
-    // Compatibility callers may provide a fixture-local catalog. Keep that
-    // Adapter isolated from the document registry so one caller cannot replace
-    // the token knowledge used by the live inspector session.
+    // Fixture-local catalogs stay out of the document registry so they cannot replace the live session's token knowledge.
     const session = createBrowserCssInspection({
         document: doc,
         tokenKnowledge: { definitions, entries, generation: "compatibility" },
@@ -52,11 +51,7 @@ function catalogEntry(definition) {
         })),
     };
 }
-/**
- * Returns the inspector's stable, read-only facts for one rendered element.
- * Compatibility tests and the React UI cross the same resolver/projection seam;
- * this function deliberately performs no selection or edit side effects.
- */
+/** Deliberately performs no selection or edit side effects. */
 export function inspectElement(element, options = {}) {
     const runtimeConfig = getNudgeUiRuntimeConfig();
     const definitions = options.catalog ?? runtimeConfig.tokenCatalog;
@@ -81,9 +76,7 @@ export function inspectElement(element, options = {}) {
             return diagnostic ? [{ property: change.property, ...diagnostic.result }] : [];
         }),
     };
-    // Local vanilla-extract themes attach contract variables to a theme class,
-    // not necessarily :root. The selected element is therefore the correct
-    // availability context for an element inspection.
+    // vanilla-extract themes attach contract variables to a theme class, not :root, so the element is the availability context.
     const controls = properties
         .filter((property) => !property.property.startsWith("--"))
         .map((property) => ({
@@ -117,7 +110,7 @@ export function inspectElement(element, options = {}) {
             : null,
     };
 }
-/** Installs the dev-only browser seam used by compatibility applications. */
+/** Dev-only seam used by compatibility applications. */
 export function installInspectionBridge(target = window) {
     const bridge = {
         version: NUDGE_UI_INSPECTION_VERSION,

package/dist/inspector/inspection/browserCssInspection.d.ts

@@ -1,3 +1,4 @@
+import { type ContainerQueryEvaluator } from "../tokens/resolution/containerQueryEvaluator.js";
 import type { TokenDefinition, TokenEntry } from "../../css/model/index.js";
 import type { ResolvedProperty } from "../../css/model/index.js";
 import type { InteractionState } from "../shell/styleState.js";
@@ -5,8 +6,7 @@ import { type TokenCatalogRow } from "../tokens/catalog.js";
 export interface BrowserTokenKnowledge {
     /** Build-time definitions normalized by a build-tool Adapter. */
     definitions: readonly TokenDefinition[];
-    /** Optional compiler entries used to resolve authored references that are
-     * intentionally not mounted as custom properties in the current document. */
+    /** Compiler entries for authored references intentionally not mounted as custom properties. */
     entries?: readonly TokenEntry[];
     /** Changes whenever the Adapter publishes a new token inventory. */
     generation: string | number;
@@ -15,16 +15,13 @@ export interface BrowserCssInspectionConfig {
     document: Document;
     tokenKnowledge: BrowserTokenKnowledge;
 }
-/**
- * Cascade transform owned exclusively by this module:
- * - authored: interaction-state attribution (default; state defaults to base)
- * - live: raw CSSOM matching as currently painted
- * - stable: drops transient pseudo-class rules for editor token linking
- */
+/** authored: interaction-state attribution; live: raw CSSOM as painted; stable: drops transient pseudo-class rules for token linking. */
 export type InspectionCascade = "authored" | "live" | "stable";
 export interface BrowserCssInspectionOptions {
     state?: InteractionState;
     cascade?: InspectionCascade;
+    /** Shared only within one synchronous refresh. */
+    containerQueries?: ContainerQueryEvaluator;
 }
 export type InspectionTargetStatus = "attached" | "detached" | "foreign-document" | "unsupported" | "disabled" | "disposed";
 export type InspectionDiagnosticCode = "target-document-mismatch" | "target-detached" | "target-unsupported" | "state-unavailable" | "inspection-failed" | "production-disabled" | "session-disposed";
@@ -62,12 +59,16 @@ export interface DocumentTokenInspectionSnapshot {
 }
 export interface BrowserCssInspection {
     inspect(element: HTMLElement, options?: BrowserCssInspectionOptions): InspectionSnapshot;
+    /** Resolves one selection with a shared, short-lived container evaluator. */
+    refresh?(elements: readonly HTMLElement[], state: InteractionState): {
+        elements: readonly InspectionSnapshot[];
+        stableProperties: readonly ResolvedProperty[];
+    };
     inspectTokens(root?: HTMLElement): DocumentTokenInspectionSnapshot;
     subscribe(listener: (revision: InspectionRevision) => void): () => void;
-    /** Integration hook for managed CSSOM writes. */
+    /** Integration hook for writes to the inspector's own managed stylesheets. */
     notifyStylesheetChange(): void;
-    /** Optional: warms the CSSOM rule snapshot so the next inspect does not pay
-     * the stylesheet walk inside its own budget. Cheap when already warm. */
+    /** Warms the CSSOM rule snapshot so the next inspect does not pay the stylesheet walk. */
     prewarmRules?(): void;
     dispose(): void;
 }

package/dist/inspector/inspection/browserCssInspection.js

@@ -1,7 +1,9 @@
+import { createContainerQueryEvaluator } from "../tokens/resolution/containerQueryEvaluator.js";
 import { isNudgeUiDev } from "../runtime/devFlag.js";
-import { buildTokenTable, getAvailableInteractionStates, getAvailableTokenCatalog, getAvailableTokenEntriesForElement, getResolvedProperties, getResolvedPropertiesForState, getResolvedPropertiesStable, invalidateStyleResolutionCache, prewarmCssomRuleSnapshot, } from "../tokens/resolution.js";
+import { countInspectionWork } from "./performanceDiagnostics.js";
+import { buildTokenTable, getAvailableInteractionStates, getAvailableTokenCatalog, getAvailableTokenEntriesForElement, getResolvedProperties, getResolvedPropertiesForState, getResolvedPropertiesStable, invalidateStyleResolutionCache, prewarmCssomRuleSnapshot, prefetchContainerQueries, } from "../tokens/resolution.js";
 import { buildTokenCatalogRows } from "../tokens/catalog.js";
-import { documentRevisions, registerResolutionElement, retainDocumentResolution, subscribeDocumentRevision, } from "../tokens/resolution/cssomCollector.js";
+import { documentRevisions, invalidateOwnedStyleResolution, registerResolutionElement, retainDocumentResolution, subscribeDocumentRevision, } from "../tokens/resolution/cssomCollector.js";
 function revisionSnapshot(revisions, tokenGeneration) {
     return {
         element: revisions.element,
@@ -119,12 +121,12 @@ function disabledInspection(config) {
 function notifyRevision(listener, revisions, tokenGeneration) {
     listener(revisionSnapshot(revisions, tokenGeneration));
 }
-function resolveCascadeProperties(element, table, cascade, state) {
+function resolveCascadeProperties(element, table, cascade, state, evaluator) {
     if (cascade === "live")
-        return getResolvedProperties(element, table);
+        return getResolvedProperties(element, table, evaluator);
     if (cascade === "stable")
-        return getResolvedPropertiesStable(element, table);
-    return getResolvedPropertiesForState(element, table, state);
+        return getResolvedPropertiesStable(element, table, evaluator);
+    return getResolvedPropertiesForState(element, table, state, evaluator);
 }
 export function createBrowserCssInspection(config) {
     if (!isNudgeUiDev())
@@ -136,8 +138,7 @@ export function createBrowserCssInspection(config) {
     const releaseDocumentResolution = retainDocumentResolution(config.document);
     const revisionUnsubscribers = new Set();
     const elementTables = new WeakMap();
-    // When compiler entries are merged ahead of runtime availability, keep one
-    // table per availableTokens identity so resolver caches stay warm.
+    // When compiler entries are merged ahead of runtime availability, keep one table per availableTokens identity so resolver caches stay warm.
     const mergedTables = new WeakMap();
     const mediaCleanup = [];
     const mediaQueries = new Set(definitions.flatMap((definition) => definition.declarations.flatMap((declaration) => (declaration.context.wrappers ?? [])
@@ -197,6 +198,7 @@ export function createBrowserCssInspection(config) {
     }
     const session = {
         inspect(element, options = {}) {
+            countInspectionWork(config.document, "inspections");
             const state = options.state ?? "base";
             const cascade = options.cascade ?? "authored";
             const status = disposed ? "disposed" : targetStatus(element, config.document);
@@ -214,10 +216,7 @@ export function createBrowserCssInspection(config) {
             }
             try {
                 const { availableTokens, table } = tokenTableFor(element);
-                // Only the authored cascade reports which interaction states have
-                // authored rules (the panel's state selector reads it there). Stable
-                // and live consumers project properties only, so skip the O(rules)
-                // per-state matching sweep for them.
+                // Only the authored cascade reports authored interaction states; the O(rules) per-state sweep is skipped elsewhere.
                 const availableStates = cascade === "stable"
                     ? ["base"]
                     : getAvailableInteractionStates(element);
@@ -227,7 +226,7 @@ export function createBrowserCssInspection(config) {
                         message: `The ${state} interaction state has no matching authored rule for this element.`,
                     });
                 }
-                const properties = resolveCascadeProperties(element, table, cascade, state);
+                const properties = resolveCascadeProperties(element, table, cascade, state, options.containerQueries ?? createContainerQueryEvaluator(config.document));
                 return {
                     target: { status },
                     cascade,
@@ -249,6 +248,25 @@ export function createBrowserCssInspection(config) {
                 return emptySnapshot(status, cascade, state, revision, diagnostics);
             }
         },
+        refresh(elements, state) {
+            const containerQueries = createContainerQueryEvaluator(config.document);
+            const targets = elements.filter((element) => element.ownerDocument === config.document);
+            try {
+                if (!disposed)
+                    prefetchContainerQueries(targets, state, containerQueries);
+            }
+            catch (error) {
+                return {
+                    elements: elements.map((element) => emptySnapshot(targetStatus(element, config.document), "authored", state, currentRevision(), [{ code: "inspection-failed", message: error instanceof Error ? error.message : "Container query evaluation failed." }])),
+                    stableProperties: [],
+                };
+            }
+            return {
+                elements: elements.map((element) => session.inspect(element, { state, containerQueries })),
+                stableProperties: elements[0] && state === "base"
+                    ? session.inspect(elements[0], { cascade: "stable", containerQueries }).properties : [],
+            };
+        },
         inspectTokens(root = config.document.documentElement) {
             const diagnostics = [];
             const revision = currentRevision();
@@ -296,7 +314,7 @@ export function createBrowserCssInspection(config) {
         },
         notifyStylesheetChange() {
             if (!disposed)
-                invalidateStyleResolutionCache(config.document);
+                invalidateOwnedStyleResolution(config.document);
         },
         prewarmRules() {
             if (!disposed)

package/dist/inspector/inspection/browserCssInspectionRegistry.d.ts

@@ -1,12 +1,5 @@
 import { type BrowserCssInspection, type BrowserTokenKnowledge } from "./browserCssInspection.js";
-/**
- * Binds a document to token knowledge. When generation changes, the previous
- * session is disposed and replaced so callers never keep a stale catalog.
- */
 export declare function bindBrowserCssInspection(doc: Document, knowledge: BrowserTokenKnowledge): BrowserCssInspection;
-/** Returns the one browser inspection session owned by a document. */
 export declare function getBrowserCssInspection(doc?: Document): BrowserCssInspection;
-/** Invalidates every browser-inspection snapshot affected by a CSSOM write. */
 export declare function notifyBrowserStylesheetChange(doc?: Document): void;
-/** Releases a document session when its inspector/Canvas lifecycle ends. */
 export declare function disposeBrowserCssInspection(doc: Document): void;

package/dist/inspector/inspection/browserCssInspectionRegistry.js

@@ -6,15 +6,7 @@ let catalogSignature = "";
 let catalogRevision = 0;
 function currentTokenKnowledge() {
     const { tokenCatalog, tokenGeneration } = getNudgeUiRuntimeConfig();
-    // The inventory snapshot generation is the authoritative fingerprint: when
-    // observable inventory facts change, the virtual module re-evaluates and
-    // `tokenGeneration` carries a new value, so document sessions recreate with
-    // the new definitions instead of freezing the first catalog snapshot.
-    //
-    // A catalog signature supplements the inventory generation because S2-B
-    // still has temporary post-snapshot Tailwind/vanilla-extract enrichment.
-    // It advances only when those observable transport definitions change, not
-    // for a no-op virtual-module replacement.
+    // The inventory generation recreates document sessions with new definitions; the catalog signature supplements it for post-snapshot enrichment.
     if (catalogReference !== tokenCatalog) {
         catalogReference = tokenCatalog;
         const nextSignature = JSON.stringify(tokenCatalog);
@@ -28,10 +20,6 @@ function currentTokenKnowledge() {
         : catalogRevision === 0 ? tokenGeneration : `${tokenGeneration}:${catalogRevision}`;
     return { definitions: tokenCatalog, generation };
 }
-/**
- * Binds a document to token knowledge. When generation changes, the previous
- * session is disposed and replaced so callers never keep a stale catalog.
- */
 export function bindBrowserCssInspection(doc, knowledge) {
     const existing = sessions.get(doc);
     if (existing && existing.generation === knowledge.generation) {
@@ -48,15 +36,12 @@ export function bindBrowserCssInspection(doc, knowledge) {
     sessions.set(doc, { session, generation: knowledge.generation });
     return session;
 }
-/** Returns the one browser inspection session owned by a document. */
 export function getBrowserCssInspection(doc = document) {
     return bindBrowserCssInspection(doc, currentTokenKnowledge());
 }
-/** Invalidates every browser-inspection snapshot affected by a CSSOM write. */
 export function notifyBrowserStylesheetChange(doc = document) {
     getBrowserCssInspection(doc).notifyStylesheetChange();
 }
-/** Releases a document session when its inspector/Canvas lifecycle ends. */
 export function disposeBrowserCssInspection(doc) {
     const entry = sessions.get(doc);
     if (!entry)

package/dist/inspector/inspection/inspectionSnapshot.d.ts

@@ -0,0 +1,6 @@
+import type { InteractionState } from "../shell/styleState.js";
+import type { InspectionSnapshot } from "./browserCssInspection.js";
+/** Publishes the hook's completed refresh before its controls render. */
+export declare function publishInspectionSnapshot(element: HTMLElement, snapshot: InspectionSnapshot): void;
+/** Reads the current view without starting another cascade inspection. */
+export declare function readInspectionSnapshot(element: HTMLElement, state: InteractionState): InspectionSnapshot | undefined;

package/dist/inspector/inspection/inspectionSnapshot.js

@@ -0,0 +1,10 @@
+const snapshots = new WeakMap();
+/** Publishes the hook's completed refresh before its controls render. */
+export function publishInspectionSnapshot(element, snapshot) {
+    snapshots.set(element, snapshot);
+}
+/** Reads the current view without starting another cascade inspection. */
+export function readInspectionSnapshot(element, state) {
+    const snapshot = snapshots.get(element);
+    return snapshot?.requestedState === state ? snapshot : undefined;
+}

package/dist/inspector/inspection/performanceDiagnostics.d.ts

@@ -0,0 +1,18 @@
+type Interaction = "selection" | "hover" | "drag" | "idle";
+type Counter = "inspections" | "refreshes" | "containerChecks" | "probePairs" | "probeBatches";
+type Counts = Record<Counter, number>;
+interface InspectionPerformanceDiagnostics {
+    read(): Record<Interaction, Counts>;
+    reset(): void;
+    dispose(): void;
+}
+declare global {
+    interface Window {
+        __nudgeUiPerformance?: InspectionPerformanceDiagnostics;
+    }
+}
+/** Records work only when diagnostics are explicitly enabled for a document. */
+export declare function countInspectionWork(doc: Document, counter: Counter, count?: number): void;
+/** Groups asynchronous inspection work by the most recent pointer gesture. */
+export declare function enableInspectionPerformanceDiagnostics(doc: Document): void;
+export {};

package/dist/inspector/inspection/performanceDiagnostics.js

@@ -0,0 +1,31 @@
+const counters = new WeakMap();
+/** Records work only when diagnostics are explicitly enabled for a document. */
+export function countInspectionWork(doc, counter, count = 1) {
+    counters.get(doc)?.(counter, count);
+}
+/** Groups asynchronous inspection work by the most recent pointer gesture. */
+export function enableInspectionPerformanceDiagnostics(doc) {
+    const view = doc.defaultView;
+    if (!view || view.__nudgeUiPerformance)
+        return;
+    let interaction = "idle";
+    const empty = () => ({ inspections: 0, refreshes: 0, containerChecks: 0, probePairs: 0, probeBatches: 0 });
+    let counts = { idle: empty(), selection: empty(), hover: empty(), drag: empty() };
+    const move = (event) => { interaction = event.buttons ? "drag" : "hover"; };
+    const select = () => { interaction = "selection"; };
+    doc.addEventListener("pointermove", move, true);
+    doc.addEventListener("pointerdown", select, true);
+    doc.addEventListener("click", select, true);
+    counters.set(doc, (counter, count) => { counts[interaction][counter] += count; });
+    view.__nudgeUiPerformance = {
+        read: () => structuredClone(counts),
+        reset() { counts = { idle: empty(), selection: empty(), hover: empty(), drag: empty() }; },
+        dispose() {
+            doc.removeEventListener("pointermove", move, true);
+            doc.removeEventListener("pointerdown", select, true);
+            doc.removeEventListener("click", select, true);
+            counters.delete(doc);
+            delete view.__nudgeUiPerformance;
+        },
+    };
+}

package/dist/inspector/inspection/selectionProperty.d.ts

@@ -13,7 +13,6 @@ export type SelectionToken = {
 } | {
     kind: "mixed";
 };
-/** One CSS property projected across every element in the current selection. */
 export interface SelectionProperty {
     property: string;
     value: SelectionValue;
@@ -21,12 +20,8 @@ export interface SelectionProperty {
     primaryRow: ResolvedProperty | null;
     rows: readonly (ResolvedProperty | null)[];
 }
-/**
- * Projects browser values and authored inspection rows into group-safe facts.
- * The returned type cannot masquerade as an authored CSS row.
- */
+/** The result cannot masquerade as an authored CSS row. */
 export declare function projectSelectionProperty(property: string, rows: readonly (ResolvedProperty | null)[], values: readonly string[], primaryIndex: number): SelectionProperty | null;
-/** Returns the token entries available to every inspected target. */
 export declare function intersectTokenEntries<T extends {
     name: string;
     value: string;

package/dist/inspector/inspection/selectionProperty.js

@@ -7,10 +7,7 @@ function tokenFor(rows) {
         ? { kind: "common", name: first }
         : { kind: "mixed" };
 }
-/**
- * Projects browser values and authored inspection rows into group-safe facts.
- * The returned type cannot masquerade as an authored CSS row.
- */
+/** The result cannot masquerade as an authored CSS row. */
 export function projectSelectionProperty(property, rows, values, primaryIndex) {
     if (values.length === 0 || rows.length !== values.length)
         return null;
@@ -25,7 +22,6 @@ export function projectSelectionProperty(property, rows, values, primaryIndex) {
         rows,
     };
 }
-/** Returns the token entries available to every inspected target. */
 export function intersectTokenEntries(entries) {
     const first = entries[0];
     if (!first)

package/dist/inspector/inspection/useBrowserCssInspection.d.ts

@@ -12,9 +12,5 @@ export interface BrowserCssInspectionViewOptions {
     includeDocumentTokens?: boolean;
     session?: BrowserCssInspection;
 }
-/**
- * React Adapter for one revision-aware browser inspection view. This is the
- * sole owner of subscription and scheduling policy; UI callers only project
- * the returned snapshots.
- */
+/** Sole owner of subscription and scheduling policy; callers only project the returned snapshots. */
 export declare function useBrowserCssInspection(selected: SelectedElement | readonly SelectedElement[] | null, state?: InteractionState, options?: BrowserCssInspectionViewOptions): BrowserCssInspectionView;

package/dist/inspector/inspection/useBrowserCssInspection.js

@@ -1,5 +1,7 @@
+import { publishInspectionSnapshot } from "./inspectionSnapshot.js";
 import { useEffect, useMemo, useRef, useState } from "react";
 import { getBrowserCssInspection } from "./browserCssInspectionRegistry.js";
+import { countInspectionWork } from "./performanceDiagnostics.js";
 const SELECTION_DEBOUNCE_MS = 8;
 const EMPTY_SELECTION = [];
 function isSelectedElementList(selected) {
@@ -18,30 +20,19 @@ function normalizeSelection(selected) {
         return selected;
     return [selected];
 }
-function inspectAuthoredElements(session, selected, state) {
-    return selected.map((element) => session.inspect(element.domElement, { state, cascade: "authored" }));
-}
-function inspectStableView(session, selected, state, includeDocumentTokens, elements) {
-    const primary = elements[0] ?? null;
-    const stableProperties = selected[0] && state === "base"
-        ? session.inspect(selected[0].domElement, { cascade: "stable" }).properties
-        : [];
-    const documentTokens = includeDocumentTokens ? session.inspectTokens() : null;
+function inspectView(session, selected, state, includeDocumentTokens) {
+    const result = session.refresh?.(selected.map((element) => element.domElement), state);
+    const elements = result?.elements ?? selected.map((element) => session.inspect(element.domElement, { state, cascade: "authored" }));
+    const stableProperties = result?.stableProperties ?? (selected[0] && state === "base"
+        ? session.inspect(selected[0].domElement, { cascade: "stable" }).properties : []);
+    elements.forEach((snapshot, index) => publishInspectionSnapshot(selected[index].domElement, snapshot));
     return {
-        selection: selected,
-        state,
-        session,
-        element: primary,
-        elements,
-        stableProperties,
-        documentTokens,
+        selection: selected, state, session,
+        element: elements[0] ?? null, elements, stableProperties,
+        documentTokens: includeDocumentTokens ? session.inspectTokens() : null,
     };
 }
-/**
- * React Adapter for one revision-aware browser inspection view. This is the
- * sole owner of subscription and scheduling policy; UI callers only project
- * the returned snapshots.
- */
+/** Sole owner of subscription and scheduling policy; callers only project the returned snapshots. */
 export function useBrowserCssInspection(selected, state = "base", options = {}) {
     const selectedElements = useMemo(() => normalizeSelection(selected), [selected]);
     const selectedDocument = selectedElements[0]?.domElement.ownerDocument ?? document;
@@ -49,14 +40,15 @@ export function useBrowserCssInspection(selected, state = "base", options = {})
     const includeDocumentTokens = options.includeDocumentTokens ?? false;
     const latest = useRef({ selected: selectedElements, state, session, includeDocumentTokens });
     latest.current = { selected: selectedElements, state, session, includeDocumentTokens };
-    const [view, setView] = useState(() => inspectStableView(session, selectedElements, state, includeDocumentTokens, inspectAuthoredElements(session, selectedElements, state)));
+    const [view, setView] = useState(() => ({
+        ...EMPTY_VIEW, selection: EMPTY_SELECTION, state, session,
+    }));
     const timerRef = useRef(null);
     const lastSelectionResolveAtRef = useRef(0);
     const revisionFrameRef = useRef(null);
     const revisionSecondFrameRef = useRef(null);
     const revisionThirdFrameRef = useRef(null);
     const revisionWarmFrameRef = useRef(null);
-    const stableFrameRef = useRef(null);
     const cancelScheduledInspection = () => {
         if (timerRef.current !== null) {
             clearTimeout(timerRef.current);
@@ -78,36 +70,16 @@ export function useBrowserCssInspection(selected, state = "base", options = {})
             cancelAnimationFrame(revisionWarmFrameRef.current);
             revisionWarmFrameRef.current = null;
         }
-        if (stableFrameRef.current !== null) {
-            cancelAnimationFrame(stableFrameRef.current);
-            stableFrameRef.current = null;
-        }
     };
     const resolveSync = () => {
         const current = latest.current;
+        countInspectionWork(selectedDocument, "refreshes");
         lastSelectionResolveAtRef.current = performance.now();
-        setView(inspectStableView(current.session, current.selected, current.state, current.includeDocumentTokens, inspectAuthoredElements(current.session, current.selected, current.state)));
-    };
-    const resolveSplit = () => {
-        const current = latest.current;
-        // Post-commit refresh: the authored cascade resolves in this task and the
-        // secondary stable cascade continues one frame later. Rapid successive
-        // edits therefore cancel the pending refresh (revision bumps reschedule)
-        // instead of finding a long blocking task already running, and the two
-        // resolution sweeps never block one task for their combined duration.
-        // The view still commits once, with the same data and ordering.
-        const elements = inspectAuthoredElements(current.session, current.selected, current.state);
-        stableFrameRef.current = requestAnimationFrame(() => {
-            stableFrameRef.current = null;
-            setView(inspectStableView(current.session, current.selected, current.state, current.includeDocumentTokens, elements));
-        });
+        setView(inspectView(current.session, current.selected, current.state, current.includeDocumentTokens));
     };
     const scheduleSelectionInspection = () => {
         cancelScheduledInspection();
-        // Leading-edge resolve: a selection change resolves immediately instead
-        // of always waiting out the debounce. Rapid re-selections inside the
-        // trailing window still coalesce onto one trailing resolve, so the final
-        // view is identical and repeated selections cannot stack full sweeps.
+        // Leading-edge resolve: a selection change resolves immediately, and rapid re-selections coalesce onto one trailing resolve.
         const sinceLast = performance.now() - lastSelectionResolveAtRef.current;
         if (sinceLast >= SELECTION_DEBOUNCE_MS) {
             resolveSync();
@@ -120,12 +92,7 @@ export function useBrowserCssInspection(selected, state = "base", options = {})
     };
     const scheduleRevisionInspection = () => {
         cancelScheduledInspection();
-        // Let the host commit and paint before refreshing the inspector
-        // projection. The extra frames keep the refresh start past the gap
-        // between rapid successive edits, so a new revision cancels the pending
-        // refresh instead of colliding with a running one, and they give the
-        // stylesheet walk its own frame so no single refresh task blocks for the
-        // combined duration of the walk plus a cascade sweep.
+        // Let the host commit and paint: the extra frames let a new revision cancel the pending refresh and give the stylesheet walk its own frame.
         revisionFrameRef.current = requestAnimationFrame(() => {
             revisionFrameRef.current = null;
             revisionSecondFrameRef.current = requestAnimationFrame(() => {
@@ -135,7 +102,7 @@ export function useBrowserCssInspection(selected, state = "base", options = {})
                     latest.current.session.prewarmRules?.();
                     revisionWarmFrameRef.current = requestAnimationFrame(() => {
                         revisionWarmFrameRef.current = null;
-                        resolveSplit();
+                        resolveSync();
                     });
                 });
             });
@@ -146,10 +113,7 @@ export function useBrowserCssInspection(selected, state = "base", options = {})
         return cancelScheduledInspection;
     }, [includeDocumentTokens, selectedElements, state, session]);
     useEffect(() => session.subscribe(scheduleRevisionInspection), [session]);
-    // Warm the CSSOM rule snapshot during idle time so the first selection does
-    // not pay the stylesheet walk inside its own interaction. The idle timeout
-    // bounds the wait without competing with page-load paint; the walk is
-    // idempotent per stylesheet revision, so this is a no-op once warm.
+    // Warm during idle so the first selection does not pay the stylesheet walk; the walk is idempotent per stylesheet revision.
     const prewarmedSessionRef = useRef(null);
     useEffect(() => {
         if (prewarmedSessionRef.current === session)
@@ -164,8 +128,7 @@ export function useBrowserCssInspection(selected, state = "base", options = {})
         const timeoutId = setTimeout(warm, 200);
         return () => clearTimeout(timeoutId);
     }, [session, selectedDocument]);
-    // Selection effects run after children render. Never expose the previous
-    // element's authored rows while the new selection is waiting for inspection.
+    // Selection effects run after children render; never expose the previous element's rows while inspection is pending.
     const matchesSelection = view.session === session && view.state === state
         && view.selection.length === selectedElements.length
         && view.selection.every((element, index) => element.domElement === selectedElements[index]?.domElement);

package/dist/inspector/iterations/capture.d.ts

@@ -1,2 +1,2 @@
-/** Captures the visible DOM of a same-origin frame as a script-free HTML iteration. */
-export declare function captureHtmlIteration(frame: HTMLIFrameElement): Promise<string>;
+import type { CanvasFrame } from "../canvas/canvasFrame.js";
+export declare function captureHtmlIteration(frame: CanvasFrame): Promise<string>;

package/dist/inspector/iterations/capture.js

@@ -1,6 +1,5 @@
 import { HTML_ARTIFACT_REVISION_ATTRIBUTE } from "../../transport/artifacts.js";
 import { FRAME_SCROLLBAR_STYLE_ID } from "../canvas/frameScrollbarStyles.js";
-/** Captures the visible DOM of a same-origin frame as a script-free HTML iteration. */
 export async function captureHtmlIteration(frame) {
     const source = frame.contentDocument;
     const view = frame.contentWindow;
@@ -19,11 +18,9 @@ export async function captureHtmlIteration(frame) {
         const copied = copiedElements[index];
         if (sourceElement.nodeType !== 1 || copied.nodeType !== 1)
             continue;
-        // Renderer IDs belong to the source iframe's node registry. The iteration's
-        // fresh registry can reuse those values for different nodes.
+        // Renderer IDs belong to the source iframe's registry; the iteration's fresh registry can reuse them for different nodes.
         copied.removeAttribute("data-renderer-id");
-        // Preserve authored inline values (percentages, variables, and calc), rather
-        // than replacing them with computed dimensions at the capture viewport.
+        // Keep authored inline values (percentages, variables, calc) instead of computed dimensions.
         const inline = copied.getAttribute("style");
         if (inline)
             copied.setAttribute("style", await resolveCssUrls(inline, source.baseURI, assets));
@@ -100,8 +97,7 @@ async function captureStylesheets(document, copy, sourceElements, copiedElements
                 css = await response.text();
             }
             catch {
-                // Keep the stylesheet link when CORS prevents embedding it. Its URL
-                // still resolves against the original base and retains responsiveness.
+                // Keep the stylesheet link when CORS prevents embedding it; its URL still resolves against the original base.
                 continue;
             }
         }
@@ -112,8 +108,7 @@ async function captureStylesheets(document, copy, sourceElements, copiedElements
             }
         }
         style.textContent = await resolveCssUrls(css, sheet.href ?? document.baseURI, assets);
-        // Captured edits become the iteration's base. The renderer must create its own
-        // managed stylesheet for new edits instead of clearing these captured rules.
+        // Captured edits become the iteration's base; the renderer must create its own managed stylesheet for new edits.
         if (style.id === "nudge-ui-styles") {
             style.removeAttribute("id");
             style.removeAttribute("data-nudge-ui");

package/dist/inspector/iterations/client.d.ts

@@ -1,7 +1,7 @@
+import type { CanvasFrame } from "../canvas/canvasFrame.js";
 import { type HtmlArtifactRevision } from "../../transport/artifacts.js";
 export declare function artifactDocumentUrl(id: string): string;
 export declare function readHtmlArtifactRevision(id: string): Promise<HtmlArtifactRevision>;
-/** Checks the editing base before saving and promoting a captured document. */
 export declare function commitHtmlArtifact(id: string, expected: HtmlArtifactRevision, html?: string): Promise<HtmlArtifactRevision>;
-export declare function createHtmlArtifact(frame: HTMLIFrameElement, sourceUrl: string, title: string, capturedHtml?: string): Promise<string>;
+export declare function createHtmlArtifact(frame: CanvasFrame, sourceUrl: string, title: string, capturedHtml?: string): Promise<string>;
 export declare function removeHtmlArtifact(id: string): Promise<void>;

package/dist/inspector/iterations/client.js

@@ -13,7 +13,6 @@ export async function readHtmlArtifactRevision(id) {
         throw new Error("The HTML iteration returned an invalid revision.");
     return revision;
 }
-/** Checks the editing base before saving and promoting a captured document. */
 export async function commitHtmlArtifact(id, expected, html) {
     const response = await fetch(`${NUDGE_UI_ARTIFACTS_PATH}/${id}/commit`, {
         method: "POST",