auq-mcp-server 2.1.0 → 2.2.0

package/dist/src/tui/components/SessionPicker.js

@@ -0,0 +1,159 @@
+import { Box, Text, useInput, useStdout } from "ink";
+import React, { useEffect, useState } from "react";
+import { useTheme } from "../ThemeContext.js";
+import { formatRelativeTime } from "../utils/relativeTime.js";
+/* ------------------------------------------------------------------ */
+/*  Helpers                                                           */
+/* ------------------------------------------------------------------ */
+function countAnswered(answers) {
+    if (!answers)
+        return 0;
+    let count = 0;
+    for (const ans of answers.values()) {
+        if (ans.selectedOption || ans.customText) {
+            count++;
+            continue;
+        }
+        if (ans.selectedOptions && ans.selectedOptions.length > 0)
+            count++;
+    }
+    return count;
+}
+function truncate(text, max) {
+    if (text.length <= max)
+        return text;
+    return text.slice(0, max - 1) + "…";
+}
+/* ------------------------------------------------------------------ */
+/*  Component                                                         */
+/* ------------------------------------------------------------------ */
+/**
+ * SessionPicker — a modal overlay listing all queued sessions.
+ *
+ * Opened via Ctrl+S. Each row shows:
+ *   {index}. {title} — {workDir}  [{answered}/{total}]  {age}
+ *
+ * Navigation:
+ *   ↑ / ↓ : move highlight
+ *   Enter  : select highlighted session
+ *   Esc    : close without switching
+ */
+export const SessionPicker = ({ isOpen, sessions, activeIndex, sessionUIStates, onSelectIndex, onClose, }) => {
+    const { theme } = useTheme();
+    const { stdout } = useStdout();
+    const termHeight = stdout?.rows ?? 24;
+    const termWidth = stdout?.columns ?? 80;
+    // ── Highlight state ──────────────────────────────────────────────
+    const [highlightIndex, setHighlightIndex] = useState(activeIndex);
+    // Reset highlight to active index each time the picker opens
+    useEffect(() => {
+        if (isOpen) {
+            setHighlightIndex(activeIndex);
+        }
+    }, [isOpen, activeIndex]);
+    // ── Keyboard handling (only active when overlay is open) ────────
+    useInput((input, key) => {
+        if (key.upArrow) {
+            setHighlightIndex((prev) => Math.max(0, prev - 1));
+        }
+        else if (key.downArrow) {
+            setHighlightIndex((prev) => Math.min(sessions.length - 1, prev + 1));
+        }
+        else if (key.return) {
+            onSelectIndex(highlightIndex);
+            onClose();
+        }
+        else if (key.escape) {
+            onClose();
+        }
+        else {
+            // Direct number jump (1-9)
+            const num = parseInt(input, 10);
+            if (num >= 1 && num <= sessions.length) {
+                onSelectIndex(num - 1);
+                onClose();
+            }
+        }
+    }, { isActive: isOpen });
+    // ── Render nothing when closed ──────────────────────────────────
+    if (!isOpen)
+        return null;
+    // ── Scrolling logic ─────────────────────────────────────────────
+    // Reserve lines for border (2), title (1), padding (2), footer hint (2)
+    const chromeLines = 7;
+    const maxVisibleRows = Math.max(1, termHeight - chromeLines);
+    const needsScroll = sessions.length > maxVisibleRows;
+    let scrollOffset = 0;
+    if (needsScroll) {
+        // Keep highlighted row centred in the visible window
+        scrollOffset = Math.max(0, Math.min(highlightIndex - Math.floor(maxVisibleRows / 2), sessions.length - maxVisibleRows));
+    }
+    const visibleSessions = sessions.slice(scrollOffset, scrollOffset + maxVisibleRows);
+    // ── Derive max label widths from terminal size ──────────────────
+    // Layout: " {idx}. {title} — {dir}  [{x}/{y}]  {age} "
+    // We cap the variable-width parts to fit a single line.
+    const innerWidth = Math.max(30, termWidth - 6); // 6 for border + padding
+    const fixedOverhead = 18; // " 1. " + " — " + "  [x/y]  " + " Xm ago"
+    const dynamicWidth = Math.max(10, innerWidth - fixedOverhead);
+    const titleMax = Math.max(6, Math.floor(dynamicWidth * 0.55));
+    const dirMax = Math.max(4, dynamicWidth - titleMax);
+    return (React.createElement(Box, { flexDirection: "column", alignItems: "center", justifyContent: "center" },
+        React.createElement(Box, { flexDirection: "column", borderStyle: "round", borderColor: theme.components.sessionPicker.border, paddingX: 2, paddingY: 1, width: Math.min(innerWidth + 6, termWidth) },
+            React.createElement(Box, { justifyContent: "center", marginBottom: 1 },
+                React.createElement(Text, { bold: true, color: theme.components.sessionPicker.title }, "Switch Session"),
+                React.createElement(Text, { color: theme.components.sessionPicker.rowDim },
+                    "  ",
+                    "(",
+                    sessions.length,
+                    " queued)")),
+            needsScroll && scrollOffset > 0 && (React.createElement(Box, { justifyContent: "center" },
+                React.createElement(Text, { color: theme.components.sessionPicker.rowDim }, "\u25B2 more"))),
+            visibleSessions.map((session, visibleIdx) => {
+                const realIdx = scrollOffset + visibleIdx;
+                const isHighlighted = realIdx === highlightIndex;
+                const isActive = realIdx === activeIndex;
+                const uiState = sessionUIStates[session.sessionId];
+                const questions = session.sessionRequest.questions;
+                const title = truncate(questions[0]?.title || "Untitled", titleMax);
+                const dir = truncate(session.sessionRequest.workingDirectory || "unknown", dirMax);
+                const total = questions.length;
+                const answered = countAnswered(uiState?.answers);
+                const age = formatRelativeTime(session.timestamp);
+                // Row colors
+                const rowBg = isHighlighted
+                    ? theme.components.sessionPicker.highlightBg
+                    : undefined;
+                const textColor = isHighlighted
+                    ? theme.components.sessionPicker.highlightFg
+                    : isActive
+                        ? theme.components.sessionPicker.activeMark
+                        : theme.components.sessionPicker.rowText;
+                // Progress color
+                const progressColor = answered === total && total > 0
+                    ? theme.components.sessionPicker.progress
+                    : answered > 0
+                        ? theme.components.sessionPicker.progress
+                        : theme.components.sessionPicker.rowDim;
+                return (React.createElement(Box, { key: session.sessionId },
+                    React.createElement(Text, { backgroundColor: rowBg, bold: isHighlighted, color: textColor },
+                        isActive ? "►" : " ",
+                        " ",
+                        realIdx + 1,
+                        ". ",
+                        title),
+                    React.createElement(Text, { backgroundColor: rowBg, color: theme.components.sessionPicker.rowDim },
+                        " — ",
+                        dir),
+                    React.createElement(Text, { backgroundColor: rowBg, color: progressColor },
+                        "  [",
+                        answered,
+                        "/",
+                        total,
+                        "]"),
+                    React.createElement(Text, { backgroundColor: rowBg, color: theme.components.sessionPicker.rowDim, dimColor: true }, age)));
+            }),
+            needsScroll && scrollOffset + maxVisibleRows < sessions.length && (React.createElement(Box, { justifyContent: "center" },
+                React.createElement(Text, { color: theme.components.sessionPicker.rowDim }, "\u25BC more"))),
+            React.createElement(Box, { justifyContent: "center", marginTop: 1 },
+                React.createElement(Text, { color: theme.components.sessionPicker.rowDim, dimColor: true }, "\u2191\u2193 navigate \u00B7 Enter select \u00B7 Esc close \u00B7 1-9 jump")))));
+};

package/dist/src/tui/components/StepperView.js

@@ -1,4 +1,4 @@
-import { Box, useApp, useInput } from "ink";
+import { Box, useApp, useInput, useStdout } from "ink";
 import React, { useEffect, useMemo, useRef, useState } from "react";
 import { t } from "../../i18n/index.js";
 import { ResponseFormatter } from "../../session/ResponseFormatter.js";
@@ -14,7 +14,7 @@ import { ReviewScreen } from "./ReviewScreen.js";
  * StepperView orchestrates the question-answering flow
  * Manages state for current question, answers, and navigation
  */
-export const StepperView = ({ onComplete, onProgress, sessionId, sessionRequest, }) => {
+export const StepperView = ({ onComplete, onProgress, hasMultipleSessions, initialState, onStateSnapshot, onFlowStateChange, sessionId, sessionRequest, }) => {
     const { theme } = useTheme();
     const config = useConfig();
     const { exit } = useApp();
@@ -25,6 +25,7 @@ export const StepperView = ({ onComplete, onProgress, sessionId, sessionRequest,
     const [showRejectionConfirm, setShowRejectionConfirm] = useState(false);
     const [elapsedSeconds, setElapsedSeconds] = useState(0);
     const [focusContext, setFocusContext] = useState("option");
+    const [focusedOptionIndex, setFocusedOptionIndex] = useState(0);
     const [hasRecommendedOptions, setHasRecommendedOptions] = useState(false);
     // Session-level flag: true if ANY question in the session has recommended options
     const [hasAnyRecommendedInSession, setHasAnyRecommendedInSession] = useState(false);
@@ -44,6 +45,10 @@ export const StepperView = ({ onComplete, onProgress, sessionId, sessionRequest,
             .map((value) => value.toString().padStart(2, "0"))
             .join(":");
     }, [elapsedSeconds]);
+    // Detect if content overflows terminal height to pause periodic re-renders
+    const { stdout } = useStdout();
+    const terminalRows = stdout?.rows ?? 24;
+    const [isOverflowing, setIsOverflowing] = useState(false);
     // Report progress when question index changes
     useEffect(() => {
         if (onProgress) {
@@ -131,6 +136,7 @@ export const StepperView = ({ onComplete, onProgress, sessionId, sessionRequest,
     };
     // Track mount status to avoid state updates after unmount
     const isMountedRef = useRef(true);
+    const skipSnapshotRef = useRef(true);
     useEffect(() => {
         isMountedRef.current = true;
         return () => {
@@ -139,25 +145,84 @@ export const StepperView = ({ onComplete, onProgress, sessionId, sessionRequest,
     }, []);
     // Reset internal stepper state when the session changes (safety in case component isn't remounted)
     useEffect(() => {
-        setCurrentQuestionIndex(0);
-        setAnswers(new Map());
-        setShowReview(false);
+        const maxQuestionIndex = Math.max(0, sessionRequest.questions.length - 1);
+        if (initialState) {
+            const hydratedQuestionIndex = Math.min(Math.max(initialState.currentQuestionIndex, 0), maxQuestionIndex);
+            const hydratedQuestion = sessionRequest.questions[hydratedQuestionIndex];
+            const maxFocusedOptionIndex = (hydratedQuestion?.options.length ?? 0) + 1;
+            setCurrentQuestionIndex(hydratedQuestionIndex);
+            setAnswers(new Map(initialState.answers));
+            setElaborateMarks(new Map(initialState.elaborateMarks));
+            setFocusContext(initialState.focusContext);
+            setFocusedOptionIndex(Math.min(Math.max(initialState.focusedOptionIndex, 0), Math.max(0, maxFocusedOptionIndex)));
+            setShowReview(initialState.showReview);
+        }
+        else {
+            setCurrentQuestionIndex(0);
+            setAnswers(new Map());
+            setElaborateMarks(new Map());
+            setFocusContext("option");
+            setFocusedOptionIndex(0);
+            setShowReview(false);
+        }
         setSubmitting(false);
         setShowRejectionConfirm(false);
         setElapsedSeconds(0);
-        setElaborateMarks(new Map());
+        skipSnapshotRef.current = true;
         // Compute session-level recommended flag: true if ANY question has recommended options
         const anyHasRecommended = sessionRequest.questions.some((question) => question.options.some((opt) => isRecommendedOption(opt.label)));
         setHasAnyRecommendedInSession(anyHasRecommended);
-    }, [sessionId, sessionRequest.questions]);
+    }, [initialState, sessionId, sessionRequest.questions]);
+    useEffect(() => {
+        if (!onStateSnapshot) {
+            return;
+        }
+        if (skipSnapshotRef.current) {
+            skipSnapshotRef.current = false;
+            return;
+        }
+        onStateSnapshot(sessionId, {
+            currentQuestionIndex,
+            answers: new Map(answers),
+            elaborateMarks: new Map(elaborateMarks),
+            focusContext,
+            focusedOptionIndex,
+            showReview,
+        });
+    }, [
+        answers,
+        currentQuestionIndex,
+        elaborateMarks,
+        focusContext,
+        focusedOptionIndex,
+        onStateSnapshot,
+        sessionId,
+        showReview,
+    ]);
+    useEffect(() => {
+        onFlowStateChange?.({ showReview, showRejectionConfirm });
+    }, [onFlowStateChange, showRejectionConfirm, showReview]);
     // Update elapsed time since session creation
+    // IMPORTANT: Pause when content overflows terminal to prevent scroll-snapping
     useEffect(() => {
+        if (isOverflowing)
+            return;
         const timer = setInterval(() => {
             const elapsed = Math.floor((Date.now() - sessionCreatedAt) / 1000);
             setElapsedSeconds(elapsed >= 0 ? elapsed : 0);
         }, 1000);
         return () => clearInterval(timer);
-    }, [sessionCreatedAt]);
+    }, [sessionCreatedAt, isOverflowing]);
+    // Detect overflow: estimate content height vs terminal rows
+    useEffect(() => {
+        const currentQ = sessionRequest.questions[safeIndex];
+        const optionCount = currentQ?.options?.length ?? 0;
+        // Conservative estimate: header(2) + tabbar(3) + prompt(3) + options(2 each)
+        // + footer(2) + custom/elaborate(6) + padding(2)
+        const estimatedContentHeight = 2 + 3 + 3 + optionCount * 2 + 2 + 6 + 2;
+        const nextOverflow = estimatedContentHeight > terminalRows;
+        setIsOverflowing((prev) => (prev === nextOverflow ? prev : nextOverflow));
+    }, [safeIndex, sessionRequest.questions, terminalRows]);
     // Handle answer confirmation
     const handleConfirm = async (userAnswers) => {
         setSubmitting(true);
@@ -417,5 +482,5 @@ export const StepperView = ({ onComplete, onProgress, sessionId, sessionRequest,
         return (React.createElement(ReviewScreen, { isSubmitting: submitting, answers: answers, elapsedLabel: elapsedLabel, onConfirm: handleConfirm, onGoBack: handleGoBack, questions: sessionRequest.questions, sessionId: sessionId, elaborateMarks: elaborateMarks }));
     }
     // Show question display (default)
-    return (React.createElement(QuestionDisplay, { currentQuestion: currentQuestion, currentQuestionIndex: currentQuestionIndex, customAnswer: currentAnswer?.customText, elapsedLabel: elapsedLabel, onAdvanceToNext: handleAdvanceToNext, onChangeCustomAnswer: handleChangeCustomAnswer, onSelectOption: handleSelectOption, onToggleOption: handleToggleOption, multiSelect: currentQuestion.multiSelect, questions: sessionRequest.questions, selectedOption: currentAnswer?.selectedOption, answers: answers, onFocusContextChange: setFocusContext, workingDirectory: sessionRequest.workingDirectory, onRecommendedDetected: setHasRecommendedOptions, hasRecommendedOptions: hasRecommendedOptions, hasAnyRecommendedInSession: hasAnyRecommendedInSession, elaborateMarks: elaborateMarks, onElaborateSelect: handleElaborateSelect, elaborateText: elaborateMarks.get(currentQuestionIndex) || "", onElaborateTextChange: handleElaborateTextChange }));
+    return (React.createElement(QuestionDisplay, { currentQuestion: currentQuestion, currentQuestionIndex: currentQuestionIndex, customAnswer: currentAnswer?.customText, elapsedLabel: elapsedLabel, onAdvanceToNext: handleAdvanceToNext, onChangeCustomAnswer: handleChangeCustomAnswer, onSelectOption: handleSelectOption, onToggleOption: handleToggleOption, multiSelect: currentQuestion.multiSelect, questions: sessionRequest.questions, selectedOption: currentAnswer?.selectedOption, answers: answers, focusContext: focusContext, onFocusContextChange: setFocusContext, focusedOptionIndex: focusedOptionIndex, onFocusedOptionIndexChange: setFocusedOptionIndex, workingDirectory: sessionRequest.workingDirectory, onRecommendedDetected: setHasRecommendedOptions, hasRecommendedOptions: hasRecommendedOptions, hasAnyRecommendedInSession: hasAnyRecommendedInSession, elaborateMarks: elaborateMarks, onElaborateSelect: handleElaborateSelect, elaborateText: elaborateMarks.get(currentQuestionIndex) || "", onElaborateTextChange: handleElaborateTextChange, showSessionSwitching: hasMultipleSessions && !showReview && !showRejectionConfirm }));
 };

package/dist/src/tui/components/__tests__/SessionDots.test.js

@@ -0,0 +1,92 @@
+import React from "react";
+import { cleanup, render } from "ink-testing-library";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { ThemeContext } from "../../ThemeContext.js";
+import { darkTheme } from "../../themes/dark.js";
+import { SessionDots } from "../SessionDots.js";
+const mockThemeValue = {
+    theme: darkTheme,
+    themeName: "AUQ dark",
+    cycleTheme: () => { },
+};
+function renderWithTheme(ui) {
+    return render(React.createElement(ThemeContext.Provider, { value: mockThemeValue }, ui));
+}
+function getOutput(frame) {
+    return (frame ?? "").replace(/\x1b\[[0-9;]*m/g, "").replace(/\r/g, "");
+}
+function createSession(id) {
+    return {
+        sessionId: `test-id-${id}`,
+        sessionRequest: {
+            sessionId: `test-id-${id}`,
+            status: "pending",
+            timestamp: new Date("2026-01-01T00:00:00.000Z").toISOString(),
+            workingDirectory: `/test/${id}`,
+            questions: [
+                {
+                    title: `Q${id}`,
+                    prompt: "test?",
+                    options: [{ label: "A" }],
+                    multiSelect: false,
+                },
+            ],
+        },
+        timestamp: new Date("2026-01-01T00:00:00.000Z"),
+    };
+}
+afterEach(() => {
+    cleanup();
+    vi.restoreAllMocks();
+});
+describe("SessionDots", () => {
+    it("renders nothing when sessions length is less than 2", () => {
+        const instance = renderWithTheme(React.createElement(SessionDots, { sessions: [createSession(1)], activeIndex: 0, sessionUIStates: {} }));
+        expect(getOutput(instance.lastFrame())).toBe("");
+    });
+    it("renders numbered dots for each session", () => {
+        const sessions = [createSession(1), createSession(2), createSession(3)];
+        const instance = renderWithTheme(React.createElement(SessionDots, { sessions: sessions, activeIndex: 1, sessionUIStates: {} }));
+        const output = getOutput(instance.lastFrame());
+        expect(output).toContain("1");
+        expect(output).toContain("2");
+        expect(output).toContain("3");
+        expect(output).toContain("●");
+        expect(output).toContain("○");
+    });
+    it("renders progress-state sessions with one active and remaining inactive dots", () => {
+        const sessions = [
+            createSession(1),
+            createSession(2),
+            createSession(3),
+            createSession(4),
+        ];
+        const answeredState = {
+            currentQuestionIndex: 0,
+            answers: new Map([[0, { selectedOption: "A" }]]),
+            elaborateMarks: new Map(),
+            focusContext: "option",
+            focusedOptionIndex: 0,
+            showReview: false,
+        };
+        const inProgressState = {
+            currentQuestionIndex: 0,
+            answers: new Map(),
+            elaborateMarks: new Map(),
+            focusContext: "option",
+            focusedOptionIndex: 0,
+            showReview: false,
+        };
+        const instance = renderWithTheme(React.createElement(SessionDots, { sessions: sessions, activeIndex: 0, sessionUIStates: {
+                [sessions[1].sessionId]: answeredState,
+                [sessions[2].sessionId]: inProgressState,
+            } }));
+        const output = getOutput(instance.lastFrame());
+        expect((output.match(/●/g) ?? []).length).toBe(1);
+        expect((output.match(/○/g) ?? []).length).toBe(3);
+        expect(output).toContain("1");
+        expect(output).toContain("2");
+        expect(output).toContain("3");
+        expect(output).toContain("4");
+    });
+});

package/dist/src/tui/components/__tests__/SessionPicker.test.js

@@ -0,0 +1,125 @@
+import React from "react";
+import { cleanup, render } from "ink-testing-library";
+import { afterEach, describe, expect, it, vi } from "vitest";
+const inputState = vi.hoisted(() => ({
+    handler: null,
+}));
+vi.mock("ink", async () => {
+    const actual = await vi.importActual("ink");
+    return {
+        ...actual,
+        useInput: (handler, options) => {
+            if (options?.isActive) {
+                inputState.handler = handler;
+            }
+        },
+    };
+});
+import { ThemeContext } from "../../ThemeContext.js";
+import { darkTheme } from "../../themes/dark.js";
+import { SessionPicker, } from "../SessionPicker.js";
+const mockThemeValue = {
+    theme: darkTheme,
+    themeName: "AUQ dark",
+    cycleTheme: () => { },
+};
+function renderWithTheme(ui) {
+    return render(React.createElement(ThemeContext.Provider, { value: mockThemeValue }, ui));
+}
+function getOutput(frame) {
+    return (frame ?? "").replace(/\x1b\[[0-9;]*m/g, "").replace(/\r/g, "");
+}
+function createSession(id) {
+    return {
+        sessionId: `picker-id-${id}`,
+        sessionRequest: {
+            sessionId: `picker-id-${id}`,
+            status: "pending",
+            timestamp: new Date("2026-01-01T00:00:00.000Z").toISOString(),
+            workingDirectory: `/work/dir-${id}`,
+            questions: [
+                {
+                    title: `Title ${id}`,
+                    prompt: "choose",
+                    options: [{ label: "A" }],
+                    multiSelect: false,
+                },
+            ],
+        },
+        timestamp: new Date("2026-01-01T00:00:00.000Z"),
+    };
+}
+afterEach(() => {
+    cleanup();
+    inputState.handler = null;
+    vi.restoreAllMocks();
+});
+describe("SessionPicker", () => {
+    it("renders nothing when isOpen is false", () => {
+        const instance = renderWithTheme(React.createElement(SessionPicker, { isOpen: false, sessions: [createSession(1), createSession(2)], activeIndex: 0, sessionUIStates: {}, onSelectIndex: () => { }, onClose: () => { } }));
+        expect(getOutput(instance.lastFrame())).toBe("");
+    });
+    it("renders session rows with number, title, directory, progress, and active marker", () => {
+        const sessions = [createSession(1), createSession(2)];
+        const answeredState = {
+            currentQuestionIndex: 0,
+            answers: new Map([[0, { selectedOption: "A" }]]),
+            elaborateMarks: new Map(),
+            focusContext: "option",
+            focusedOptionIndex: 0,
+            showReview: false,
+        };
+        const instance = renderWithTheme(React.createElement(SessionPicker, { isOpen: true, sessions: sessions, activeIndex: 0, sessionUIStates: { [sessions[0].sessionId]: answeredState }, onSelectIndex: () => { }, onClose: () => { } }));
+        const output = getOutput(instance.lastFrame());
+        expect(output).toContain("Switch Session");
+        expect(output).toContain("1. Title 1");
+        expect(output).toContain("2. Title 2");
+        expect(output).toContain("/work/dir-1");
+        expect(output).toContain("[1/1]");
+        expect(output).toContain("[0/1]");
+        expect(output).toContain("► 1.");
+    });
+    it("handles down arrow without immediate selection", async () => {
+        const sessions = [createSession(1), createSession(2), createSession(3)];
+        const onSelectIndex = vi.fn();
+        const onClose = vi.fn();
+        renderWithTheme(React.createElement(SessionPicker, { isOpen: true, sessions: sessions, activeIndex: 0, sessionUIStates: {}, onSelectIndex: onSelectIndex, onClose: onClose }));
+        expect(inputState.handler).not.toBeNull();
+        inputState.handler("", { downArrow: true });
+        await Promise.resolve();
+        expect(onSelectIndex).not.toHaveBeenCalled();
+        expect(onClose).not.toHaveBeenCalled();
+    });
+    it("selects the currently highlighted session on Enter", async () => {
+        const sessions = [createSession(1), createSession(2), createSession(3)];
+        const onSelectIndex = vi.fn();
+        const onClose = vi.fn();
+        renderWithTheme(React.createElement(SessionPicker, { isOpen: true, sessions: sessions, activeIndex: 0, sessionUIStates: {}, onSelectIndex: onSelectIndex, onClose: onClose }));
+        expect(inputState.handler).not.toBeNull();
+        inputState.handler("", { return: true });
+        await Promise.resolve();
+        expect(onSelectIndex).toHaveBeenCalledWith(0);
+        expect(onClose).toHaveBeenCalled();
+    });
+    it("supports direct number key selection", async () => {
+        const sessions = [createSession(1), createSession(2), createSession(3)];
+        const onSelectIndex = vi.fn();
+        const onClose = vi.fn();
+        renderWithTheme(React.createElement(SessionPicker, { isOpen: true, sessions: sessions, activeIndex: 0, sessionUIStates: {}, onSelectIndex: onSelectIndex, onClose: onClose }));
+        expect(inputState.handler).not.toBeNull();
+        inputState.handler("2", {});
+        await Promise.resolve();
+        expect(onSelectIndex).toHaveBeenCalledWith(1);
+        expect(onClose).toHaveBeenCalled();
+    });
+    it("calls onClose on Escape", async () => {
+        const onSelectIndex = vi.fn();
+        const onClose = vi.fn();
+        renderWithTheme(React.createElement(SessionPicker, { isOpen: true, sessions: [createSession(1), createSession(2)], activeIndex: 0, sessionUIStates: {}, onSelectIndex: onSelectIndex, onClose: onClose }));
+        expect(inputState.handler).not.toBeNull();
+        inputState.handler("", { escape: true });
+        await Promise.resolve();
+        expect(onClose).toHaveBeenCalledTimes(1);
+        expect(onSelectIndex).not.toHaveBeenCalled();
+    });
+});

package/dist/src/tui/components/__tests__/StepperView.state.test.js

@@ -0,0 +1,101 @@
+import React from "react";
+import { cleanup, render } from "ink-testing-library";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { ConfigProvider } from "../../ConfigContext.js";
+import { ThemeContext } from "../../ThemeContext.js";
+import { darkTheme } from "../../themes/dark.js";
+import { StepperView } from "../StepperView.js";
+const mockThemeValue = {
+    theme: darkTheme,
+    themeName: "AUQ dark",
+    cycleTheme: () => { },
+};
+const sessionRequest = {
+    sessionId: "session-1",
+    status: "pending",
+    timestamp: new Date().toISOString(),
+    callId: "call-1",
+    questions: [
+        {
+            title: "Language",
+            prompt: "Pick a language",
+            options: [{ label: "TypeScript" }, { label: "Python" }],
+        },
+        {
+            title: "Framework",
+            prompt: "Pick a framework",
+            options: [{ label: "React" }, { label: "Vue" }],
+        },
+        {
+            title: "Runtime",
+            prompt: "Pick a runtime",
+            options: [{ label: "Bun" }, { label: "Node.js" }],
+        },
+    ],
+};
+function renderStepper(props = {}) {
+    return render(React.createElement(ThemeContext.Provider, { value: mockThemeValue },
+        React.createElement(ConfigProvider, null,
+            React.createElement(StepperView, { sessionId: sessionRequest.sessionId, sessionRequest: sessionRequest, ...props }))));
+}
+function getOutput(frame) {
+    return (frame ?? "").replace(/\x1b\[[0-9;]*m/g, "").replace(/\r/g, "");
+}
+afterEach(() => {
+    cleanup();
+    vi.restoreAllMocks();
+});
+describe("StepperView SessionUIState boundary", () => {
+    it("hydrates from initialState and starts on the hydrated question", async () => {
+        const initialState = {
+            currentQuestionIndex: 1,
+            answers: new Map([[0, { selectedOption: "TypeScript" }]]),
+            elaborateMarks: new Map([[0, "Please elaborate"]]),
+            focusContext: "option",
+            focusedOptionIndex: 1,
+            showReview: false,
+        };
+        const instance = renderStepper({ initialState });
+        await vi.waitFor(() => {
+            const hydratedOutput = getOutput(instance.lastFrame());
+            expect(hydratedOutput).toContain("Pick a framework");
+        });
+        const output = getOutput(instance.lastFrame());
+        expect(output).not.toContain("Pick a language");
+        expect(output).toContain("1/3");
+    });
+    it("uses default state when no initialState is provided", () => {
+        const instance = renderStepper();
+        const output = getOutput(instance.lastFrame());
+        expect(output).toContain("Pick a language");
+        expect(output).not.toContain("Pick a framework");
+        expect(output).toContain("0/3");
+    });
+    it("emits snapshot after state change and skips initial mount emission", async () => {
+        const onStateSnapshot = vi.fn();
+        const instance = renderStepper({ onStateSnapshot });
+        expect(onStateSnapshot).not.toHaveBeenCalled();
+        instance.stdin.write("\t");
+        await vi.waitFor(() => {
+            expect(onStateSnapshot).toHaveBeenCalled();
+        });
+        const [sessionId, state] = onStateSnapshot.mock.lastCall;
+        expect(sessionId).toBe("session-1");
+        expect(state.currentQuestionIndex).toBe(1);
+        expect(state.focusContext).toBe("option");
+        expect(state.showReview).toBe(false);
+        expect(state.answers).toBeInstanceOf(Map);
+        expect(state.elaborateMarks).toBeInstanceOf(Map);
+    });
+    it("emits initial flow state via onFlowStateChange", async () => {
+        const onFlowStateChange = vi.fn();
+        renderStepper({ onFlowStateChange });
+        await vi.waitFor(() => {
+            expect(onFlowStateChange).toHaveBeenCalled();
+        });
+        expect(onFlowStateChange).toHaveBeenCalledWith({
+            showReview: false,
+            showRejectionConfirm: false,
+        });
+    });
+});

package/dist/src/tui/themes/catppuccin-latte.js

@@ -98,5 +98,23 @@ export const catppuccinLatteTheme = {
             codeBlockText: "#4c4f69",
             codeBlockBorder: "#ccd0da",
         },
+        sessionDots: {
+            active: "#1e66f5",
+            answered: "#40a02b",
+            inProgress: "#df8e1d",
+            untouched: "#acb0c0",
+            number: "#4c4f69",
+            activeNumber: "#1e66f5",
+        },
+        sessionPicker: {
+            border: "#1e66f5",
+            title: "#1e66f5",
+            rowText: "#4c4f69",
+            rowDim: "#acb0c0",
+            highlightBg: "#ccd0da",
+            highlightFg: "#40a02b",
+            activeMark: "#1e66f5",
+            progress: "#04a5e5",
+        },
     },
 };

package/dist/src/tui/themes/catppuccin-mocha.js

@@ -98,5 +98,23 @@ export const catppuccinMochaTheme = {
             codeBlockText: "#cdd6f4",
             codeBlockBorder: "#313244",
         },
+        sessionDots: {
+            active: "#89b4fa",
+            answered: "#a6e3a1",
+            inProgress: "#f9e2af",
+            untouched: "#8688a0",
+            number: "#cdd6f4",
+            activeNumber: "#89b4fa",
+        },
+        sessionPicker: {
+            border: "#89b4fa",
+            title: "#89b4fa",
+            rowText: "#cdd6f4",
+            rowDim: "#8688a0",
+            highlightBg: "#313244",
+            highlightFg: "#a6e3a1",
+            activeMark: "#89b4fa",
+            progress: "#89dceb",
+        },
     },
 };