nudge-ui 0.2.3 → 0.2.5

package/dist/inspector/prompt/generatePrompt.js

@@ -1,16 +1,37 @@
-import { isComponentChange, isElementChange, isTextContentChange, isTokenChange } from "../changes/changesLog.js";
-import { canonicalizeChanges, changeKey, tokenReference } from "../changes/model.js";
-import { getAnyPreviewDiagnostic } from "../changes/previewDiagnostics.js";
+import { isComponentChange, isElementChange, isTextContentChange, isTokenChange } from "../changes/types.js";
+import { canonicalizeChanges, tokenReference } from "../changes/model.js";
 import { formatComponentPropBaseline, formatComponentPropValue, } from "../componentSemantics/changeModel.js";
 import { boundRuntimeEvidence, isRuntimeGeneratedSource, normalizeRuntimeTag, normalizeRuntimeText, } from "../runtime/staticHtmlRuntimeIdentity.js";
 import { getSourceCoordinatePolicy } from "../runtime/runtimeConfig.js";
 import { DEFAULT_CUSTOM_INSTRUCTIONS } from "./promptSettings.js";
+import { PROMPT_TITLE } from "./promptDocument.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.";
+/** Labels describe the observed tag, without guessing its role in the page. */
+function elementLabel(tag) {
+    const normalized = normalizeRuntimeTag(tag);
+    const labels = {
+        p: "Paragraph", button: "Button", a: "Link", img: "Image", input: "Input",
+        textarea: "Text area", select: "Select", form: "Form", nav: "Navigation", section: "Section",
+    };
+    const label = /^h[1-6]$/.test(normalized) ? "Heading" : labels[normalized] ?? "Element";
+    return normalized ? `${label} (${promptText(`<${normalized}>`)})` : label;
+}
+/** Runtime IDs identify one DOM element; authored sites can render several items. */
+function elementPromptKey(cid, src, scope, locator) {
+    if (!src || isRuntimeGeneratedSource(src))
+        return JSON.stringify(["runtime", cid]);
+    return JSON.stringify([cid, src, scope, scope === "rendered-instance" ? [
+            locator?.occurrence, locator?.props, locator?.ariaLabel ?? null, locator?.invocation?.callsiteId ?? null,
+        ] : null]);
+}
+function refPromptKey(ref) {
+    return elementPromptKey(ref.sourceSite.cid, ref.sourceSite.src, "rendered-instance", ref.locator);
+}
 function renderPrompt(sections, customInstructions) {
     const lines = [
-        "# Requested design changes",
+        PROMPT_TITLE,
     ];
     for (const section of sections) {
         const content = [...section.lines];
@@ -47,6 +68,7 @@ function groupElementChanges(changes) {
                 line: change.source.line || change.line,
                 column: change.column ?? 0,
                 runtimeEvidence: change.runtimeEvidence,
+                sourceEvidence: change.sourceEvidence,
                 instanceOverride,
                 changes: [],
             };
@@ -56,28 +78,24 @@ function groupElementChanges(changes) {
     }
     return [...map.values()];
 }
-function conflictSuffix(rec) {
-    const result = getAnyPreviewDiagnostic(changeKey(rec))?.result;
-    if (!result || result.status === "applied")
-        return "";
-    return ` — preview conflict: browser computed \`${result.computedValue || "(no value)"}\` (${result.reason ?? "cascade conflict"}); implement the requested value without assuming \`!important\``;
-}
 function elementChangeLine(rec) {
+    const state = rec.state && rec.state !== "base" ? ` (${rec.state})` : "";
+    const property = `\`${rec.property}\`${state}`;
     if (rec.newToken && rec.oldToken) {
-        return `- \`${rec.property}\`: \`${rec.oldToken.name}\` → \`${rec.newToken.name}\`${conflictSuffix(rec)}`;
+        return `- **Change:** ${property}: \`${rec.oldToken.name}\` → \`${rec.newToken.name}\``;
     }
     if (rec.newToken) {
         const before = rec.oldRawValue !== undefined ? `\`${rec.oldRawValue}\` → ` : "";
         // Describe exactly the value the managed stylesheet wrote for this swap
         // (adapter literal or var(cssName)); a bare var(name) would be invalid
         // CSS for adapter tokens whose names are not custom-property names.
-        return `- \`${rec.property}\`: ${before}\`${tokenReference(rec.newToken)}\`${conflictSuffix(rec)}`;
+        return `- **Change:** ${property}: ${before}\`${tokenReference(rec.newToken)}\``;
     }
     if (rec.rawValue !== undefined) {
         const before = rec.oldRawValue !== undefined ? `\`${rec.oldRawValue}\` → ` : "";
-        return `- \`${rec.property}\`: ${before}\`${rec.rawValue}\`${conflictSuffix(rec)}`;
+        return `- **Change:** ${property}: ${before}\`${rec.rawValue}\``;
     }
-    return `- \`${rec.property}\`: (no value)`;
+    return `- **Change:** ${property}: (no value)`;
 }
 function sourceIntentLine(rec) {
     if (!rec.sourceProperty || rec.sourceProperty === rec.property)
@@ -86,27 +104,22 @@ function sourceIntentLine(rec) {
     return `  - Source declaration (CSSOM): \`${rec.sourceProperty}${authored}\`; preview edit uses physical \`${rec.property}\``;
 }
 function tokenChangeLine(rec) {
-    return `- \`${rec.tokenName}\` (${rec.contextLabel}, ${rec.file}:${rec.line}): \`${rec.oldRawValue}\` → \`${rec.rawValue}\`${conflictSuffix(rec)}`;
+    return `- **Change:** \`${rec.tokenName}\` (${rec.contextLabel}, ${rec.file}:${rec.line}): \`${rec.oldRawValue}\` → \`${rec.rawValue}\``;
 }
 function componentChangeLine(rec) {
     const sourceGuidance = rec.authoredAs === "literal"
         ? rec.property === "children"
             ? "replace the literal child text"
-            : "replace the invocation prop literal"
+            : ""
         : rec.authoredAs === "default"
             ? "add the prop at this invocation"
             : `preserve the authored ${rec.authoredAs} and update its source logic`;
-    const scope = rec.scope === "rendered-instance"
-        ? "this rendered item only"
-        : "all outputs at this source site";
-    return `- \`${rec.property}\`: \`${formatComponentPropBaseline(rec.before)}\` → \`${formatComponentPropValue(rec.after)}\` — ${sourceGuidance}; scope: ${scope}`;
+    return `- **Change:** \`${rec.property}\`: \`${formatComponentPropBaseline(rec.before)}\` → \`${formatComponentPropValue(rec.after)}\`${sourceGuidance ? ` — ${sourceGuidance}` : ""}`;
 }
-function textAuthorshipGuidance(authoredAs) {
-    if (authoredAs === "literal")
-        return "replace the authored literal text";
-    if (authoredAs === "expression")
-        return "preserve the expression and update its source logic";
-    return "update the source that produces this rendered copy";
+function editScopeLine(scope) {
+    return scope === "rendered-instance"
+        ? "  - Apply to this selected item only; keep other instances unchanged."
+        : "  - Apply to all items rendered at this source location.";
 }
 /** Keep arbitrary rendered copy valid inside the Markdown prompt. */
 function promptText(value) {
@@ -116,35 +129,62 @@ function promptText(value) {
     const fence = "~".repeat(Math.max(3, longestTildeRun + 1));
     return `${fence}text\n${value}\n${fence}`;
 }
-function textEvidenceLines(target) {
-    const sourceLabel = isRuntimeGeneratedSource(target.sourceSite.src)
-        ? `${target.sourceSite.cid} (source unknown; runtime-created DOM)`
-        : `${target.sourceSite.cid} (\`${target.sourceSite.src}\`)`;
-    const lines = [
-        `  - Source site: ${sourceLabel}`,
-    ];
-    const props = boundRuntimeEvidence(target.props);
-    const ariaLabel = boundRuntimeEvidence(target.ariaLabel);
-    if (props)
-        lines.push(`  - Props evidence: ${promptText(props)}`);
-    if (ariaLabel)
-        lines.push(`  - Accessible name evidence: ${promptText(ariaLabel)}`);
-    return lines;
-}
-function textScopeLines(change) {
-    const scope = change.scope === "source-site" ? "source site / all outputs" : "this rendered item only";
-    const lines = [`  - Scope: ${scope}`];
+function textBindingLines(change, sourceLocation) {
+    const lines = [];
     if (change.evidence) {
-        lines.push(`  - Semantic evidence: \`${change.evidence.componentName}.${change.evidence.property}\` at callsite \`${change.evidence.callsiteId}\` (${change.evidence.mountedCount} mounted outputs)`);
+        const evidence = change.evidence;
+        const location = evidence.callsiteId === sourceLocation ? "" : ` at ${promptText(evidence.callsiteId)}`;
+        lines.push(`  - Text source: ${promptText(`${evidence.componentName}.${evidence.property}`)}${location} (${evidence.mountedCount} rendered instances).`);
     }
     return lines;
 }
+/** Shared presentation for captured facts; these do not change target matching. */
+function targetEvidenceLines(evidence, example = false) {
+    const text = normalizeRuntimeText(evidence.text ?? null);
+    const ariaLabel = boundRuntimeEvidence(evidence.ariaLabel ?? null);
+    const elementId = boundRuntimeEvidence(evidence.elementId ?? null);
+    const props = boundRuntimeEvidence(evidence.props ?? null);
+    const lines = [];
+    if (elementId && !example)
+        lines.push(`- Element ID: ${promptText(elementId)}`);
+    if (text)
+        lines.push(`- ${example ? "Example text" : "Text"}: ${promptText(text)}`);
+    if (ariaLabel)
+        lines.push(`- ${example ? "Example accessible name" : "Accessible name"}: ${promptText(ariaLabel)}`);
+    if (props && props !== `id:${elementId}`)
+        lines.push(`- ${example ? "Example props" : "Props"}: ${promptText(props)}`);
+    if (evidence.domPath && !example)
+        lines.push(`- DOM path: ${promptText(evidence.domPath)}`);
+    return lines;
+}
+function readableTargetLabel(text, tag) {
+    if (tag)
+        return elementLabel(tag);
+    const bounded = normalizeRuntimeText(text);
+    return bounded ? `Text: ${inlineHeadingText(bounded)}` : "Element";
+}
+/** Use an inline code span even when copy contains Markdown delimiters. */
+function inlineHeadingText(text) {
+    const runs = text.match(/`+/g) ?? [];
+    const delimiter = "`".repeat(Math.max(0, ...runs.map((run) => run.length)) + 1);
+    const padding = text.startsWith("`") || text.endsWith("`") ? " " : "";
+    return `${delimiter}${padding}${text}${padding}${delimiter}`;
+}
 function boundedEvidence(value) {
     return boundRuntimeEvidence(value);
 }
 function sourceSiteLabel(ref) {
-    if (isRuntimeGeneratedSource(ref.sourceSite.src)) {
-        return `${ref.sourceSite.cid} (source unknown; runtime-created DOM)`;
+    if (!ref.sourceSite.src || isRuntimeGeneratedSource(ref.sourceSite.src)) {
+        const text = boundedEvidence(ref.locator.text);
+        const ariaLabel = boundedEvidence(ref.locator.ariaLabel ?? null);
+        const props = boundedEvidence(ref.locator.props);
+        if (ariaLabel)
+            return `the element named ${promptText(ariaLabel)}`;
+        if (text)
+            return `the element with text ${promptText(text)}`;
+        if (props)
+            return `the element with props ${promptText(props)}`;
+        return "the element";
     }
     return `${ref.sourceSite.cid} (${ref.sourceSite.src})`;
 }
@@ -159,25 +199,27 @@ function structuralParentIdentityKey(ref) {
         locator.ariaLabel ?? null,
     ]);
 }
-function runtimeEvidenceLines(group) {
-    const evidence = group.runtimeEvidence;
-    if (!evidence)
-        return [];
-    const tagName = normalizeRuntimeTag(evidence.tagName) || "unknown";
-    const text = normalizeRuntimeText(evidence.text);
-    const ariaLabel = boundRuntimeEvidence(evidence.ariaLabel);
-    const props = boundRuntimeEvidence(evidence.props);
-    const lines = [
-        "  - Source: unknown; locate the JavaScript or template that creates this runtime DOM.",
-        `  - Rendered element: \`<${tagName}>\``,
-    ];
-    if (text)
-        lines.push(`  - Text evidence: ${promptText(text)}`);
-    if (ariaLabel)
-        lines.push(`  - Accessible name evidence: ${promptText(ariaLabel)}`);
-    if (props)
-        lines.push(`  - Props evidence: ${promptText(props)}`);
-    return lines;
+function elementEvidenceLines(group, example = false) {
+    const evidence = group.runtimeEvidence ?? group.sourceEvidence;
+    return evidence ? targetEvidenceLines(evidence, example)
+        : group.instanceOverride ? targetEvidenceLines(group.instanceOverride.target.locator, example) : [];
+}
+/** Combine identical final requests for individually selected elements. */
+function selectedStyleGroupKey(group) {
+    const requests = group.changes.map((change) => JSON.stringify([elementChangeLine(change), sourceIntentLine(change)])).sort();
+    return JSON.stringify(["selected-styles", requests]);
+}
+function selectedItemLine(group, sourceLocation) {
+    const facts = elementEvidenceLines(group).map((line) => line.slice(2));
+    if (sourceLocation)
+        facts.unshift(`Source: ${promptText(sourceLocation)}`);
+    const invocation = group.instanceOverride?.target.locator.invocation;
+    if (invocation)
+        facts.push(`Component usage: ${promptText(invocation.callsiteId)}`);
+    return `  - ${facts.join("; ") || "Selected element"}`;
+}
+function setHeading(label, tag) {
+    return tag ? `${label} (${promptText(`<${normalizeRuntimeTag(tag)}>`)})` : label;
 }
 /**
  * Coordinate precision follows each element's identity origin, not the
@@ -194,7 +236,7 @@ function hasExactAuthoredCoordinates(policy, cid, file) {
     return policy.exactFileExtensions.some((extension) => file.endsWith(extension));
 }
 /**
- * Formats one source location for a prompt heading. Exact origins keep the
+ * Formats one source location for a prompt. Exact origins keep the
  * authored column; line-only origins — and sites whose column is unknown —
  * degrade to `file:line` rather than fabricating precision.
  */
@@ -204,27 +246,19 @@ function formatSourceLocation(policy, source) {
     }
     return `${source.file}:${source.line}`;
 }
-function elementGroupSource(group, policy) {
-    if (group.runtimeEvidence) {
-        return group.runtimeEvidence.reason === "unannotated"
-            ? "source unknown; no authored location available"
-            : "source unknown; runtime-created DOM";
-    }
-    return formatSourceLocation(policy, group);
-}
 function renderedInstanceDescription(ref) {
     const text = boundedEvidence(ref.locator.text);
     const ariaLabel = boundedEvidence(ref.locator.ariaLabel ?? null);
     const props = boundedEvidence(ref.locator.props);
-    const source = isRuntimeGeneratedSource(ref.sourceSite.src)
-        ? sourceSiteLabel(ref)
-        : ref.sourceSite.src;
+    const source = ref.sourceSite.src && !isRuntimeGeneratedSource(ref.sourceSite.src)
+        ? ` (${ref.sourceSite.src})`
+        : "";
     if (text)
-        return `text ${promptText(text)} (${source})`;
+        return `text ${promptText(text)}${source}`;
     if (ariaLabel)
-        return `the element named ${promptText(ariaLabel)} (${source})`;
+        return `the element named ${promptText(ariaLabel)}${source}`;
     if (props)
-        return `the element with props ${promptText(props)} (${source})`;
+        return `the element with props ${promptText(props)}${source}`;
     // With no semantic evidence, the ordinal is the only way to distinguish
     // repeated outputs from the same source site.
     return `rendered instance ${ref.locator.occurrence + 1} of ${sourceSiteLabel(ref)}`;
@@ -232,7 +266,10 @@ function renderedInstanceDescription(ref) {
 function structuralChangeLine(change) {
     const target = renderedInstanceDescription(change.target);
     if (change.kind === "delete") {
-        return `- Remove ${target} from the source.`;
+        const invocation = change.target.locator.invocation;
+        return invocation
+            ? `- Remove the ${promptText(`<${invocation.componentName}>`)} invocation at ${invocation.callsiteId} from the source; keep its other invocations. It renders ${target}.`
+            : `- Remove ${target} from the source.`;
     }
     const before = change.destination.before;
     const sourceParent = sourceSiteLabel(change.source.parent);
@@ -254,6 +291,7 @@ function renderedInstanceKey(ref) {
         locator.props,
         locator.text,
         locator.ariaLabel ?? null,
+        locator.invocation?.callsiteId ?? null,
     ]);
 }
 /** Export final intent, not the gesture history required to replay the preview. */
@@ -328,82 +366,144 @@ export function generatePrompt(changes, frameworkHints, structuralChanges = [],
             lines: tokenChanges.map(tokenChangeLine),
         });
     }
-    if (componentChanges.length > 0) {
-        const lines = [];
-        for (const change of componentChanges) {
-            const target = change.target;
-            const source = formatSourceLocation(coordinatePolicy, target);
-            lines.push(`### ${target.componentName} invocation (${source})`);
-            lines.push(componentChangeLine(change));
-            lines.push(`  - Component contract: \`${target.componentId}\``);
-            if (change.evidence) {
-                lines.push(`  - Rendered evidence: ${change.evidence.mountedCount} mounted outputs`);
-                if (change.evidence.props)
-                    lines.push(`    - Props evidence: ${promptText(boundedEvidence(change.evidence.props) ?? "")}`);
-                if (change.evidence.ariaLabel)
-                    lines.push(`    - Accessible name evidence: ${promptText(boundedEvidence(change.evidence.ariaLabel) ?? "")}`);
-                lines.push(`    - Before text: ${promptText(change.evidence.beforeText)}`);
-            }
-            lines.push("");
+    const groups = new Map();
+    function groupFor(key, heading, tag) {
+        let group = groups.get(key);
+        if (!group) {
+            group = { heading, details: new Set(), lines: [] };
+            groups.set(key, group);
         }
-        sections.push({ heading: "Component prop changes", lines });
+        if (tag)
+            group.heading = elementLabel(tag);
+        return group;
     }
-    if (elementGroups.length > 0) {
-        const lines = [];
-        for (const group of elementGroups) {
-            const state = group.changes[0]?.state ?? "base";
-            lines.push(`### ${group.cid} (${elementGroupSource(group, coordinatePolicy)}) · ${state}`);
-            if (group.instanceOverride) {
-                lines.push(`- Applies only to ${renderedInstanceDescription(group.instanceOverride.target)}.`);
-            }
-            lines.push(...runtimeEvidenceLines(group));
-            for (const change of group.changes) {
-                lines.push(elementChangeLine(change));
+    for (const change of componentChanges) {
+        const target = change.target;
+        const evidence = change.evidence;
+        const scope = change.scope ?? "source-site";
+        const key = JSON.stringify(["component", target.callsiteId, scope, scope === "rendered-instance"
+                ? [evidence?.occurrence, evidence?.props, evidence?.ariaLabel] : null]);
+        const group = groupFor(key, `${target.componentName} component`);
+        group.lines.push(componentChangeLine(change));
+        group.lines.push(editScopeLine(scope));
+        group.details.add(`- Source: ${promptText(formatSourceLocation(coordinatePolicy, target))}`);
+        if (evidence) {
+            group.details.add(`- Rendered instances: ${evidence.mountedCount}`);
+            if (evidence.props)
+                group.details.add(`- Props: ${promptText(boundedEvidence(evidence.props) ?? "")}`);
+            if (evidence.ariaLabel)
+                group.details.add(`- Accessible name: ${promptText(boundedEvidence(evidence.ariaLabel) ?? "")}`);
+            group.details.add(`- Before text: ${promptText(evidence.beforeText)}`);
+        }
+    }
+    const selectedSets = new Map();
+    for (const element of elementGroups) {
+        if (!element.instanceOverride && element.changes[0]?.sourceInstanceCount !== 1)
+            continue;
+        const key = selectedStyleGroupKey(element);
+        const selected = selectedSets.get(key) ?? [];
+        selected.push(element);
+        selectedSets.set(key, selected);
+    }
+    const exportedSets = new Set();
+    for (const element of elementGroups) {
+        const first = element.changes[0];
+        const runtimeCreated = !!element.runtimeEvidence || !element.file || isRuntimeGeneratedSource(element.file);
+        const src = runtimeCreated ? "" : `${element.file}:${element.line}:${element.column}`;
+        const key = element.instanceOverride ? refPromptKey(element.instanceOverride.target)
+            : first.scope === "rendered-instance" && !runtimeCreated ? `style:${element.key}`
+                : elementPromptKey(element.cid, src, "source-site");
+        const tag = element.runtimeEvidence?.tagName ?? element.sourceEvidence?.tagName;
+        const label = readableTargetLabel(element.runtimeEvidence?.text ?? element.sourceEvidence?.text ?? null, tag);
+        const selectedKey = selectedStyleGroupKey(element);
+        const selected = element.instanceOverride || first.sourceInstanceCount === 1 ? selectedSets.get(selectedKey) ?? [] : [];
+        if (selected.length > 1) {
+            if (exportedSets.has(selectedKey))
+                continue;
+            exportedSets.add(selectedKey);
+            const tags = new Set(selected.map((item) => item.runtimeEvidence?.tagName ?? item.sourceEvidence?.tagName));
+            const group = groupFor(selectedKey, setHeading("Selected elements", tags.size === 1 ? tag : undefined));
+            const locations = selected.map((item) => !item.runtimeEvidence && item.file && !isRuntimeGeneratedSource(item.file)
+                ? formatSourceLocation(coordinatePolicy, item) : null);
+            const sharedLocation = new Set(locations).size === 1 ? locations[0] : null;
+            if (sharedLocation)
+                group.details.add(`- Source: ${promptText(sharedLocation)}`);
+            group.details.add(["- Selected items:", ...selected.map((item, index) => selectedItemLine(item, sharedLocation ? null : locations[index] ?? null))].join("\n"));
+            for (const change of element.changes) {
+                group.lines.push(`${elementChangeLine(change)} for these selected items.`);
                 const intent = sourceIntentLine(change);
                 if (intent)
-                    lines.push(intent);
+                    group.lines.push(intent);
             }
-            lines.push("");
+            continue;
         }
-        sections.push({ heading: "Changes", lines });
-    }
-    if (textChanges.length > 0) {
-        const lines = [];
-        for (const change of textChanges) {
-            const runtimeCreated = isRuntimeGeneratedSource(change.target.sourceSite.src);
-            const textSource = runtimeCreated
-                ? "source unknown; runtime-created DOM"
-                : formatSourceLocation(coordinatePolicy, {
-                    cid: change.target.sourceSite.cid,
-                    file: change.source.file,
-                    line: change.source.line,
-                    column: change.source.column,
-                });
-            lines.push(`### ${change.source.component || change.target.sourceSite.cid} (${textSource})`);
-            lines.push(`- Rendered text: ${promptText(change.before)} → ${promptText(change.after)} — ${textAuthorshipGuidance(change.authoredAs)}`);
-            lines.push(...textScopeLines(change));
-            lines.push(...textEvidenceLines(change.target));
-            lines.push("");
+        const linked = !element.instanceOverride && !runtimeCreated && first.scope !== "rendered-instance"
+            && (element.changes.some((change) => (change.sourceInstanceCount ?? 1) > 1)
+                || first.scope === "source-site" && first.sourceInstanceCount === undefined);
+        const group = groupFor(key, label, tag);
+        if (linked)
+            group.heading = setHeading("Linked elements", tag);
+        if (!runtimeCreated) {
+            group.details.add(`- Source: \`${formatSourceLocation(coordinatePolicy, element)}\``);
+        }
+        for (const detail of elementEvidenceLines(element, linked))
+            group.details.add(detail);
+        for (const change of element.changes) {
+            const targetSet = linked ? " for all items rendered at this source location."
+                : element.instanceOverride ? " for this selected item." : "";
+            group.lines.push(`${elementChangeLine(change)}${targetSet}`);
+            const intent = sourceIntentLine(change);
+            if (intent)
+                group.lines.push(intent);
         }
-        sections.push({ heading: "Rendered text changes", lines });
     }
-    if (structuralIntent.length > 0) {
-        sections.push({
-            heading: "Structural changes",
-            lines: structuralIntent.map(structuralChangeLine),
+    for (const change of textChanges) {
+        const target = change.target;
+        const runtimeCreated = !target.sourceSite.src || isRuntimeGeneratedSource(target.sourceSite.src);
+        const scope = change.scope ?? "rendered-instance";
+        const key = elementPromptKey(target.sourceSite.cid, target.sourceSite.src, scope, {
+            kind: "evidence", occurrence: target.occurrence, props: target.props, text: target.beforeText, ariaLabel: target.ariaLabel,
         });
-    }
-    if (comments.length > 0) {
-        sections.push({
-            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)}`,
-                "",
-            ]),
+        const group = groupFor(key, readableTargetLabel(change.before, target.tagName), target.tagName);
+        const sourceLocation = runtimeCreated ? null : formatSourceLocation(coordinatePolicy, {
+            cid: target.sourceSite.cid, ...change.source,
         });
+        if (sourceLocation)
+            group.details.add(`- Source: ${promptText(sourceLocation)}`);
+        group.lines.push(`- **Change:** Replace text ${promptText(change.before)} with ${promptText(change.after)}.`);
+        if (change.scope)
+            group.lines.push(editScopeLine(change.scope));
+        if (change.authoredAs === "expression")
+            group.lines.push("  - Preserve the expression and update its source logic.");
+        group.lines.push(...textBindingLines(change, sourceLocation));
+        for (const detail of targetEvidenceLines({
+            ...target, text: group.heading.startsWith("Text:") ? null : target.beforeText,
+        }))
+            group.details.add(detail);
+    }
+    for (const change of structuralIntent) {
+        const ref = change.target;
+        const group = groupFor(refPromptKey(ref), readableTargetLabel(ref.locator.text));
+        group.lines.push(structuralChangeLine(change));
+    }
+    for (const comment of comments) {
+        const ref = comment.target;
+        const runtimeCreated = !ref.sourceSite.src || isRuntimeGeneratedSource(ref.sourceSite.src);
+        const group = groupFor(refPromptKey(ref), elementLabel(comment.tag), comment.tag);
+        if (!runtimeCreated) {
+            const parsed = /^(.*):(\d+):(\d+)$/.exec(ref.sourceSite.src);
+            const location = parsed ? formatSourceLocation(coordinatePolicy, {
+                cid: ref.sourceSite.cid, file: parsed[1], line: Number(parsed[2]), column: Number(parsed[3]),
+            }) : ref.sourceSite.src;
+            group.details.add(`- Source: ${promptText(location)}`);
+        }
+        group.details.add(`- Page: ${promptText(comment.route)}`);
+        for (const detail of targetEvidenceLines(ref.locator))
+            group.details.add(detail);
+        group.lines.push(`- **Note:** ${promptText(comment.note)}`);
+    }
+    for (const group of groups.values()) {
+        sections.push({ heading: group.heading, lines: group.details.size > 0 ? [...group.details, "", ...group.lines] : group.lines });
     }
     return renderPrompt(sections, customInstructions);
 }

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

@@ -0,0 +1,3 @@
+export declare const PROMPT_TITLE = "# Requested design changes";
+/** Keeps the title first when a host adds page or iteration instructions. */
+export declare function withPromptContext(context: readonly string[], prompt: string): string;

package/dist/inspector/prompt/promptDocument.js

@@ -0,0 +1,8 @@
+export const PROMPT_TITLE = "# Requested design changes";
+/** Keeps the title first when a host adds page or iteration instructions. */
+export function withPromptContext(context, prompt) {
+    const body = prompt === PROMPT_TITLE || prompt.startsWith(`${PROMPT_TITLE}\n`)
+        ? prompt.slice(PROMPT_TITLE.length).trimStart()
+        : prompt;
+    return [PROMPT_TITLE, "", ...context, ...(body.trim() ? ["", body] : [])].join("\n");
+}

package/dist/inspector/prompt/promptSettings.js

@@ -1,3 +1,5 @@
+import { inspectorStorage } from "../runtime/inspectorStorage.js";
+import { isDemoRuntime } from "../runtime/runtimeConfig.js";
 /** The default guidance included in every generated prompt. */
 export const DEFAULT_CUSTOM_INSTRUCTIONS = "Preserve existing tokens, logical properties, and CSS intent while applying these rendered changes.";
 function storageKey(projectId) {
@@ -5,10 +7,10 @@ function storageKey(projectId) {
 }
 /** Reads the project-scoped custom prompt instructions from browser storage. */
 export function loadCustomInstructions(projectId) {
-    if (typeof localStorage === "undefined")
+    if (isDemoRuntime())
         return DEFAULT_CUSTOM_INSTRUCTIONS;
     try {
-        return localStorage.getItem(storageKey(projectId)) ?? DEFAULT_CUSTOM_INSTRUCTIONS;
+        return inspectorStorage()?.getItem(storageKey(projectId)) ?? DEFAULT_CUSTOM_INSTRUCTIONS;
     }
     catch {
         return DEFAULT_CUSTOM_INSTRUCTIONS;
@@ -16,10 +18,10 @@ export function loadCustomInstructions(projectId) {
 }
 /** Persists custom prompt instructions without making storage availability a prerequisite for editing. */
 export function saveCustomInstructions(projectId, instructions) {
-    if (typeof localStorage === "undefined")
-        return;
+    if (isDemoRuntime())
+        return; // demo runtimes never persist
     try {
-        localStorage.setItem(storageKey(projectId), instructions);
+        inspectorStorage()?.setItem(storageKey(projectId), instructions);
     }
     catch {
         // Storage can be disabled or full; the in-memory UI state still applies.

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

@@ -0,0 +1,17 @@
+/** The synchronous subset of `Storage` that inspector persistence uses. */
+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>;
+}
+/** Replaces `localStorage` for inspector-owned state, for example with extension storage. */
+export declare function configureInspectorStorage(storage: InspectorStorage | null): void;
+/** The configured storage, else `localStorage`; null where neither exists. */
+export declare function inspectorStorage(): InspectorStorage | null;
+/**
+ * Serves reads from a snapshot loaded before boot and forwards each write.
+ * Asynchronous backends stay behind the synchronous interface callers expect.
+ */
+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,42 @@
+let configured = null;
+/** Replaces `localStorage` for inspector-owned state, for example with extension storage. */
+export function configureInspectorStorage(storage) {
+    configured = storage;
+}
+/** The configured storage, else `localStorage`; null where neither exists. */
+export function inspectorStorage() {
+    if (configured)
+        return configured;
+    return typeof localStorage === "undefined" ? null : localStorage;
+}
+/**
+ * Serves reads from a snapshot loaded before boot and forwards each write.
+ * Asynchronous backends stay behind the synchronous interface callers expect.
+ */
+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);
+            },
+        } : {}),
+    };
+}