nudge-ui 0.2.2 → 0.2.3

package/dist/inspector/projection/textProjection.d.ts

@@ -1,3 +1,4 @@
+import type { FrameProjection } from "../canvas/projection.js";
 import { isTextProjectionTargetValue, type TextContentChangeRecord, type TextProjectionTarget, type TextProjectionScope, type TextBindingEvidence } from "../inline-text/textChangeBoundary.js";
 /** Strict JSON boundary guard for a text projection target. */
 export declare const isTextProjectionTarget: typeof isTextProjectionTargetValue;
@@ -48,7 +49,7 @@ export declare function setCanonicalTextContentChanges(changes: ReadonlyArray<Te
 export declare function getTextProjectionReports(doc: Document): readonly TextProjectionReport[];
 export declare function subscribeTextProjectionDiagnostics(listener: () => void): () => void;
 export declare function getTextProjectionDiagnosticRevision(): number;
-export declare function recordCanvasTextProjectionReports(cardId: string, revision: number, reports: readonly TextProjectionReport[]): void;
+export declare function recordCanvasTextProjectionReports(cardId: string, revision: number, reports: readonly TextProjectionReport[], projection?: FrameProjection): void;
 export declare function clearCanvasTextProjectionReports(cardId: string): void;
 export declare function getTextContentChangeDiagnostics(changeId: string): TextContentProjectionDiagnostic[];
 export declare function isTextProjectionReport(value: unknown): value is TextProjectionReport;

package/dist/inspector/projection/textProjection.js

@@ -1,3 +1,4 @@
+import { getActiveDraftChanges, getDraftChanges } from "../changes/draftChanges.js";
 import { sourceSiteSelector } from "../selection/sourceSite.js";
 import { isNudgeUiDev } from "../runtime/devFlag.js";
 import { isTextContentChangeValue, isTextProjectionTargetValue, } from "../inline-text/textChangeBoundary.js";
@@ -640,10 +641,10 @@ export function subscribeTextProjectionDiagnostics(listener) {
 export function getTextProjectionDiagnosticRevision() {
     return diagnosticRevision;
 }
-export function recordCanvasTextProjectionReports(cardId, revision, reports) {
+export function recordCanvasTextProjectionReports(cardId, revision, reports, projection) {
     if (!Number.isSafeInteger(revision) || revision < 0 || !reports.every(isTextProjectionReport))
         return;
-    const expected = new Set(canonicalChanges.keys());
+    const expected = projection ? new Set(projection.textContentChanges.map((record) => record.id)) : new Set(canonicalChanges.keys());
     if (reports.length !== expected.size
         || new Set(reports.map((report) => report.changeId)).size !== reports.length
         || reports.some((report) => !expected.has(report.changeId)))
@@ -654,7 +655,8 @@ export function recordCanvasTextProjectionReports(cardId, revision, reports) {
     const next = reports.map((report) => ({ ...report }));
     if (existing && existing.revision === revision && sameReports(existing.reports, next))
         return;
-    reportsByCanvasCard.set(cardId, { revision, reports: next });
+    const current = getActiveDraftChanges();
+    reportsByCanvasCard.set(cardId, { revision, reports: next, draftId: projection?.draftId ?? current.draftId, draftRevision: projection?.draftRevision ?? current.revision });
     notifyDiagnostics();
 }
 export function clearCanvasTextProjectionReports(cardId) {
@@ -664,7 +666,7 @@ export function clearCanvasTextProjectionReports(cardId) {
 }
 export function getTextContentChangeDiagnostics(changeId) {
     const diagnostics = [];
-    const change = canonicalChanges.get(changeId);
+    const change = getActiveDraftChanges().changes.find((change) => change.kind === "text-content" && change.id === changeId) ?? canonicalChanges.get(changeId);
     const host = reportsByDocument.get(document)?.find((report) => report.changeId === changeId);
     if (host)
         diagnostics.push({
@@ -674,6 +676,8 @@ export function getTextContentChangeDiagnostics(changeId) {
             evidence: change?.evidence,
         });
     for (const [cardId, entry] of reportsByCanvasCard) {
+        if (entry.draftId !== getActiveDraftChanges().draftId || entry.draftRevision !== getDraftChanges(entry.draftId).revision)
+            continue;
         const report = entry.reports.find((candidate) => candidate.changeId === changeId);
         if (report)
             diagnostics.push({

package/dist/inspector/prompt/PromptSettingsDialog.js

@@ -2,11 +2,7 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
 import { useRef } from "react";
 import { Dialog } from "@base-ui/react/dialog";
 import { IconX } from "@tabler/icons-react";
-function portalContainer() {
-    return typeof document !== "undefined"
-        ? document.getElementById("nudge-ui-root")?.shadowRoot ?? document.body
-        : null;
-}
+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

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

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