fix(ux): stabilize explore mode toggle visuals in extraction overlay (#931)

## Summary

- **Hint bar stability**: `a`/`x`/`esc` now always appear as trailing
group in both pipeline and explore modes — mode-specific hints precede
them
- **Overlay height stability**: `stablePreviewLines()` reserves height
from tallest tab across all preview groups, padding shorter tabs with
newlines
- **Tab persistence**: exiting explore mode preserves last-viewed
preview tab instead of resetting to tab 0
- **Edge case**: unknown-table ops (empty preview groups) fall back to
rendered line count

## Reproduction steps

1. Open extraction overlay on a document with preview data
2. Note position of `a`/`x`/`esc` in hint bar and overlay height
3. Press `x` to toggle explore mode
4. **Before fix**: hint bar jumps (x key moves), overlay height changes
5. **After fix**: hint bar stable, overlay height unchanged, tab
preserved

## Changes

- `internal/app/extraction_render.go` — hint bar reorder,
`stablePreviewLines()`, tab persistence, unknown-table fallback
- `internal/app/extraction_test.go` — 5 new tests covering all fix
behaviors

Closes #892

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: cpcloud

internal/app/extraction_render.go

@@ -55,6 +55,25 @@ func previewNaturalWidth(groups []previewTableGroup, sepW int, currencySymbol st
 	return maxW
 }
 
+// stablePreviewLines returns a stable line reservation for the preview
+// section based on the tallest tab's row count. This prevents the overlay
+// height from changing when switching between tabs with different row counts.
+func stablePreviewLines(groups []previewTableGroup) int {
+	if len(groups) == 0 {
+		return 0
+	}
+	maxRows := 0
+	for _, g := range groups {
+		if len(g.cells) > maxRows {
+			maxRows = len(g.cells)
+		}
+	}
+	// Preview section structure: tabBar + underline + header + divider + rows.
+	// That's maxRows+3 newlines within the section itself, plus 2 for the
+	// separator rule and blank line above the section.
+	return maxRows + 3 + 2
+}
+
 // buildExtractionPipelineOverlay renders the pipeline step view with an
 // optional operation preview section below. The preview is dimmed when
 // not in explore mode and fully interactive when exploring.
@@ -133,7 +152,22 @@ func (m *Model) buildExtractionPipelineOverlay(
 	previewLines := 0
 	if hasOps {
 		previewSection = m.renderOperationPreviewSection(innerW, ex.exploring)
-		previewLines = strings.Count(previewSection, "\n") + 2 // +2 for separator + blank
+		// Reserve height for the tallest preview tab so the overlay
+		// doesn't jump when switching tabs in explore mode.
+		previewLines = stablePreviewLines(ex.previewGroups)
+		if previewLines == 0 {
+			// Fallback for unknown-table ops where no preview groups
+			// are generated: use rendered section's actual line count.
+			previewLines = strings.Count(previewSection, "\n") + 2
+		} else {
+			// Pad rendered section to stable height so the overlay
+			// doesn't shrink when a shorter tab is displayed.
+			actualLines := strings.Count(previewSection, "\n")
+			targetLines := previewLines - 2 // -2: sep+blank added as separate parts
+			if pad := targetLines - actualLines; pad > 0 {
+				previewSection += strings.Repeat("\n", pad)
+			}
+		}
 	}
 
 	maxH := max(m.effectiveHeight()*2/3-6-previewLines, 4)
@@ -209,9 +243,6 @@ func (m *Model) buildExtractionPipelineOverlay(
 		if cursorStatus != stepPending {
 			hints = append(hints, m.helpItem(symReturn, "expand"))
 		}
-		if hasOps {
-			hints = append(hints, m.helpItem(keyX, "explore"))
-		}
 		if ex.Done {
 			if ex.hasLLM {
 				label := "layout on"
@@ -220,7 +251,11 @@ func (m *Model) buildExtractionPipelineOverlay(
 				}
 				hints = append(hints, m.helpItem(keyT, label))
 			}
-			hints = append(hints, m.helpItem(keyA, "accept"), m.helpItem(keyEsc, "discard"))
+			if hasOps {
+				hints = append(hints, m.helpItem(keyA, "accept"), m.helpItem(keyX, "explore"), m.helpItem(keyEsc, "discard"))
+			} else {
+				hints = append(hints, m.helpItem(keyA, "accept"), m.helpItem(keyEsc, "discard"))
+			}
 		} else {
 			hints = append(hints,
 				m.helpItem(symCtrlC, "int"),
@@ -279,12 +314,10 @@ func (m *Model) renderOperationPreviewSection(innerW int, interactive bool) stri
 	tabBar := lipgloss.JoinHorizontal(lipgloss.Left, tabParts...)
 	underline := m.styles.TabUnderline().Render(strings.Repeat(symHLineHeavy, innerW))
 
-	// Always render a single tab: the active one in explore mode,
-	// the first one in pipeline mode.
-	tabIdx := 0
-	if interactive {
-		tabIdx = ex.previewTab
-	}
+	// Always render the active preview tab. In explore mode it follows
+	// user navigation; in pipeline mode it preserves the last-explored
+	// tab so the view doesn't reset on toggle.
+	tabIdx := ex.previewTab
 	if tabIdx >= len(groups) {
 		tabIdx = 0
 	}

internal/app/extraction_test.go

@@ -6,6 +6,7 @@ package app
 import (
 	"context"
 	"errors"
+	"strings"
 	"testing"
 	"time"
 
@@ -52,6 +53,13 @@ func newExtractionModel(t *testing.T, steps map[extractionStep]stepStatus) *Mode
 	return m
 }
 
+// hintIndex returns the byte index of a hint label in ANSI-stripped overlay
+// output. Keycap rendering inserts variable padding between key and label,
+// so this searches by label word alone.
+func hintIndex(stripped, label string) int {
+	return strings.Index(stripped, label)
+}
+
 func sendExtractionKey(m *Model, key string) {
 	var msg tea.KeyPressMsg
 	switch key {
@@ -3644,3 +3652,165 @@ func TestExtractionClient_RetryClearsErrorOnSuccess(t *testing.T) {
 	require.NoError(t, m.ex.extractionClientErr)
 	require.Equal(t, "some-model", client.Model())
 }
+
+func TestExploreMode_HintBarTrailingOrder(t *testing.T) {
+	t.Parallel()
+	m := newPreviewModel(t, []extract.Operation{
+		{Action: "create", Table: data.TableVendors, Data: map[string]any{"name": "A"}},
+	})
+	ex := m.ex.extraction
+
+	// Pipeline mode: x should come after a and before esc.
+	pipelineOut := m.buildExtractionPipelineOverlay(100, 90, "test")
+	pipelinePlain := ansi.Strip(pipelineOut)
+
+	pipelineAcceptIdx := hintIndex(pipelinePlain, "accept")
+	pipelineExploreIdx := hintIndex(pipelinePlain, "explore")
+	pipelineEscIdx := hintIndex(pipelinePlain, "discard")
+	require.Positive(t, pipelineAcceptIdx, "accept hint should appear")
+	require.Positive(t, pipelineExploreIdx, "explore hint should appear")
+	require.Positive(t, pipelineEscIdx, "discard hint should appear")
+	assert.Less(t, pipelineAcceptIdx, pipelineExploreIdx,
+		"accept should come before explore")
+	assert.Less(t, pipelineExploreIdx, pipelineEscIdx,
+		"explore should come before discard")
+
+	// Enter explore mode: x should still come after a and before esc.
+	sendExtractionKey(m, "x")
+	require.True(t, ex.exploring)
+
+	exploreOut := m.buildExtractionPipelineOverlay(100, 90, "test")
+	explorePlain := ansi.Strip(exploreOut)
+
+	exploreAcceptIdx := hintIndex(explorePlain, "accept")
+	exploreBackIdx := hintIndex(explorePlain, "back")
+	exploreEscIdx := hintIndex(explorePlain, "discard")
+	require.Positive(t, exploreAcceptIdx, "accept hint should appear")
+	require.Positive(t, exploreBackIdx, "back hint should appear")
+	require.Positive(t, exploreEscIdx, "discard hint should appear")
+	assert.Less(t, exploreAcceptIdx, exploreBackIdx,
+		"accept should come before back")
+	assert.Less(t, exploreBackIdx, exploreEscIdx,
+		"back should come before discard")
+}
+
+func TestExploreMode_HintBarTrailingOrderMultiTab(t *testing.T) {
+	t.Parallel()
+	m := newPreviewModel(t, []extract.Operation{
+		{Action: "create", Table: data.TableVendors, Data: map[string]any{"name": "A"}},
+		{
+			Action: "create",
+			Table:  data.TableQuotes,
+			Data:   map[string]any{"total_cents": float64(100)},
+		},
+	})
+	ex := m.ex.extraction
+
+	// Explore mode with multiple tabs: b/f tabs hint appears but
+	// a/x/esc must still be trailing three.
+	sendExtractionKey(m, "x")
+	require.True(t, ex.exploring)
+	require.Greater(t, len(ex.previewGroups), 1, "need multiple tabs")
+
+	out := m.buildExtractionPipelineOverlay(100, 90, "test")
+	plain := ansi.Strip(out)
+
+	tabsIdx := hintIndex(plain, "tabs")
+	acceptIdx := hintIndex(plain, "accept")
+	backIdx := hintIndex(plain, "back")
+	escIdx := hintIndex(plain, "discard")
+	require.Positive(t, tabsIdx, "tabs hint should appear")
+	require.Positive(t, acceptIdx)
+	require.Positive(t, backIdx)
+	require.Positive(t, escIdx)
+
+	assert.Less(t, tabsIdx, acceptIdx,
+		"tabs should come before stable trailing group")
+	assert.Less(t, acceptIdx, backIdx,
+		"accept should come before back")
+	assert.Less(t, backIdx, escIdx,
+		"back should come before discard")
+}
+
+func TestExploreMode_OverlayHeightStableAcrossToggle(t *testing.T) {
+	t.Parallel()
+	// Two tables with different row counts to trigger height change.
+	m := newPreviewModel(t, []extract.Operation{
+		{Action: "create", Table: data.TableVendors, Data: map[string]any{"name": "A"}},
+		{Action: "create", Table: data.TableVendors, Data: map[string]any{"name": "B"}},
+		{Action: "create", Table: data.TableVendors, Data: map[string]any{"name": "C"}},
+		{
+			Action: "create",
+			Table:  data.TableQuotes,
+			Data:   map[string]any{"total_cents": float64(100)},
+		},
+	})
+	ex := m.ex.extraction
+
+	// Pipeline mode overlay.
+	pipelineOut := m.buildExtractionPipelineOverlay(100, 90, "test")
+	pipelineLines := strings.Count(pipelineOut, "\n")
+
+	// Enter explore mode and switch to tab with fewer rows.
+	sendExtractionKey(m, "x")
+	require.True(t, ex.exploring)
+	sendExtractionKey(m, "f") // switch to quotes tab (1 row vs 3)
+	require.Equal(t, 1, ex.previewTab)
+
+	exploreOut := m.buildExtractionPipelineOverlay(100, 90, "test")
+	exploreLines := strings.Count(exploreOut, "\n")
+
+	assert.Equal(t, pipelineLines, exploreLines,
+		"overlay height should be identical regardless of active tab row count")
+}
+
+func TestExploreMode_TabPersistsOnExit(t *testing.T) {
+	t.Parallel()
+	m := newPreviewModel(t, []extract.Operation{
+		{Action: "create", Table: data.TableVendors, Data: map[string]any{"name": "A"}},
+		{
+			Action: "create",
+			Table:  data.TableQuotes,
+			Data:   map[string]any{"total_cents": float64(100)},
+		},
+	})
+	ex := m.ex.extraction
+
+	// Enter explore, switch to tab 1, exit.
+	sendExtractionKey(m, "x")
+	require.True(t, ex.exploring)
+	sendExtractionKey(m, "f")
+	require.Equal(t, 1, ex.previewTab)
+	sendExtractionKey(m, "x") // exit explore
+	require.False(t, ex.exploring)
+
+	// Pipeline mode should now show tab 1 (dimmed), not reset to 0.
+	out := m.renderOperationPreviewSection(80, false)
+	plain := ansi.Strip(out)
+	// Tab 1 is Quotes -- its data should appear in rendered table.
+	assert.Contains(t, plain, "Total",
+		"pipeline mode should show last-explored tab content")
+}
+
+func TestExploreMode_UnknownTableOverlayStable(t *testing.T) {
+	t.Parallel()
+	// Unknown tables produce no preview groups but hasOps is still true.
+	// Overlay should render without panicking and maintain stable height.
+	m := newPreviewModel(t, []extract.Operation{
+		{Action: "create", Table: "unknown_table", Data: map[string]any{"x": "y"}},
+	})
+
+	out := m.buildExtractionPipelineOverlay(100, 90, "test")
+	plain := ansi.Strip(out)
+	lines := strings.Count(out, "\n")
+
+	assert.Positive(t, lines, "overlay should render with nonzero height")
+	assert.Contains(t, plain, "no operations",
+		"should show fallback text for unknown tables")
+
+	// Build again -- height should be identical (stable).
+	out2 := m.buildExtractionPipelineOverlay(100, 90, "test")
+	lines2 := strings.Count(out2, "\n")
+	assert.Equal(t, lines, lines2,
+		"overlay height should be stable across renders")
+}