nudge-ui 0.2.5 → 0.2.6

package/dist/inspector/projection/textProjection.js

@@ -16,7 +16,6 @@ function hasOnlyKeys(value, allowed) {
 export const TEXT_PROJECTION_ATTR = "data-projection-text";
 /** Inspector-owned hit target for a projected text node whose value is empty. */
 export const EMPTY_TEXT_PROJECTION_ATTR = "data-empty-text";
-/** Inspector-owned exact-node evidence paired with EMPTY_TEXT_PROJECTION_ATTR. */
 export const EMPTY_TEXT_PROJECTION_PATH_ATTR = "data-empty-text-path";
 const UNSAFE_TEXT_TAGS = new Set(["SCRIPT", "STYLE", "TEXTAREA", "OPTION"]);
 const UNSAFE_MIXED_DESCENDANT_TAGS = new Set([
@@ -50,19 +49,14 @@ function isEmptyTextAffordance(node) {
 function hasInlineTextEditor(element) {
     return element.querySelector('[data-inline-editor="true"]') !== null;
 }
-/**
- * What the application last rendered into each projected Text node. A source
- * update can render the projected value itself, so restoring `before` would
- * overwrite real application output that the framework will not repaint.
- */
+/** A restore must not overwrite real application output that the framework will not repaint. */
 let applicationText = new WeakMap();
 function isInlineEditorNode(node) {
     return node.nodeType === 1 && (node.matches('[data-inline-editor="true"]')
         || hasInlineTextEditor(node));
 }
 function recordApplicationWrites(records) {
-    // The inline editor swaps its wrapper back for the original node, writing
-    // the draft, in one task. That write belongs to the editor.
+    // The inline editor writes the draft while swapping its wrapper back in the same task; that write belongs to the editor.
     if (records.some((record) => record.type === "childList"
         && [...record.addedNodes, ...record.removedNodes].some(isInlineEditorNode)))
         return;
@@ -167,8 +161,7 @@ function nodeAtPath(root, path) {
     }
     return current;
 }
-/** Find the exact text node represented by a target, tolerating a changed
- * child path only when one bounded before/after text node remains unique. */
+/** Tolerates a changed child path only when one before/after text node remains unique. */
 export function resolveTextProjectionTextNode(element, target, expectedText = target.beforeText) {
     if (target.textNodePath) {
         const atPath = nodeAtPath(element, target.textNodePath);
@@ -191,22 +184,17 @@ export function resolveTextProjectionTextNode(element, target, expectedText = ta
     }
     return matches.length === 1 ? matches[0] : null;
 }
-/** Whether an element's text is code, form state, or other non-prose content. */
 export function isUnsafeTextHost(element) {
     return UNSAFE_TEXT_TAGS.has(element.tagName);
 }
-/** Whether an application-owned editing region contains the element. */
 export function isInApplicationEditingHost(element) {
     const editingHost = element.closest("[contenteditable]");
     return Boolean(editingHost
         && editingHost.getAttribute("data-inline-editor") !== "true"
         && editingHost.getAttribute("contenteditable") !== "false");
 }
-/** Whether replacing one text node inside the element keeps its authored markup. */
 export function hasSafeMixedDescendants(element) {
-    // <br> only controls line layout. The projection targets one exact text
-    // node, so keeping the break while changing that node is safe; formatting
-    // descendants below still reject a flattening text projection.
+    // <br> only controls line layout, so it stays allowed; the projection targets one exact text node.
     for (const descendant of Array.from(element.querySelectorAll("*"))) {
         if (UNSAFE_MIXED_DESCENDANT_TAGS.has(descendant.tagName))
             return false;
@@ -228,9 +216,7 @@ function textHostIsSafe(element, allowEmpty = false, target) {
             && (allowEmpty || textNode.nodeValue?.length)
             && hasSafeMixedDescendants(element));
     }
-    // An empty-text affordance is inspector-owned and deliberately sits beside
-    // the retained empty Text node. Ignore it when proving that a direct leaf
-    // remains safe; otherwise the affordance would invalidate its own target.
+    // Ignore inspector-owned affordances here; otherwise the affordance would invalidate its own target.
     const applicationChildren = Array.from(element.children)
         .filter((child) => !isEmptyTextAffordance(child)
         && child.getAttribute("data-inline-editor") !== "true");
@@ -240,17 +226,10 @@ function textHostIsSafe(element, allowEmpty = false, target) {
     if (textNodes.length === 1) {
         return allowEmpty || Boolean(textNodes[0]?.nodeValue?.length);
     }
-    // The temporary inline editor wraps the retained direct Text node. Treat
-    // that inspector-owned wrapper as transparent while validating the
-    // canonical projection; otherwise its insertion would self-report as an
-    // application reconciliation and remove the re-entry slot mid-session.
+    // The inline editor's wrapper is inspector-owned; treating it as an application child would drop the re-entry slot.
     const editingHosts = Array.from(element.children)
         .filter((child) => child.getAttribute("data-inline-editor") === "true");
-    // The browser may split/replace the retained empty Text node while the
-    // native editor receives its first input. The wrapper is still inspector
-    // owned; its plain-text input guards are responsible for rejecting rich or
-    // paragraph edits, so validation must not cancel the session on that
-    // transient child shape.
+    // The browser may split the empty Text node on first input; that transient shape must not cancel the session.
     return editingHosts.length === 1;
 }
 function sourceCandidates(doc, sourceSite) {
@@ -274,7 +253,6 @@ function evidenceMatches(element, target, expectedText) {
                 && target.textNodePath === undefined
                 && (element.textContent ?? "") === ""));
 }
-/** Capture stable source/evidence identity without retaining a DOM reference. */
 export function captureTextProjectionTarget(element, beforeText = element.textContent ?? "", selectedTextNode) {
     if (!element.isConnected)
         return null;
@@ -306,11 +284,7 @@ export function captureTextProjectionTarget(element, beforeText = element.textCo
         ...pathTarget,
     };
 }
-/**
- * Resolve against source identity and bounded evidence. Occurrence is kept as
- * presentation metadata only and is never used to choose among identical
- * repeated outputs.
- */
+/** Occurrence is presentation metadata only; identical repeated outputs resolve as ambiguous. */
 export function resolveTextProjectionTarget(doc, target, afterText) {
     const candidates = sourceCandidates(doc, target.sourceSite);
     const evidence = candidates.filter((element) => evidenceMatches(element, target, target.beforeText)
@@ -355,9 +329,7 @@ function emptyTextAffordanceFor(doc, state, change, element) {
         return null;
     const parentElement = parent;
     const path = markerKey(change.target);
-    // During re-entry the temporary editor wraps the empty Text node. The
-    // existing slot remains beside that wrapper; search the whole projected
-    // root before creating another slot inside the editing host.
+    // Search the whole root before creating another slot; during re-entry the editor wrapper sits between the slot and the Text node.
     const existing = Array.from(element.querySelectorAll(`[${EMPTY_TEXT_PROJECTION_ATTR}]`))
         .find((child) => child.getAttribute(EMPTY_TEXT_PROJECTION_ATTR) === change.id
         && child.getAttribute(EMPTY_TEXT_PROJECTION_PATH_ATTR) === path);
@@ -373,18 +345,13 @@ function emptyTextAffordanceFor(doc, state, change, element) {
     affordance.setAttribute("role", "presentation");
     affordance.setAttribute("contenteditable", "false");
     affordance.tabIndex = -1;
-    // It has no application text and is never a source identity. The
-    // interaction stylesheet supplies its visible, borderless hit geometry.
+    // Never a source identity; the interaction stylesheet supplies its hit geometry.
     affordance.hidden = !isInteractionStylesInstalled(doc);
     parentElement.insertBefore(affordance, textNode.nextSibling);
     state.emptyAffordances.set(change.id, affordance);
     return affordance;
 }
-/**
- * Keep inspector-owned empty-text hit slots aligned with the canonical text
- * projection. Slots are colocated with the exact retained Text node, so they
- * do not replace application structure or alter the durable text path.
- */
+/** Slots are colocated with the retained Text node so they never alter the durable text path. */
 function syncEmptyTextAffordances(doc, state, changes) {
     const emptyChanges = new Map(changes.filter((change) => change.after.length === 0).map((change) => [change.id, change]));
     const seen = new Set();
@@ -422,7 +389,6 @@ function syncEmptyTextAffordances(doc, state, changes) {
         emptyTextAffordanceFor(doc, state, change, applied.element);
     }
 }
-/** Returns the canonical record represented by an inspector empty-text slot. */
 export function getTextContentChangeById(changeId) {
     return canonicalChanges.get(changeId) ?? null;
 }
@@ -458,9 +424,7 @@ function restoreAppliedProjection(state, applied) {
         return;
     if (!hasProjectionMarker(element, applied.change.target, applied.change.id))
         return;
-    // Never overwrite a newer application/reconciliation state during undo or
-    // clear. The marker, identity evidence, and projected value must all still
-    // belong to us; text alone is not proof after a source-site identity change.
+    // Only restore when the marker and identity evidence still match; text alone is not proof.
     if (!textProjectionIdentityMatches(element, applied.change))
         return;
     const textNode = resolveTextProjectionTextNode(element, applied.change.target, applied.change.after);
@@ -491,11 +455,7 @@ function validationStatus(applied) {
     const directEmpty = applied.change.target.textNodePath === undefined
         && applied.change.after.length === 0
         && (element.textContent ?? "") === "";
-    // While an empty projection is being reopened, the native editor owns a
-    // draft value that intentionally differs from the canonical empty value.
-    // Keep the projection applied until the editor restores its Text node and
-    // appends the next canonical snapshot; otherwise removing the slot changes
-    // the wrapper's ownership and cancels the draft mid-keystroke.
+    // While an empty projection is reopened the editor's draft intentionally differs; dropping it mid-keystroke would cancel the draft.
     const inlineDraft = hasInlineTextEditor(element);
     const identityValid = textProjectionIdentityMatches(element, applied.change);
     const safe = textHostIsSafe(element, applied.change.after.length === 0, applied.change.target);
@@ -504,12 +464,7 @@ function validationStatus(applied) {
     }
     return "applied";
 }
-/**
- * A controller can hydrate before a lazy route has mounted its tracked roots.
- * Keep a missing/ambiguous record pending and retry only when the document
- * mutates; an overridden projection remains authoritative and is never
- * re-applied.
- */
+/** Missing/ambiguous records stay pending until the document mutates; an overridden projection is never re-applied. */
 function resolvePendingProjection(doc, state, applied) {
     if (applied.status !== "missing" && applied.status !== "ambiguous") {
         return validationStatus(applied);
@@ -593,7 +548,6 @@ function getDocumentState(doc) {
     documentStates.set(doc, state);
     return state;
 }
-/** Apply one controller-owned text snapshot to a document adapter. */
 export function applyTextContentProjection(doc, changes) {
     if (!isNudgeUiDev())
         return [];
@@ -601,9 +555,7 @@ export function applyTextContentProjection(doc, changes) {
     setCanonicalTextContentChanges(changes);
     const key = JSON.stringify(changes);
     if (state.snapshotKey === key) {
-        // Reconciliation can happen between controller snapshots. Validate before
-        // reporting so a pending MutationObserver callback cannot leave a stale
-        // "applied" result visible to the Changes Log.
+        // Validate before reporting so a pending observer callback cannot leave a stale result in the Changes Log.
         validateAppliedProjection(doc, state);
         const reports = reportsForSnapshot(state, changes);
         storeReports(doc, reports);
@@ -612,10 +564,7 @@ export function applyTextContentProjection(doc, changes) {
     const previous = state.applied;
     const next = new Map();
     const incomingIds = new Set(changes.map((change) => change.id));
-    // Removing a canonical record is an explicit revert/clear. Restore only a
-    // marker/value still owned by that record; every surviving record keeps its
-    // current application status and must not be replayed merely because an
-    // unrelated change altered the shared snapshot.
+    // Removed records are an explicit revert; surviving records keep their status and must not be replayed because an unrelated change altered the snapshot.
     for (const [id, applied] of previous) {
         if (incomingIds.has(id))
             continue;
@@ -663,9 +612,7 @@ export function applyTextContentProjection(doc, changes) {
     }
     state.applied = next;
     syncEmptyTextAffordances(doc, state, changes);
-    // Drop markers that do not belong to the current controller snapshot. This
-    // also cleans a marker left by a previous runtime instance without touching
-    // a surviving overridden projection in `next`.
+    // Also cleans markers left by a previous runtime instance without touching a surviving overridden projection.
     for (const marker of Array.from(doc.querySelectorAll(`[${TEXT_PROJECTION_ATTR}]`))) {
         const markers = readProjectionMarkers(marker);
         for (const [key, id] of markers) {

package/dist/inspector/prompt/PromptSettingsDialog.d.ts

@@ -10,6 +10,5 @@ export interface PromptSettingsFieldsProps {
     onChange: (value: string) => void;
     instructionsRef?: RefObject<HTMLTextAreaElement | null>;
 }
-/** Edits the instructions appended to every generated prompt. */
 export declare function PromptSettingsFields({ value, onChange, instructionsRef, }: PromptSettingsFieldsProps): ReactElement;
 export declare function PromptSettingsDialog({ open, value, onChange, onOpenChange, }: PromptSettingsDialogProps): ReactElement;

package/dist/inspector/prompt/PromptSettingsDialog.js

@@ -3,7 +3,6 @@ import { useRef } from "react";
 import { Dialog } from "@base-ui/react/dialog";
 import { IconX } from "@tabler/icons-react";
 import { portalContainer } from "../ui/portalContainer.js";
-/** Edits the instructions appended to every generated prompt. */
 export function PromptSettingsFields({ value, onChange, instructionsRef, }) {
     return (_jsxs(_Fragment, { children: [_jsx("div", { className: "prompt-settings__field", children: _jsx("textarea", { ref: instructionsRef, id: "nudge-ui-custom-instructions", className: "prompt-settings__textarea", "data-test": "prompt-custom-instructions", "aria-label": "Custom instructions", rows: 6, value: value, onChange: (event) => onChange(event.currentTarget.value) }) }), _jsx("div", { className: "prompt-settings__actions", children: _jsx(Dialog.Close, { className: "button button--primary", "data-test": "prompt-settings-done", type: "button", children: "Done" }) })] }));
 }

package/dist/inspector/prompt/clipboardHandoff.d.ts

@@ -27,14 +27,6 @@ export declare function getClipboardHandoffRecords(draftId: string): {
     structuralChanges: StructuralChange[];
 };
 export declare function reconcileClipboardHandoff(doc?: Document): Promise<number>;
-/**
- * Verifies copied edits after the document changes. Each check briefly removes
- * the copied preview, so a check that reconciles nothing doubles the minimum
- * interval before the next one: a page that mutates continuously (clocks,
- * carousels) would otherwise flash the preview every few hundred milliseconds.
- * Later changes never postpone a pending check, so a busy page is still
- * checked once per interval. Returning to the page or copying a new prompt
- * resets the interval.
- */
+/** A check briefly removes the copied preview, so reconciling nothing doubles the interval to avoid flashing on continuously mutating pages. */
 export declare function startClipboardHandoffController(doc?: Document): () => void;
 export {};

package/dist/inspector/prompt/clipboardHandoff.js

@@ -126,15 +126,7 @@ export async function reconcileClipboardHandoff(doc = document) {
 }
 const CHECK_DELAY_MS = 450;
 const MAX_CHECK_DELAY_MS = 8_000;
-/**
- * Verifies copied edits after the document changes. Each check briefly removes
- * the copied preview, so a check that reconciles nothing doubles the minimum
- * interval before the next one: a page that mutates continuously (clocks,
- * carousels) would otherwise flash the preview every few hundred milliseconds.
- * Later changes never postpone a pending check, so a busy page is still
- * checked once per interval. Returning to the page or copying a new prompt
- * resets the interval.
- */
+/** A check briefly removes the copied preview, so reconciling nothing doubles the interval to avoid flashing on continuously mutating pages. */
 export function startClipboardHandoffController(doc = document) {
     const view = doc.defaultView;
     let timer = null;

package/dist/inspector/prompt/generatePrompt.d.ts

@@ -6,6 +6,6 @@ export interface FrameworkHints {
     framework?: string;
     stylingSystem?: string;
 }
-/** Counts the final edit intents exported by the prompt, preserving gesture history for undo. */
+/** Counts the exported intents, not the raw gesture history. */
 export declare function countPromptChanges(changes: readonly ChangeRecord[], structuralChanges?: readonly StructuralChange[], sketchCount?: number): number;
 export declare function generatePrompt(changes: ChangeRecord[], frameworkHints?: FrameworkHints, structuralChanges?: readonly StructuralChange[], customInstructions?: string, sketches?: readonly AgentSketchMetadata[], comments?: readonly ElementComment[]): string;

package/dist/inspector/prompt/generatePrompt.js

@@ -11,11 +11,11 @@ const EMPTY_SENTINEL = "<!-- No changes to export -->\n\nThe changes log is empt
 /** Labels describe the observed tag, without guessing its role in the page. */
 function elementLabel(tag) {
     const normalized = normalizeRuntimeTag(tag);
-    const labels = {
-        p: "Paragraph", button: "Button", a: "Link", img: "Image", input: "Input",
-        textarea: "Text area", select: "Select", form: "Form", nav: "Navigation", section: "Section",
-    };
-    const label = /^h[1-6]$/.test(normalized) ? "Heading" : labels[normalized] ?? "Element";
+    const labels = new Map([
+        ["p", "Paragraph"], ["button", "Button"], ["a", "Link"], ["img", "Image"], ["input", "Input"],
+        ["textarea", "Text area"], ["select", "Select"], ["form", "Form"], ["nav", "Navigation"], ["section", "Section"],
+    ]);
+    const label = /^h[1-6]$/.test(normalized) ? "Heading" : labels.get(normalized) ?? "Element";
     return normalized ? `${label} (${promptText(`<${normalized}>`)})` : label;
 }
 /** Runtime IDs identify one DOM element; authored sites can render several items. */
@@ -86,9 +86,7 @@ function elementChangeLine(rec) {
     }
     if (rec.newToken) {
         const before = rec.oldRawValue !== undefined ? `\`${rec.oldRawValue}\` → ` : "";
-        // Describe exactly the value the managed stylesheet wrote for this swap
-        // (adapter literal or var(cssName)); a bare var(name) would be invalid
-        // CSS for adapter tokens whose names are not custom-property names.
+        // Adapter token names are not always custom-property names, so emit the literal the stylesheet wrote.
         return `- **Change:** ${property}: ${before}\`${tokenReference(rec.newToken)}\``;
     }
     if (rec.rawValue !== undefined) {
@@ -221,12 +219,7 @@ function selectedItemLine(group, sourceLocation) {
 function setHeading(label, tag) {
     return tag ? `${label} (${promptText(`<${normalizeRuntimeTag(tag)}>`)})` : label;
 }
-/**
- * Coordinate precision follows each element's identity origin, not the
- * document's framework hint (ADR-0011 Stage 5). The active host Adapter
- * declares which origins carry exact authored coordinates through the
- * runtime configuration; hosts that declare nothing are exact everywhere.
- */
+/** Precision follows each element's identity origin, not the framework hint; hosts that declare nothing are exact everywhere. */
 function hasExactAuthoredCoordinates(policy, cid, file) {
     if (policy === null)
         return true;
@@ -235,11 +228,6 @@ function hasExactAuthoredCoordinates(policy, cid, file) {
     }
     return policy.exactFileExtensions.some((extension) => file.endsWith(extension));
 }
-/**
- * Formats one source location for a prompt. Exact origins keep the
- * authored column; line-only origins — and sites whose column is unknown —
- * degrade to `file:line` rather than fabricating precision.
- */
 function formatSourceLocation(policy, source) {
     if (hasExactAuthoredCoordinates(policy, source.cid, source.file) && source.column > 0) {
         return `${source.file}:${source.line}:${source.column}`;
@@ -259,8 +247,7 @@ function renderedInstanceDescription(ref) {
         return `the element named ${promptText(ariaLabel)}${source}`;
     if (props)
         return `the element with props ${promptText(props)}${source}`;
-    // With no semantic evidence, the ordinal is the only way to distinguish
-    // repeated outputs from the same source site.
+    // Without semantic evidence, the ordinal is the only way to distinguish repeated outputs from one source site.
     return `rendered instance ${ref.locator.occurrence + 1} of ${sourceSiteLabel(ref)}`;
 }
 function structuralChangeLine(change) {
@@ -324,9 +311,7 @@ function canonicalizeStructuralChanges(changes) {
             && first.presentation.fromIndex === latest.presentation.toIndex;
         if (returnedToStart)
             continue;
-        // The final destination is the useful handoff. Keep the first source
-        // context when the gesture crossed intermediate containers so the prompt
-        // describes the authored move rather than the drag history.
+        // Keep the first source context so the prompt describes the authored move, not the drag history.
         if (first && first !== latest && latest.kind === "move") {
             canonical.push({
                 ...latest,
@@ -344,7 +329,7 @@ function canonicalizeStructuralChanges(changes) {
     }
     return canonical;
 }
-/** Counts the final edit intents exported by the prompt, preserving gesture history for undo. */
+/** Counts the exported intents, not the raw gesture history. */
 export function countPromptChanges(changes, structuralChanges = [], sketchCount = 0) {
     return canonicalizeChanges([...changes]).length + canonicalizeStructuralChanges(structuralChanges).length + sketchCount;
 }

package/dist/inspector/prompt/promptSettings.d.ts

@@ -1,8 +1,5 @@
-/** The default guidance included in every generated prompt. */
 export declare const DEFAULT_CUSTOM_INSTRUCTIONS = "Preserve existing tokens, logical properties, and CSS intent while applying these rendered changes.";
 declare function storageKey(projectId: string): string;
-/** Reads the project-scoped custom prompt instructions from browser storage. */
 export declare function loadCustomInstructions(projectId: string): string;
-/** Persists custom prompt instructions without making storage availability a prerequisite for editing. */
 export declare function saveCustomInstructions(projectId: string, instructions: string): void;
 export { storageKey as promptSettingsStorageKey };

package/dist/inspector/prompt/promptSettings.js

@@ -1,11 +1,9 @@
 import { inspectorStorage } from "../runtime/inspectorStorage.js";
 import { isDemoRuntime } from "../runtime/runtimeConfig.js";
-/** The default guidance included in every generated prompt. */
 export const DEFAULT_CUSTOM_INSTRUCTIONS = "Preserve existing tokens, logical properties, and CSS intent while applying these rendered changes.";
 function storageKey(projectId) {
     return `nudge-ui:${projectId}:prompt-settings`;
 }
-/** Reads the project-scoped custom prompt instructions from browser storage. */
 export function loadCustomInstructions(projectId) {
     if (isDemoRuntime())
         return DEFAULT_CUSTOM_INSTRUCTIONS;
@@ -16,7 +14,6 @@ export function loadCustomInstructions(projectId) {
         return DEFAULT_CUSTOM_INSTRUCTIONS;
     }
 }
-/** Persists custom prompt instructions without making storage availability a prerequisite for editing. */
 export function saveCustomInstructions(projectId, instructions) {
     if (isDemoRuntime())
         return; // demo runtimes never persist

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

@@ -1,28 +1,5 @@
-/**
- * Decides the shared dev gate from one bundler observation and one host
- * observation. Pure so every precedence rule is unit-testable without a
- * particular bundler present.
- *
- * Precedence: an explicit host flag wins (a compiler without a define must
- * still be authoritative); otherwise the bundler define decides; with neither,
- * development is assumed absent — the gate fails closed rather than guessing.
- */
+/** An explicit host flag wins; otherwise the bundler define; neither means not-development. */
 export declare function resolveNudgeUiDev(bundlerDefinedDev: boolean | undefined, hostFlag: boolean | undefined): boolean;
-/**
- * Records whether the host Adapter is running a development server (ADR-0002).
- *
- * Vite and the standalone esbuild pipeline statically replace
- * `import.meta.env.DEV`, so their bundles need no runtime flag. Hosts whose
- * compiler cannot supply that define — Next.js/SWC has no equivalent of Vite's
- * `define` for `import.meta.env` — must call this before bootstrapping the
- * inspector. Passing `undefined` clears the override and restores the static
- * define as the sole authority.
- *
- * The flag is process-global state by design: every inspector Module shares
- * one dev gate, and a host configures it once per document, not per Module.
- */
+/** For hosts whose compiler cannot supply the bundler define (Next.js/SWC); call before bootstrapping, `undefined` clears it. */
 export declare function setNudgeUiHostDevFlag(value: boolean | undefined): void;
-/**
- * Dev-phase gate shared by every inspector Module (ADR-0002).
- */
 export declare function isNudgeUiDev(): boolean;

package/dist/inspector/runtime/devFlag.js

@@ -1,12 +1,4 @@
-/**
- * Decides the shared dev gate from one bundler observation and one host
- * observation. Pure so every precedence rule is unit-testable without a
- * particular bundler present.
- *
- * Precedence: an explicit host flag wins (a compiler without a define must
- * still be authoritative); otherwise the bundler define decides; with neither,
- * development is assumed absent — the gate fails closed rather than guessing.
- */
+/** An explicit host flag wins; otherwise the bundler define; neither means not-development. */
 export function resolveNudgeUiDev(bundlerDefinedDev, hostFlag) {
     if (hostFlag !== undefined)
         return hostFlag;
@@ -15,33 +7,14 @@ export function resolveNudgeUiDev(bundlerDefinedDev, hostFlag) {
     return false;
 }
 let hostDevFlag;
-/**
- * Records whether the host Adapter is running a development server (ADR-0002).
- *
- * Vite and the standalone esbuild pipeline statically replace
- * `import.meta.env.DEV`, so their bundles need no runtime flag. Hosts whose
- * compiler cannot supply that define — Next.js/SWC has no equivalent of Vite's
- * `define` for `import.meta.env` — must call this before bootstrapping the
- * inspector. Passing `undefined` clears the override and restores the static
- * define as the sole authority.
- *
- * The flag is process-global state by design: every inspector Module shares
- * one dev gate, and a host configures it once per document, not per Module.
- */
+/** For hosts whose compiler cannot supply the bundler define (Next.js/SWC); call before bootstrapping, `undefined` clears it. */
 export function setNudgeUiHostDevFlag(value) {
     hostDevFlag = value;
 }
-/**
- * Dev-phase gate shared by every inspector Module (ADR-0002).
- */
 export function isNudgeUiDev() {
     try {
-        // Under Vite (and the standalone esbuild build) this member expression is
-        // statically replaced, so the read cannot throw there. In a bundle whose
-        // compiler defines nothing — Next.js/SWC — `import.meta.env` is undefined
-        // and the bare property read throws a TypeError. A build-mode name (such
-        // as the landing demo's `nudge-demo`) must never widen this gate; the
-        // demo runtime opens it for its own document instead (ADR-0014).
+        // Statically replaced under Vite; where nothing defines it (Next.js/SWC)
+        // this read throws and the catch fails closed.
         return resolveNudgeUiDev(import.meta.env.DEV === true, hostDevFlag);
     }
     catch {

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

@@ -1,6 +1,5 @@
 import type { TokenCatalogDiagnostic, TokenDefinition } from "../../css/model/index.js";
 import type { NudgeUiRuntimeConfig } from "./runtimeConfig.js";
-/** Evidence collected from the browser's current stylesheet order. */
 export interface DocumentStylesheetOrderEvidence {
     readonly projectPaths: readonly string[];
     /** False when a sheet is cross-origin, inline, unloaded, or duplicated. */
@@ -8,7 +7,6 @@ export interface DocumentStylesheetOrderEvidence {
 }
 /** Reads same-origin stylesheet order without making directory order authoritative. */
 export declare function collectDocumentStylesheetOrder(document: Document): DocumentStylesheetOrderEvidence;
-/** Token catalog plus diagnostics produced by document-order reconciliation. */
 export interface DocumentTokenCatalogReconciliation {
     readonly catalog: readonly TokenDefinition[];
     readonly diagnostics: readonly TokenCatalogDiagnostic[];

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

@@ -1,2 +1 @@
-/** Returns whether a document is the application-free editor controller. */
 export declare function isEditorShellDocument(doc?: Document): boolean;

package/dist/inspector/runtime/editorShell.js

@@ -1,4 +1,3 @@
-/** Returns whether a document is the application-free editor controller. */
 export function isEditorShellDocument(doc = document) {
     return doc.documentElement.hasAttribute("data-nudge-ui-editor");
 }

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

@@ -1,4 +1,3 @@
-/** The synchronous subset of `Storage` that inspector persistence uses. */
 export interface InspectorStorage {
     getItem(key: string): string | null;
     setItem(key: string, value: string): void;
@@ -6,12 +5,7 @@ export interface InspectorStorage {
     /** Reloads an asynchronous backend under the lease, before controller hydration. */
     refresh?(): Promise<void>;
 }
-/** Replaces `localStorage` for inspector-owned state, for example with extension storage. */
 export declare function configureInspectorStorage(storage: InspectorStorage | null): void;
-/** The configured storage, else `localStorage`; null where neither exists. */
 export declare function inspectorStorage(): InspectorStorage | null;
-/**
- * Serves reads from a snapshot loaded before boot and forwards each write.
- * Asynchronous backends stay behind the synchronous interface callers expect.
- */
+/** Keeps an asynchronous backend behind the synchronous interface callers expect. */
 export declare function createMirroredStorage(initial: Readonly<Record<string, string>>, persist: (key: string, value: string | null) => void, read?: () => Promise<Readonly<Record<string, string>>>): InspectorStorage;

package/dist/inspector/runtime/inspectorStorage.js

@@ -1,18 +1,13 @@
 let configured = null;
-/** Replaces `localStorage` for inspector-owned state, for example with extension storage. */
 export function configureInspectorStorage(storage) {
     configured = storage;
 }
-/** The configured storage, else `localStorage`; null where neither exists. */
 export function inspectorStorage() {
     if (configured)
         return configured;
     return typeof localStorage === "undefined" ? null : localStorage;
 }
-/**
- * Serves reads from a snapshot loaded before boot and forwards each write.
- * Asynchronous backends stay behind the synchronous interface callers expect.
- */
+/** Keeps an asynchronous backend behind the synchronous interface callers expect. */
 export function createMirroredStorage(initial, persist, read) {
     const values = new Map(Object.entries(initial));
     let refreshId = 0;

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

@@ -1,15 +1,9 @@
 type StyleRoot = Document | ShadowRoot;
 /** Transient visual state projection, excluded from authored CSS inspection. */
 export declare const STATE_PREVIEW_SHEET_ID = "nudge-ui-state-preview";
-/**
- * Uses constructable stylesheets everywhere without probing the page policy.
- * A blocked probe logs a violation and can send one to the site's CSP report endpoint.
- */
+/** Skips the style-element probe because a blocked probe can log a violation to the site's CSP report endpoint. */
 export declare function preferAdoptedStylesheets(): void;
-/**
- * A strict `style-src` policy blocks `<style>` elements, leaving them without
- * a sheet, but not constructable stylesheets. Checked once per document.
- */
+/** A strict `style-src` blocks `<style>` elements but not constructable stylesheets; checked once per document. */
 export declare function allowsStyleElements(doc: Document): boolean;
 /** Creates or replaces the adopted sheet stored under `key`, after the root's own stylesheets. */
 export declare function adoptStylesheet(root: StyleRoot, key: string, cssText: string): CSSStyleSheet | null;

package/dist/inspector/runtime/ownedStylesheets.js

@@ -3,17 +3,11 @@ export const STATE_PREVIEW_SHEET_ID = "nudge-ui-state-preview";
 const styleElementSupport = new WeakMap();
 const adoptedSheets = new WeakMap();
 let adoptedOnly = false;
-/**
- * Uses constructable stylesheets everywhere without probing the page policy.
- * A blocked probe logs a violation and can send one to the site's CSP report endpoint.
- */
+/** Skips the style-element probe because a blocked probe can log a violation to the site's CSP report endpoint. */
 export function preferAdoptedStylesheets() {
     adoptedOnly = true;
 }
-/**
- * A strict `style-src` policy blocks `<style>` elements, leaving them without
- * a sheet, but not constructable stylesheets. Checked once per document.
- */
+/** A strict `style-src` blocks `<style>` elements but not constructable stylesheets; checked once per document. */
 export function allowsStyleElements(doc) {
     if (adoptedOnly)
         return false;