@contentful/experience-design-system-cli 2.11.4-dev-build-d47ab65.0 → 2.12.1-dev-build-589b615.0

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

@@ -1,8 +1,9 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { useState } from 'react';
+import React, { useState } from 'react';
 import { Box, Text } from 'ink';
 import { CDF_PROPERTY_TYPES, CDF_PROPERTY_CATEGORIES, DESIGN_TOKEN_TYPES, } from '@contentful/experience-design-system-types';
 import { useImmediateInput } from '../hooks/useImmediateInput.js';
+import { computeNextScrollOffset } from '../hooks/scroll-offset.js';
 // Section indices for top-level navigation
 // 0 = component $description row
 // 1 = $properties header (then props[0..n-1])
@@ -39,9 +40,21 @@ function parseToState(json) {
     const rawProps = (component.$properties ?? {});
     const props = Object.entries(rawProps).map(([name, raw]) => {
         const p = (raw ?? {});
+        const type = CDF_PROPERTY_TYPES.includes(p.$type) ? p.$type : 'string';
+        let defaultValue = null;
+        if (p.$default !== undefined && p.$default !== null) {
+            if (type === 'boolean') {
+                defaultValue = typeof p.$default === 'boolean' ? p.$default : null;
+            }
+            else {
+                // Store as string for string/number/token/enum. Numbers/JSON values
+                // are stringified — downstream serialization re-emits the string.
+                defaultValue = typeof p.$default === 'string' ? p.$default : String(p.$default);
+            }
+        }
         return {
             name,
-            type: CDF_PROPERTY_TYPES.includes(p.$type) ? p.$type : 'string',
+            type,
             category: CDF_PROPERTY_CATEGORIES.includes(p.$category)
                 ? p.$category
                 : 'content',
@@ -49,6 +62,7 @@ function parseToState(json) {
             description: typeof p.$description === 'string' ? p.$description : '',
             values: Array.isArray(p.$values) ? p.$values.filter((v) => typeof v === 'string') : [],
             tokenKind: typeof p['$token.kind'] === 'string' ? p['$token.kind'] : '',
+            default: defaultValue,
         };
     });
     const rawSlots = (component.$slots ?? {});
@@ -58,6 +72,9 @@ function parseToState(json) {
             name,
             description: typeof s.$description === 'string' ? s.$description : '',
             required: s.$required === true,
+            allowedComponents: Array.isArray(s.$allowedComponents)
+                ? s.$allowedComponents.filter((v) => typeof v === 'string')
+                : [],
         };
     });
     return { state: { componentDescription, props, slots }, error: null };
@@ -92,6 +109,19 @@ function serializeState(state, originalJson) {
             def.$values = p.values;
         if (p.type === 'token' && p.tokenKind)
             def['$token.kind'] = p.tokenKind;
+        // $default — gated per type so e.g. boolean props don't get string defaults.
+        // Empty string == unset for text-typed defaults. richtext/media/link don't
+        // emit a default (defaults aren't meaningful for those types).
+        if (p.default !== null) {
+            if (p.type === 'boolean' && typeof p.default === 'boolean') {
+                def.$default = p.default;
+            }
+            else if ((p.type === 'string' || p.type === 'token' || p.type === 'enum') &&
+                typeof p.default === 'string' &&
+                p.default !== '') {
+                def.$default = p.default;
+            }
+        }
         $properties[p.name] = def;
     }
     const entry = {
@@ -108,6 +138,8 @@ function serializeState(state, originalJson) {
                 slotDef.$description = s.description;
             if (s.required)
                 slotDef.$required = true;
+            if (s.allowedComponents.length > 0)
+                slotDef.$allowedComponents = s.allowedComponents;
             entry.$slots[s.name] = slotDef;
         }
     }
@@ -123,53 +155,168 @@ function Picker({ value, active }) {
 function Toggle({ value, active }) {
     return (_jsx(Box, { children: _jsx(Text, { color: active ? 'cyan' : value ? 'green' : undefined, children: value ? '[✓]' : '[ ]' }) }));
 }
-function PropRow({ prop, selected, activeField, textCursor, valueCursor, cursorVisible, width, }) {
+function DefaultSubRow({ prop, active, textCursor, cursorVisible, }) {
+    const cursor = cursorVisible ? '█' : ' ';
+    // richtext/media/link don't support defaults — render an inert dim line.
+    if (prop.type === 'richtext' || prop.type === 'media' || prop.type === 'link') {
+        return (_jsxs(Box, { paddingLeft: 2, gap: 1, children: [_jsx(Text, { dimColor: true, children: "default:" }), _jsx(Text, { dimColor: true, children: "(not applicable)" })] }));
+    }
+    // boolean — tri-state picker: true | false | (unset).
+    if (prop.type === 'boolean') {
+        const display = prop.default === true ? 'true' : prop.default === false ? 'false' : '(unset)';
+        return (_jsxs(Box, { paddingLeft: 2, gap: 1, children: [_jsx(Text, { dimColor: true, children: "default:" }), active ? _jsx(Picker, { value: display, active: true }) : _jsx(Text, { color: "white", children: display })] }));
+    }
+    // enum — picker over prop.values plus (unset).
+    if (prop.type === 'enum') {
+        if (prop.values.length === 0) {
+            return (_jsxs(Box, { paddingLeft: 2, gap: 1, children: [_jsx(Text, { dimColor: true, children: "default:" }), _jsx(Text, { dimColor: true, children: "(no values defined)" })] }));
+        }
+        const display = typeof prop.default === 'string' && prop.default !== '' ? prop.default : '(unset)';
+        return (_jsxs(Box, { paddingLeft: 2, gap: 1, children: [_jsx(Text, { dimColor: true, children: "default:" }), active ? _jsx(Picker, { value: display, active: true }) : _jsx(Text, { color: "white", children: display })] }));
+    }
+    // string / number / token — text input. Active state shows bordered cyan
+    // box analogous to the description editor.
+    const value = typeof prop.default === 'string' ? prop.default : '';
+    if (active) {
+        return (_jsxs(Box, { paddingLeft: 2, flexDirection: "row", children: [_jsx(Text, { dimColor: true, children: "default:" }), _jsxs(Box, { flexGrow: 1, borderStyle: "round", borderColor: "cyan", paddingX: 1, children: [_jsx(Text, { children: value.slice(0, textCursor) }), _jsx(Text, { inverse: cursorVisible, children: value[textCursor] ?? cursor }), _jsx(Text, { children: value.slice(textCursor + 1) })] })] }));
+    }
+    return (_jsxs(Box, { paddingLeft: 2, gap: 1, children: [_jsx(Text, { dimColor: true, children: "default:" }), _jsx(Text, { color: value ? 'white' : undefined, dimColor: !value, children: value || '(none)' })] }));
+}
+function PropRow({ prop, selected, activeField, textCursor, valueCursor, cursorVisible, editingValue, valueText, width, rationale, rowKey, }) {
     const cursor = cursorVisible ? '█' : ' ';
     const bg = selected ? 'blue' : undefined;
+    const descActive = activeField === 'description';
     // Name column — fixed 14 chars
     const nameDisplay = prop.name.length > 14 ? prop.name.slice(0, 13) + '…' : prop.name.padEnd(14);
-    return (_jsxs(Box, { flexDirection: "column", width: width, children: [_jsxs(Box, { gap: 1, children: [_jsxs(Text, { color: selected ? 'white' : 'cyan', bold: selected, backgroundColor: bg, children: [' ', nameDisplay, ' '] }), _jsx(Text, { dimColor: !selected, children: "type:" }), activeField === 'type' ? (_jsx(Picker, { value: prop.type, active: true })) : (_jsx(Text, { color: selected ? 'yellow' : 'white', children: prop.type })), _jsx(Text, { dimColor: !selected, children: "cat:" }), activeField === 'category' ? (_jsx(Picker, { value: prop.category, active: true })) : (_jsx(Text, { color: selected ? 'magenta' : 'white', children: prop.category })), _jsx(Text, { dimColor: !selected, children: "req:" }), activeField === 'required' ? (_jsx(Toggle, { value: prop.required, active: true })) : (_jsx(Toggle, { value: prop.required, active: false })), prop.type === 'token' && (_jsxs(_Fragment, { children: [_jsx(Text, { dimColor: !selected, children: "kind:" }), activeField === 'tokenKind' ? (_jsx(Picker, { value: prop.tokenKind || DESIGN_TOKEN_TYPES[0], active: true })) : (_jsx(Text, { color: selected ? 'green' : 'white', children: prop.tokenKind || '—' }))] }))] }), selected && (_jsxs(Box, { paddingLeft: 2, gap: 1, children: [_jsx(Text, { dimColor: true, children: "desc:" }), activeField === 'description' ? (_jsxs(Box, { children: [_jsx(Text, { children: prop.description.slice(0, textCursor) }), _jsx(Text, { inverse: cursorVisible, children: prop.description[textCursor] ?? cursor }), _jsx(Text, { children: prop.description.slice(textCursor + 1) })] })) : (_jsx(Text, { color: "green", children: prop.description || '—' }))] })), selected && prop.type === 'enum' && (_jsxs(Box, { paddingLeft: 2, flexDirection: "column", children: [_jsx(Text, { dimColor: true, children: "values:" }), prop.values.length === 0 && _jsx(Text, { dimColor: true, children: " (none)" }), prop.values.map((v, i) => (_jsx(Box, { gap: 1, paddingLeft: 2, children: _jsx(Text, { color: activeField === 'values' && valueCursor === i ? 'cyan' : 'white', children: activeField === 'values' && valueCursor === i ? `▶ ${v}` : `  ${v}` }) }, i))), activeField === 'values' && (_jsx(Box, { paddingLeft: 2, children: _jsx(Text, { dimColor: true, children: "[+] add [x] remove [[] up []] down [Esc] done" }) }))] }))] }));
+    return (_jsxs(Box, { flexDirection: "column", width: width, children: [_jsxs(Box, { gap: 1, children: [_jsxs(Text, { color: selected ? 'white' : 'cyan', bold: selected, backgroundColor: bg, children: [' ', nameDisplay, ' '] }), _jsx(Text, { dimColor: !selected, children: "type:" }), activeField === 'type' ? (_jsx(Picker, { value: prop.type, active: true })) : (_jsx(Text, { color: selected ? 'yellow' : 'white', children: prop.type })), _jsx(Text, { dimColor: !selected, children: "cat:" }), activeField === 'category' ? (_jsx(Picker, { value: prop.category, active: true })) : (_jsx(Text, { color: selected ? 'magenta' : 'white', children: prop.category })), _jsx(Text, { dimColor: !selected, children: "req:" }), activeField === 'required' ? (_jsx(Toggle, { value: prop.required, active: true })) : (_jsx(Toggle, { value: prop.required, active: false })), prop.type === 'token' && (_jsxs(_Fragment, { children: [_jsx(Text, { dimColor: !selected, children: "kind:" }), activeField === 'tokenKind' ? (_jsx(Picker, { value: prop.tokenKind || DESIGN_TOKEN_TYPES[0], active: true })) : (_jsx(Text, { color: selected ? 'green' : 'white', children: prop.tokenKind || '—' }))] }))] }), selected && (_jsx(DefaultSubRow, { prop: prop, active: activeField === 'default', textCursor: textCursor, cursorVisible: cursorVisible })), selected && descActive && (_jsxs(Box, { paddingLeft: 2, flexDirection: "row", children: [_jsx(Text, { dimColor: true, children: "desc:" }), _jsxs(Box, { flexGrow: 1, borderStyle: "round", borderColor: "cyan", paddingX: 1, children: [_jsx(Text, { children: prop.description.slice(0, textCursor) }), _jsx(Text, { inverse: cursorVisible, children: prop.description[textCursor] ?? cursor }), _jsx(Text, { children: prop.description.slice(textCursor + 1) })] })] })), selected && !descActive && (_jsxs(Box, { paddingLeft: 2, gap: 1, children: [_jsx(Text, { dimColor: true, children: "desc:" }), _jsx(Text, { color: "green", children: prop.description || '—' })] })), selected && rationale && rationale.trim().length > 0 && (_jsx(Box, { paddingLeft: 2, children: _jsx(Text, { dimColor: true, children: (() => {
+                        const max = Math.max(8, width - 8);
+                        const text = `~ ${rationale}`;
+                        return text.length > max ? text.slice(0, max - 1) + '…' : text;
+                    })() }) }, rowKey ? `rationale-${rowKey}` : undefined)), selected && prop.type === 'enum' && (_jsxs(Box, { paddingLeft: 2, flexDirection: "column", children: [_jsxs(Box, { children: [_jsx(Text, { dimColor: true, children: "values:" }), activeField === 'values' && (_jsx(Text, { dimColor: true, children: '  [a]dd  [e]dit  [r]emove  [↑↓] navigate  [K/J] reorder' }))] }), prop.values.length === 0 && !editingValue && _jsx(Text, { dimColor: true, children: " (none \u2014 press [a] to add)" }), prop.values.map((v, i) => {
+                        const isActiveCursor = activeField === 'values' && valueCursor === i;
+                        const isBeingEdited = editingValue?.mode === 'edit' && editingValue.index === i;
+                        if (isBeingEdited) {
+                            return (_jsxs(Box, { paddingLeft: 2, children: [_jsx(Text, { color: "cyan", children: '✎ ' }), _jsx(Text, { children: valueText }), _jsx(Text, { inverse: cursorVisible, children: " " })] }, i));
+                        }
+                        return (_jsx(Box, { gap: 1, paddingLeft: 2, children: _jsx(Text, { color: isActiveCursor ? 'cyan' : 'white', children: isActiveCursor ? `▶ ${v}` : `  ${v}` }) }, i));
+                    }), editingValue?.mode === 'add' && (_jsxs(Box, { paddingLeft: 2, children: [_jsx(Text, { color: "cyan", children: '+ ' }), _jsx(Text, { children: valueText }), _jsx(Text, { inverse: cursorVisible, children: " " })] }))] }))] }));
 }
-function SlotRow({ slot, selected, activeField, textCursor, cursorVisible, width, }) {
+function SlotRow({ slot, selected, activeField, textCursor, valueCursor, cursorVisible, editingValue, valueText, width, }) {
     const cursor = cursorVisible ? '█' : ' ';
     const bg = selected ? 'blue' : undefined;
     const nameDisplay = slot.name.length > 14 ? slot.name.slice(0, 13) + '…' : slot.name.padEnd(14);
-    return (_jsxs(Box, { flexDirection: "column", width: width, children: [_jsxs(Box, { gap: 1, children: [_jsxs(Text, { color: selected ? 'white' : 'cyan', bold: selected, backgroundColor: bg, children: [' ', nameDisplay, ' '] }), _jsx(Text, { dimColor: !selected, children: "req:" }), activeField === 'required' ? (_jsx(Toggle, { value: slot.required, active: true })) : (_jsx(Toggle, { value: slot.required, active: false }))] }), selected && (_jsxs(Box, { paddingLeft: 2, gap: 1, children: [_jsx(Text, { dimColor: true, children: "desc:" }), activeField === 'description' ? (_jsxs(Box, { children: [_jsx(Text, { children: slot.description.slice(0, textCursor) }), _jsx(Text, { inverse: cursorVisible, children: slot.description[textCursor] ?? cursor }), _jsx(Text, { children: slot.description.slice(textCursor + 1) })] })) : (_jsx(Text, { color: "green", children: slot.description || '—' }))] }))] }));
+    return (_jsxs(Box, { flexDirection: "column", width: width, children: [_jsxs(Box, { gap: 1, children: [_jsxs(Text, { color: selected ? 'white' : 'cyan', bold: selected, backgroundColor: bg, children: [' ', nameDisplay, ' '] }), _jsx(Text, { dimColor: !selected, children: "req:" }), activeField === 'required' ? (_jsx(Toggle, { value: slot.required, active: true })) : (_jsx(Toggle, { value: slot.required, active: false }))] }), selected && (_jsxs(Box, { paddingLeft: 2, flexDirection: "column", children: [_jsxs(Box, { children: [_jsx(Text, { dimColor: true, children: "allowed:" }), activeField === 'allowedComponents' && (_jsx(Text, { dimColor: true, children: '  [a]dd  [e]dit  [r]emove  [↑↓] navigate  [K/J] reorder' }))] }), slot.allowedComponents.length === 0 && !editingValue && (_jsx(Box, { paddingLeft: 2, children: _jsx(Text, { dimColor: true, children: activeField === 'allowedComponents' ? '(any — press [a] to add)' : '(any)' }) })), slot.allowedComponents.map((v, i) => {
+                        const isActiveCursor = activeField === 'allowedComponents' && valueCursor === i;
+                        const isBeingEdited = editingValue?.mode === 'edit' && editingValue.index === i;
+                        if (isBeingEdited) {
+                            return (_jsxs(Box, { paddingLeft: 2, children: [_jsx(Text, { color: "cyan", children: '✎ ' }), _jsx(Text, { children: valueText }), _jsx(Text, { inverse: cursorVisible, children: " " })] }, i));
+                        }
+                        return (_jsx(Box, { gap: 1, paddingLeft: 2, children: _jsx(Text, { color: isActiveCursor ? 'cyan' : 'white', children: isActiveCursor ? `▶ ${v}` : `  ${v}` }) }, i));
+                    }), editingValue?.mode === 'add' && activeField === 'allowedComponents' && (_jsxs(Box, { paddingLeft: 2, children: [_jsx(Text, { color: "cyan", children: '+ ' }), _jsx(Text, { children: valueText }), _jsx(Text, { inverse: cursorVisible, children: " " })] }))] })), selected && activeField === 'description' && (_jsxs(Box, { paddingLeft: 2, flexDirection: "row", children: [_jsx(Text, { dimColor: true, children: "desc:" }), _jsxs(Box, { flexGrow: 1, borderStyle: "round", borderColor: "cyan", paddingX: 1, children: [_jsx(Text, { children: slot.description.slice(0, textCursor) }), _jsx(Text, { inverse: cursorVisible, children: slot.description[textCursor] ?? cursor }), _jsx(Text, { children: slot.description.slice(textCursor + 1) })] })] })), selected && activeField !== 'description' && (_jsxs(Box, { paddingLeft: 2, gap: 1, children: [_jsx(Text, { dimColor: true, children: "desc:" }), _jsx(Text, { color: "green", children: slot.description || '—' })] }))] }));
 }
-const PROP_FIELDS_BASE = ['type', 'category', 'required', 'description'];
+// Field order is intentional: description is LAST so it's the "edge" of the
+// field cycle. The user reaches description by walking through type → category
+// → required → [tokenKind?] → [values?] → [default?] → description via j/k;
+// once active, description swallows j/k as literal text input. Putting it last
+// means the user has to deliberately navigate to it, avoiding accidental
+// text-entry. `default` slots in BEFORE description for the same reason —
+// description-as-last is invariant. richtext/media/link omit `default` because
+// defaults aren't meaningful for those types (per spec D1).
 function propFields(prop) {
-    const fields = [...PROP_FIELDS_BASE];
+    const fields = ['type', 'category', 'required'];
     if (prop.type === 'token')
-        fields.splice(3, 0, 'tokenKind');
+        fields.push('tokenKind');
     if (prop.type === 'enum')
         fields.push('values');
+    if (prop.type !== 'richtext' && prop.type !== 'media' && prop.type !== 'link') {
+        fields.push('default');
+    }
+    fields.push('description');
     return fields;
 }
-const SLOT_FIELDS = ['required', 'description'];
+// Slot fields: description stays last for the same invariant reason. Allowed-
+// components is a list-typed field that swallows j/k similarly to enum $values
+// — placing it before description preserves description-as-last.
+const SLOT_FIELDS = ['required', 'allowedComponents', 'description'];
 // ── Main component ────────────────────────────────────────────────────────────
-export function FieldEditor({ value, width, height, onChange, onSave, onDiscard, }) {
+export function FieldEditor({ value, width, height, active = true, onChange, onSave, onDiscard, onExit, metadata, onTogglePropRationale, onToggleComponentRationale, onToggleSourceExternal, onTextEntryActiveChange, }) {
     const { state: initialState, error: parseError } = parseToState(value);
     const [editorState, setEditorState] = useState(initialState);
     const [parseErr] = useState(parseError);
-    // Navigation state
-    const [focusLevel, setFocusLevel] = useState('prop');
+    // Navigation state — initial state lands at the row level with NO field
+    // auto-active. The user presses Return to enter field-edit at the first
+    // field of the row (type), then j/k to walk through fields uniformly:
+    // type → category → required → [tokenKind?] → [values?] → description.
+    // Description is reached via navigation, not auto-focus — this avoids
+    // trapping the user in description-edit (where j/k type literals).
+    const initialFocus = (() => {
+        if (initialState.props.length > 0) {
+            return {
+                focusLevel: 'prop',
+                inSlots: false,
+                activeField: null,
+                textCursor: 0,
+            };
+        }
+        if (initialState.slots.length > 0) {
+            return {
+                focusLevel: 'slot',
+                inSlots: true,
+                activeField: null,
+                textCursor: 0,
+            };
+        }
+        return {
+            focusLevel: 'prop',
+            inSlots: false,
+            activeField: null,
+            textCursor: 0,
+        };
+    })();
+    const [focusLevel, setFocusLevel] = useState(initialFocus.focusLevel);
     const [propIdx, setPropIdx] = useState(0);
     const [slotIdx, setSlotIdx] = useState(0);
-    // Whether we're navigating props (true) or slots (false) at the top level
-    const [inSlots, setInSlots] = useState(false);
+    // Whether we're navigating props (false) or slots (true) at the top level
+    const [inSlots, setInSlots] = useState(initialFocus.inSlots);
+    // True when the active focus is the component-level $description row (rather
+    // than a prop/slot row). Lives parallel to inSlots — they're mutually exclusive.
+    const [inComponentDesc, setInComponentDesc] = useState(false);
     // Active field within a prop/slot
-    const [activeField, setActiveField] = useState(null);
+    const [activeField, setActiveField] = useState(initialFocus.activeField);
     // Text cursor position for description fields
-    const [textCursor, setTextCursor] = useState(0);
+    const [textCursor, setTextCursor] = useState(initialFocus.textCursor);
     // Value list cursor for $values editing
     const [valueCursor, setValueCursor] = useState(0);
-    // New value being typed in $values add mode
-    const [addingValue, setAddingValue] = useState(false);
-    const [newValueText, setNewValueText] = useState('');
+    // Inline text-entry mode for adding/editing a $values entry.
+    // mode='add' — append on Enter; mode='edit' — replace at index on Enter.
+    const [editingValue, setEditingValue] = useState(null);
+    const [valueText, setValueText] = useState('');
     const [validationError, setValidationError] = useState(null);
     const [cursorVisible] = useState(true);
+    // Feature 1: source-view panel toggle. Opens with `s`, closes with `s` or Esc.
+    // When open, Esc closes the panel only (does not bubble to onExit).
+    const [sourceOpen, setSourceOpen] = useState(false);
+    // Feature 11: rationale panel toggle (`i`). Mutually exclusive with the
+    // source panel — opening one closes the other.
+    const [rationaleOpen, setRationaleOpen] = useState(false);
+    const [rationaleScrollOffset, setRationaleScrollOffset] = useState(0);
+    // Discoverability overlay. `?` toggles a modal listing every wired
+    // keybinding grouped by context. While open, every other handler is inert
+    // — only `?` and Esc respond. Esc here closes the overlay and does NOT
+    // bubble to onExit.
+    const [showHelp, setShowHelp] = useState(false);
     const props = editorState.props;
     const slots = editorState.slots;
+    // Report text-entry-active state to parent so it can gate top-level `i`/`I`/`s`
+    // keybinds against literal keystrokes inside any text-entry surface.
+    const textEntryActive = (focusLevel === 'field' && activeField === 'description') ||
+        (focusLevel === 'field' &&
+            activeField === 'default' &&
+            (editorState.props[propIdx]?.type === 'string' || editorState.props[propIdx]?.type === 'token')) ||
+        editingValue != null;
+    React.useEffect(() => {
+        onTextEntryActiveChange?.(textEntryActive);
+    }, [textEntryActive, onTextEntryActiveChange]);
     const currentProp = props[propIdx] ?? null;
     const currentSlot = slots[slotIdx] ?? null;
     // Emit serialized JSON whenever state changes
@@ -178,58 +325,213 @@ export function FieldEditor({ value, width, height, onChange, onSave, onDiscard,
         onChange(serializeState(next, value));
     };
     useImmediateInput((input, key) => {
+        if (!active)
+            return;
+        // ── Help overlay (`?`) — highest priority ───────────────────────────────
+        // When open, only `?` (toggle) and Esc (close) respond. All other input
+        // is swallowed so j/k/Enter/Ctrl+S can't move state behind the modal.
+        if (showHelp) {
+            if (input === '?' || key.escape) {
+                setShowHelp(false);
+            }
+            return;
+        }
+        // Open the overlay. Skip when in any inline text-entry context to keep
+        // `?` literal there: description text-entry, string-typed default
+        // text-entry, and the values/allowedComponents add/edit text-entry.
+        const inDescriptionTextEntryForHelp = focusLevel === 'field' && activeField === 'description';
+        const inStringDefaultTextEntryForHelp = focusLevel === 'field' &&
+            activeField === 'default' &&
+            currentProp != null &&
+            (currentProp.type === 'string' || currentProp.type === 'token');
+        const inValueListTextEntry = editingValue != null;
+        if (input === '?' &&
+            !key.ctrl &&
+            !key.meta &&
+            !inDescriptionTextEntryForHelp &&
+            !inStringDefaultTextEntryForHelp &&
+            !inValueListTextEntry) {
+            setShowHelp(true);
+            return;
+        }
+        // ── Inline value text-entry (add or edit) ─ highest priority ───────────
+        // Handles enum prop $values AND slot $allowedComponents — both use the
+        // same add/edit/remove/reorder list shape.
+        const isPropValuesEntry = editingValue && currentProp && activeField === 'values' && !inSlots;
+        const isSlotAllowedEntry = editingValue && currentSlot && activeField === 'allowedComponents' && inSlots;
+        if (isPropValuesEntry || isSlotAllowedEntry) {
+            const vals = isPropValuesEntry ? currentProp.values : currentSlot.allowedComponents;
+            if (key.return) {
+                const trimmed = valueText.trim();
+                if (trimmed) {
+                    let nextVals;
+                    let cursorAfter;
+                    if (editingValue.mode === 'add') {
+                        nextVals = [...vals, trimmed];
+                        cursorAfter = nextVals.length - 1;
+                    }
+                    else {
+                        const idx = editingValue.index ?? 0;
+                        nextVals = vals.map((v, i) => (i === idx ? trimmed : v));
+                        cursorAfter = idx;
+                    }
+                    if (isPropValuesEntry) {
+                        const nextProps = props.map((p, i) => (i === propIdx ? { ...p, values: nextVals } : p));
+                        commit({ ...editorState, props: nextProps });
+                    }
+                    else {
+                        const nextSlots = slots.map((s, i) => (i === slotIdx ? { ...s, allowedComponents: nextVals } : s));
+                        commit({ ...editorState, slots: nextSlots });
+                    }
+                    setValueCursor(cursorAfter);
+                }
+                setEditingValue(null);
+                setValueText('');
+                return;
+            }
+            if (key.escape) {
+                setEditingValue(null);
+                setValueText('');
+                return;
+            }
+            if (key.backspace) {
+                setValueText((t) => t.slice(0, -1));
+                return;
+            }
+            if (input && input.length === 1 && !key.ctrl && !key.meta) {
+                setValueText((t) => t + input);
+                return;
+            }
+            return;
+        }
         // ── Save / Discard ───────────────────────────────────────────────────────
         if (key.ctrl && input === 's') {
             setValidationError(null);
             onSave();
             return;
         }
+        // ── Feature 1: source-view panel toggle ─────────────────────────────────
+        // `s` (without Ctrl) opens/closes the source-view panel. Skip when in
+        // inline text-entry contexts (description text-entry, value-list edit).
+        // Description text-entry is gated by focusLevel === 'field' && activeField
+        // === 'description' — we guard against typing 's' as a literal there.
+        const inDescriptionTextEntry = focusLevel === 'field' && activeField === 'description';
+        const inComponentDescTextEntry = focusLevel === 'field' && inComponentDesc && activeField === 'description';
+        if (input === 's' && !key.ctrl && !key.meta && !inDescriptionTextEntry && !inComponentDescTextEntry) {
+            // When the parent owns the source panel, delegate; otherwise fall
+            // back to the internal toggle for backward compat.
+            if (onToggleSourceExternal) {
+                onToggleSourceExternal();
+                return;
+            }
+            // Mutual exclusion with the rationale panel (Feature 11) — only when
+            // internally managed.
+            setRationaleOpen(false);
+            setRationaleScrollOffset(() => 0);
+            setSourceOpen((o) => !o);
+            return;
+        }
+        // ── Rationale-panel scroll while internally open (legacy path) ─────────
+        // When the parent does not own the panel (no onTogglePropRationale prop),
+        // FieldEditor preserves its legacy in-place panel for backward compat
+        // with mounts that pre-date the lifted-panel refactor.
+        if (rationaleOpen && !onTogglePropRationale) {
+            const PANEL_HEIGHT = 12;
+            const next = computeNextScrollOffset(rationaleScrollOffset, input, key, 9999, PANEL_HEIGHT);
+            if (next !== null) {
+                setRationaleScrollOffset(() => next);
+                return;
+            }
+            if (input === 'i' || key.escape) {
+                setRationaleOpen(false);
+                setRationaleScrollOffset(() => 0);
+                return;
+            }
+            return;
+        }
+        // ── Rationale + component-rationale keybinds (`i` / `I`) ────────────────
+        // `i`/`I` are literal in every text-entry context: description editor,
+        // component-description editor, string/token default editor, and the
+        // values/allowedComponents add/edit text-entry.
+        const inStringDefaultTextEntry = focusLevel === 'field' &&
+            activeField === 'default' &&
+            currentProp != null &&
+            (currentProp.type === 'string' || currentProp.type === 'token');
+        const rationaleKeyAllowed = !key.ctrl &&
+            !key.meta &&
+            !inDescriptionTextEntry &&
+            !inComponentDescTextEntry &&
+            !inStringDefaultTextEntry &&
+            !inValueListTextEntry;
+        if (input === 'i' && rationaleKeyAllowed) {
+            if (onTogglePropRationale) {
+                onTogglePropRationale();
+                return;
+            }
+            // Legacy in-place toggle (no parent callback wired).
+            setSourceOpen(false);
+            setRationaleScrollOffset(() => 0);
+            setRationaleOpen((o) => !o);
+            return;
+        }
+        if (input === 'I' && rationaleKeyAllowed && onToggleComponentRationale) {
+            onToggleComponentRationale();
+            return;
+        }
+        // ── Esc when source panel is open: close panel only, do not bubble ─────
+        if (key.escape && sourceOpen) {
+            setSourceOpen(false);
+            return;
+        }
         if (key.escape) {
             if (focusLevel === 'field') {
-                // Exit field editing back to prop/slot row level
-                setFocusLevel(inSlots ? 'slot' : 'prop');
+                // Exit field editing back to prop/slot/component-description row level
+                if (inComponentDesc)
+                    setFocusLevel('componentDescription');
+                else
+                    setFocusLevel(inSlots ? 'slot' : 'prop');
                 setActiveField(null);
-                setAddingValue(false);
-                setNewValueText('');
                 return;
             }
-            if (focusLevel === 'value') {
-                setFocusLevel('field');
-                setAddingValue(false);
-                setNewValueText('');
-                return;
+            // Row-level Esc: bounce focus back out of the panel via onExit.
+            // Falls back to onDiscard when the caller hasn't wired onExit.
+            if (onExit) {
+                onExit();
+            }
+            else {
+                onDiscard();
             }
-            onDiscard();
             return;
         }
         // ── Prop-level navigation (not inside a field) ───────────────────────────
+        // Arrows / j / k move between rows. Return enters field-edit at the FIRST
+        // field of the current prop (type). No auto-focus on description.
         if (focusLevel === 'prop') {
             if (key.upArrow || input === 'k') {
                 if (propIdx > 0) {
-                    setPropIdx((i) => i - 1);
-                    setActiveField(null);
+                    setPropIdx(propIdx - 1);
                 }
-                else if (slots.length > 0) {
-                    setInSlots(true);
-                    setFocusLevel('slot');
-                    setActiveField(null);
+                else {
+                    // From prop[0], k enters the component-description row above.
+                    setFocusLevel('componentDescription');
+                    setInSlots(false);
+                    setInComponentDesc(true);
                 }
                 return;
             }
             if (key.downArrow || input === 'j') {
                 if (propIdx < props.length - 1) {
-                    setPropIdx((i) => i + 1);
-                    setActiveField(null);
+                    setPropIdx(propIdx + 1);
                 }
                 else if (slots.length > 0) {
                     setInSlots(true);
+                    setSlotIdx(0);
                     setFocusLevel('slot');
-                    setActiveField(null);
                 }
                 return;
             }
             if (key.return && currentProp) {
-                // Enter field editing on the first field of this prop
+                // Enter field editing on the first field of this prop (type).
                 setFocusLevel('field');
                 setActiveField(propFields(currentProp)[0] ?? null);
                 setTextCursor(currentProp.description.length);
@@ -237,25 +539,55 @@ export function FieldEditor({ value, width, height, onChange, onSave, onDiscard,
             }
             return;
         }
+        // ── Component-description row navigation ─────────────────────────────────
+        if (focusLevel === 'componentDescription') {
+            if (key.upArrow || input === 'k') {
+                // Already at the top-most row — stay put.
+                return;
+            }
+            if (key.downArrow || input === 'j') {
+                // Move down into the first prop row, or first slot row when no props.
+                if (props.length > 0) {
+                    setFocusLevel('prop');
+                    setPropIdx(0);
+                    setInSlots(false);
+                    setInComponentDesc(false);
+                }
+                else if (slots.length > 0) {
+                    setFocusLevel('slot');
+                    setSlotIdx(0);
+                    setInSlots(true);
+                    setInComponentDesc(false);
+                }
+                return;
+            }
+            if (key.return) {
+                // Enter the single field — description text input.
+                setFocusLevel('field');
+                setActiveField('description');
+                setTextCursor(editorState.componentDescription.length);
+                return;
+            }
+            return;
+        }
         // ── Slot-level navigation ────────────────────────────────────────────────
+        // Arrows / j / k move between rows. Return enters field-edit at the FIRST
+        // field of the slot (required). No auto-focus on description.
         if (focusLevel === 'slot') {
             if (key.upArrow || input === 'k') {
                 if (slotIdx > 0) {
-                    setSlotIdx((i) => i - 1);
-                    setActiveField(null);
+                    setSlotIdx(slotIdx - 1);
                 }
                 else if (props.length > 0) {
                     setInSlots(false);
-                    setFocusLevel('prop');
                     setPropIdx(props.length - 1);
-                    setActiveField(null);
+                    setFocusLevel('prop');
                 }
                 return;
             }
             if (key.downArrow || input === 'j') {
                 if (slotIdx < slots.length - 1) {
-                    setSlotIdx((i) => i + 1);
-                    setActiveField(null);
+                    setSlotIdx(slotIdx + 1);
                 }
                 return;
             }
@@ -271,32 +603,67 @@ export function FieldEditor({ value, width, height, onChange, onSave, onDiscard,
         if (focusLevel === 'field') {
             const fields = inSlots ? SLOT_FIELDS : currentProp ? propFields(currentProp) : [];
             const currentFieldIdx = fields.indexOf(activeField);
-            if (key.upArrow || input === 'k') {
-                if (currentFieldIdx > 0) {
-                    const next = fields[currentFieldIdx - 1];
-                    setActiveField(next);
-                    if (next === 'description') {
-                        const desc = inSlots ? (currentSlot?.description ?? '') : (currentProp?.description ?? '');
-                        setTextCursor(desc.length);
+            const isDescriptionTextEntry = activeField === 'description';
+            // String/token defaults are also text-entry; j/k must type literals
+            // there too (consistency with description). boolean/enum defaults use
+            // ←/→ pickers so j/k can keep cycling fields.
+            const isDefaultTextEntry = activeField === 'default' &&
+                currentProp != null &&
+                (currentProp.type === 'string' || currentProp.type === 'token');
+            const isValuesNav = activeField === 'values' || activeField === 'allowedComponents';
+            const arrowUp = key.upArrow;
+            const arrowDown = key.downArrow;
+            // ── Inside values: arrow keys AND j/k navigate BETWEEN VALUES, not
+            //    between fields. Reorder is K/J (capital). Same logic for prop
+            //    enum $values and slot $allowedComponents.
+            if (isValuesNav) {
+                const vals = activeField === 'values' && currentProp
+                    ? currentProp.values
+                    : activeField === 'allowedComponents' && currentSlot
+                        ? currentSlot.allowedComponents
+                        : null;
+                if (vals !== null) {
+                    if (arrowUp || input === 'k') {
+                        setValueCursor((c) => Math.max(0, c - 1));
+                        return;
+                    }
+                    if (arrowDown || input === 'j') {
+                        setValueCursor((c) => Math.max(0, Math.min(vals.length - 1, c + 1)));
+                        return;
                     }
                 }
-                else {
-                    // Back to row navigation
-                    setFocusLevel(inSlots ? 'slot' : 'prop');
-                    setActiveField(null);
-                }
-                return;
             }
-            if (key.downArrow || input === 'j') {
-                if (currentFieldIdx < fields.length - 1) {
-                    const next = fields[currentFieldIdx + 1];
+            // ── Field cycling within the current prop/slot.
+            //    Arrows always cycle (including from description, which means in
+            //    description-active state arrows leave text-entry to navigate fields
+            //    of the SAME prop). j/k only cycle when NOT in description, so that
+            //    description preserves literal text-entry for those characters. Use
+            //    Esc to leave the current prop and return to row-level navigation.
+            if (!isValuesNav) {
+                const navUp = arrowUp || (!isDescriptionTextEntry && !isDefaultTextEntry && input === 'k');
+                const navDown = arrowDown || (!isDescriptionTextEntry && !isDefaultTextEntry && input === 'j');
+                if ((navUp || navDown) && fields.length > 0) {
+                    const lastIdx = fields.length - 1;
+                    const targetIdx = navDown
+                        ? currentFieldIdx >= lastIdx
+                            ? 0
+                            : currentFieldIdx + 1
+                        : currentFieldIdx <= 0
+                            ? lastIdx
+                            : currentFieldIdx - 1;
+                    const next = fields[targetIdx];
                     setActiveField(next);
                     if (next === 'description') {
                         const desc = inSlots ? (currentSlot?.description ?? '') : (currentProp?.description ?? '');
                         setTextCursor(desc.length);
                     }
+                    else if (next === 'default' && currentProp) {
+                        // Land cursor at end of any string-typed default for ergonomic typing.
+                        const cur = typeof currentProp.default === 'string' ? currentProp.default : '';
+                        setTextCursor(cur.length);
+                    }
+                    return;
                 }
-                return;
             }
             // ── Picker fields (left/right cycle) ──────────────────────────────────
             if (activeField === 'type' && (key.leftArrow || key.rightArrow) && currentProp) {
@@ -348,11 +715,76 @@ export function FieldEditor({ value, width, height, onChange, onSave, onDiscard,
                 }
                 return;
             }
+            // ── $default editing per type ─────────────────────────────────────────
+            if (activeField === 'default' && currentProp) {
+                const setProp = (next) => {
+                    const nextProps = props.map((p, i) => (i === propIdx ? next : p));
+                    commit({ ...editorState, props: nextProps });
+                };
+                // boolean: tri-state cycle (unset → true → false → unset).
+                if (currentProp.type === 'boolean' && (key.leftArrow || key.rightArrow)) {
+                    const cycle = [null, true, false];
+                    const curIdx = cycle.findIndex((v) => v === currentProp.default);
+                    const idx = curIdx < 0 ? 0 : curIdx;
+                    const nextIdx = key.rightArrow ? (idx + 1) % cycle.length : (idx - 1 + cycle.length) % cycle.length;
+                    setProp({ ...currentProp, default: cycle[nextIdx] });
+                    return;
+                }
+                // enum: cycle through prop.values plus (unset).
+                if (currentProp.type === 'enum' && (key.leftArrow || key.rightArrow)) {
+                    const opts = [null, ...currentProp.values];
+                    const cur = typeof currentProp.default === 'string' ? currentProp.default : null;
+                    const curIdx = opts.findIndex((v) => v === cur);
+                    const idx = curIdx < 0 ? 0 : curIdx;
+                    const nextIdx = key.rightArrow ? (idx + 1) % opts.length : (idx - 1 + opts.length) % opts.length;
+                    setProp({ ...currentProp, default: opts[nextIdx] });
+                    return;
+                }
+                // string/token: text input. Mirrors description input subroutine.
+                if (currentProp.type === 'string' || currentProp.type === 'token') {
+                    const cur = typeof currentProp.default === 'string' ? currentProp.default : '';
+                    const setVal = (next) => setProp({ ...currentProp, default: next === '' ? null : next });
+                    if (key.leftArrow) {
+                        setTextCursor((c) => Math.max(0, c - 1));
+                        return;
+                    }
+                    if (key.rightArrow) {
+                        setTextCursor((c) => Math.min(cur.length, c + 1));
+                        return;
+                    }
+                    if (key.backspace) {
+                        if (textCursor > 0) {
+                            setVal(cur.slice(0, textCursor - 1) + cur.slice(textCursor));
+                            setTextCursor((c) => c - 1);
+                        }
+                        return;
+                    }
+                    if (key.delete) {
+                        if (textCursor < cur.length)
+                            setVal(cur.slice(0, textCursor) + cur.slice(textCursor + 1));
+                        return;
+                    }
+                    if (input && input.length === 1 && !key.ctrl && !key.meta && !key.return) {
+                        setVal(cur.slice(0, textCursor) + input + cur.slice(textCursor));
+                        setTextCursor((c) => c + 1);
+                        return;
+                    }
+                    return;
+                }
+                return;
+            }
             // ── Description text input ─────────────────────────────────────────────
             if (activeField === 'description') {
-                const getDesc = () => (inSlots ? (currentSlot?.description ?? '') : (currentProp?.description ?? ''));
+                const getDesc = () => inComponentDesc
+                    ? editorState.componentDescription
+                    : inSlots
+                        ? (currentSlot?.description ?? '')
+                        : (currentProp?.description ?? '');
                 const setDesc = (next) => {
-                    if (inSlots && currentSlot) {
+                    if (inComponentDesc) {
+                        commit({ ...editorState, componentDescription: next });
+                    }
+                    else if (inSlots && currentSlot) {
                         const nextSlots = slots.map((s, i) => (i === slotIdx ? { ...s, description: next } : s));
                         commit({ ...editorState, slots: nextSlots });
                     }
@@ -397,84 +829,88 @@ export function FieldEditor({ value, width, height, onChange, onSave, onDiscard,
                 }
                 return;
             }
-            // ── Enter $values sub-list ─────────────────────────────────────────────
-            if (activeField === 'values' && key.return && currentProp) {
-                setFocusLevel('value');
-                setValueCursor(0);
-                return;
-            }
-            return;
-        }
-        // ── Value-list editing ────────────────────────────────────────────────────
-        if (focusLevel === 'value' && currentProp) {
-            const vals = currentProp.values;
-            if (addingValue) {
-                // Typing a new value
-                if (key.return) {
-                    if (newValueText.trim()) {
-                        const nextVals = [...vals, newValueText.trim()];
-                        const nextProps = props.map((p, i) => (i === propIdx ? { ...p, values: nextVals } : p));
-                        commit({ ...editorState, props: nextProps });
-                        setValueCursor(nextVals.length - 1);
-                    }
-                    setAddingValue(false);
-                    setNewValueText('');
+            // ── $allowedComponents inline manipulation (slot-level) ──────────────
+            // Mirrors the $values block exactly, but operates on the slot's
+            // allowedComponents list.
+            if (activeField === 'allowedComponents' && currentSlot) {
+                const vals = currentSlot.allowedComponents;
+                const setSlotVals = (next) => {
+                    const nextSlots = slots.map((s, i) => (i === slotIdx ? { ...s, allowedComponents: next } : s));
+                    commit({ ...editorState, slots: nextSlots });
+                };
+                if (input === 'a') {
+                    setEditingValue({ mode: 'add' });
+                    setValueText('');
                     return;
                 }
-                if (key.escape) {
-                    setAddingValue(false);
-                    setNewValueText('');
+                if (input === 'e' && vals.length > 0) {
+                    setEditingValue({ mode: 'edit', index: valueCursor });
+                    setValueText(vals[valueCursor] ?? '');
                     return;
                 }
-                if (key.backspace) {
-                    setNewValueText((t) => t.slice(0, -1));
+                if (input === 'r' && vals.length > 0) {
+                    const nextVals = vals.filter((_, i) => i !== valueCursor);
+                    setSlotVals(nextVals);
+                    setValueCursor((c) => Math.max(0, Math.min(c, nextVals.length - 1)));
                     return;
                 }
-                if (input && input.length === 1 && !key.ctrl && !key.meta) {
-                    setNewValueText((t) => t + input);
+                if (input === 'K' && valueCursor > 0) {
+                    const nextVals = [...vals];
+                    [nextVals[valueCursor - 1], nextVals[valueCursor]] = [nextVals[valueCursor], nextVals[valueCursor - 1]];
+                    setSlotVals(nextVals);
+                    setValueCursor((c) => c - 1);
+                    return;
+                }
+                if (input === 'J' && valueCursor < vals.length - 1) {
+                    const nextVals = [...vals];
+                    [nextVals[valueCursor], nextVals[valueCursor + 1]] = [nextVals[valueCursor + 1], nextVals[valueCursor]];
+                    setSlotVals(nextVals);
+                    setValueCursor((c) => c + 1);
                     return;
                 }
                 return;
             }
-            if (key.upArrow || input === 'k') {
-                setValueCursor((c) => Math.max(0, c - 1));
-                return;
-            }
-            if (key.downArrow || input === 'j') {
-                setValueCursor((c) => Math.max(0, Math.min(vals.length - 1, c + 1)));
-                return;
-            }
-            if (key.escape) {
-                setFocusLevel('field');
-                return;
-            }
-            if (input === '+') {
-                setAddingValue(true);
-                setNewValueText('');
-                return;
-            }
-            if (input === 'x' && vals.length > 0) {
-                const nextVals = vals.filter((_, i) => i !== valueCursor);
-                const nextProps = props.map((p, i) => (i === propIdx ? { ...p, values: nextVals } : p));
-                commit({ ...editorState, props: nextProps });
-                setValueCursor((c) => Math.max(0, Math.min(c, nextVals.length - 1)));
-                return;
-            }
-            // '[' moves item up, ']' moves item down
-            if (input === '[' && valueCursor > 0) {
-                const nextVals = [...vals];
-                [nextVals[valueCursor - 1], nextVals[valueCursor]] = [nextVals[valueCursor], nextVals[valueCursor - 1]];
-                const nextProps = props.map((p, i) => (i === propIdx ? { ...p, values: nextVals } : p));
-                commit({ ...editorState, props: nextProps });
-                setValueCursor((c) => c - 1);
-                return;
-            }
-            if (input === ']' && valueCursor < vals.length - 1) {
-                const nextVals = [...vals];
-                [nextVals[valueCursor], nextVals[valueCursor + 1]] = [nextVals[valueCursor + 1], nextVals[valueCursor]];
-                const nextProps = props.map((p, i) => (i === propIdx ? { ...p, values: nextVals } : p));
-                commit({ ...editorState, props: nextProps });
-                setValueCursor((c) => c + 1);
+            // ── $values inline manipulation (flat — no extra Return) ───────────────
+            if (activeField === 'values' && currentProp) {
+                const vals = currentProp.values;
+                // a — add new value (inline text-entry)
+                if (input === 'a') {
+                    setEditingValue({ mode: 'add' });
+                    setValueText('');
+                    return;
+                }
+                // e — edit value at cursor (inline text-entry, pre-filled)
+                if (input === 'e' && vals.length > 0) {
+                    setEditingValue({ mode: 'edit', index: valueCursor });
+                    setValueText(vals[valueCursor] ?? '');
+                    return;
+                }
+                // r — remove value at cursor
+                if (input === 'r' && vals.length > 0) {
+                    const nextVals = vals.filter((_, i) => i !== valueCursor);
+                    const nextProps = props.map((p, i) => (i === propIdx ? { ...p, values: nextVals } : p));
+                    commit({ ...editorState, props: nextProps });
+                    setValueCursor((c) => Math.max(0, Math.min(c, nextVals.length - 1)));
+                    return;
+                }
+                // K (Shift+K) — move value up
+                if (input === 'K' && valueCursor > 0) {
+                    const nextVals = [...vals];
+                    [nextVals[valueCursor - 1], nextVals[valueCursor]] = [nextVals[valueCursor], nextVals[valueCursor - 1]];
+                    const nextProps = props.map((p, i) => (i === propIdx ? { ...p, values: nextVals } : p));
+                    commit({ ...editorState, props: nextProps });
+                    setValueCursor((c) => c - 1);
+                    return;
+                }
+                // J (Shift+J) — move value down
+                if (input === 'J' && valueCursor < vals.length - 1) {
+                    const nextVals = [...vals];
+                    [nextVals[valueCursor], nextVals[valueCursor + 1]] = [nextVals[valueCursor + 1], nextVals[valueCursor]];
+                    const nextProps = props.map((p, i) => (i === propIdx ? { ...p, values: nextVals } : p));
+                    commit({ ...editorState, props: nextProps });
+                    setValueCursor((c) => c + 1);
+                    return;
+                }
                 return;
             }
             return;
@@ -486,20 +922,38 @@ export function FieldEditor({ value, width, height, onChange, onSave, onDiscard,
         return (_jsxs(Box, { flexDirection: "column", width: width, borderStyle: "single", borderColor: "red", children: [_jsx(Text, { bold: true, color: "red", children: "FIELD EDITOR \u2014 parse error" }), _jsx(Text, { color: "red", children: parseErr }), _jsx(Text, { dimColor: true, children: "Cannot display structured editor. Fix the JSON first." })] }));
     }
     if (props.length === 0 && slots.length === 0) {
-        return (_jsxs(Box, { flexDirection: "column", width: width, borderStyle: "single", borderColor: "yellow", children: [_jsx(Text, { bold: true, children: "FIELD EDITOR \u2014 no fields" }), _jsx(Text, { dimColor: true, children: "This component has no properties or slots to edit." }), _jsx(Text, { dimColor: true, children: "Ctrl+S to save \u00B7 Esc to discard" })] }));
+        return (_jsxs(Box, { flexDirection: "column", width: width, borderStyle: "single", borderColor: "yellow", children: [_jsx(Text, { bold: true, color: "yellow", children: "FIELD EDITOR \u2014 no fields" }), _jsx(Text, { color: "yellow", children: "⚠ No properties classified for this component. The LLM didn't find anything to classify." }), _jsx(Text, { dimColor: true, children: "You can add fields manually below or reject this component." }), _jsx(Text, { dimColor: true, children: "Ctrl+S to save \u00B7 Esc to discard" })] }));
     }
-    const modeLabel = focusLevel === 'field' && activeField === 'description'
-        ? '← → move cursor  Esc exit field'
-        : focusLevel === 'field' && (activeField === 'type' || activeField === 'category' || activeField === 'tokenKind')
-            ? '← → cycle values  ↑↓ next field  Esc exit'
-            : focusLevel === 'field' && activeField === 'required'
-                ? 'Space/Enter toggle  ↑↓ next field  Esc exit'
-                : focusLevel === 'field' && activeField === 'values'
-                    ? 'Enter edit list  Esc exit field'
-                    : focusLevel === 'value'
-                        ? '+ add  x remove  [ up  ] down  Esc done'
-                        : '↑↓ navigate  Enter edit fields  Ctrl+S save  Esc discard';
+    // When $properties is empty but $slots exist, surface the same warning
+    // prominently in the panel so the user understands why the component looks
+    // sparse — and can act on it (manually add a prop or reject).
+    const hasEmptyProperties = props.length === 0;
+    const modeLabel = (() => {
+        if (editingValue) {
+            return editingValue.mode === 'add' ? 'Enter to add · Esc to cancel' : 'Enter to save edit · Esc to cancel';
+        }
+        if (focusLevel === 'field' && activeField === 'description') {
+            return 'Type to edit  ←→ cursor  ↑↓ cycle field  Esc row  Ctrl+S save';
+        }
+        if (focusLevel === 'field' &&
+            (activeField === 'type' || activeField === 'category' || activeField === 'tokenKind')) {
+            return '←→ cycle value  ↑↓/jk cycle field  Esc row';
+        }
+        if (focusLevel === 'field' && activeField === 'required') {
+            return 'Space/Enter toggle  ↑↓/jk cycle field  Esc row';
+        }
+        if (focusLevel === 'field' && (activeField === 'values' || activeField === 'allowedComponents')) {
+            return '[a]dd  [e]dit  [r]emove  ↑↓/jk navigate  [K/J] reorder  Esc row';
+        }
+        if (rationaleOpen) {
+            return 'jk/Ctrl+u/d scroll  i/Esc close  rationale panel';
+        }
+        return '↑↓/jk navigate rows  Enter edit fields  s source  i prop rationale  I component rationale  ? help  Ctrl+S save  Esc exit panel';
+    })();
     const rows = [];
+    // Component-level $description always renders first so it's reachable as
+    // the topmost navigable row, even when empty (the operator can populate it).
+    rows.push({ kind: 'component-description' });
     if (props.length > 0) {
         rows.push({ kind: 'header', label: `── $properties (${props.length}) ` });
         props.forEach((_, i) => rows.push({ kind: 'prop', idx: i }));
@@ -509,23 +963,45 @@ export function FieldEditor({ value, width, height, onChange, onSave, onDiscard,
         slots.forEach((_, i) => rows.push({ kind: 'slot', idx: i }));
     }
     // Scroll to keep selected row visible
-    const selectedRowIdx = rows.findIndex((r) => (r.kind === 'prop' && !inSlots && r.idx === propIdx && focusLevel !== 'section') ||
-        (r.kind === 'slot' && inSlots && r.idx === slotIdx));
+    const selectedRowIdx = rows.findIndex((r) => (r.kind === 'prop' && !inSlots && !inComponentDesc && r.idx === propIdx) ||
+        (r.kind === 'slot' && inSlots && r.idx === slotIdx) ||
+        (r.kind === 'component-description' && inComponentDesc));
     const visibleRows = Math.max(1, height - 3); // title + hint bar + border
     const scrollStart = selectedRowIdx < 0 ? 0 : Math.max(0, Math.min(selectedRowIdx, rows.length - visibleRows));
     const visibleRowSlice = rows.slice(scrollStart, scrollStart + visibleRows);
-    return (_jsxs(Box, { flexDirection: "column", width: width, borderStyle: "single", borderColor: "cyan", children: [_jsx(Text, { bold: true, color: "cyan", children: 'FIELDS [Ctrl+S save · Esc discard]' }), _jsxs(Box, { flexDirection: "column", width: innerWidth, children: [visibleRowSlice.map((row, i) => {
-                        if (row.kind === 'header') {
-                            return (_jsx(Text, { dimColor: true, children: row.label }, i));
-                        }
-                        if (row.kind === 'prop') {
-                            const p = props[row.idx];
-                            const isSelected = !inSlots && row.idx === propIdx;
-                            return (_jsx(PropRow, { prop: p, selected: isSelected, activeField: isSelected && focusLevel === 'field' ? activeField : null, textCursor: textCursor, valueCursor: valueCursor, cursorVisible: cursorVisible, width: innerWidth }, row.idx));
-                        }
-                        // slot row
-                        const s = slots[row.idx];
-                        const isSelected = inSlots && row.idx === slotIdx;
-                        return (_jsx(SlotRow, { slot: s, selected: isSelected, activeField: isSelected && focusLevel === 'field' ? activeField : null, textCursor: textCursor, cursorVisible: cursorVisible, width: innerWidth }, `slot-${row.idx}`));
-                    }), focusLevel === 'value' && addingValue && (_jsxs(Box, { paddingLeft: 4, gap: 1, children: [_jsx(Text, { color: "cyan", children: "+ " }), _jsx(Text, { children: newValueText }), _jsx(Text, { inverse: cursorVisible, children: " " }), _jsx(Text, { dimColor: true, children: "(Enter confirm \u00B7 Esc cancel)" })] }))] }), validationError && _jsx(Text, { color: "red", children: '✗ ' + validationError }), _jsx(Text, { dimColor: true, children: modeLabel })] }));
+    return (_jsxs(Box, { flexDirection: "column", width: width, borderStyle: "single", borderColor: hasEmptyProperties ? 'yellow' : 'cyan', children: [_jsx(Text, { bold: true, color: hasEmptyProperties ? 'yellow' : 'cyan', children: 'FIELDS [Ctrl+S save · Esc discard]' }), hasEmptyProperties && (_jsx(Text, { color: "yellow", children: "⚠ No properties classified for this component. The LLM didn't find anything to classify. Reject this component or add fields manually." })), _jsx(Box, { flexDirection: "column", width: innerWidth, children: visibleRowSlice.map((row, i) => {
+                    if (row.kind === 'header') {
+                        return (_jsx(Text, { dimColor: true, children: row.label }, `header-${i}`));
+                    }
+                    if (row.kind === 'component-description') {
+                        const isSelected = inComponentDesc;
+                        const isEditing = isSelected && focusLevel === 'field' && activeField === 'description';
+                        const desc = editorState.componentDescription;
+                        return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Box, { gap: 1, children: _jsx(Text, { color: isSelected ? 'white' : 'cyan', bold: isSelected, backgroundColor: isSelected ? 'blue' : undefined, children: ' component-$description ' }) }), isEditing ? (_jsx(Box, { paddingLeft: 2, flexDirection: "row", children: _jsxs(Box, { flexGrow: 1, borderStyle: "round", borderColor: "cyan", paddingX: 1, children: [_jsx(Text, { children: desc.slice(0, textCursor) }), _jsx(Text, { inverse: cursorVisible, children: desc[textCursor] ?? (cursorVisible ? '█' : ' ') }), _jsx(Text, { children: desc.slice(textCursor + 1) })] }) })) : (_jsx(Box, { paddingLeft: 2, children: _jsx(Text, { color: desc ? 'green' : undefined, dimColor: !desc, children: desc || '(none — Return to edit)' }) }))] }, `component-description-${i}`));
+                    }
+                    if (row.kind === 'prop') {
+                        const p = props[row.idx];
+                        const isSelected = !inSlots && !inComponentDesc && row.idx === propIdx;
+                        const propMeta = metadata?.props?.[p.name];
+                        return (_jsx(PropRow, { prop: p, selected: isSelected, activeField: isSelected && focusLevel === 'field' ? activeField : null, textCursor: textCursor, valueCursor: valueCursor, cursorVisible: cursorVisible, editingValue: isSelected ? editingValue : null, valueText: isSelected ? valueText : '', width: innerWidth, rationale: propMeta?.rationale ?? null, rowKey: String(row.idx) }, `prop-${row.idx}`));
+                    }
+                    // slot row
+                    const s = slots[row.idx];
+                    const isSelected = inSlots && row.idx === slotIdx;
+                    return (_jsx(SlotRow, { slot: s, selected: isSelected, activeField: isSelected && focusLevel === 'field' ? activeField : null, textCursor: textCursor, valueCursor: valueCursor, cursorVisible: cursorVisible, editingValue: isSelected ? editingValue : null, valueText: isSelected ? valueText : '', width: innerWidth }, `slot-${row.idx}`));
+                }) }), sourceOpen &&
+                !onToggleSourceExternal &&
+                (() => {
+                    const propMeta = !inSlots && !inComponentDesc && currentProp ? metadata?.props?.[currentProp.name] : undefined;
+                    const start = propMeta?.sourceStartLine ?? null;
+                    const end = propMeta?.sourceEndLine ?? null;
+                    const path = metadata?.sourcePath ?? null;
+                    const src = metadata?.componentSource ?? null;
+                    const headerPath = path ?? '<unknown source path>';
+                    if (!start || !end || !src) {
+                        return (_jsxs(Box, { flexDirection: "column", borderStyle: "single", borderColor: "gray", paddingX: 1, children: [_jsx(Text, { dimColor: true, bold: true, children: `source: ${headerPath}` }), _jsx(Text, { dimColor: true, children: "(no source location captured for this prop)" }), _jsx(Text, { dimColor: true, children: "[s] close" })] }));
+                    }
+                    const lines = src.split('\n').slice(Math.max(0, start - 1), end);
+                    return (_jsxs(Box, { flexDirection: "column", borderStyle: "single", borderColor: "gray", paddingX: 1, children: [_jsx(Text, { dimColor: true, bold: true, children: `${headerPath}: lines ${start}–${end}` }), lines.map((ln, i) => (_jsx(Text, { dimColor: true, children: ln }, `source-line-${i}`))), _jsx(Text, { dimColor: true, children: "[s] close \u00B7 [Esc] close" })] }));
+                })(), showHelp && (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: "cyan", paddingX: 1, children: [_jsx(Text, { bold: true, color: "cyan", children: "Keybindings" }), _jsx(Text, { children: " " }), _jsx(Text, { bold: true, children: "Row navigation" }), _jsx(Text, { children: '  ↑/↓ or j/k       move between rows' }), _jsx(Text, { children: '  Enter            edit fields on the current row' }), _jsx(Text, { children: '  Esc              exit the panel' }), _jsx(Text, { children: " " }), _jsx(Text, { bold: true, children: "Field editing" }), _jsx(Text, { children: '  ↑/↓ or j/k       cycle through fields (j/k literal in text inputs)' }), _jsx(Text, { children: '  ←/→              cycle picker values · move cursor in text inputs' }), _jsx(Text, { children: '  Space/Enter      toggle required' }), _jsx(Text, { children: '  Type             edit description / string default' }), _jsx(Text, { children: '  Ctrl+S           save changes' }), _jsx(Text, { children: '  Esc              exit field-edit back to the row' }), _jsx(Text, { children: " " }), _jsx(Text, { bold: true, children: "Values / allowedComponents" }), _jsx(Text, { children: '  a / e / r        add · edit · remove' }), _jsx(Text, { children: '  ↑↓ or j/k        navigate the list' }), _jsx(Text, { children: '  K / J            reorder up · down' }), _jsx(Text, { children: " " }), _jsx(Text, { bold: true, children: "Panels" }), _jsx(Text, { children: '  s                toggle source-view for the current prop' }), _jsx(Text, { children: '  i                toggle prop rationale panel' }), _jsx(Text, { children: '  I                toggle component rationale panel' }), _jsx(Text, { children: '  d                toggle removed-components panel (wizard final-review)' }), _jsx(Text, { children: '  ?                toggle this overlay' }), _jsx(Text, { children: " " }), _jsx(Text, { dimColor: true, children: "press ? or Esc to close" })] })), validationError && _jsx(Text, { color: "red", children: '✗ ' + validationError }), _jsx(Text, { dimColor: true, children: modeLabel })] }));
 }