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

package/dist/src/import/tui/steps/GenerateReviewStep.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { useEffect, useState } from 'react';
+import { useEffect, useRef, useState } from 'react';
 import { Box, Text, useStdout } from 'ink';
 import { Sidebar } from '../../../analyze/select/tui/components/Sidebar.js';
 import { JsonPanel } from '../../../analyze/select/tui/components/JsonPanel.js';
@@ -8,10 +8,34 @@ import { StatusBar } from '../../../analyze/select/tui/components/StatusBar.js';
 import { FinalizeDialog } from '../../../analyze/select/tui/components/FinalizeDialog.js';
 import { QuitDialog } from '../../../analyze/select/tui/components/QuitDialog.js';
 import { useImmediateInput } from '../../../analyze/select/tui/hooks/useImmediateInput.js';
-import { openPipelineDb, loadCDFComponents, storeCDFComponents } from '../../../session/db.js';
+import { openPipelineDb, loadCDFComponents, storeCDFComponents, loadComponentReviewMetadata, loadComponentRationale, } from '../../../session/db.js';
+import { RationalePanel } from '../../../analyze/select/tui/components/RationalePanel.js';
+import { ComponentRationalePanel } from '../../../analyze/select/tui/components/ComponentRationalePanel.js';
+import { applyPreviewAnnotations } from '../../../analyze/select/preview-annotations.js';
+import { useLivePreview } from '../useLivePreview.js';
+import { computeNextScrollOffset } from '../../../analyze/select/tui/hooks/scroll-offset.js';
+/**
+ * Sort components for the final-review sidebar so the underlying data array
+ * matches the visual order. Empty components (zero classified $properties)
+ * surface at the top via the warning-tier path in Sidebar.tsx; we mirror that
+ * here so `selectedIdx` indexes into the same order the user sees. Without
+ * this, j/k navigation lands on different rows than the visually-selected
+ * one (INTEG-4259).
+ *
+ * Within each tier (empty / non-empty) we tie-break alphabetically by `key`.
+ */
+export function sortComponentsForSidebar(components) {
+    return [...components].sort((a, b) => {
+        const aEmpty = Object.keys(a.entry.$properties ?? {}).length === 0;
+        const bEmpty = Object.keys(b.entry.$properties ?? {}).length === 0;
+        if (aEmpty !== bEmpty)
+            return aEmpty ? -1 : 1;
+        return a.key.localeCompare(b.key);
+    });
+}
 const VISIBLE_COUNT = 20;
 const PANEL_HEIGHT = 22;
-export function GenerateReviewStep({ extractSessionId, onFinalize, onQuit, }) {
+export function GenerateReviewStep({ extractSessionId, onFinalize, onQuit, livePreview = true, spaceId = '', environmentId = '', cmaToken = '', host = '', tokensPath = '', }) {
     const { stdout } = useStdout();
     const terminalWidth = stdout?.columns ?? 80;
     const [components, setComponents] = useState([]);
@@ -23,9 +47,58 @@ export function GenerateReviewStep({ extractSessionId, onFinalize, onQuit, }) {
     const [sidebarFocused, setSidebarFocused] = useState(true);
     const [showFinalize, setShowFinalize] = useState(false);
     const [showQuit, setShowQuit] = useState(false);
-    const [editMode, setEditMode] = useState(false);
+    // FieldEditor is the default editor. JSON view is an opt-in read-only toggle.
+    const [showJson, setShowJson] = useState(false);
     const [draftValue, setDraftValue] = useState('');
     const [saveError, setSaveError] = useState(null);
+    // Feature 1: per-component review metadata (rationale + source location)
+    // for the currently-selected component. Reloaded when selection changes.
+    const [reviewMetadata, setReviewMetadata] = useState(null);
+    // Feature 2: per-component preview annotations refreshed after every
+    // FieldEditor save via the useLivePreview hook below. Empty when live
+    // preview is disabled, when creds are missing, or before the first response.
+    const [previewAnnotations, setPreviewAnnotations] = useState(new Map());
+    // Pilot-2026-06-24: raw removed list for the `d` detail panel. The
+    // annotation map only carries kind, not the rich summaries we need to list
+    // names/ids when the operator asks "which ones?".
+    const [removedComponents, setRemovedComponents] = useState([]);
+    const [showRemovedPanel, setShowRemovedPanel] = useState(false);
+    // Lifted rationale + source panels (replaces FieldEditor's right pane).
+    // Mutually exclusive states.
+    const [panelOpen, setPanelOpen] = useState('none');
+    const [panelScrollOffset, setPanelScrollOffset] = useState(0);
+    const [textEntryActive, setTextEntryActive] = useState(false);
+    const [componentRationale, setComponentRationale] = useState(null);
+    // Tracks the first `g` of a potential `gg` double-tap (jumps to top in
+    // JSON-view + panel-focused state). Reset on any non-`g` key.
+    const pendingGRef = useRef(false);
+    const handleLivePreviewResult = (response) => {
+        if (!response)
+            return;
+        setPreviewAnnotations(applyPreviewAnnotations(response, components.map((c) => c.key)));
+        setRemovedComponents(response.components.removed ?? []);
+    };
+    const livePreviewHook = useLivePreview({
+        enabled: livePreview,
+        sessionId: extractSessionId,
+        tokensPath,
+        spaceId,
+        environmentId,
+        cmaToken,
+        host,
+        onResult: handleLivePreviewResult,
+    });
+    // Manual spinner cycling (no extra dep) for the sidebar status-row
+    // indicator. Runs only while the live-preview hook reports `running`.
+    const SPINNER_FRAMES = '⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏';
+    const [spinnerTick, setSpinnerTick] = useState(0);
+    useEffect(() => {
+        if (livePreviewHook.status !== 'running')
+            return;
+        const id = setInterval(() => setSpinnerTick((t) => t + 1), 80);
+        return () => clearInterval(id);
+    }, [livePreviewHook.status]);
+    const livePreviewSpinner = SPINNER_FRAMES[spinnerTick % SPINNER_FRAMES.length];
     useEffect(() => {
         async function load() {
             const db = openPipelineDb();
@@ -41,7 +114,12 @@ export function GenerateReviewStep({ extractSessionId, onFinalize, onQuit, }) {
                 setLoading(false);
                 return;
             }
-            setComponents(cdfComponents.map(({ key, entry }) => ({ key, entry, status: 'needs-review' })));
+            const reviewEntries = cdfComponents.map(({ key, entry }) => ({
+                key,
+                entry,
+                status: 'needs-review',
+            }));
+            setComponents(sortComponentsForSidebar(reviewEntries));
             setLoading(false);
         }
         load().catch((e) => {
@@ -49,18 +127,81 @@ export function GenerateReviewStep({ extractSessionId, onFinalize, onQuit, }) {
             setLoading(false);
         });
     }, []);
+    // Pilot-2026-06-23 R2: fire the live preview once on entry to final-review
+    // so diff badges populate before the operator's first save. We gate on the
+    // livePreview prop to honor --no-live-preview without depending on the
+    // hook's internal short-circuit. Cred-missing is still handled by the
+    // hook's own no-op path.
+    useEffect(() => {
+        if (loading)
+            return;
+        if (!livePreview)
+            return;
+        if (components.length === 0)
+            return;
+        livePreviewHook.trigger();
+        // Intentionally only on load completion — subsequent fires happen via
+        // handleEditSave. Adding livePreviewHook to deps would re-fire on every
+        // hook re-creation.
+    }, [loading]);
+    // Feature 1: load review metadata (rationale + source location) for the
+    // selected component when selection changes.
+    useEffect(() => {
+        const current = components[selectedIdx];
+        if (!current) {
+            setReviewMetadata(null);
+            return;
+        }
+        const db = openPipelineDb();
+        try {
+            setReviewMetadata(loadComponentReviewMetadata(db, extractSessionId, current.key));
+        }
+        catch {
+            setReviewMetadata(null);
+        }
+        finally {
+            db.close();
+        }
+    }, [selectedIdx, components, extractSessionId]);
+    // Load component-level rationale for the selected component (drives the
+    // `I` ComponentRationalePanel). Decoupled from review metadata so the data
+    // contracts can evolve independently.
+    useEffect(() => {
+        const current = components[selectedIdx];
+        if (!current) {
+            setComponentRationale(null);
+            return;
+        }
+        const db = openPipelineDb();
+        try {
+            setComponentRationale(loadComponentRationale(db, extractSessionId, current.key));
+        }
+        catch {
+            setComponentRationale(null);
+        }
+        finally {
+            db.close();
+        }
+    }, [selectedIdx, components, extractSessionId]);
     const updateStatus = (idx, status) => {
         setComponents((prev) => prev.map((c, i) => (i === idx ? { ...c, status } : c)));
     };
     const handleFinalizeConfirm = () => {
-        const rejected = components.filter((c) => c.status === 'rejected').map((c) => c.key);
-        if (rejected.length > 0) {
+        // Strict opt-in: only EXPLICITLY ACCEPTED components ship. Anything left
+        // in 'needs-review' OR explicitly 'rejected' is downgraded to
+        // 'generate-rejected' so loadCDFComponents excludes it from the manifest.
+        // The operator told us they want accept-to-ship semantics — leaving a
+        // component unresolved should NOT silently push it (Pilot-2026-06-24 R2).
+        const explicitlyRejected = components.filter((c) => c.status === 'rejected').map((c) => c.key);
+        const unresolved = components.filter((c) => c.status === 'needs-review').map((c) => c.key);
+        const toReject = [...explicitlyRejected, ...unresolved];
+        if (toReject.length > 0) {
             const db = openPipelineDb();
             try {
                 const stmt = db.prepare(`UPDATE raw_components SET status = 'generate-rejected' WHERE session_id = ? AND name = ?`);
                 db.exec('BEGIN');
                 try {
-                    for (const name of rejected) {
+                    for (const name of toReject) {
                         stmt.run(extractSessionId, name);
                     }
                     db.exec('COMMIT');
@@ -74,8 +215,8 @@ export function GenerateReviewStep({ extractSessionId, onFinalize, onQuit, }) {
                 db.close();
             }
         }
-        const accepted = components.filter((c) => c.status !== 'rejected').length;
-        onFinalize(accepted, rejected.length);
+        const acceptedCount = components.filter((c) => c.status === 'accepted').length;
+        onFinalize(acceptedCount, explicitlyRejected.length, unresolved.length);
     };
     const handleEditSave = () => {
         const current = components[selectedIdx];
@@ -93,7 +234,6 @@ export function GenerateReviewStep({ extractSessionId, onFinalize, onQuit, }) {
                 return;
             }
             setComponents((prev) => prev.map((c, i) => i === selectedIdx ? { ...c, entry, status: c.status === 'needs-review' ? 'accepted' : c.status } : c));
-            setEditMode(false);
             setDraftValue('');
             setSaveError(null);
             const db = openPipelineDb();
@@ -103,13 +243,15 @@ export function GenerateReviewStep({ extractSessionId, onFinalize, onQuit, }) {
             finally {
                 db.close();
             }
+            // Feature 2: re-fire the live preview now that pipeline.db reflects
+            // the new state. The hook owns debounce + cred-missing short-circuit.
+            livePreviewHook.trigger();
         }
         catch (e) {
             setSaveError(String(e));
         }
     };
     const handleEditDiscard = () => {
-        setEditMode(false);
         setDraftValue('');
         setSaveError(null);
     };
@@ -119,20 +261,148 @@ export function GenerateReviewStep({ extractSessionId, onFinalize, onQuit, }) {
             return;
         if (dialogOpen)
             return;
-        if (editMode)
+        // Pilot-2026-06-24: removed-detail panel. When open, only `d` (toggle)
+        // and Esc (close) respond — all other input is swallowed so j/k/Enter/
+        // Ctrl+S can't move state behind the modal. Mirrors the `?` overlay
+        // pattern from 8f0c62e in FieldEditor.
+        if (showRemovedPanel) {
+            if (input === 'd' || key.escape) {
+                setShowRemovedPanel(false);
+            }
             return;
-        if (input === 'q') {
-            setShowQuit(true);
+        }
+        // `d` opens the panel only when live-preview is enabled and there is at
+        // least one removed component to display. Sidebar-focused only so it
+        // doesn't collide with FieldEditor input.
+        if (input === 'd' && sidebarFocused && livePreview && removedComponents.length > 0) {
+            setShowRemovedPanel(true);
             return;
         }
-        if (input === 'F') {
-            setShowFinalize(true);
+        // Lifted rationale + source panels: i/I/s fire from anywhere (sidebar OR
+        // panel focus). Gated against text-entry surfaces inside FieldEditor
+        // (description editors, string-default editor, value-list text entry)
+        // via the `onTextEntryActiveChange` callback, plus the help/finalize/quit
+        // overlays and the JSON view.
+        if (panelOpen !== 'none') {
+            const PANEL_HEIGHT_LOCAL = 12;
+            const next = computeNextScrollOffset(panelScrollOffset, input, key, 9999, PANEL_HEIGHT_LOCAL);
+            if (next !== null) {
+                setPanelScrollOffset(() => next);
+                return;
+            }
+            if (key.escape) {
+                setPanelOpen('none');
+                setPanelScrollOffset(() => 0);
+                return;
+            }
+            // Guard against Ctrl-letter aliases (Tab is Ctrl+I in ASCII, Ctrl+S would
+            // collide with save in nested editors). Only react to bare keystrokes.
+            const togglable = !key.ctrl && !key.tab && !key.meta && !key.return;
+            if (togglable && input === 'i' && panelOpen === 'prop-rationale') {
+                setPanelOpen('none');
+                setPanelScrollOffset(() => 0);
+                return;
+            }
+            if (togglable && input === 'I' && panelOpen === 'component-rationale') {
+                setPanelOpen('none');
+                setPanelScrollOffset(() => 0);
+                return;
+            }
+            if (togglable && input === 's' && panelOpen === 'source') {
+                setPanelOpen('none');
+                setPanelScrollOffset(() => 0);
+                return;
+            }
+            // Cross-panel toggles while one is open.
+            if (togglable && input === 'i') {
+                setPanelOpen('prop-rationale');
+                setPanelScrollOffset(() => 0);
+                return;
+            }
+            if (togglable && input === 'I') {
+                setPanelOpen('component-rationale');
+                setPanelScrollOffset(() => 0);
+                return;
+            }
+            if (togglable && input === 's') {
+                setPanelOpen('source');
+                setPanelScrollOffset(() => 0);
+                return;
+            }
             return;
         }
+        const rationaleKeyOk = !textEntryActive && !showJson && !key.ctrl && !key.tab && !key.meta && !key.return;
+        if (rationaleKeyOk) {
+            if (input === 'i') {
+                setPanelOpen('prop-rationale');
+                setPanelScrollOffset(() => 0);
+                return;
+            }
+            if (input === 'I') {
+                setPanelOpen('component-rationale');
+                setPanelScrollOffset(() => 0);
+                return;
+            }
+        }
+        // Tab toggles focus bidirectionally between sidebar and panel. `e` is a
+        // sidebar-only alias for crossing INTO the panel — gating it to the
+        // sidebar-focused state prevents collision with FieldEditor's enum-values
+        // `e` binding (INTEG-4254) when the panel is focused. Crossing back from
+        // panel to sidebar is Tab-only.
         if (key.tab) {
             setSidebarFocused((prev) => !prev);
             return;
         }
+        if (input === 'e' && sidebarFocused) {
+            setSidebarFocused(false);
+            return;
+        }
+        // JSON view + panel focused: own j/k/arrows/PageUp/PageDown/Ctrl+u/d/gg/G
+        // for scrolling. Computed against the live `selectedJson` so the
+        // viewport math matches what JsonPanel renders.
+        if (!sidebarFocused && showJson) {
+            const current = components[selectedIdx];
+            const currentJson = current ? JSON.stringify({ [current.key]: current.entry }, null, 2) : '';
+            const totalLines = currentJson.split('\n').length;
+            const maxOffset = Math.max(0, totalLines - PANEL_HEIGHT);
+            // `gg` double-tap to jump to top; single `g` arms the pending flag.
+            if (input === 'g' && !key.ctrl) {
+                if (pendingGRef.current) {
+                    pendingGRef.current = false;
+                    setJsonScrollOffset(() => 0);
+                    return;
+                }
+                pendingGRef.current = true;
+                return;
+            }
+            const next = computeNextScrollOffset(jsonScrollOffset, input, key, totalLines, PANEL_HEIGHT);
+            if (next !== null) {
+                pendingGRef.current = false;
+                // Functional setState mirrors the cursor-stutter fix (commit 5d11e60).
+                // Clamp against maxOffset re-computed at apply time in case totalLines
+                // shifted between events (defensive — helper already clamps).
+                const clamped = Math.min(maxOffset, Math.max(0, next));
+                setJsonScrollOffset(() => clamped);
+                return;
+            }
+            // Any other key in this slice resets the gg-pending flag, then falls
+            // through to the early-return below so the panel-focused state still
+            // swallows non-scroll input.
+            pendingGRef.current = false;
+        }
+        // When the panel is focused, FieldEditor (or JsonPanel) owns the keys.
+        // Only Tab (handled above) should escape from the panel-focused state.
+        if (!sidebarFocused)
+            return;
+        // Sidebar-focused keymap.
+        if (input === 'q') {
+            setShowQuit(true);
+            return;
+        }
+        if (input === 'F') {
+            setShowFinalize(true);
+            return;
+        }
         if (input === 'a') {
             updateStatus(selectedIdx, 'accepted');
             return;
@@ -145,32 +415,41 @@ export function GenerateReviewStep({ extractSessionId, onFinalize, onQuit, }) {
             setComponents((prev) => prev.map((c) => (c.status === 'needs-review' ? { ...c, status: 'accepted' } : c)));
             return;
         }
-        if (input === 'e' && selected) {
-            setDraftValue(JSON.stringify({ [selected.key]: selected.entry }, null, 2));
-            setEditMode(true);
+        if (input === 'J') {
+            // Toggle read-only JSON view.
+            setShowJson((prev) => !prev);
+            setJsonScrollOffset(0);
+            pendingGRef.current = false;
             return;
         }
-        if (sidebarFocused) {
-            if (key.upArrow || input === 'k') {
-                const newIdx = Math.max(0, selectedIdx - 1);
-                setSelectedIdx(newIdx);
-                setJsonScrollOffset(0);
-                setSidebarScrollOffset((prev) => Math.min(prev, newIdx));
-            }
-            else if (key.downArrow || input === 'j') {
-                const newIdx = Math.min(components.length - 1, selectedIdx + 1);
-                setSelectedIdx(newIdx);
-                setJsonScrollOffset(0);
-                setSidebarScrollOffset((prev) => (newIdx >= prev + VISIBLE_COUNT ? newIdx - VISIBLE_COUNT + 1 : prev));
-            }
+        if (key.upArrow || input === 'k') {
+            // Pilot-2026-06-23 bug: rapid k/j bursts could lose cursor position
+            // because the previous implementation read `selectedIdx` from the
+            // handler's closure. Under high keyboard-repeat rate multiple key
+            // events fire between Ink render flushes, so every invocation saw the
+            // same stale value and recomputed the same `newIdx`. Using functional
+            // setState chains the updates correctly: each pending update sees the
+            // post-update value of the previous one. The viewport offset update is
+            // nested inside the cursor updater so it always reflects the same
+            // newIdx that selectedIdx is being set to.
+            setSelectedIdx((prev) => {
+                const newIdx = Math.max(0, prev - 1);
+                setSidebarScrollOffset((off) => Math.min(off, newIdx));
+                return newIdx;
+            });
+            setJsonScrollOffset(0);
+            setDraftValue('');
+            setSaveError(null);
         }
-        else {
-            if (key.upArrow || input === 'k') {
-                setJsonScrollOffset((prev) => Math.max(0, prev - 1));
-            }
-            else if (key.downArrow || input === 'j') {
-                setJsonScrollOffset((prev) => prev + 1);
-            }
+        else if (key.downArrow || input === 'j') {
+            setSelectedIdx((prev) => {
+                const newIdx = Math.min(components.length - 1, prev + 1);
+                setSidebarScrollOffset((off) => (newIdx >= off + VISIBLE_COUNT ? newIdx - VISIBLE_COUNT + 1 : off));
+                return newIdx;
+            });
+            setJsonScrollOffset(0);
+            setDraftValue('');
+            setSaveError(null);
         }
     });
     if (loading) {
@@ -181,32 +460,117 @@ export function GenerateReviewStep({ extractSessionId, onFinalize, onQuit, }) {
     }
     const selected = components[selectedIdx] ?? null;
     const selectedJson = selected ? JSON.stringify({ [selected.key]: selected.entry }, null, 2) : '';
+    // A component with zero classified $properties is a real defensibility issue —
+    // it can't be pushed to Contentful (no fields). Surface it in the sidebar via
+    // the existing warning-color path (yellow) and a "(empty)" suffix so the user
+    // can see what went wrong. They can manually add props in FieldEditor or
+    // explicitly reject the component.
+    const isEmpty = (c) => Object.keys(c.entry.$properties).length === 0;
+    const emptyCount = components.filter(isEmpty).length;
     const sidebarItems = components.map((c) => ({
         id: c.key,
-        name: c.key,
+        name: isEmpty(c) ? `${c.key} (empty)` : c.key,
         status: c.status,
+        previewAnnotation: previewAnnotations.get(c.key),
         extractionConfidence: null,
         needsReview: false,
         validationErrorCount: 0,
-        validationWarningCount: 0,
+        validationWarningCount: isEmpty(c) ? 1 : 0,
     }));
-    const longestName = components.reduce((m, c) => Math.max(m, c.key.length), 0);
-    const sidebarWidth = Math.min(Math.max(longestName + 4, 14), 22);
+    // Account for the "(empty)" suffix added to zero-prop component names so the
+    // sidebar doesn't truncate it.
+    const longestName = components.reduce((m, c) => Math.max(m, c.key.length + (isEmpty(c) ? ' (empty)'.length : 0)), 0);
+    // +5 = border (1) + status icon (1) + badge column (1) + space (1) + border (1).
+    // The badge column is reserved even when no annotation is present so the
+    // sidebar width doesn't jitter as live-preview annotations flip in/out.
+    const sidebarWidth = Math.min(Math.max(longestName + 5, 14), 30);
     const panelWidth = Math.max(10, terminalWidth - sidebarWidth - 4);
     const accepted = components.filter((c) => c.status === 'accepted').length;
     const rejected = components.filter((c) => c.status === 'rejected').length;
     const needsReview = components.filter((c) => c.status === 'needs-review').length;
     const propCount = selected ? Object.keys(selected.entry.$properties).length : 0;
     const slotCount = selected?.entry.$slots ? Object.keys(selected.entry.$slots).length : 0;
-    return (_jsxs(Box, { flexDirection: "column", children: [showFinalize && (_jsx(FinalizeDialog, { accepted: accepted, rejected: rejected, needsReview: needsReview, onConfirm: handleFinalizeConfirm, onCancel: () => setShowFinalize(false) })), showQuit && _jsx(QuitDialog, { hasUnsavedDrafts: false, onConfirm: onQuit, onCancel: () => setShowQuit(false) }), !dialogOpen && (_jsxs(Box, { children: [_jsx(Sidebar, { components: sidebarItems, selectedId: selected?.key ?? null, focused: sidebarFocused, scrollOffset: sidebarScrollOffset, visibleCount: VISIBLE_COUNT, onSelect: (id) => {
+    return (_jsxs(Box, { flexDirection: "column", children: [showFinalize && (_jsx(FinalizeDialog, { accepted: accepted, rejected: rejected, needsReview: needsReview, onConfirm: handleFinalizeConfirm, onCancel: () => setShowFinalize(false) })), showQuit && _jsx(QuitDialog, { hasUnsavedDrafts: false, onConfirm: onQuit, onCancel: () => setShowQuit(false) }), showRemovedPanel && !dialogOpen && (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: "cyan", paddingX: 1, children: [_jsx(Text, { bold: true, color: "cyan", children: `Removed components (${removedComponents.length})` }), _jsx(Text, { dimColor: true, children: "these will be DELETED from the target space" }), _jsx(Text, { children: " " }), removedComponents.map((rc) => (_jsx(Text, { children: `- ${rc.name}${rc.id ? `  (${rc.id})` : ''}` }, rc.id))), _jsx(Text, { children: " " }), _jsx(Text, { dimColor: true, children: "press d or Esc to close" })] })), !dialogOpen &&
+                livePreview &&
+                (() => {
+                    // Pilot-2026-06-23 R2: at-a-glance diff summary at the top of the
+                    // step. Mutually exclusive states:
+                    //   - hook running (and we don't yet have annotations) → spinner.
+                    //   - hook disabled (creds rejected) → static disabled hint.
+                    //   - annotations populated → counts.
+                    //   - idle, no annotations, not disabled → render nothing.
+                    const counts = { new: 0, changed: 0, removed: 0, breaking: 0 };
+                    for (const v of previewAnnotations.values()) {
+                        counts[v] = (counts[v] ?? 0) + 1;
+                    }
+                    const hasCounts = counts.new + counts.changed + counts.removed + counts.breaking > 0;
+                    if (livePreviewHook.disabled) {
+                        return _jsx(Text, { dimColor: true, children: 'Preview: disabled (creds rejected)' });
+                    }
+                    if (livePreviewHook.status === 'running' && !hasCounts) {
+                        return _jsx(Text, { dimColor: true, children: `Preview: ${livePreviewSpinner} running...` });
+                    }
+                    if (!hasCounts)
+                        return null;
+                    return (_jsxs(Box, { children: [_jsx(Text, { children: 'Preview: ' }), _jsx(Text, { color: "green", children: `${counts.new} new` }), _jsx(Text, { children: ' · ' }), _jsx(Text, { color: "yellow", children: `${counts.changed} changed` }), _jsx(Text, { children: ' · ' }), _jsx(Text, { dimColor: true, children: `${counts.removed} removed` }), removedComponents.length > 0 && _jsx(Text, { dimColor: true, children: ' ([d] removed list)' }), _jsx(Text, { children: ' · ' }), _jsx(Text, { color: "red", bold: true, children: `${counts.breaking} breaking` })] }));
+                })(), !dialogOpen && emptyCount > 0 && (_jsx(Text, { color: "yellow", children: `⚠ ${emptyCount} component${emptyCount === 1 ? '' : 's'} had no classifiable props — review with care` })), !dialogOpen && (_jsxs(Box, { children: [_jsx(Sidebar, { components: sidebarItems, selectedId: selected?.key ?? null, focused: sidebarFocused, scrollOffset: sidebarScrollOffset, visibleCount: VISIBLE_COUNT, onSelect: (id) => {
                             const idx = components.findIndex((c) => c.key === id);
                             if (idx >= 0) {
                                 setSelectedIdx(idx);
                                 setJsonScrollOffset(0);
                             }
-                        }, onScrollChange: setSidebarScrollOffset, width: sidebarWidth }), _jsx(Box, { flexGrow: 1, paddingLeft: 1, flexDirection: "column", children: selected ? (_jsxs(_Fragment, { children: [_jsxs(Box, { children: [_jsx(Text, { bold: true, children: selected.key }), _jsx(Box, { flexGrow: 1 }), _jsxs(Text, { dimColor: true, children: [propCount, " prop", propCount !== 1 ? 's' : '', slotCount > 0 ? ` · ${slotCount} slot${slotCount !== 1 ? 's' : ''}` : '', '  ', sidebarFocused ? '[Tab] focus panel' : '[Tab] focus list'] })] }), editMode ? (_jsx(FieldEditor, { value: draftValue || selectedJson, width: panelWidth, height: PANEL_HEIGHT, onChange: setDraftValue, onSave: handleEditSave, onDiscard: handleEditDiscard })) : (_jsx(JsonPanel, { label: "GENERATED DEFINITION", value: selectedJson, scrollOffset: jsonScrollOffset, width: panelWidth, height: PANEL_HEIGHT, active: !sidebarFocused })), saveError && _jsx(Text, { color: "red", children: '✗ ' + saveError }), _jsx(Text, { dimColor: true, children: editMode
-                                        ? '  [Ctrl+S] save  [Esc] discard'
-                                        : '  [a] accept  [r] reject  [e] edit  [A] accept all  [F] finalize  [Tab] toggle focus  [q] quit' })] })) : (_jsx(Text, { dimColor: true, children: "No component selected" })) })] })), !dialogOpen && (_jsx(StatusBar, { accepted: accepted, rejected: rejected, reviewed: 0, needsReview: needsReview, onApproveAll: () => {
+                        }, onScrollChange: setSidebarScrollOffset, width: sidebarWidth }), _jsx(Box, { flexGrow: 1, paddingLeft: 1, flexDirection: "column", children: selected ? (_jsxs(_Fragment, { children: [_jsxs(Box, { children: [_jsx(Text, { bold: true, children: selected.key }), _jsx(Box, { flexGrow: 1 }), _jsxs(Text, { dimColor: true, children: [propCount, " prop", propCount !== 1 ? 's' : '', slotCount > 0 ? ` · ${slotCount} slot${slotCount !== 1 ? 's' : ''}` : '', '  ', sidebarFocused ? '[e/Tab] focus panel' : '[Tab] focus list'] })] }), panelOpen === 'prop-rationale' ? ((() => {
+                                    const rows = [
+                                        ...(componentRationale?.props ?? []).map((p) => ({
+                                            name: p.name,
+                                            kind: 'prop',
+                                            rationale: p.rationale ?? '',
+                                        })),
+                                        ...(componentRationale?.slots ?? []).map((s) => ({
+                                            name: s.name,
+                                            kind: 'slot',
+                                            rationale: s.rationale ?? '',
+                                        })),
+                                    ];
+                                    return (_jsx(RationalePanel, { componentName: componentRationale?.name ?? selected.key, rows: rows, scrollOffset: panelScrollOffset, width: panelWidth, height: PANEL_HEIGHT, active: true }));
+                                })()) : panelOpen === 'component-rationale' ? (_jsx(ComponentRationalePanel, { data: componentRationale ?? {
+                                        name: selected.key,
+                                        description: null,
+                                        descriptionRationale: null,
+                                        propsRationale: null,
+                                        slotsRationale: null,
+                                        props: [],
+                                        slots: [],
+                                    }, scrollOffset: panelScrollOffset, width: panelWidth, height: PANEL_HEIGHT, active: true })) : panelOpen === 'source' ? ((() => {
+                                    const path = reviewMetadata?.sourcePath ?? null;
+                                    const src = reviewMetadata?.componentSource ?? null;
+                                    const headerPath = path ?? '<unknown source path>';
+                                    const lines = src ? src.split('\n').slice(panelScrollOffset, panelScrollOffset + PANEL_HEIGHT) : [];
+                                    return (_jsxs(Box, { flexDirection: "column", width: panelWidth, borderStyle: "single", borderColor: "gray", paddingX: 1, children: [_jsx(Text, { dimColor: true, bold: true, children: `source: ${headerPath}` }), src ? (lines.map((ln, i) => (_jsx(Text, { dimColor: true, children: ln }, `source-line-${i}`)))) : (_jsx(Text, { dimColor: true, children: '(no source captured)' })), _jsx(Text, { dimColor: true, children: '[s/Esc] close' })] }));
+                                })()) : showJson ? (_jsx(JsonPanel, { label: "GENERATED DEFINITION (read-only)", value: selectedJson, scrollOffset: jsonScrollOffset, width: panelWidth, height: PANEL_HEIGHT, active: !sidebarFocused })) : (_jsx(FieldEditor, { value: draftValue || selectedJson, width: panelWidth, height: PANEL_HEIGHT, active: !sidebarFocused, onChange: setDraftValue, onSave: handleEditSave, onDiscard: handleEditDiscard, onExit: () => setSidebarFocused(true), metadata: reviewMetadata
+                                        ? {
+                                            sourcePath: reviewMetadata.sourcePath,
+                                            componentSource: reviewMetadata.componentSource,
+                                            props: reviewMetadata.props,
+                                        }
+                                        : undefined, onTogglePropRationale: () => {
+                                        setPanelOpen('prop-rationale');
+                                        setPanelScrollOffset(() => 0);
+                                    }, onToggleComponentRationale: () => {
+                                        setPanelOpen('component-rationale');
+                                        setPanelScrollOffset(() => 0);
+                                    }, onToggleSourceExternal: () => {
+                                        setPanelOpen('source');
+                                        setPanelScrollOffset(() => 0);
+                                    }, onTextEntryActiveChange: setTextEntryActive }, selected.key)), saveError && _jsx(Text, { color: "red", children: '✗ ' + saveError }), _jsxs(Text, { dimColor: true, children: [sidebarFocused
+                                            ? '  [a] accept  [r] reject  [A] accept all  [J] ' +
+                                                (showJson ? 'hide JSON' : 'show JSON') +
+                                                '  [F] finalize  [e/Tab] focus panel' +
+                                                (livePreview && removedComponents.length > 0 ? '  [d] removed list' : '') +
+                                                '  [q] quit'
+                                            : showJson
+                                                ? '  [j/k] scroll  [Ctrl+u/d] half-page  [gg/G] top/bottom  [Tab] focus list'
+                                                : '  [Tab] focus list  (edit fields)', livePreviewHook.status === 'running' && _jsx(Text, { children: `  ${livePreviewSpinner} live preview` }), livePreviewHook.disabled && _jsx(Text, { children: '  · live preview disabled' })] })] })) : (_jsx(Text, { dimColor: true, children: "No component selected" })) })] })), !dialogOpen && (_jsx(StatusBar, { accepted: accepted, rejected: rejected, reviewed: 0, needsReview: needsReview, onApproveAll: () => {
                     setComponents((prev) => prev.map((c) => (c.status === 'needs-review' ? { ...c, status: 'accepted' } : c)));
                 }, onFinalize: () => setShowFinalize(true) }))] }));
 }

package/dist/src/import/tui/steps/PushDecisionGateStep.d.ts

@@ -0,0 +1,19 @@
+import React from 'react';
+export type PushDecisionChoice = 'both' | 'push-only' | 'save-only';
+type PushDecisionGateStepProps = {
+    summary: string;
+    context: string;
+    fileList: string;
+    onChoice: (choice: PushDecisionChoice) => void;
+    onQuit: () => void;
+    /**
+     * Skip-credentials spec — Task 3. When the operator advanced past the
+     * credentials screen via the skip path, push options are not actually
+     * usable (we never validated a token). Render all three rows for visual
+     * continuity but disable "Save AND push" and "Push only", with the
+     * `(unavailable — credentials skipped)` suffix.
+     */
+    pushDisabled?: boolean;
+};
+export declare function PushDecisionGateStep({ summary, context, onChoice, onQuit, pushDisabled, }: PushDecisionGateStepProps): React.ReactElement;
+export {};