nudge-ui 0.2.1 → 0.2.3

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

@@ -1,34 +1,26 @@
-import { type ChangeRecord } from "../changes/changesLog.js";
-import { type StructuralChange } from "../projection/structuralProjection.js";
+import type { ChangeRecord } from "../changes/types.js";
+import type { StructuralChange } from "../changes/structuralTypes.js";
+import { type HandoffOwner } from "../agent/verification.js";
 export interface ClipboardHandoffFingerprint {
     readonly key: string;
     readonly fingerprint: string;
 }
-export interface ClipboardHandoffSnapshot {
+interface ClipboardDraftHandoff {
+    readonly owner: HandoffOwner;
     readonly changes: readonly ClipboardHandoffFingerprint[];
     readonly structuralChanges: readonly ClipboardHandoffFingerprint[];
 }
-/** Validates an origin-local persisted clipboard checkpoint. */
+export interface ClipboardHandoffSnapshot {
+    readonly drafts: readonly ClipboardDraftHandoff[];
+}
 export declare function isClipboardHandoffSnapshot(value: unknown): value is ClipboardHandoffSnapshot | null;
-/** Captures the exact records included in a successful clipboard copy. */
-export declare function recordClipboardHandoff(changes: readonly ChangeRecord[], structuralChanges?: readonly StructuralChange[]): void;
-/** Returns a defensive copy for durable-session serialization. */
+export declare function recordClipboardHandoff(changes: readonly ChangeRecord[], structuralChanges?: readonly StructuralChange[], owner?: HandoffOwner): void;
 export declare function getClipboardHandoffSnapshot(): ClipboardHandoffSnapshot | null;
-/** Replaces the in-memory checkpoint from a validated durable session. */
 export declare function hydrateClipboardHandoff(value: ClipboardHandoffSnapshot | null): void;
 export declare function clearClipboardHandoff(): void;
 export declare function subscribeClipboardHandoff(listener: () => void): () => void;
-/** Monotonic external-store snapshot for persistence and React consumers. */
 export declare function getClipboardHandoffRevision(): number;
 export declare function getLastClipboardReconciledCount(): number;
-/**
- * Checks a copied prompt against source-rendered output and reconciles only
- * exact records that the browser can positively verify.
- */
 export declare function reconcileClipboardHandoff(doc?: Document): Promise<number>;
-/**
- * Watches source-driven document refreshes and page-return signals. The
- * trailing debounce lets an HMR commit settle before verification lifts the
- * inspector preview for two frames.
- */
 export declare function startClipboardHandoffController(doc?: Document): () => void;
+export {};

package/dist/inspector/prompt/clipboardHandoff.js

@@ -1,212 +1,161 @@
 import { changeKey } from "../changes/model.js";
-import { subscribeChanges, } from "../changes/changesLog.js";
-import {} from "../projection/structuralProjection.js";
-import { getWorkspaceChanges } from "../changes/workspaceChanges.js";
+import { getDraftChanges, getActiveDraftChanges, subscribeActiveDraftChanges } from "../changes/draftChanges.js";
 import { documentRevisions, subscribeDocumentRevision } from "../tokens/resolution/cssomCollector.js";
-import { handoffChangeFingerprint, handoffStructuralFingerprint, verifyAndReconcileHandoff, } from "../agent/verification.js";
-const MAX_HANDOFF_RECORDS = 10_000;
-const MAX_KEY_LENGTH = 16_384;
-const MAX_FINGERPRINT_LENGTH = 1_048_576;
-const RECONCILE_DEBOUNCE_MS = 450;
-let checkpoint = null;
+import { captureHandoffOwner, handoffChangeFingerprint, handoffStructuralFingerprint, verifyAndReconcileHandoff, } from "../agent/verification.js";
+import { isDraftTarget } from "../drafts/model.js";
+const checkpoints = new Map();
 let revision = 0;
-let lastReconciledCount = 0;
+const reconciledCounts = new Map();
 const listeners = new Set();
 function notify() {
     revision += 1;
     for (const listener of listeners)
         listener();
 }
-function cloneSnapshot(snapshot) {
-    return {
-        changes: snapshot.changes.map((entry) => ({ ...entry })),
-        structuralChanges: snapshot.structuralChanges.map((entry) => ({ ...entry })),
-    };
-}
 function isFingerprint(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
+    if (!value || typeof value !== "object")
         return false;
     const entry = value;
-    return Object.keys(entry).every((key) => key === "key" || key === "fingerprint")
-        && typeof entry.key === "string"
-        && entry.key.length > 0
-        && entry.key.length <= MAX_KEY_LENGTH
-        && typeof entry.fingerprint === "string"
-        && entry.fingerprint.length > 0
-        && entry.fingerprint.length <= MAX_FINGERPRINT_LENGTH;
+    return typeof entry.key === "string" && entry.key.length > 0 && entry.key.length <= 16_384
+        && typeof entry.fingerprint === "string" && entry.fingerprint.length > 0 && entry.fingerprint.length <= 1_048_576;
 }
-/** Validates an origin-local persisted clipboard checkpoint. */
 export function isClipboardHandoffSnapshot(value) {
     if (value === null)
         return true;
-    if (!value || typeof value !== "object" || Array.isArray(value))
+    if (!value || typeof value !== "object")
         return false;
-    const candidate = value;
-    if (!Object.keys(candidate).every((key) => key === "changes" || key === "structuralChanges")
-        || !Array.isArray(candidate.changes)
-        || !Array.isArray(candidate.structuralChanges)
-        || candidate.changes.length + candidate.structuralChanges.length > MAX_HANDOFF_RECORDS
-        || !candidate.changes.every(isFingerprint)
-        || !candidate.structuralChanges.every(isFingerprint)) {
+    const snapshot = value;
+    if (!Array.isArray(snapshot.drafts) || snapshot.drafts.length > 512)
         return false;
+    const ids = new Set();
+    for (const draft of snapshot.drafts) {
+        const owner = draft?.owner;
+        if (!owner || typeof owner.draftId !== "string" || ids.has(owner.draftId)
+            || !Number.isSafeInteger(owner.draftRevision) || owner.draftRevision < 0 || !isDraftTarget(owner.target)
+            || !Array.isArray(owner.frameIds) || owner.frameIds.some((id) => typeof id !== "string")
+            || !Array.isArray(draft.changes) || !Array.isArray(draft.structuralChanges)
+            || draft.changes.length + draft.structuralChanges.length > 10_000
+            || !draft.changes.every(isFingerprint) || !draft.structuralChanges.every(isFingerprint)
+            || new Set(draft.changes.map((entry) => entry.key)).size !== draft.changes.length
+            || new Set(draft.structuralChanges.map((entry) => entry.key)).size !== draft.structuralChanges.length)
+            return false;
+        ids.add(owner.draftId);
     }
-    const changeKeys = candidate.changes.map((entry) => entry.key);
-    const structuralKeys = candidate.structuralChanges.map((entry) => entry.key);
-    return new Set(changeKeys).size === changeKeys.length
-        && new Set(structuralKeys).size === structuralKeys.length;
+    return true;
 }
-/** Captures the exact records included in a successful clipboard copy. */
-export function recordClipboardHandoff(changes, structuralChanges = []) {
-    checkpoint = {
-        changes: changes.map((change) => ({
-            key: changeKey(change),
-            fingerprint: handoffChangeFingerprint(change),
-        })),
-        structuralChanges: structuralChanges.map((change) => ({
-            key: change.id,
-            fingerprint: handoffStructuralFingerprint(change),
-        })),
+function fingerprintSnapshot(owner, changes, structuralChanges) {
+    return {
+        owner: structuredClone(owner),
+        changes: changes.map((change) => ({ key: changeKey(change), fingerprint: handoffChangeFingerprint(change) })),
+        structuralChanges: structuralChanges.map((change) => ({ key: change.id, fingerprint: handoffStructuralFingerprint(change) })),
     };
-    lastReconciledCount = 0;
+}
+export function recordClipboardHandoff(changes, structuralChanges = [], owner = captureHandoffOwner()) {
+    checkpoints.set(owner.draftId, fingerprintSnapshot(owner, changes, structuralChanges));
+    reconciledCounts.delete(owner.draftId);
     notify();
 }
-/** Returns a defensive copy for durable-session serialization. */
 export function getClipboardHandoffSnapshot() {
-    return checkpoint ? cloneSnapshot(checkpoint) : null;
+    return checkpoints.size ? structuredClone({ drafts: [...checkpoints.values()] }) : null;
 }
-/** Replaces the in-memory checkpoint from a validated durable session. */
 export function hydrateClipboardHandoff(value) {
-    if (!value && !checkpoint && lastReconciledCount === 0)
-        return;
-    checkpoint = value ? cloneSnapshot(value) : null;
-    lastReconciledCount = 0;
+    checkpoints.clear();
+    for (const draft of value?.drafts ?? [])
+        checkpoints.set(draft.owner.draftId, structuredClone(draft));
+    reconciledCounts.clear();
     notify();
 }
 export function clearClipboardHandoff() {
-    if (!checkpoint && lastReconciledCount === 0)
+    if (!checkpoints.size && !reconciledCounts.size)
         return;
-    checkpoint = null;
-    lastReconciledCount = 0;
+    checkpoints.clear();
+    reconciledCounts.clear();
     notify();
 }
 export function subscribeClipboardHandoff(listener) {
     listeners.add(listener);
     return () => listeners.delete(listener);
 }
-/** Monotonic external-store snapshot for persistence and React consumers. */
-export function getClipboardHandoffRevision() {
-    return revision;
-}
-export function getLastClipboardReconciledCount() {
-    return lastReconciledCount;
-}
-function matchingChanges(snapshot) {
-    const expected = new Map(snapshot.changes.map((entry) => [entry.key, entry.fingerprint]));
-    return getWorkspaceChanges().changes.filter((change) => expected.get(changeKey(change)) === handoffChangeFingerprint(change));
-}
-function matchingStructuralChanges(snapshot) {
-    const expected = new Map(snapshot.structuralChanges.map((entry) => [entry.key, entry.fingerprint]));
-    return getWorkspaceChanges().structuralChanges.filter((change) => expected.get(change.id) === handoffStructuralFingerprint(change));
+export function getClipboardHandoffRevision() { return revision; }
+export function getLastClipboardReconciledCount() { return reconciledCounts.get(getActiveDraftChanges().draftId) ?? 0; }
+function matchingRecords(snapshot) {
+    const workspace = getDraftChanges(snapshot.owner.draftId);
+    const changes = new Map(snapshot.changes.map((entry) => [entry.key, entry.fingerprint]));
+    const structures = new Map(snapshot.structuralChanges.map((entry) => [entry.key, entry.fingerprint]));
+    return {
+        changes: workspace.changes.filter((change) => changes.get(changeKey(change)) === handoffChangeFingerprint(change)),
+        structuralChanges: workspace.structuralChanges.filter((change) => structures.get(change.id) === handoffStructuralFingerprint(change)),
+    };
 }
-/** Drops checkpoint entries that no longer describe current canonical intent. */
-function pruneCheckpoint() {
-    if (!checkpoint)
-        return false;
-    const changes = matchingChanges(checkpoint);
-    const structuralChanges = matchingStructuralChanges(checkpoint);
-    if (changes.length === checkpoint.changes.length
-        && structuralChanges.length === checkpoint.structuralChanges.length) {
-        return false;
+function pruneCheckpoints() {
+    let changed = false;
+    for (const [id, snapshot] of checkpoints) {
+        const matching = matchingRecords(snapshot);
+        if (matching.changes.length === snapshot.changes.length && matching.structuralChanges.length === snapshot.structuralChanges.length)
+            continue;
+        changed = true;
+        if (matching.changes.length + matching.structuralChanges.length === 0)
+            checkpoints.delete(id);
+        else
+            checkpoints.set(id, fingerprintSnapshot(snapshot.owner, matching.changes, matching.structuralChanges));
     }
-    checkpoint = changes.length + structuralChanges.length === 0
-        ? null
-        : {
-            changes: changes.map((change) => ({
-                key: changeKey(change),
-                fingerprint: handoffChangeFingerprint(change),
-            })),
-            structuralChanges: structuralChanges.map((change) => ({
-                key: change.id,
-                fingerprint: handoffStructuralFingerprint(change),
-            })),
-        };
-    notify();
-    return true;
+    if (changed)
+        notify();
 }
-/**
- * Checks a copied prompt against source-rendered output and reconciles only
- * exact records that the browser can positively verify.
- */
 export async function reconcileClipboardHandoff(doc = document) {
-    const snapshot = checkpoint;
-    if (!snapshot)
-        return 0;
-    const changes = matchingChanges(snapshot);
-    const structuralChanges = matchingStructuralChanges(snapshot);
-    if (changes.length + structuralChanges.length === 0) {
-        pruneCheckpoint();
-        return 0;
+    let removed = 0;
+    for (const snapshot of [...checkpoints.values()]) {
+        const matching = matchingRecords(snapshot);
+        if (matching.changes.length + matching.structuralChanges.length === 0)
+            continue;
+        const count = await verifyAndReconcileHandoff({ owner: snapshot.owner, ...matching }, doc);
+        if (count > 0)
+            reconciledCounts.set(snapshot.owner.draftId, count);
+        removed += count;
     }
-    const removed = await verifyAndReconcileHandoff({ changes, structuralChanges }, doc);
-    pruneCheckpoint();
+    pruneCheckpoints();
     if (removed > 0) {
-        lastReconciledCount = removed;
         notify();
     }
     return removed;
 }
-/**
- * Watches source-driven document refreshes and page-return signals. The
- * trailing debounce lets an HMR commit settle before verification lifts the
- * inspector preview for two frames.
- */
 export function startClipboardHandoffController(doc = document) {
-    const ownerWindow = doc.defaultView;
+    const view = doc.defaultView;
     let timer = null;
     let checking = false;
     let stopped = false;
     const schedule = () => {
-        if (stopped || checking || !checkpoint)
+        if (stopped || checking || !checkpoints.size)
             return;
         if (timer !== null)
             clearTimeout(timer);
         timer = setTimeout(() => {
             timer = null;
-            if (stopped || checking || !checkpoint)
+            if (stopped || checking || !checkpoints.size)
                 return;
             checking = true;
-            void reconcileClipboardHandoff(doc)
-                .catch(() => undefined)
-                .finally(() => {
-                // Keep the guard through the MutationObserver microtask generated by
-                // restoring managed projections, preventing a verification loop.
+            void reconcileClipboardHandoff(doc).catch(() => undefined).finally(() => {
                 setTimeout(() => { checking = false; }, 0);
             });
-        }, RECONCILE_DEBOUNCE_MS);
-    };
-    const onCanonicalChange = () => {
-        pruneCheckpoint();
-    };
-    const onVisibilityChange = () => {
-        if (doc.visibilityState === "visible")
-            schedule();
+        }, 450);
     };
-    // Initializes the document observer before registering the listener.
+    const visible = () => { if (doc.visibilityState === "visible")
+        schedule(); };
     documentRevisions(doc);
-    const unsubscribeRevision = subscribeDocumentRevision(doc, schedule);
-    const unsubscribeChanges = subscribeChanges(onCanonicalChange);
-    ownerWindow?.addEventListener("focus", schedule);
-    ownerWindow?.addEventListener("pageshow", schedule);
-    doc.addEventListener("visibilitychange", onVisibilityChange);
+    const stopRevision = subscribeDocumentRevision(doc, schedule);
+    const stopChanges = subscribeActiveDraftChanges(pruneCheckpoints);
+    view?.addEventListener("focus", schedule);
+    view?.addEventListener("pageshow", schedule);
+    doc.addEventListener("visibilitychange", visible);
     schedule();
     return () => {
         stopped = true;
         if (timer !== null)
             clearTimeout(timer);
-        unsubscribeRevision();
-        unsubscribeChanges();
-        ownerWindow?.removeEventListener("focus", schedule);
-        ownerWindow?.removeEventListener("pageshow", schedule);
-        doc.removeEventListener("visibilitychange", onVisibilityChange);
+        stopRevision();
+        stopChanges();
+        view?.removeEventListener("focus", schedule);
+        view?.removeEventListener("pageshow", schedule);
+        doc.removeEventListener("visibilitychange", visible);
     };
 }

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

@@ -1,8 +1,11 @@
 import type { ChangeRecord } from "../changes/changesLog.js";
 import type { StructuralChange } from "../projection/structuralProjection.js";
 import type { AgentSketchMetadata } from "../agent/protocol.js";
+import { type ElementComment } from "../comments/store.js";
 export interface FrameworkHints {
     framework?: string;
     stylingSystem?: string;
 }
-export declare function generatePrompt(changes: ChangeRecord[], frameworkHints?: FrameworkHints, structuralChanges?: readonly StructuralChange[], customInstructions?: string, sketches?: readonly AgentSketchMetadata[]): string;
+/** Counts the final edit intents exported by the prompt, preserving gesture history for undo. */
+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

@@ -5,6 +5,8 @@ import { formatComponentPropBaseline, formatComponentPropValue, } from "../compo
 import { boundRuntimeEvidence, isRuntimeGeneratedSource, normalizeRuntimeTag, normalizeRuntimeText, } from "../runtime/staticHtmlRuntimeIdentity.js";
 import { getSourceCoordinatePolicy } from "../runtime/runtimeConfig.js";
 import { DEFAULT_CUSTOM_INSTRUCTIONS } from "./promptSettings.js";
+import { getCommentsForTarget } from "../comments/store.js";
+import { documentTarget } from "../drafts/model.js";
 const EMPTY_SENTINEL = "<!-- No changes to export -->\n\nThe changes log is empty. Make a change in the Nudge UI inspector first.";
 function renderPrompt(sections, customInstructions) {
     const lines = [
@@ -244,17 +246,6 @@ function structuralChangeLine(change) {
         ? `- Move ${target} before ${renderedInstanceDescription(before)} in ${destinationParent}.`
         : `- Move ${target} to the end of ${destinationParent}.`;
 }
-function sketchLines(sketches) {
-    const titles = [...new Set(sketches.map((sketch) => sketch.capture.title || "(untitled)"))];
-    return [
-        ...titles.map((title) => `- Page title: ${promptText(title)}`),
-        ...sketches.flatMap((sketch) => [
-            ...(sketch.description ? [`- Description: ${promptText(sketch.description)}`] : []),
-            ...(sketch.annotations ?? []).map((annotation) => `- Annotation ${annotation.number}: ${promptText(annotation.description)}`),
-        ]),
-        "- Interpret the attached frozen screenshot, blue strokes, and numbered annotations as visual feedback. Do not derive selectors, source coordinates, or semantics from the strokes. Use each annotation number to match the note to its numbered dot.",
-    ];
-}
 function renderedInstanceKey(ref) {
     const { sourceSite, locator } = ref;
     return JSON.stringify([
@@ -315,10 +306,14 @@ function canonicalizeStructuralChanges(changes) {
     }
     return canonical;
 }
-export function generatePrompt(changes, frameworkHints, structuralChanges = [], customInstructions = DEFAULT_CUSTOM_INSTRUCTIONS, sketches = []) {
+/** Counts the final edit intents exported by the prompt, preserving gesture history for undo. */
+export function countPromptChanges(changes, structuralChanges = [], sketchCount = 0) {
+    return canonicalizeChanges([...changes]).length + canonicalizeStructuralChanges(structuralChanges).length + sketchCount;
+}
+export function generatePrompt(changes, frameworkHints, structuralChanges = [], customInstructions = DEFAULT_CUSTOM_INSTRUCTIONS, sketches = [], comments = getCommentsForTarget(documentTarget(window.location.href))) {
     const deduplicated = canonicalizeChanges(changes);
     const structuralIntent = canonicalizeStructuralChanges(structuralChanges);
-    if (deduplicated.length === 0 && structuralIntent.length === 0 && sketches.length === 0)
+    if (deduplicated.length === 0 && structuralIntent.length === 0 && sketches.length === 0 && comments.length === 0)
         return EMPTY_SENTINEL;
     const tokenChanges = deduplicated.filter(isTokenChange);
     const componentChanges = deduplicated.filter(isComponentChange);
@@ -398,10 +393,16 @@ export function generatePrompt(changes, frameworkHints, structuralChanges = [],
             lines: structuralIntent.map(structuralChangeLine),
         });
     }
-    if (sketches.length > 0) {
+    if (comments.length > 0) {
         sections.push({
-            heading: "Sketch annotations",
-            lines: sketchLines(sketches),
+            heading: "Element comments",
+            lines: comments.flatMap((comment) => [
+                `### <${comment.tag}> (${comment.target.sourceSite.src || "source unknown"})`,
+                `- Page: ${promptText(comment.route)}`,
+                `- Target: ${renderedInstanceDescription(comment.target)}`,
+                `- Note: ${promptText(comment.note)}`,
+                "",
+            ]),
         });
     }
     return renderPrompt(sections, customInstructions);

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

@@ -24,7 +24,7 @@ export interface NudgeUiRuntimeCapabilities {
     readonly canvas: boolean;
     /** Whether framework component inspection and prop overrides are available. */
     readonly componentSemantics: boolean;
-    /** Whether the experimental DOM navigation section is available. */
+    /** Whether the DOM navigator overlay is available. */
     readonly domNavigation?: boolean;
     /**
      * Source-coordinate precision policy for prompts; every source site is
@@ -39,6 +39,11 @@ export interface NudgeUiRuntimeCapabilities {
      */
     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 canvasIterations?: boolean;
+}
 /**
  * Browser knowledge supplied by a host Adapter before the inspector mounts.
  *
@@ -53,6 +58,8 @@ export interface NudgeUiRuntimeConfig {
     readonly framework: NudgeUiRuntimeFramework;
     readonly stylingSystem: string;
     readonly capabilities: NudgeUiRuntimeCapabilities;
+    /** Product-level feature switches; omitted features remain enabled. */
+    readonly features?: NudgeUiRuntimeFeatures;
     readonly tokenCatalog: readonly TokenDefinition[];
     readonly tokens: readonly TokenEntry[];
     readonly tokenDiagnostics: readonly TokenCatalogDiagnostic[];
@@ -91,6 +98,8 @@ export declare function normalizeNudgeUiRuntimeConfig(input: unknown): NudgeUiRu
 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

package/dist/inspector/runtime/runtimeConfig.js

@@ -98,6 +98,15 @@ function optionalBoolean(input, field) {
     }
     return value;
 }
+function optionalFeatureBoolean(input, field) {
+    const value = input[field];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "boolean") {
+        throw new TypeError(`Nudge UI runtime feature "${field}" must be a boolean; received ${JSON.stringify(value)}.`);
+    }
+    return value;
+}
 function optionalNonEmptyString(input, field) {
     const value = input[field];
     if (value === undefined)
@@ -142,6 +151,15 @@ function normalizeCapabilities(input) {
         scopingSelectorPattern: optionalNonEmptyString(input, "scopingSelectorPattern"),
     };
 }
+function normalizeFeatures(input) {
+    if (input === undefined)
+        return undefined;
+    if (!isPlainRecord(input)) {
+        throw new TypeError('Nudge UI runtime configuration field "features" must be an object.');
+    }
+    const canvasIterations = optionalFeatureBoolean(input, "canvasIterations");
+    return canvasIterations === undefined ? {} : { canvasIterations };
+}
 function optionalDemoFlag(input) {
     const value = input.demo;
     if (value === undefined || value === false)
@@ -172,12 +190,14 @@ export function normalizeNudgeUiRuntimeConfig(input) {
     const demo = optionalDemoFlag(input);
     const demoPages = optionalStringArray(input, "demoPages");
     const demoCardLabels = optionalStringArray(input, "demoCardLabels");
+    const features = normalizeFeatures(input.features);
     const normalized = cloneAndFreeze({
         projectId: requireString(input, "projectId"),
         host: requireEnum(input, "host", RUNTIME_HOSTS),
         framework: requireEnum(input, "framework", RUNTIME_FRAMEWORKS),
         stylingSystem: optionalString(input, "stylingSystem"),
         capabilities: normalizeCapabilities(input.capabilities),
+        ...(features === undefined ? {} : { features }),
         tokenCatalog: optionalArray(input, "tokenCatalog"),
         tokens: optionalArray(input, "tokens"),
         tokenDiagnostics: optionalArray(input, "tokenDiagnostics"),
@@ -217,6 +237,10 @@ export function configureNudgeUiRuntime(config) {
 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

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

@@ -3,5 +3,11 @@ export interface DescendantNode {
     element: HTMLElement;
     depth: number;
 }
+export interface NavigationNode {
+    element: HTMLElement;
+    direction: "up" | "down";
+    depth: number;
+}
 /** Returns the nearest tracked descendants, breadth-first and document-ordered. */
 export declare function computeDescendants(el: HTMLElement, maxDepth?: number, maxNodes?: number): DescendantNode[];
+export declare function computeNavigationNodes(el: HTMLElement, hierarchy?: HTMLElement[]): NavigationNode[];

package/dist/inspector/selection/hierarchy.js

@@ -40,3 +40,11 @@ export function computeDescendants(el, maxDepth = 2, maxNodes = 2) {
         .sort((left, right) => left.depth - right.depth || left.order - right.order);
     return descendants.slice(0, maxNodes).map(({ element, depth }) => ({ element, depth }));
 }
+export function computeNavigationNodes(el, hierarchy = computeHierarchy(el)) {
+    const children = computeDescendants(el, 2, 2);
+    const parents = hierarchy.slice(1, (children.length > 0 ? 2 : 4) + 1);
+    return [
+        ...parents.map((element, index) => ({ element, direction: "up", depth: index + 1 })),
+        ...children.map(({ element, depth }) => ({ element, direction: "down", depth })),
+    ];
+}

package/dist/inspector/settings/SettingsDialog.d.ts

@@ -9,4 +9,4 @@ export interface SettingsDialogProps extends McpConnectionContentProps {
     readonly onOpenChange: (open: boolean) => void;
 }
 /** Provides one settings surface for prompt, MCP, and token configuration. */
-export declare function SettingsDialog({ open, initialSection, value, onValueChange, onOpenChange, projectId, origin, snapshot, onConnect, onDisconnect, onCheckAgain, }: SettingsDialogProps): ReactElement;
+export declare function SettingsDialog({ open, initialSection, value, onValueChange, onOpenChange, projectId, origin, snapshot, onConnect, onTakeOver, onDisconnect, onCheckAgain, }: SettingsDialogProps): ReactElement;

package/dist/inspector/settings/SettingsDialog.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useRef, useState } from "react";
 import { Dialog } from "@base-ui/react/dialog";
-import { IconColorSwatch, IconPlugConnected, IconSettings, IconX, } from "@tabler/icons-react";
+import { IconColorSwatch, IconPlugConnected, IconSettings, IconX, IconTrash, } from "@tabler/icons-react";
 import { useBrowserCssInspection } from "../inspection/useBrowserCssInspection.js";
 import { McpConnectionContent, } from "../agent/McpConnectionDialog.js";
 import { PromptSettingsFields, } from "../prompt/PromptSettingsDialog.js";
@@ -10,10 +10,17 @@ import { useSelectedElement } from "../selection/selectionStore.js";
 import { useFocusedCardId, useSelectedCardId } from "../canvas/canvasStore.js";
 import { getRegisteredFrames } from "../canvas/projection.js";
 import { getBrowserCssInspection } from "../inspection/browserCssInspectionRegistry.js";
+import { portalContainer } from "../ui/portalContainer.js";
+import { clearRestoreCount, clearSession } from "../canvas/sessionStore.js";
+import { hasWriteLease } from "../canvas/workspaceLease.js";
+import { cancelSketchInteraction } from "../sketch/interaction.js";
+import { closeSketchNote } from "../sketch/sketchNote.js";
+import { clearSketchClipboardHandoff } from "../sketch/handoff.js";
+import { clearSketchesForProject } from "../sketch/store.js";
 const SETTINGS_SECTIONS = [
     {
         id: "instructions",
-        label: "Custom instructions",
+        label: "Instructions",
         icon: _jsx(IconSettings, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }),
     },
     {
@@ -27,13 +34,8 @@ const SETTINGS_SECTIONS = [
         icon: _jsx(IconColorSwatch, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }),
     },
 ];
-function portalContainer() {
-    return typeof document !== "undefined"
-        ? document.getElementById("nudge-ui-root")?.shadowRoot ?? document.body
-        : null;
-}
 /** Provides one settings surface for prompt, MCP, and token configuration. */
-export function SettingsDialog({ open, initialSection, value, onValueChange, onOpenChange, projectId, origin, snapshot, onConnect, onDisconnect, onCheckAgain, }) {
+export function SettingsDialog({ open, initialSection, value, onValueChange, onOpenChange, projectId, origin, snapshot, onConnect, onTakeOver, onDisconnect, onCheckAgain, }) {
     const [activeSection, setActiveSection] = useState(initialSection);
     const closeRef = useRef(null);
     const instructionsRef = useRef(null);
@@ -52,5 +54,16 @@ export function SettingsDialog({ open, initialSection, value, onValueChange, onO
         if (open)
             setActiveSection(initialSection);
     }, [initialSection, open]);
-    return (_jsx(Dialog.Root, { open: open, onOpenChange: onOpenChange, children: _jsxs(Dialog.Portal, { container: portalContainer(), children: [_jsx(Dialog.Backdrop, { className: "settings__backdrop", "data-test": "settings-backdrop" }), _jsxs(Dialog.Popup, { className: "settings__popup", "data-test": "settings-dialog", initialFocus: closeRef, children: [_jsx(Dialog.Title, { className: "settings__visually-hidden", children: "Settings" }), _jsx(Dialog.Description, { className: "settings__visually-hidden", children: "Configure how Nudge connects to your coding agent and uses your design system." }), _jsx(Dialog.Close, { ref: closeRef, className: "icon-button icon-button--quiet settings__close", "aria-label": "Close settings", "data-test": "settings-close", type: "button", children: _jsx(IconX, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }) }), _jsxs("div", { className: "settings__body", children: [_jsxs("nav", { className: "settings__nav", "aria-label": "Settings sections", children: [_jsx("span", { className: "settings__nav-label", children: "Settings" }), _jsx("div", { className: "settings__nav-items", children: SETTINGS_SECTIONS.map((section) => (_jsxs("button", { className: `settings__nav-item${activeSection === section.id ? " settings__nav-item--active" : ""}`, "data-test": `settings-nav-${section.id}`, type: "button", "aria-current": activeSection === section.id ? "page" : undefined, onClick: () => setActiveSection(section.id), children: [section.icon, _jsx("span", { className: "settings__nav-item-label", children: section.label })] }, section.id))) })] }), _jsxs("main", { className: "settings__content", "data-test": "settings-content", children: [activeSection === "instructions" ? (_jsxs("section", { className: "settings__section", "data-test": "prompt-settings-dialog", "data-settings-section": "instructions", children: [_jsx("h2", { className: "settings__section-title", children: activeDefinition.label }), _jsx("p", { className: "settings__section-description", children: "These instructions are added to the end of every copied prompt." }), _jsx(PromptSettingsFields, { value: value, onChange: onValueChange, instructionsRef: instructionsRef })] })) : null, activeSection === "mcp" ? (_jsxs("section", { className: "settings__section", "data-test": "settings-section-mcp", children: [_jsx("h2", { className: "settings__section-title", children: activeDefinition.label }), _jsx("div", { "data-test": "mcp-connection-dialog", children: _jsx(McpConnectionContent, { projectId: projectId, origin: origin, snapshot: snapshot, onConnect: onConnect, onDisconnect: onDisconnect, onCheckAgain: onCheckAgain }) })] })) : null, activeSection === "tokens" ? (_jsxs("section", { className: "settings__section", "data-test": "settings-section-tokens", children: [_jsx("h2", { className: "settings__section-title", children: activeDefinition.label }), _jsx("p", { className: "settings__section-description", children: "Inspect and edit the design tokens available in this page." }), _jsx(TokensPanel, { rows: tokenRows })] })) : null] })] })] })] }) }));
+    function resetCanvas() {
+        if (!hasWriteLease())
+            return;
+        cancelSketchInteraction();
+        closeSketchNote();
+        clearSketchClipboardHandoff();
+        clearSession();
+        clearRestoreCount();
+        void clearSketchesForProject(projectId).catch(() => undefined);
+        onOpenChange(false);
+    }
+    return (_jsx(Dialog.Root, { open: open, onOpenChange: onOpenChange, children: _jsxs(Dialog.Portal, { container: portalContainer(), children: [_jsx(Dialog.Backdrop, { className: "settings__backdrop", "data-test": "settings-backdrop" }), _jsxs(Dialog.Popup, { className: "settings__popup", "data-test": "settings-dialog", initialFocus: closeRef, children: [_jsx(Dialog.Title, { className: "settings__visually-hidden", children: "Settings" }), _jsx(Dialog.Description, { className: "settings__visually-hidden", children: "Configure how Nudge connects to your coding agent and uses your design system." }), _jsx(Dialog.Close, { ref: closeRef, className: "icon-button icon-button--quiet settings__close", "aria-label": "Close settings", "data-test": "settings-close", type: "button", children: _jsx(IconX, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }) }), _jsxs("div", { className: "settings__body", children: [_jsxs("nav", { className: "settings__nav", "aria-label": "Settings sections", children: [_jsx("span", { className: "settings__nav-label", children: "Settings" }), _jsx("div", { className: "settings__nav-items", children: SETTINGS_SECTIONS.map((section) => (_jsxs("button", { className: `settings__nav-item${activeSection === section.id ? " settings__nav-item--active" : ""}`, "data-test": `settings-nav-${section.id}`, type: "button", "aria-current": activeSection === section.id ? "page" : undefined, onClick: () => setActiveSection(section.id), children: [section.icon, _jsx("span", { className: "settings__nav-item-label", children: section.label })] }, section.id))) }), _jsxs("button", { className: "settings__nav-item settings__reset-canvas", "data-test": "settings-reset-canvas", type: "button", onClick: resetCanvas, children: [_jsx(IconTrash, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }), _jsx("span", { className: "settings__nav-item-label", children: "Reset canvas" })] })] }), _jsxs("main", { className: "settings__content", "data-test": "settings-content", children: [activeSection === "instructions" ? (_jsxs("section", { className: "settings__section", "data-test": "prompt-settings-dialog", "data-settings-section": "instructions", children: [_jsx("h2", { className: "settings__section-title", children: "Custom instructions" }), _jsx("p", { className: "settings__section-description", children: "These instructions are added to the end of every copied prompt." }), _jsx(PromptSettingsFields, { value: value, onChange: onValueChange, instructionsRef: instructionsRef })] })) : null, activeSection === "mcp" ? (_jsxs("section", { className: "settings__section", "data-test": "settings-section-mcp", children: [_jsx("h2", { className: "settings__section-title", children: activeDefinition.label }), _jsx("div", { "data-test": "mcp-connection-dialog", children: _jsx(McpConnectionContent, { projectId: projectId, origin: origin, snapshot: snapshot, onConnect: onConnect, onTakeOver: onTakeOver, onDisconnect: onDisconnect, onCheckAgain: onCheckAgain }) })] })) : null, activeSection === "tokens" ? (_jsxs("section", { className: "settings__section", "data-test": "settings-section-tokens", children: [_jsx("h2", { className: "settings__section-title", children: activeDefinition.label }), _jsx("p", { className: "settings__section-description", children: "Inspect and edit the design tokens available in this page." }), _jsx(TokensPanel, { rows: tokenRows })] })) : null] })] })] })] }) }));
 }