@contentful/experience-design-system-cli 2.12.0 → 2.12.1-dev-build-bae15c7.0

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experience-design-system-cli",
-  "version": "2.12.0",
+  "version": "2.12.1-dev-build-bae15c7.0",
   "description": "Contentful Experiences design system import CLI",
   "license": "MIT",
   "type": "module",

package/dist/src/analyze/extract/astro.js

@@ -108,6 +108,8 @@ function extractPropsFromFrontmatter(frontmatter) {
                 type: typeText,
                 required,
                 ...(allowedValues && { allowedValues }),
+                sourceStartLine: member.getStartLineNumber(),
+                sourceEndLine: member.getEndLineNumber(),
             });
         }
     }
@@ -127,6 +129,12 @@ function extractPropsFromFrontmatter(frontmatter) {
                 type: typeText,
                 required,
                 ...(allowedValues && { allowedValues }),
+                ...(typeof decl.getStartLineNumber === 'function'
+                    ? {
+                        sourceStartLine: decl.getStartLineNumber(),
+                        sourceEndLine: decl.getEndLineNumber(),
+                    }
+                    : {}),
             });
         }
     }
@@ -236,6 +244,7 @@ function extractFromAstroFile(filePath, source) {
     return {
         name,
         source: filePath,
+        sourcePath: filePath,
         framework: 'astro',
         props: propsWithDefaults,
         slots,

package/dist/src/analyze/extract/react.js

@@ -485,6 +485,12 @@ function extractPropsFromTypeSymbols(type, slotNames, suppressNeverChildrenSlot
             type: typeText,
             required,
             ...(allowedValues && { allowedValues }),
+            ...(typeof declaration.getStartLineNumber === 'function'
+                ? {
+                    sourceStartLine: declaration.getStartLineNumber(),
+                    sourceEndLine: declaration.getEndLineNumber(),
+                }
+                : {}),
         });
     }
     return {
@@ -539,6 +545,12 @@ function extractPropsFromInterfaceDeclaration(declaration, slotNames, seen, excl
                 type: typeText,
                 required,
                 ...(allowedValues && { allowedValues }),
+                ...(typeof decl.getStartLineNumber === 'function'
+                    ? {
+                        sourceStartLine: decl.getStartLineNumber(),
+                        sourceEndLine: decl.getEndLineNumber(),
+                    }
+                    : {}),
             });
             return acc;
         }, { props: [], hasChildren: false })
@@ -921,6 +933,13 @@ function extractDestructuredBindingFallbackProps(func, param, existingPropNames,
                 name: propName,
                 type: propertyType === 'unknown' ? 'any' : propertyType,
                 required: property ? !property.isOptional() : false,
+                ...(declaration &&
+                    typeof declaration.getStartLineNumber === 'function'
+                    ? {
+                        sourceStartLine: declaration.getStartLineNumber(),
+                        sourceEndLine: declaration.getEndLineNumber(),
+                    }
+                    : {}),
             });
         }
     }
@@ -1674,6 +1693,7 @@ function extractFromSourceFile(sourceFile, isNext) {
             components.push({
                 name,
                 source: sourceFile.getFilePath(),
+                sourcePath: sourceFile.getFilePath(),
                 framework: isNext ? 'next' : 'react',
                 props: [],
                 slots: [],
@@ -1759,6 +1779,7 @@ function extractFromSourceFile(sourceFile, isNext) {
         components.push({
             name,
             source: sourceFile.getFilePath(),
+            sourcePath: sourceFile.getFilePath(),
             framework: isNext ? 'next' : 'react',
             props: propsAfterSlotExpansion,
             slots: finalSlots,
@@ -1823,6 +1844,8 @@ function extractPropTypes(sourceFile, componentName) {
                 type,
                 required,
                 ...(allowedValues && { allowedValues }),
+                sourceStartLine: property.getStartLineNumber(),
+                sourceEndLine: property.getEndLineNumber(),
             });
         }
         return props.sort((a, b) => a.name.localeCompare(b.name));

package/dist/src/analyze/extract/stencil.js

@@ -99,6 +99,8 @@ function extractProps(classDecl) {
             ...(defaultValue !== undefined && { defaultValue }),
             ...(description && { description }),
             ...(allowedValues && { allowedValues }),
+            sourceStartLine: property.getStartLineNumber(),
+            sourceEndLine: property.getEndLineNumber(),
         });
     }
     return props.sort((a, b) => a.name.localeCompare(b.name));
@@ -231,6 +233,7 @@ function extractFromSourceFile(sourceFile, warnings) {
         components.push({
             name,
             source: sourceFile.getFilePath(),
+            sourcePath: sourceFile.getFilePath(),
             framework: 'stencil',
             props,
             slots,

package/dist/src/analyze/extract/vue.js

@@ -78,6 +78,7 @@ async function extractFromVueSFC(filePath, source) {
         component: {
             name,
             source: filePath,
+            sourcePath: filePath,
             framework: 'vue',
             props,
             slots,
@@ -104,6 +105,7 @@ async function extractOptionsComponent(filePath, scriptContent, fileWarnings, na
         component: {
             name,
             source: filePath,
+            sourcePath: filePath,
             framework: 'vue',
             props,
             slots,
@@ -552,6 +554,8 @@ function parseObjectProps(obj) {
                 name,
                 type: VUE_TYPE_MAP[initText] ?? 'any',
                 required: false,
+                sourceStartLine: prop.getStartLineNumber(),
+                sourceEndLine: prop.getEndLineNumber(),
             });
             continue;
         }
@@ -585,6 +589,8 @@ function parseObjectProps(obj) {
             type,
             required,
             ...(defaultValue !== undefined && { defaultValue }),
+            sourceStartLine: prop.getStartLineNumber(),
+            sourceEndLine: prop.getEndLineNumber(),
         });
     }
     return result;

package/dist/src/analyze/extract/web-components.js

@@ -364,6 +364,8 @@ function extractClassProperties(classDecl, applyRuntimeFieldDenylist = false) {
             type,
             required: false,
             ...(defaultValue !== undefined && { defaultValue }),
+            sourceStartLine: property.getStartLineNumber(),
+            sourceEndLine: property.getEndLineNumber(),
         });
     }
     return props;
@@ -417,10 +419,17 @@ function extractAccessorProperties(classDecl, applyRuntimeFieldDenylist = false)
         if (!hasPropertyDecorator && !(getter && setter))
             continue;
         const type = getter?.getReturnTypeNode()?.getText() ?? setter?.getParameters()[0]?.getTypeNode()?.getText() ?? 'any';
+        const accessorNode = getter ?? setter;
         props.push({
             name,
             type,
             required: false,
+            ...(accessorNode
+                ? {
+                    sourceStartLine: accessorNode.getStartLineNumber(),
+                    sourceEndLine: accessorNode.getEndLineNumber(),
+                }
+                : {}),
         });
     }
     return props;
@@ -824,6 +833,7 @@ function extractFromSourceFile(sourceFile, project) {
         components.push({
             name,
             source: sourceFile.getFilePath(),
+            sourcePath: sourceFile.getFilePath(),
             framework: 'web-component',
             props,
             slots,

package/dist/src/analyze/pre-classify.d.ts

@@ -1,7 +1,7 @@
 import type { RawPropDefinition, RawComponentDefinition } from '../types.js';
 export interface PreClassification {
     category: 'content' | 'design' | 'state' | 'exclude';
-    cdfTypeHint?: 'string' | 'enum' | 'richtext' | 'media';
+    cdfTypeHint?: 'string' | 'enum' | 'richtext' | 'media' | 'boolean';
 }
 /**
  * Deterministic pre-classification rule engine.

package/dist/src/analyze/pre-classify.js

@@ -142,14 +142,14 @@ export function preClassifyProp(prop) {
     if (isBooleanType(type)) {
         const stateNames = ['disabled', 'loading', 'expanded', 'isOpen', 'selected', 'checked', 'active', 'preview'];
         if (stateNames.includes(name)) {
-            return { category: 'state', cdfTypeHint: 'string' };
+            return { category: 'state', cdfTypeHint: 'boolean' };
         }
     }
     // Rule 9: Boolean + visual toggle name
     if (isBooleanType(type)) {
         const visualToggle = /^(hide|show|enable|disable|vertical|horizontal|reverse|bold|italic|imageOn|with)/i;
         if (visualToggle.test(name)) {
-            return { category: 'design', cdfTypeHint: 'string' };
+            return { category: 'design', cdfTypeHint: 'boolean' };
         }
     }
     // Rule 11: State identifiers
@@ -178,7 +178,7 @@ export function preClassifyProp(prop) {
     }
     // Rule 15: Remaining booleans
     if (isBooleanType(type)) {
-        return { category: 'design', cdfTypeHint: 'string' };
+        return { category: 'design', cdfTypeHint: 'boolean' };
     }
     // Rule 16: Remaining numbers
     if (isNumberType(type)) {

package/dist/src/analyze/select/persistence.d.ts

@@ -1,3 +1,4 @@
+import type { DatabaseSync } from 'node:sqlite';
 import type { ReviewSessionPaths, ReviewSessionSnapshot } from './types.js';
 export declare function getRefineArtifactsRoot(): string;
 export declare function getRefineSessionPaths(sessionId: string, artifactsRoot: string): Promise<ReviewSessionPaths>;
@@ -7,3 +8,15 @@ export declare function appendReviewEvent(eventsPath: string, event: {
     payload: Record<string, unknown>;
 }): Promise<void>;
 export declare function ensureRefineSession(sessionId: string, artifactsRoot: string, initialSnapshot: ReviewSessionSnapshot): Promise<ReviewSessionSnapshot>;
+/**
+ * Persist scope-gate decisions to `current-review-state.json` so downstream
+ * consumers (notably `loadAcceptedNames` in `generate components`) can filter
+ * out rejected components. The wizard's scope-gate doesn't drive the rich
+ * `analyze select` TUI, so fields that file consumes (resolvedSourcePath,
+ * sourceCode) are populated with safe placeholders. Only `name` and `status`
+ * matter for `loadAcceptedNames`.
+ */
+export declare function writeScopeDecisionsSnapshot(db: DatabaseSync, sessionId: string, decisions: {
+    accepted: string[];
+    rejected: string[];
+}): Promise<void>;

package/dist/src/analyze/select/persistence.js

@@ -1,6 +1,7 @@
 import { access, appendFile, mkdir, readFile, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { resolve } from 'node:path';
+import { loadRawComponents } from '../../session/db.js';
 export function getRefineArtifactsRoot() {
     if (process.env.EDS_REVIEW_ARTIFACTS_DIR) {
         return resolve(process.env.EDS_REVIEW_ARTIFACTS_DIR);
@@ -40,3 +41,40 @@ export async function ensureRefineSession(sessionId, artifactsRoot, initialSnaps
         return initialSnapshot;
     }
 }
+/**
+ * Persist scope-gate decisions to `current-review-state.json` so downstream
+ * consumers (notably `loadAcceptedNames` in `generate components`) can filter
+ * out rejected components. The wizard's scope-gate doesn't drive the rich
+ * `analyze select` TUI, so fields that file consumes (resolvedSourcePath,
+ * sourceCode) are populated with safe placeholders. Only `name` and `status`
+ * matter for `loadAcceptedNames`.
+ */
+export async function writeScopeDecisionsSnapshot(db, sessionId, decisions) {
+    const acceptedSet = new Set(decisions.accepted);
+    const rawComponents = loadRawComponents(db, sessionId);
+    const records = rawComponents.map((c) => {
+        const status = acceptedSet.has(c.name) ? 'accepted' : 'rejected';
+        const proposal = {
+            name: c.name,
+            source: c.source,
+            framework: c.framework,
+            props: c.props,
+            slots: c.slots,
+            ...(c.extractionConfidence !== undefined ? { extractionConfidence: c.extractionConfidence } : {}),
+            ...(c.reviewReasons !== undefined ? { reviewReasons: c.reviewReasons } : {}),
+            ...(c.needsReview !== undefined ? { needsReview: c.needsReview } : {}),
+        };
+        return {
+            id: c.component_id,
+            name: c.name,
+            resolvedSourcePath: '',
+            sourceCode: null,
+            originalProposal: proposal,
+            editedProposal: proposal,
+            status,
+        };
+    });
+    const paths = await getRefineSessionPaths(sessionId, getRefineArtifactsRoot());
+    await mkdir(paths.sessionDir, { recursive: true });
+    await saveReviewState(paths.statePath, { components: records });
+}

package/dist/src/analyze/select/preview-annotations.d.ts

@@ -0,0 +1,26 @@
+import type { ServerPreviewResponse } from '@contentful/experience-design-system-types';
+import type { PreviewAnnotation } from './types.js';
+/**
+ * Pure mapper from a `ServerPreviewResponse` to a per-component-name
+ * `PreviewAnnotation` map. Consumed by the wizard's final-review sidebar
+ * (and any other surface that wants to render diff badges next to a
+ * component row).
+ *
+ * The `new` bucket of `ServerPreviewResponse.components` is `CDFComponentEntry[]`
+ * — those entries do NOT carry a `name` field on the wire (the name is the
+ * KEY in the parent manifest). So instead of trying to read names off entries,
+ * we derive the "new" set as:
+ *
+ *   new = localNames \ (unchangedNames ∪ changedNames ∪ removedNames)
+ *
+ * Callers must pass the local manifest's component keys as `localNames` so
+ * we can perform the set difference. Removed components from the server that
+ * aren't in the local manifest are still annotated as `'removed'` (so the
+ * detail panel can list them).
+ *
+ * Precedence: `breaking` > `changed` > `removed` > `new`.
+ *
+ * Unchanged entries are omitted from the map — callers should treat
+ * `map.get(name) === undefined` as "no annotation".
+ */
+export declare function applyPreviewAnnotations(preview: ServerPreviewResponse, localNames: readonly string[]): Map<string, PreviewAnnotation>;

package/dist/src/analyze/select/preview-annotations.js

@@ -0,0 +1,62 @@
+/**
+ * Pure mapper from a `ServerPreviewResponse` to a per-component-name
+ * `PreviewAnnotation` map. Consumed by the wizard's final-review sidebar
+ * (and any other surface that wants to render diff badges next to a
+ * component row).
+ *
+ * The `new` bucket of `ServerPreviewResponse.components` is `CDFComponentEntry[]`
+ * — those entries do NOT carry a `name` field on the wire (the name is the
+ * KEY in the parent manifest). So instead of trying to read names off entries,
+ * we derive the "new" set as:
+ *
+ *   new = localNames \ (unchangedNames ∪ changedNames ∪ removedNames)
+ *
+ * Callers must pass the local manifest's component keys as `localNames` so
+ * we can perform the set difference. Removed components from the server that
+ * aren't in the local manifest are still annotated as `'removed'` (so the
+ * detail panel can list them).
+ *
+ * Precedence: `breaking` > `changed` > `removed` > `new`.
+ *
+ * Unchanged entries are omitted from the map — callers should treat
+ * `map.get(name) === undefined` as "no annotation".
+ */
+export function applyPreviewAnnotations(preview, localNames) {
+    const out = new Map();
+    const unchanged = new Set(preview.components.unchanged);
+    // Annotate changed first; collect their names so we can exclude from "new".
+    const changedNames = new Set();
+    for (const item of preview.components.changed) {
+        const name = item.current?.name;
+        if (typeof name !== 'string')
+            continue;
+        changedNames.add(name);
+        if (item.changeClassification?.classification === 'breaking') {
+            out.set(name, 'breaking');
+        }
+        else {
+            out.set(name, 'changed');
+        }
+    }
+    // Annotate removed.
+    const removedNames = new Set();
+    for (const entity of preview.components.removed) {
+        if (entity.name) {
+            removedNames.add(entity.name);
+            out.set(entity.name, 'removed');
+        }
+    }
+    // Derive `new` = localNames \ (unchanged ∪ changed ∪ removed).
+    for (const name of localNames) {
+        if (unchanged.has(name))
+            continue;
+        if (changedNames.has(name))
+            continue;
+        if (removedNames.has(name))
+            continue;
+        if (out.has(name))
+            continue;
+        out.set(name, 'new');
+    }
+    return out;
+}

package/dist/src/analyze/select/tui/App.js

@@ -363,8 +363,11 @@ export function App({ sessionId, artifactsRoot, reviewRoot }) {
     const collapsed = terminalWidth < 80;
     const visibleCount = 20;
     const longestName = session.components.reduce((max, c) => Math.max(max, c.name.length), 0);
-    // icon + space + name + 2 border chars; min 14, max 22
-    const sidebarWidth = collapsed ? 3 : Math.min(Math.max(longestName + 4, 14), 22);
+    // icon + badge + space + name + 2 border chars; min 14, max 22.
+    // The badge column is reserved (pilot R2) even when no annotation is set —
+    // see Sidebar.previewBadge — so the column width is stable as live-preview
+    // annotations flip in/out.
+    const sidebarWidth = collapsed ? 3 : Math.min(Math.max(longestName + 5, 14), 22);
     const handleDraftSave = async (draft) => {
         if (!selectedId || !session || !paths)
             return;

package/dist/src/analyze/select/tui/components/ComponentRationalePanel.d.ts

@@ -0,0 +1,30 @@
+import React from 'react';
+import type { ComponentRationale } from '../../../../session/db.js';
+export type ComponentRationalePanelProps = {
+    data: ComponentRationale;
+    scrollOffset: number;
+    width: number;
+    height: number;
+    active: boolean;
+};
+type RenderedLine = {
+    kind: 'heading';
+    text: string;
+} | {
+    kind: 'text';
+    text: string;
+    dim?: boolean;
+} | {
+    kind: 'list-name';
+    text: string;
+    sublabel?: string;
+} | {
+    kind: 'blank';
+};
+/**
+ * Flatten the component rationale into a list of rendered lines so scrollOffset
+ * slicing matches what the operator sees.
+ */
+export declare function renderComponentRationaleLines(data: ComponentRationale, innerWidth: number): RenderedLine[];
+export declare function ComponentRationalePanel({ data, scrollOffset, width, height, active, }: ComponentRationalePanelProps): React.ReactElement;
+export {};

package/dist/src/analyze/select/tui/components/ComponentRationalePanel.js

@@ -0,0 +1,137 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+const PLACEHOLDER = '(no rationale captured)';
+/**
+ * Word-wrap a paragraph to fit `innerWidth` columns. Mirrors the helper in
+ * RationalePanel.tsx so wrapping is identical across both panels.
+ */
+function wrapText(text, innerWidth) {
+    if (!text)
+        return [''];
+    const width = Math.max(1, innerWidth);
+    const words = text.split(/\s+/).filter((w) => w.length > 0);
+    if (words.length === 0)
+        return [''];
+    const lines = [];
+    let current = '';
+    for (const w of words) {
+        if (current.length === 0) {
+            if (w.length > width) {
+                let rest = w;
+                while (rest.length > width) {
+                    lines.push(rest.slice(0, width));
+                    rest = rest.slice(width);
+                }
+                current = rest;
+            }
+            else {
+                current = w;
+            }
+            continue;
+        }
+        if (current.length + 1 + w.length <= width) {
+            current += ' ' + w;
+        }
+        else {
+            lines.push(current);
+            if (w.length > width) {
+                let rest = w;
+                while (rest.length > width) {
+                    lines.push(rest.slice(0, width));
+                    rest = rest.slice(width);
+                }
+                current = rest;
+            }
+            else {
+                current = w;
+            }
+        }
+    }
+    if (current.length > 0)
+        lines.push(current);
+    return lines.length > 0 ? lines : [''];
+}
+/**
+ * Flatten the component rationale into a list of rendered lines so scrollOffset
+ * slicing matches what the operator sees.
+ */
+export function renderComponentRationaleLines(data, innerWidth) {
+    const out = [];
+    const pushSection = (heading, body) => {
+        out.push({ kind: 'heading', text: heading });
+        const text = body && body.trim().length > 0 ? body : PLACEHOLDER;
+        for (const ln of wrapText(text, Math.max(1, innerWidth - 2))) {
+            out.push({ kind: 'text', text: '  ' + ln, dim: !body });
+        }
+        out.push({ kind: 'blank' });
+    };
+    // "Description" section shows the human-facing component description.
+    // The `descriptionRationale` (WHY the component was classified this way)
+    // is appended as a small "why" line so the operator can see the LLM's
+    // reasoning without leaving the panel.
+    out.push({ kind: 'heading', text: 'Description' });
+    const descBody = data.description && data.description.trim().length > 0 ? data.description : PLACEHOLDER;
+    for (const ln of wrapText(descBody, Math.max(1, innerWidth - 2))) {
+        out.push({ kind: 'text', text: '  ' + ln, dim: !data.description });
+    }
+    if (data.descriptionRationale && data.descriptionRationale.trim().length > 0) {
+        for (const ln of wrapText(`why: ${data.descriptionRationale}`, Math.max(1, innerWidth - 2))) {
+            out.push({ kind: 'text', text: '  ' + ln, dim: true });
+        }
+    }
+    out.push({ kind: 'blank' });
+    pushSection('Why these props', data.propsRationale);
+    pushSection('Why these slots', data.slotsRationale);
+    out.push({ kind: 'heading', text: 'Props' });
+    if (data.props.length === 0) {
+        out.push({ kind: 'text', text: '  ' + PLACEHOLDER, dim: true });
+    }
+    else {
+        for (const p of data.props) {
+            const sub = p.category ? `(${p.category})` : undefined;
+            out.push({ kind: 'list-name', text: p.name, sublabel: sub });
+            const text = p.rationale && p.rationale.trim().length > 0 ? p.rationale : PLACEHOLDER;
+            for (const ln of wrapText(text, Math.max(1, innerWidth - 4))) {
+                out.push({ kind: 'text', text: '    ' + ln, dim: !p.rationale });
+            }
+        }
+    }
+    out.push({ kind: 'blank' });
+    out.push({ kind: 'heading', text: 'Slots' });
+    if (data.slots.length === 0) {
+        out.push({ kind: 'text', text: '  ' + PLACEHOLDER, dim: true });
+    }
+    else {
+        for (const s of data.slots) {
+            out.push({ kind: 'list-name', text: s.name });
+            const text = s.rationale && s.rationale.trim().length > 0 ? s.rationale : PLACEHOLDER;
+            for (const ln of wrapText(text, Math.max(1, innerWidth - 4))) {
+                out.push({ kind: 'text', text: '    ' + ln, dim: !s.rationale });
+            }
+        }
+    }
+    return out;
+}
+export function ComponentRationalePanel({ data, scrollOffset, width, height, active, }) {
+    const innerWidth = Math.max(1, width - 2);
+    const all = renderComponentRationaleLines(data, innerWidth);
+    const totalLines = all.length;
+    // Reserve one line at the bottom for the legend.
+    const contentHeight = Math.max(1, height - 1);
+    const visible = all.slice(scrollOffset, scrollOffset + contentHeight);
+    const overflowed = totalLines > contentHeight;
+    const visibleStart = totalLines === 0 ? 0 : scrollOffset + 1;
+    const visibleEnd = Math.min(totalLines, scrollOffset + contentHeight);
+    return (_jsxs(Box, { flexDirection: "column", width: width, height: height + 2, borderStyle: "single", borderColor: active ? 'white' : undefined, children: [_jsx(Box, { children: _jsx(Text, { bold: true, dimColor: !active, children: `Component rationale: ${data.name}` }) }), visible.map((line, i) => {
+                if (line.kind === 'blank') {
+                    return (_jsx(Box, { children: _jsx(Text, { children: " " }) }, i));
+                }
+                if (line.kind === 'heading') {
+                    return (_jsx(Box, { children: _jsx(Text, { bold: true, color: "cyan", dimColor: !active, children: line.text }) }, i));
+                }
+                if (line.kind === 'list-name') {
+                    return (_jsxs(Box, { children: [_jsx(Text, { children: '  - ' }), _jsx(Text, { bold: true, dimColor: !active, children: line.text }), line.sublabel ? _jsx(Text, { dimColor: true, children: ' ' + line.sublabel }) : null] }, i));
+                }
+                return (_jsx(Box, { children: _jsx(Text, { dimColor: !active || line.dim, children: line.text }) }, i));
+            }), _jsx(Box, { children: overflowed ? (_jsx(Text, { dimColor: true, children: `${visibleStart}-${visibleEnd}/${totalLines}    [j/k] scroll    [I/Esc] close` })) : (_jsx(Text, { dimColor: true, children: '[I/Esc] close' })) })] }));
+}

package/dist/src/analyze/select/tui/components/FieldEditor.d.ts

@@ -1,11 +1,68 @@
 import React from 'react';
+/** Per-prop / per-component metadata captured by the extractor + generate phase.
+ * Optional; when omitted, the FieldEditor renders without rationale/source
+ * affordances (backwards-compatible with mounts that pre-date Feature 1). */
+export type PropMetadata = {
+    rationale?: string | null;
+    sourceStartLine?: number | null;
+    sourceEndLine?: number | null;
+};
+export type FieldEditorMetadata = {
+    /** Absolute path to the component's source file. Null/undefined = unknown. */
+    sourcePath?: string | null;
+    /** Full source text of the component (used by the source-view panel). */
+    componentSource?: string | null;
+    /** Per-prop metadata keyed by prop name. */
+    props?: Record<string, PropMetadata>;
+};
 type FieldEditorProps = {
     value: string;
     width: number;
     height: number;
+    /**
+     * When false, the editor is mounted but does not consume keystrokes.
+     * Used by callers (e.g. GenerateReviewStep) that toggle focus between
+     * a sidebar and this editor — the editor stays visible while the sidebar
+     * has the keyboard.
+     */
+    active?: boolean;
     onChange: (value: string) => void;
     onSave: () => void;
     onDiscard: () => void;
+    /**
+     * Called when the user requests to exit the panel from row-level (Esc).
+     * Distinct from onDiscard, which drops pending edits without changing focus.
+     * Callers that embed FieldEditor inside a sidebar+panel layout wire this to
+     * return focus to the sidebar (e.g. setSidebarFocused(true)). When omitted,
+     * row-level Esc falls back to onDiscard for backward compatibility.
+     */
+    onExit?: () => void;
+    /** Feature 1: source code + LLM rationale metadata. Optional. */
+    metadata?: FieldEditorMetadata;
+    /**
+     * When provided, the parent owns the prop-rationale panel: pressing `i`
+     * inside FieldEditor calls this callback (subject to text-entry gating)
+     * instead of toggling internal state. The panel is rendered by the parent
+     * in place of FieldEditor — FieldEditor no longer renders its own panel.
+     */
+    onTogglePropRationale?: () => void;
+    /**
+     * When provided, the parent owns the component-rationale panel: pressing
+     * `I` (uppercase) calls this callback (subject to text-entry gating).
+     */
+    onToggleComponentRationale?: () => void;
+    /**
+     * When provided, the parent owns the source-view panel: pressing `s`
+     * calls this callback (subject to text-entry gating). FieldEditor will not
+     * render its own source panel in that case.
+     */
+    onToggleSourceExternal?: () => void;
+    /**
+     * Reports text-entry-active state changes to the parent so the parent can
+     * gate top-level keybinds (i/I/s) against literal keystrokes inside
+     * description editors, string default editors, and value-list text entry.
+     */
+    onTextEntryActiveChange?: (active: boolean) => void;
 };
-export declare function FieldEditor({ value, width, height, onChange, onSave, onDiscard, }: FieldEditorProps): React.ReactElement;
+export declare function FieldEditor({ value, width, height, active, onChange, onSave, onDiscard, onExit, metadata, onTogglePropRationale, onToggleComponentRationale, onToggleSourceExternal, onTextEntryActiveChange, }: FieldEditorProps): React.ReactElement;
 export {};