nudge-ui 0.2.5 → 0.2.6

package/dist/inspector/inline-text/inlineTextEditor.js

@@ -11,8 +11,7 @@ const listeners = new Set();
 let activeSession = null;
 let activeSessionDocument = null;
 let pendingEditIntent = null;
-// This remains armed if blur replaces the DOM between the second pointer-down
-// and dblclick; only the next handoff attempt or explicit teardown consumes it.
+// Stays armed if blur replaces the DOM between the second pointer-down and dblclick; the next handoff attempt or teardown consumes it.
 let handoffPointerArmed = false;
 let pendingReplayScheduled = false;
 let sessionRevision = 0;
@@ -51,7 +50,6 @@ export function cancelInlineTextEdit() {
     else
         clearInlineTextDiagnostics();
 }
-/** End a session owned by a document/frame that is about to be disposed. */
 export function disposeInlineTextEdit(reason = "frame-disposed", ownerDocument) {
     if (!ownerDocument) {
         discardPendingInlineTextEdit();
@@ -134,11 +132,7 @@ function schedulePendingInlineTextEdit() {
         drainPendingInlineTextEdit();
     });
 }
-/**
- * Request inline editing from a document gesture. This is the interaction
- * seam: it owns active-session handoff so gesture routers never discard a
- * valid target switch merely because another draft is settling.
- */
+/** Owns active-session handoff so gesture routers never discard a valid target switch. */
 function requestInlineTextEdit(target, point) {
     if (activeSession) {
         const hitTarget = target.ownerDocument.elementFromPoint?.(point.x, point.y);
@@ -147,10 +141,7 @@ function requestInlineTextEdit(target, point) {
             return "stop-propagation";
         }
     }
-    // Application-owned contenteditable surfaces must retain native editing
-    // semantics. They are intentionally rejected by text binding, but that
-    // rejection must not become an inspector-level suppression when another
-    // inline edit is already active.
+    // Application-owned contenteditable surfaces keep native editing semantics; their binding rejection must not become an inspector-level suppression.
     if (isApplicationOwnedEditingSurface(target))
         return "pass-through";
     const intent = {
@@ -170,11 +161,7 @@ function requestInlineTextEdit(target, point) {
         drainPendingInlineTextEdit();
     return "suppress";
 }
-/**
- * Handle one native interaction while keeping session-transition policy
- * local. Pointer-down preserves double-click intent across the first click's
- * blur commit, even when canonical projection replaces the target DOM.
- */
+/** Pointer-down preserves double-click intent across the first click's blur commit. */
 export function handleInlineTextEditIntent(intent) {
     if (intent.kind === "double-click") {
         return requestInlineTextEdit(intent.target, intent.point);
@@ -221,9 +208,7 @@ function restoreSelection(doc, snapshot) {
                 selection.addRange(range);
             }
             catch {
-                // A framework rerender can invalidate a saved range between cleanup
-                // and restoration. Removing the transient selection is safer than
-                // retaining a range in a detached editing wrapper.
+                // A framework rerender can invalidate a saved range; dropping the selection beats keeping a range in a detached wrapper.
                 selection.removeAllRanges();
             }
         }
@@ -240,14 +225,11 @@ function restoreDraft(candidate, host, text, ownership) {
     if (!hostIsOwned(candidate, host, ownership))
         return false;
     const original = candidate.textNode;
-    // Normal typing replaces the original node inside the wrapper, leaving it
-    // detached. If reconciliation moved that node into another live tree,
-    // never move it back into the captured position.
+    // Typing detaches the original node inside the wrapper; if reconciliation moved it into another live tree, never move it back.
     if (original.isConnected && original.parentNode !== host)
         return false;
     original.nodeValue = text;
-    // Keep the original Text node and replace only the transient wrapper. This
-    // preserves every sibling/descendant of an icon-plus-label host.
+    // Replacing only the transient wrapper preserves siblings/descendants of an icon-plus-label host.
     host.replaceWith(original);
     return true;
 }
@@ -268,8 +250,7 @@ function rangeInsideHost(host, range) {
     if (!isNodeInsideHost(host, range.startContainer)
         || !isNodeInsideHost(host, range.endContainer))
         return false;
-    // A host ancestor contains the common ancestor whenever both endpoints are
-    // inside it; StaticRange does not expose commonAncestorContainer.
+    // Endpoints inside the host imply the common ancestor is too; StaticRange does not expose commonAncestorContainer.
     return true;
 }
 function selectionInsideHost(host) {
@@ -411,8 +392,7 @@ function makeSession(candidate) {
     const originalParent = candidate.textNode.parentNode;
     const originalNextSibling = candidate.textNode.nextSibling;
     if (!originalParent) {
-        // `resolveTextBinding` only returns connected text nodes, but keep this
-        // boundary defensive if a framework mutates between resolution and wrap.
+        // resolveTextBinding returns connected text nodes, but a framework can mutate between resolution and wrap.
         throw new Error("Inline text target lost its parent before editing began.");
     }
     const ownership = { parent: originalParent, nextSibling: originalNextSibling };
@@ -423,12 +403,7 @@ function makeSession(candidate) {
     host.setAttribute("contenteditable", "plaintext-only");
     host.contentEditable = "plaintext-only";
     candidate.textNode.replaceWith(host);
-    // An empty Text node is retained for exact restoration, but leaving it as
-    // the first child of a native contenteditable makes Chromium insert the
-    // first character beside it. The input handler then has to coalesce two
-    // text nodes and the browser resets the caret to the start, reversing the
-    // visible draft. Let the empty editor start childless; restoreDraft still
-    // puts the captured node back at the owned insertion point on exit.
+    // A leading empty Text node makes Chromium insert the first character beside it and reset the caret; start childless and let restoreDraft put the node back on exit.
     if (candidate.before.length > 0)
         host.append(candidate.textNode);
     let finished = false;
@@ -486,8 +461,7 @@ function makeSession(candidate) {
         if (finished)
             return;
         const restoreFocus = editorOwnsFocus();
-        // A moved/reordered host has no safe insertion point. Remove only the
-        // temporary wrapper; never reinsert the original node into a new tree.
+        // A moved host has no safe insertion point: remove the wrapper, never reinsert the original node.
         if (host.isConnected)
             host.remove();
         finish("app-reconciled", "cancelled", discardedDraft, restoreFocus);
@@ -553,9 +527,7 @@ function makeSession(candidate) {
                 }
             }
         }
-        // A cancelled/unchanged re-entry keeps the same affordance. A committed
-        // non-empty value is synchronously reconciled by the text projection,
-        // which removes it after this session cleanup.
+        // Restore the affordance on cancel/unchanged; a committed non-empty value is removed by projection reconciliation.
         if (candidate.emptyProjectionMarker?.isConnected) {
             candidate.emptyProjectionMarker.hidden = false;
         }
@@ -566,8 +538,7 @@ function makeSession(candidate) {
         if (finished)
             return;
         if (event.isComposing || composing) {
-            // Enter/Escape belong to the IME until compositionend. Keeping the
-            // session alive makes the composition one canonical edit.
+            // Enter/Escape belong to the IME until compositionend; keeping the session alive makes the composition one canonical edit.
             event.stopPropagation();
             if (event.key === "Enter" || event.key === "Escape" || event.key === "Esc") {
                 event.preventDefault();
@@ -592,10 +563,7 @@ function makeSession(candidate) {
             session.cancel();
             return;
         }
-        // Keep inspector keyboard authority out of the draft while allowing the
-        // browser to handle ordinary typing and caret movement natively. The
-        // listener is scoped to this host so it does not intercept native input
-        // before the contenteditable target sees it.
+        // Keep inspector shortcuts out of the draft while native typing and caret movement still run.
         event.stopPropagation();
     }
     function onBlur() {
@@ -604,8 +572,7 @@ function makeSession(candidate) {
         blurPending = true;
         if (composing)
             return;
-        // Deferring one macrotask lets Escape cancel a browser blur that occurs
-        // while a contenteditable host is handling the key event.
+        // Deferring one macrotask lets Escape cancel a blur that fires while the host handles the key event.
         blurCommitHandle = setTimeout(() => {
             blurCommitHandle = null;
             if (!finished) {
@@ -618,8 +585,7 @@ function makeSession(candidate) {
         if (finished)
             return;
         const rejectBeforeInput = (reason) => {
-            // Some browsers still deliver input after a non-cancelable beforeinput.
-            // Remember the safe plain draft so that onInput can undo that mutation.
+            // Some browsers still deliver input after a non-cancelable beforeinput; remember the safe draft so onInput can undo it.
             if (!event.cancelable)
                 rejectedNextInput = reason;
             if (event.cancelable)
@@ -737,9 +703,7 @@ function makeSession(candidate) {
         event.stopPropagation();
         if (blurPending && !finished) {
             blurPending = false;
-            // Browsers may dispatch the final insertCompositionText/input after
-            // compositionend. Commit on the next macrotask so those final chars are
-            // part of this one canonical edit.
+            // Browsers may dispatch the final composition input after compositionend; commit on the next macrotask to include it.
             compositionFinalizeHandle = setTimeout(() => {
                 compositionFinalizeHandle = null;
                 if (!finished && !composing)
@@ -752,16 +716,14 @@ function makeSession(candidate) {
             return;
         const selection = doc.getSelection?.();
         if (!selection || selection.rangeCount === 0) {
-            // A panel click can clear the page selection before blur; let blur own
-            // the normal commit path unless the editing host still owns focus.
+            // A panel click can clear the page selection before blur; let blur own the commit path unless the host still owns focus.
             if (doc.activeElement === host)
                 endLifecycle("selection-removed");
             return;
         }
         if (selection && selection.rangeCount > 0 && selectionInsideHost(host))
             return;
-        // A removed selection/host is a lifecycle end, not a text operation. The
-        // original node is restored only while its owning host is still connected.
+        // A removed selection/host is a lifecycle end, not a text operation.
         if (!host.isConnected || !candidate.element.isConnected) {
             endLifecycle(!host.isConnected ? "host-removed" : "selection-removed");
             return;
@@ -777,9 +739,7 @@ function makeSession(candidate) {
         if (!OwnerNode || !(target instanceof OwnerNode))
             return;
         if (host.contains(target)) {
-            // All down/up events must reach the native editing host so caret and
-            // drag-selection behavior remains intact. The click itself is held so
-            // the app cannot activate the surrounding button/link.
+            // Down/up events must reach the host so caret and drag-selection work; the click is held so the app cannot activate the surrounding button/link.
             if (event.type === "mousedown" || event.type === "mouseup"
                 || event.type === "pointerdown" || event.type === "pointerup")
                 return;
@@ -790,9 +750,7 @@ function makeSession(candidate) {
         const inspectorRoot = doc.getElementById("nudge-ui-root");
         if (inspectorRoot && (target === inspectorRoot || inspectorRoot.contains(target)))
             return;
-        // At the document boundary, application actions are suspended for the
-        // duration of the draft. Inspector controls live in the scoped shadow
-        // host above and remain usable.
+        // Outside the inspector root, application actions are suspended for the duration of the draft.
         if (event.type !== "mousedown" && event.type !== "mouseup"
             && event.type !== "pointerdown" && event.type !== "pointerup") {
             event.preventDefault();
@@ -800,9 +758,7 @@ function makeSession(candidate) {
         event.stopPropagation();
     }
     function suppressHostPointer(event) {
-        // Keep the native default (focus transfer, caret placement, and drag
-        // selection) while preventing an application ancestor from observing the
-        // temporary host's pointer sequence.
+        // Keep native defaults; only stop an application ancestor from observing the host's pointer sequence.
         event.stopPropagation();
     }
     function onFrameDisposed() {
@@ -849,9 +805,6 @@ function makeSession(candidate) {
             }
         }
         else if (host.isConnected) {
-            // A reconciliation can move the temporary host before removing the
-            // original root. It no longer has an owned insertion point, so remove
-            // the wrapper rather than leaking an editor into the new tree.
             host.remove();
         }
         finish(reason, "cancelled", discardedDraft, restoreFocus);
@@ -914,17 +867,14 @@ function makeSession(candidate) {
                 endLifecycle("app-reconciled", after);
                 return null;
             }
-            // Always remove the temporary host before appending the canonical
-            // change. The React Adapter must own the permanent preview.
+            // Remove the temporary host before appending the change: the React Adapter must own the permanent preview.
             const restoreFocus = editorOwnsFocus();
             if (!restoreDraft(candidate, host, candidate.before, ownership)) {
                 cancelForReconciliation();
                 return null;
             }
             if (change?.kind === "text-content" && editDecision.scope === "rendered-instance") {
-                // The second text value is alternate evidence for re-entry after a
-                // previous projection. Validation happens after unwrapping because a
-                // mounted draft can make another identical root look unique.
+                // candidate.before is alternate evidence for re-entry; validate after unwrapping, when a mounted draft can make another identical root look unique.
                 const resolved = resolveTextProjectionTarget(doc, change.target, candidate.before);
                 if (resolved.status !== "resolved") {
                     if (!resumeDraft(after))
@@ -1026,8 +976,7 @@ export const inlineTextEditor = {
         return makeSession(candidate);
     },
 };
-/** Re-enter an existing canonical rendered-text projection through its empty
- * inspector affordance. This never guesses a new DOM target or source node. */
+/** Re-enters an existing projection; never guesses a new DOM target or source node. */
 export function beginInlineTextEditFromEmptyProjection(marker) {
     if (!canEditDraft()) {
         return { kind: "rejected", reason: "editing-active", message: "Wait for the iteration to finish saving before editing text." };
@@ -1049,9 +998,7 @@ export function beginInlineTextEditFromEmptyProjection(marker) {
     const candidate = resolveEmptyProjectionCandidate(marker);
     if (isTextEditRejection(candidate))
         return recordTextEditRejection(marker, candidate);
-    // Hide the affordance while its retained empty Text node is wrapped by the
-    // native editor. The marker is restored on cancel and removed by projection
-    // reconciliation on a successful non-empty commit.
+    // Hide the affordance while the editor wraps its empty Text node; cancel restores it, a non-empty commit removes it via reconciliation.
     marker.hidden = true;
     try {
         return makeSession(candidate);

package/dist/inspector/inline-text/inlineTextLifecycle.js

@@ -1,9 +1,4 @@
-/**
- * A tiny lifecycle seam keeps canonical-history clearing independent from the
- * editor implementation. The editor registers its active-session disposer;
- * changesLog can then cancel it without importing the editor back through a
- * circular module edge.
- */
+// Keeps canonical-history clearing independent of the editor without importing it back through a circular edge.
 import { clearInlineTextDiagnostics } from "./inlineTextDiagnostics.js";
 let clearHandler = null;
 export function registerInlineTextClearHandler(handler) {

package/dist/inspector/inline-text/textEditChange.d.ts

@@ -1,7 +1,6 @@
 import type { TextBindingCandidate, TextEditBinding } from "../componentSemantics/textBinding.js";
 import type { ChangeRecord } from "../changes/types.js";
 import type { TextProjectionScope, TextProjectionTarget } from "../changes/editModel.js";
-/** Binding and scope decisions, independent of native editor lifecycle state. */
 export interface TextEditDecision {
     bindingIndex: number | null;
     scope: TextProjectionScope;

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

@@ -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

@@ -21,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" },
@@ -53,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;
@@ -82,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) => ({
@@ -118,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

@@ -6,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;
@@ -16,12 +15,7 @@ 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;
@@ -72,10 +66,9 @@ export interface BrowserCssInspection {
     };
     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

@@ -3,7 +3,7 @@ import { isNudgeUiDev } from "../runtime/devFlag.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,
@@ -138,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 ?? [])
@@ -217,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);
@@ -318,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/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

@@ -32,11 +32,7 @@ function inspectView(session, selected, state, includeDocumentTokens) {
         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;
@@ -83,10 +79,7 @@ export function useBrowserCssInspection(selected, state = "base", options = {})
     };
     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();
@@ -99,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(() => {
@@ -125,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)
@@ -143,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,3 +1,2 @@
 import type { CanvasFrame } from "../canvas/canvasFrame.js";
-/** Captures the visible DOM of a same-origin frame as a script-free HTML iteration. */
 export declare function captureHtmlIteration(frame: CanvasFrame): Promise<string>;