nudge-ui 0.2.4 → 0.2.6

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

@@ -0,0 +1,11 @@
+export interface InspectorStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    /** Reloads an asynchronous backend under the lease, before controller hydration. */
+    refresh?(): Promise<void>;
+}
+export declare function configureInspectorStorage(storage: InspectorStorage | null): void;
+export declare function inspectorStorage(): InspectorStorage | null;
+/** 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

@@ -0,0 +1,37 @@
+let configured = null;
+export function configureInspectorStorage(storage) {
+    configured = storage;
+}
+export function inspectorStorage() {
+    if (configured)
+        return configured;
+    return typeof localStorage === "undefined" ? null : localStorage;
+}
+/** 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;
+    return {
+        getItem: (key) => values.get(key) ?? null,
+        setItem(key, value) {
+            values.set(key, value);
+            persist(key, value);
+        },
+        removeItem(key) {
+            if (!values.delete(key))
+                return;
+            persist(key, null);
+        },
+        ...(read ? {
+            async refresh() {
+                const id = ++refreshId;
+                const snapshot = await read();
+                if (id !== refreshId)
+                    return;
+                values.clear();
+                for (const [key, value] of Object.entries(snapshot))
+                    values.set(key, value);
+            },
+        } : {}),
+    };
+}

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

@@ -0,0 +1,14 @@
+type StyleRoot = Document | ShadowRoot;
+/** Transient visual state projection, excluded from authored CSS inspection. */
+export declare const STATE_PREVIEW_SHEET_ID = "nudge-ui-state-preview";
+/** 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` 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;
+/** The key a sheet was adopted under, or null for sheets the page adopted itself. */
+export declare function adoptedStylesheetKey(root: StyleRoot, sheet: CSSStyleSheet): string | null;
+export declare function getAdoptedStylesheet(root: StyleRoot, key: string): CSSStyleSheet | null;
+export declare function releaseAdoptedStylesheet(root: StyleRoot, key: string): void;
+export {};

package/dist/inspector/runtime/ownedStylesheets.js

@@ -0,0 +1,66 @@
+/** Transient visual state projection, excluded from authored CSS inspection. */
+export const STATE_PREVIEW_SHEET_ID = "nudge-ui-state-preview";
+const styleElementSupport = new WeakMap();
+const adoptedSheets = new WeakMap();
+let adoptedOnly = false;
+/** 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` blocks `<style>` elements but not constructable stylesheets; checked once per document. */
+export function allowsStyleElements(doc) {
+    if (adoptedOnly)
+        return false;
+    const known = styleElementSupport.get(doc);
+    if (known !== undefined)
+        return known;
+    const probe = doc.createElement("style");
+    probe.setAttribute("data-nudge-ui", "style-policy-probe");
+    probe.textContent = ":root {}";
+    (doc.head ?? doc.documentElement).appendChild(probe);
+    const allowed = probe.sheet !== null;
+    probe.remove();
+    styleElementSupport.set(doc, allowed);
+    return allowed;
+}
+function ownerDocumentOf(root) {
+    return root.nodeType === Node.DOCUMENT_NODE ? root : root.ownerDocument;
+}
+/** Creates or replaces the adopted sheet stored under `key`, after the root's own stylesheets. */
+export function adoptStylesheet(root, key, cssText) {
+    const view = ownerDocumentOf(root).defaultView;
+    if (!view)
+        return null;
+    let sheets = adoptedSheets.get(root);
+    if (!sheets) {
+        sheets = new Map();
+        adoptedSheets.set(root, sheets);
+    }
+    let sheet = sheets.get(key);
+    if (!sheet) {
+        sheet = new view.CSSStyleSheet();
+        sheets.set(key, sheet);
+    }
+    sheet.replaceSync(cssText);
+    if (!root.adoptedStyleSheets.includes(sheet))
+        root.adoptedStyleSheets = [...root.adoptedStyleSheets, sheet];
+    return sheet;
+}
+/** The key a sheet was adopted under, or null for sheets the page adopted itself. */
+export function adoptedStylesheetKey(root, sheet) {
+    for (const [key, candidate] of adoptedSheets.get(root) ?? []) {
+        if (candidate === sheet)
+            return key;
+    }
+    return null;
+}
+export function getAdoptedStylesheet(root, key) {
+    return adoptedSheets.get(root)?.get(key) ?? null;
+}
+export function releaseAdoptedStylesheet(root, key) {
+    const sheet = adoptedSheets.get(root)?.get(key);
+    if (!sheet)
+        return;
+    adoptedSheets.get(root)?.delete(key);
+    root.adoptedStyleSheets = root.adoptedStyleSheets.filter((candidate) => candidate !== sheet);
+}

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

@@ -1,132 +1,62 @@
 import type { TokenCatalogDiagnostic, TokenDefinition, TokenEntry } from "../../css/model/index.js";
 import type { ComponentContract } from "../componentSemantics/types.js";
-/** The host Adapter that supplied the active inspector runtime. */
 export type NudgeUiRuntimeHost = "vite-react" | "static-html" | "nextjs-react" | "astro";
-/** The framework semantics enabled for the active inspector runtime. */
 export type NudgeUiRuntimeFramework = "React" | "HTML" | "Astro";
-/**
- * Which identity origins carry exact authored coordinates in prompts
- * (ADR-0011 Stage 5).
- *
- * A host whose pipeline captures `data-src` positions from anything other
- * than the authored source declares the exact subset. Hosts that omit the
- * policy state that every source site is exact.
- */
 export interface SourceCoordinatePolicy {
     /** Cid prefixes whose `data-src` line:column point at authored source. */
     readonly exactCidPrefixes: readonly string[];
     /** File extensions whose `data-src` line:column point at authored source. */
     readonly exactFileExtensions: readonly string[];
 }
-/** Capabilities exposed by the active host Adapter. */
 export interface NudgeUiRuntimeCapabilities {
-    /** Whether the multi-page Canvas workspace is available. */
     readonly canvas: boolean;
-    /** Whether framework component inspection and prop overrides are available. */
     readonly componentSemantics: boolean;
-    /** Whether the DOM navigator overlay is available. */
     readonly domNavigation?: boolean;
-    /**
-     * Source-coordinate precision policy for prompts; every source site is
-     * exact when the host omits it.
-     */
+    /** Precision policy for prompt source coordinates; every source site is exact when omitted. */
     readonly sourceCoordinates?: SourceCoordinatePolicy;
-    /**
-     * Regex source matching this host's structural scoping markers, stripped
-     * from human-facing selector labels (ADR-0011). The raw selector stays in
-     * change records so managed-rule targeting keeps matching the rendered
-     * DOM. No stripping when the host omits it.
-     */
+    /** Regex for this host's scoping markers; stripped from selector labels, kept in change records. Omitted means no stripping. */
     readonly scopingSelectorPattern?: string;
 }
-/** Product features that a host can selectively expose in its inspector UI. */
 export interface NudgeUiRuntimeFeatures {
-    /** Whether Canvas can create filesystem-backed HTML iterations. */
+    readonly sketch?: boolean;
     readonly canvasIterations?: boolean;
+    /** The MCP settings section; hosts that cannot reach an MCP server turn it off. */
+    readonly mcp?: boolean;
 }
-/**
- * Browser knowledge supplied by a host Adapter before the inspector mounts.
- *
- * A host replaces the complete configuration when its document is replaced or
- * its development transport is refreshed. Shared inspector Modules read the
- * current snapshot through `getNudgeUiRuntimeConfig()` and never import a
- * host-specific transport directly.
- */
 export interface NudgeUiRuntimeConfig {
     readonly projectId: string;
     readonly host: NudgeUiRuntimeHost;
     readonly framework: NudgeUiRuntimeFramework;
     readonly stylingSystem: string;
     readonly capabilities: NudgeUiRuntimeCapabilities;
-    /** Product-level feature switches; omitted features remain enabled. */
+    /** Omitted features remain enabled. */
     readonly features?: NudgeUiRuntimeFeatures;
     readonly tokenCatalog: readonly TokenDefinition[];
     readonly tokens: readonly TokenEntry[];
     readonly tokenDiagnostics: readonly TokenCatalogDiagnostic[];
     readonly tokenGeneration: string;
     readonly componentContracts: readonly ComponentContract[];
-    /** Whether this runtime is the explicit public landing-page demo. */
+    /** Replaces the selection empty state when the page cannot be inspected. */
+    readonly inspectionUnavailableReason?: string;
     readonly demo?: boolean;
-    /** Additional same-origin pages seeded into the public demo canvas. */
+    /** Additional same-origin pages seeded into the demo canvas. */
     readonly demoPages?: readonly string[];
-    /** Labels for demo cards in display order, including the primary card. */
+    /** In display order, including the primary card. */
     readonly demoCardLabels?: readonly string[];
 }
-/**
- * Validates a host-supplied configuration and fills safe defaults.
- *
- * `projectId`, `host`, and `framework` are required identity fields; wrong
- * types or values fail fast at the host seam instead of leaking `undefined`
- * into storage keys or capability checks. Token arrays, the styling-system
- * label, generation string, and capabilities are optional and default to
- * empty/false values so a minimal host still bootstraps honestly.
- *
- * @param input The configuration supplied by a host Adapter.
- * @returns A complete plain-data configuration ready to snapshot.
- */
+/** Throws TypeError on invalid input; optional fields receive safe defaults. */
 export declare function normalizeNudgeUiRuntimeConfig(input: unknown): NudgeUiRuntimeConfig;
-/**
- * Replaces the complete runtime configuration for the active document.
- *
- * The input is validated and incomplete optional fields receive safe defaults
- * (see `normalizeNudgeUiRuntimeConfig`). Replacement is atomic from the
- * inspector's perspective. The returned snapshot owns recursively cloned and
- * frozen plain data, so a host can safely replace its virtual module values
- * during HMR without leaving shared Modules bound to an old transport object
- * or freezing caller-owned values.
- */
 export declare function configureNudgeUiRuntime(config: NudgeUiRuntimeConfig): void;
-/** Returns the immutable runtime snapshot used by shared inspector Modules. */
 export declare function getNudgeUiRuntimeConfig(): NudgeUiRuntimeConfig;
-/** Returns whether a product feature is enabled; omitted flags default to enabled. */
 export declare function isNudgeUiFeatureEnabled(features: NudgeUiRuntimeFeatures | undefined, feature: keyof NudgeUiRuntimeFeatures): boolean;
-/**
- * Whether this document runs the explicit public landing demo (ADR-0014 and
- * ADR-0016). The plugin emits `demo: true` for the flagged demo route and for
- * the explicit landing root in development and `nudge-demo` builds, so this is
- * the precise runtime boundary of the demo — narrower than any build-mode
- * name.
- */
+/** The demo boundary is this flag, never a build-mode name. */
 export declare function isDemoRuntime(): boolean;
-/**
- * Returns the active host's source-coordinate policy, or null when the host
- * declares none — every source site is exact in that case.
- */
 export declare function getSourceCoordinatePolicy(): SourceCoordinatePolicy | null;
-/**
- * Returns the active host's structural scoping-marker pattern compiled for
- * global replacement, or null when the host declares none. An invalid regex
- * source degrades to no stripping rather than breaking labeling.
- */
+/** Null when the host declares none; an invalid pattern degrades to no stripping. */
 export declare function getScopingSelectorPattern(): RegExp | null;
-/**
- * Subscribes to complete runtime replacements, such as Vite HMR updates.
- * Listeners run after the new snapshot is installed.
- */
+/** Listeners run after the new snapshot is installed. */
 export declare function subscribeNudgeUiRuntime(listener: () => void): () => void;
-/** Returns the styling-system label represented by a token inventory. */
 export declare function detectStylingSystem(tokens: readonly TokenEntry[]): string;
-/** Returns a mutable container for UI controls that require array props. */
 export declare function getNudgeUiTokenEntries(): TokenEntry[];
 export type { TokenCatalogDiagnostic, TokenDefinition, TokenEntry } from "../../css/model/index.js";
 export type { ComponentContract } from "../componentSemantics/types.js";

package/dist/inspector/runtime/runtimeConfig.js

@@ -5,9 +5,8 @@ function cloneAndFreeze(value, seen = new WeakMap()) {
     const existing = seen.get(source);
     if (existing)
         return existing;
-    // An already-frozen subtree is immutable, so it can be reused by reference.
-    // Repeated configuration with the same frozen payload (HMR re-runs, stub
-    // spread patterns) keeps array identity stable for identity-keyed caches.
+    // Frozen subtrees are reused by reference so repeated configuration with the
+    // same frozen payload keeps array identity for identity-keyed caches.
     if (Object.isFrozen(value)) {
         seen.set(source, value);
         return value;
@@ -157,8 +156,16 @@ function normalizeFeatures(input) {
     if (!isPlainRecord(input)) {
         throw new TypeError('Nudge UI runtime configuration field "features" must be an object.');
     }
+    const sketch = optionalFeatureBoolean(input, "sketch");
     const canvasIterations = optionalFeatureBoolean(input, "canvasIterations");
-    return canvasIterations === undefined ? {} : { canvasIterations };
+    const mcp = optionalFeatureBoolean(input, "mcp");
+    if (sketch === undefined && canvasIterations === undefined && mcp === undefined)
+        return {};
+    return {
+        ...(sketch === undefined ? {} : { sketch }),
+        ...(canvasIterations === undefined ? {} : { canvasIterations }),
+        ...(mcp === undefined ? {} : { mcp }),
+    };
 }
 function optionalDemoFlag(input) {
     const value = input.demo;
@@ -169,18 +176,7 @@ function optionalDemoFlag(input) {
     }
     return true;
 }
-/**
- * Validates a host-supplied configuration and fills safe defaults.
- *
- * `projectId`, `host`, and `framework` are required identity fields; wrong
- * types or values fail fast at the host seam instead of leaking `undefined`
- * into storage keys or capability checks. Token arrays, the styling-system
- * label, generation string, and capabilities are optional and default to
- * empty/false values so a minimal host still bootstraps honestly.
- *
- * @param input The configuration supplied by a host Adapter.
- * @returns A complete plain-data configuration ready to snapshot.
- */
+/** Throws TypeError on invalid input; optional fields receive safe defaults. */
 export function normalizeNudgeUiRuntimeConfig(input) {
     if (!isPlainRecord(input)) {
         throw new TypeError("Nudge UI runtime configuration must be an object.");
@@ -203,6 +199,9 @@ export function normalizeNudgeUiRuntimeConfig(input) {
         tokenDiagnostics: optionalArray(input, "tokenDiagnostics"),
         tokenGeneration: optionalString(input, "tokenGeneration"),
         componentContracts: optionalArray(input, "componentContracts"),
+        ...(input.inspectionUnavailableReason === undefined ? {} : {
+            inspectionUnavailableReason: optionalNonEmptyString(input, "inspectionUnavailableReason"),
+        }),
         ...(demo === true ? { demo: true } : {}),
         ...(demoPages === undefined ? {} : { demoPages }),
         ...(demoCardLabels === undefined ? {} : { demoCardLabels }),
@@ -212,16 +211,6 @@ export function normalizeNudgeUiRuntimeConfig(input) {
 }
 let activeRuntimeConfig = DEFAULT_RUNTIME_CONFIG;
 const runtimeListeners = new Set();
-/**
- * Replaces the complete runtime configuration for the active document.
- *
- * The input is validated and incomplete optional fields receive safe defaults
- * (see `normalizeNudgeUiRuntimeConfig`). Replacement is atomic from the
- * inspector's perspective. The returned snapshot owns recursively cloned and
- * frozen plain data, so a host can safely replace its virtual module values
- * during HMR without leaving shared Modules bound to an old transport object
- * or freezing caller-owned values.
- */
 export function configureNudgeUiRuntime(config) {
     activeRuntimeConfig = normalizeNudgeUiRuntimeConfig(config);
     for (const listener of runtimeListeners) {
@@ -233,37 +222,21 @@ export function configureNudgeUiRuntime(config) {
         }
     }
 }
-/** Returns the immutable runtime snapshot used by shared inspector Modules. */
 export function getNudgeUiRuntimeConfig() {
     return activeRuntimeConfig;
 }
-/** Returns whether a product feature is enabled; omitted flags default to enabled. */
 export function isNudgeUiFeatureEnabled(features, feature) {
     return features?.[feature] !== false;
 }
-/**
- * Whether this document runs the explicit public landing demo (ADR-0014 and
- * ADR-0016). The plugin emits `demo: true` for the flagged demo route and for
- * the explicit landing root in development and `nudge-demo` builds, so this is
- * the precise runtime boundary of the demo — narrower than any build-mode
- * name.
- */
+/** The demo boundary is this flag, never a build-mode name. */
 export function isDemoRuntime() {
     return getNudgeUiRuntimeConfig().demo === true;
 }
-/**
- * Returns the active host's source-coordinate policy, or null when the host
- * declares none — every source site is exact in that case.
- */
 export function getSourceCoordinatePolicy() {
     return activeRuntimeConfig.capabilities.sourceCoordinates ?? null;
 }
 let compiledScopingPattern = null;
-/**
- * Returns the active host's structural scoping-marker pattern compiled for
- * global replacement, or null when the host declares none. An invalid regex
- * source degrades to no stripping rather than breaking labeling.
- */
+/** Null when the host declares none; an invalid pattern degrades to no stripping. */
 export function getScopingSelectorPattern() {
     const source = activeRuntimeConfig.capabilities.scopingSelectorPattern;
     if (source === undefined)
@@ -278,15 +251,11 @@ export function getScopingSelectorPattern() {
     }
     return compiledScopingPattern.pattern;
 }
-/**
- * Subscribes to complete runtime replacements, such as Vite HMR updates.
- * Listeners run after the new snapshot is installed.
- */
+/** Listeners run after the new snapshot is installed. */
 export function subscribeNudgeUiRuntime(listener) {
     runtimeListeners.add(listener);
     return () => runtimeListeners.delete(listener);
 }
-/** Returns the styling-system label represented by a token inventory. */
 export function detectStylingSystem(tokens) {
     for (const token of tokens) {
         if (token.adapter === "vanilla-extract")
@@ -298,7 +267,6 @@ export function detectStylingSystem(tokens) {
     }
     return "CSS custom properties";
 }
-/** Returns a mutable container for UI controls that require array props. */
 export function getNudgeUiTokenEntries() {
     return [...activeRuntimeConfig.tokens];
 }

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

@@ -0,0 +1,19 @@
+import type { DraftContents } from "../drafts/model.js";
+/** Document-local identity that survives a reload only by re-attaching to the element whose rendered facts match. */
+export interface RuntimeIdentityClaim {
+    readonly cid: string;
+    readonly src: string | null;
+    readonly tagName: string;
+    readonly text: string | null;
+    readonly props: string | null;
+    readonly ariaLabel: string | null;
+    readonly domPath: string | null;
+    readonly elementId: string | null;
+}
+export declare function collectRuntimeIdentityClaims({ changes, structuralChanges }: DraftContents): RuntimeIdentityClaim[];
+/** Unmatched claims stay pending; their edits simply do not apply. */
+export declare function applyRuntimeIdentityClaims(doc: Document, claims: readonly RuntimeIdentityClaim[]): void;
+/** Stops reattachment for a document session, including queued work. */
+export declare function disposeRuntimeIdentityClaims(doc: Document): void;
+/** Runtime validation for claims received from another window. */
+export declare function isRuntimeIdentityClaim(value: unknown): value is RuntimeIdentityClaim;