@compilr-dev/cli 0.4.0 → 0.5.0

package/dist/ui/ask-user-overlay.js

@@ -1,8 +1,8 @@
 /**
- * Ask User Overlay
+ * Ask User Overlay (Refactored)
  *
  * Modal overlay for presenting multi-question forms to the user.
- * Used by the ask_user tool during /design and /refine workflows.
+ * Uses InlineOverlay base class for consistent lifecycle management.
  *
  * Features:
  * - Multiple questions with navigation (←/→ or Tab)
@@ -12,636 +12,544 @@
  * - Progress indicator showing answered questions
  */
 import chalk from 'chalk';
-import * as terminal from './terminal.js';
 import { getStyles } from '../themes/index.js';
+import { InlineOverlay } from './base/inline-overlay.js';
 // =============================================================================
-// Rendering Helpers
+// Overlay Implementation
 // =============================================================================
-function renderTabBar(questions, currentIndex, answers, isOnSubmitTab) {
-    const s = getStyles();
-    const lines = [];
-    // Tab bar like config-overlay: " Questions:  App Type   Users   Features   Submit "
-    // Current tab highlighted with bgBlue, answered tabs with success color
-    let tabLine = ' ';
-    for (let i = 0; i < questions.length; i++) {
-        const q = questions[i];
-        const hasAnswer = q.id in answers;
-        const isCurrent = i === currentIndex && !isOnSubmitTab;
-        // Use header if available, fallback to formatted id
-        const label = q.header || q.id.replace(/_/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
-        if (isCurrent) {
-            // Current tab: highlighted background (theme selection color)
-            tabLine += s.selected(` ${label} `) + ' ';
-        }
-        else if (hasAnswer) {
-            // Answered tab: success color with checkmark
-            tabLine += s.success(`✓ ${label}`) + ' ';
+class AskUserOverlayImpl extends InlineOverlay {
+    questions;
+    context;
+    constructor(options) {
+        super();
+        this.questions = options.questions;
+        this.context = options.context;
+    }
+    getInitialState() {
+        // Check if first question should auto-start in typing mode
+        const firstQ = this.questions[0];
+        const firstQAutoType = (firstQ.options?.length ?? 0) === 0 &&
+            firstQ.allowCustom !== false &&
+            firstQ.multiSelect !== true;
+        return {
+            currentQuestion: 0,
+            selectedIndex: 0,
+            inputBuffer: '',
+            isTypingCustom: firstQAutoType,
+            answers: {},
+            multiSelections: new Set(),
+            warningMessage: '',
+            isOnSubmitTab: false,
+        };
+    }
+    render() {
+        const s = getStyles();
+        const lines = [];
+        const cols = this.getTerminalWidth();
+        const border = s.muted('─'.repeat(Math.max(1, cols - 1)));
+        // Header
+        lines.push(border);
+        lines.push(' ' + s.primaryBold('Questions'));
+        lines.push('');
+        // Tab bar
+        lines.push(...this.renderTabBar());
+        lines.push('');
+        // Current question or Submit tab
+        if (this.state.isOnSubmitTab) {
+            lines.push(...this.renderSubmitTab());
         }
         else {
-            // Pending tab: muted
-            tabLine += s.muted(` ${label} `) + ' ';
+            lines.push(...this.renderQuestion());
+        }
+        // Footer with instructions
+        lines.push(...this.renderFooter());
+        // Warning message if present
+        if (this.state.warningMessage) {
+            lines.push('');
+            lines.push(s.warning(` ⚠ ${this.state.warningMessage}`));
         }
+        // Bottom border
+        lines.push(border);
+        return lines;
     }
-    // Add Submit tab at the end
-    const allAnswered = questions.every((q) => q.id in answers);
-    if (isOnSubmitTab) {
-        tabLine += s.selected(' Submit ');
+    handleKey(data) {
+        // Ctrl+C always cancels
+        if (this.isCtrlCKey(data)) {
+            return { type: 'close', result: this.getResult() };
+        }
+        // Handle Submit tab first
+        if (this.state.isOnSubmitTab) {
+            return this.handleSubmitTabKey(data);
+        }
+        // Handle typing mode
+        if (this.state.isTypingCustom) {
+            return this.handleTypingKey(data);
+        }
+        // Handle navigation mode
+        return this.handleNavigationKey(data);
     }
-    else if (allAnswered) {
-        tabLine += s.success(' Submit ');
+    getCleanupSummary(result) {
+        const s = getStyles();
+        const answeredCount = Object.keys(result.answers).length;
+        const skippedCount = result.skipped.length;
+        if (answeredCount === 0) {
+            return s.muted('Questions: ') + s.warning('Cancelled');
+        }
+        if (skippedCount > 0) {
+            return s.muted('Questions: ') + s.success(`${String(answeredCount)} answered`) + s.muted(`, ${String(skippedCount)} skipped`);
+        }
+        return s.muted('Questions: ') + s.success(`${String(answeredCount)} answered`);
     }
-    else {
-        tabLine += s.muted(' Submit ');
+    // ===========================================================================
+    // Private: Rendering Helpers
+    // ===========================================================================
+    renderTabBar() {
+        const s = getStyles();
+        const lines = [];
+        let tabLine = ' ';
+        for (let i = 0; i < this.questions.length; i++) {
+            const q = this.questions[i];
+            const hasAnswer = q.id in this.state.answers;
+            const isCurrent = i === this.state.currentQuestion && !this.state.isOnSubmitTab;
+            const label = q.header || q.id.replace(/_/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+            if (isCurrent) {
+                tabLine += s.selected(` ${label} `) + ' ';
+            }
+            else if (hasAnswer) {
+                tabLine += s.success(`✓ ${label}`) + ' ';
+            }
+            else {
+                tabLine += s.muted(` ${label} `) + ' ';
+            }
+        }
+        // Add Submit tab
+        const allAnswered = this.questions.every((q) => q.id in this.state.answers);
+        if (this.state.isOnSubmitTab) {
+            tabLine += s.selected(' Submit ');
+        }
+        else if (allAnswered) {
+            tabLine += s.success(' Submit ');
+        }
+        else {
+            tabLine += s.muted(' Submit ');
+        }
+        lines.push(tabLine);
+        return lines;
     }
-    lines.push(tabLine);
-    return lines;
-}
-function renderQuestion(question, questionIndex, totalQuestions, state, context) {
-    const s = getStyles();
-    const lines = [];
-    // Context if provided (only on first render)
-    if (context && questionIndex === 0) {
-        lines.push(s.muted(' ' + context));
+    renderQuestion() {
+        const s = getStyles();
+        const lines = [];
+        const question = this.questions[this.state.currentQuestion];
+        const questionIndex = this.state.currentQuestion;
+        const totalQuestions = this.questions.length;
+        // Context if provided (only on first question)
+        if (this.context && questionIndex === 0) {
+            lines.push(s.muted(' ' + this.context));
+            lines.push('');
+        }
+        // Question number and text
+        lines.push(chalk.bold(` [${String(questionIndex + 1)}/${String(totalQuestions)}] ${question.question}`));
         lines.push('');
-    }
-    // Question number and text
-    lines.push(chalk.bold(` [${String(questionIndex + 1)}/${String(totalQuestions)}] ${question.question}`));
-    lines.push('');
-    // Options
-    const options = question.options ?? [];
-    const allowCustom = question.allowCustom !== false; // Default true
-    const isMultiSelect = question.multiSelect === true;
-    const customIndex = options.length; // Custom is always last option
-    // Check if there's an existing answer for this question
-    const answeredOptions = new Set();
-    let customAnswerValue = '';
-    if (question.id in state.answers) {
-        const existingAnswer = state.answers[question.id];
-        if (isMultiSelect && Array.isArray(existingAnswer)) {
-            for (const ans of existingAnswer) {
-                const idx = options.indexOf(ans);
-                if (idx >= 0) {
-                    answeredOptions.add(idx);
-                }
-                else {
-                    customAnswerValue = ans;
-                }
+        // Options
+        const options = question.options ?? [];
+        const allowCustom = question.allowCustom !== false;
+        const isMultiSelect = question.multiSelect === true;
+        const customIndex = options.length;
+        // Get existing answer info
+        const { answeredOptions, customAnswerValue } = this.getAnswerInfo(question);
+        for (let i = 0; i < options.length; i++) {
+            const isCursor = this.state.selectedIndex === i;
+            const isMultiSelected = isMultiSelect && this.state.multiSelections.has(i);
+            const isAnswered = answeredOptions.has(i);
+            const prefix = isCursor ? ' ❯ ' : '   ';
+            let marker = '';
+            if (isMultiSelect) {
+                marker = isMultiSelected ? '[✓] ' : '[ ] ';
+            }
+            else if (isAnswered) {
+                marker = '● ';
+            }
+            const label = `${String(i + 1)}. ${options[i]}`;
+            if (isCursor) {
+                lines.push(s.primary(prefix + marker + label));
+            }
+            else if (isMultiSelected || isAnswered) {
+                lines.push(s.success(prefix + marker + label));
+            }
+            else {
+                lines.push(s.muted(prefix + marker + label));
             }
         }
-        else if (typeof existingAnswer === 'string') {
-            const idx = options.indexOf(existingAnswer);
-            if (idx >= 0) {
-                answeredOptions.add(idx);
+        // Custom option
+        if (allowCustom) {
+            const isCursor = this.state.selectedIndex === customIndex;
+            const prefix = isCursor ? ' ❯ ' : '   ';
+            const hasCustomAnswer = customAnswerValue !== '' || this.state.inputBuffer !== '';
+            const displayValue = this.state.inputBuffer || customAnswerValue;
+            if (this.state.isTypingCustom) {
+                lines.push(s.primary(prefix + 'Custom: ' + this.state.inputBuffer + '▋'));
+            }
+            else if (hasCustomAnswer) {
+                const marker = isMultiSelect ? '[✓] ' : '● ';
+                const label = `${String(options.length + 1)}. Custom: "${displayValue}"`;
+                lines.push(isCursor ? s.primary(prefix + marker + label) : s.success(prefix + marker + label));
             }
             else {
-                customAnswerValue = existingAnswer;
+                const label = `${String(options.length + 1)}. Type something custom...`;
+                lines.push(isCursor ? s.primary(prefix + label) : s.muted(prefix + label));
             }
         }
+        return lines;
     }
-    for (let i = 0; i < options.length; i++) {
-        const isCursor = state.selectedIndex === i;
-        const isMultiSelected = isMultiSelect && state.multiSelections.has(i);
-        const isAnswered = answeredOptions.has(i);
-        const prefix = isCursor ? ' ❯ ' : '   ';
-        // For multi-select: show checkbox state
-        // For single-select: show bullet for answered option
-        let marker = '';
-        if (isMultiSelect) {
-            marker = isMultiSelected ? '[✓] ' : '[ ] ';
+    renderSubmitTab() {
+        const s = getStyles();
+        const lines = [];
+        lines.push('');
+        lines.push(chalk.bold(' Ready to submit?'));
+        lines.push('');
+        const answeredCount = Object.keys(this.state.answers).length;
+        const totalCount = this.questions.length;
+        const allAnswered = answeredCount === totalCount;
+        if (allAnswered) {
+            lines.push(s.success(` ✓ All ${String(totalCount)} questions answered`));
+            lines.push('');
+            lines.push(' ' + s.muted('Press Enter to submit your answers.'));
         }
-        else if (isAnswered) {
-            marker = '● '; // Filled bullet for answered single-select
+        else {
+            const unansweredCount = totalCount - answeredCount;
+            lines.push(s.warning(` ⚠ ${String(unansweredCount)} of ${String(totalCount)} questions not answered`));
+            lines.push('');
+            lines.push(' ' + s.muted('Unanswered:'));
+            for (const q of this.questions) {
+                if (!(q.id in this.state.answers)) {
+                    const label = q.header || q.id.replace(/_/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+                    lines.push('   ' + s.muted(`• ${label}`));
+                }
+            }
+            lines.push('');
+            lines.push(' ' + s.muted('Press ← or Tab to go back and answer.'));
         }
-        const label = `${String(i + 1)}. ${options[i]}`;
-        if (isCursor) {
-            lines.push(s.primary(prefix + marker + label));
+        return lines;
+    }
+    renderFooter() {
+        const s = getStyles();
+        const lines = [];
+        lines.push('');
+        if (this.state.isOnSubmitTab) {
+            lines.push(s.muted(' Enter Submit all · ←/Tab Go back · Esc Cancel'));
         }
-        else if (isMultiSelected || isAnswered) {
-            lines.push(s.success(prefix + marker + label));
+        else if (this.state.isTypingCustom) {
+            lines.push(s.muted(' Enter Submit · Esc Cancel custom'));
         }
         else {
-            lines.push(s.muted(prefix + marker + label));
+            const currentQ = this.questions[this.state.currentQuestion];
+            if (currentQ.multiSelect === true) {
+                lines.push(s.muted(' ↑↓ Navigate · Space Toggle · Enter Confirm · Tab Next · Esc Cancel'));
+            }
+            else {
+                lines.push(s.muted(' ↑↓ Navigate · Enter Select · Tab Next · Esc Cancel'));
+            }
         }
+        return lines;
     }
-    // Custom option
-    if (allowCustom) {
-        const isCursor = state.selectedIndex === customIndex;
-        const prefix = isCursor ? ' ❯ ' : '   ';
-        const hasCustomAnswer = customAnswerValue !== '' || state.inputBuffer !== '';
-        const displayValue = state.inputBuffer || customAnswerValue;
-        if (state.isTypingCustom) {
-            lines.push(s.primary(prefix + 'Custom: ' + state.inputBuffer + '█'));
-        }
-        else if (hasCustomAnswer) {
-            // Show the custom answer value
-            const marker = isMultiSelect ? '[✓] ' : '● ';
-            const label = `${String(options.length + 1)}. Custom: "${displayValue}"`;
-            lines.push(isCursor ? s.primary(prefix + marker + label) : s.success(prefix + marker + label));
+    // ===========================================================================
+    // Private: Key Handlers
+    // ===========================================================================
+    handleSubmitTabKey(data) {
+        if (this.isEscapeKey(data)) {
+            return { type: 'close', result: this.getResult() };
         }
-        else {
-            const label = `${String(options.length + 1)}. Type something custom...`;
-            lines.push(isCursor ? s.primary(prefix + label) : s.muted(prefix + label));
+        if (this.isLeftArrowKey(data) || this.isTabKey(data)) {
+            this.prevQuestion();
+            return { type: 'continue' };
         }
-    }
-    return lines;
-}
-function renderFooter(isTypingCustom, isMultiSelect, isOnSubmitTab) {
-    const s = getStyles();
-    const lines = [];
-    lines.push('');
-    if (isOnSubmitTab) {
-        lines.push(s.muted(' Enter Submit all · ←/Tab Go back · Esc Cancel'));
-    }
-    else if (isTypingCustom) {
-        lines.push(s.muted(' Enter Submit · Esc Cancel custom'));
-    }
-    else if (isMultiSelect) {
-        lines.push(s.muted(' ↑↓ Navigate · Space Toggle · Enter Confirm · Tab Next · Esc Cancel'));
-    }
-    else {
-        lines.push(s.muted(' ↑↓ Navigate · Enter Select · Tab Next · Esc Cancel'));
-    }
-    return lines;
-}
-function renderSubmitTab(questions, answers) {
-    const s = getStyles();
-    const lines = [];
-    lines.push('');
-    lines.push(chalk.bold(' Ready to submit?'));
-    lines.push('');
-    // Show summary of answers
-    const answeredCount = Object.keys(answers).length;
-    const totalCount = questions.length;
-    const allAnswered = answeredCount === totalCount;
-    if (allAnswered) {
-        lines.push(s.success(` ✓ All ${String(totalCount)} questions answered`));
-        lines.push('');
-        lines.push(' ' + s.muted('Press Enter to submit your answers.'));
-    }
-    else {
-        const unansweredCount = totalCount - answeredCount;
-        lines.push(s.warning(` ⚠ ${String(unansweredCount)} of ${String(totalCount)} questions not answered`));
-        lines.push('');
-        // List unanswered questions
-        lines.push(' ' + s.muted('Unanswered:'));
-        for (const q of questions) {
-            if (!(q.id in answers)) {
-                const label = q.header || q.id.replace(/_/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
-                lines.push('   ' + s.muted(`• ${label}`));
+        if (this.isEnterKey(data)) {
+            if (this.tryComplete()) {
+                return { type: 'close', result: this.getResult() };
             }
+            // tryComplete sets warning and navigates to first unanswered
         }
-        lines.push('');
-        lines.push(' ' + s.muted('Press ← or Tab to go back and answer.'));
+        return { type: 'continue' };
     }
-    return lines;
-}
-// Debug flag - set to true to enable logging to stderr
-const ASK_USER_DEBUG = false;
-function debugLog(msg) {
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-    if (ASK_USER_DEBUG) {
-        process.stderr.write(`[ask-user] ${msg}\n`);
-    }
-}
-function render(questions, state, context, previousLineCount = 0, targetLineCount = 0) {
-    const s = getStyles();
-    const lines = [];
-    const cols = terminal.getTerminalWidth();
-    const border = s.muted('─'.repeat(Math.max(1, cols - 1)));
-    debugLog(`render: q=${String(state.currentQuestion)}, prevLines=${String(previousLineCount)}, target=${String(targetLineCount)}`);
-    // Clear previous render
-    if (previousLineCount > 0) {
-        terminal.clearLinesAbove(previousLineCount);
-    }
-    // Header
-    lines.push(border);
-    lines.push(' ' + s.primaryBold('Questions'));
-    lines.push('');
-    // Tab bar (like config-overlay) - includes Submit tab
-    lines.push(...renderTabBar(questions, state.currentQuestion, state.answers, state.isOnSubmitTab));
-    lines.push('');
-    // Current question or Submit tab
-    if (state.isOnSubmitTab) {
-        lines.push(...renderSubmitTab(questions, state.answers));
-    }
-    else {
-        const currentQ = questions[state.currentQuestion];
-        lines.push(...renderQuestion(currentQ, state.currentQuestion, questions.length, state, context));
+    handleTypingKey(data) {
+        const currentQ = this.questions[this.state.currentQuestion];
+        const options = currentQ.options ?? [];
+        if (this.isEscapeKey(data)) {
+            this.state.isTypingCustom = false;
+            this.state.inputBuffer = '';
+            return { type: 'continue' };
+        }
+        if (this.isUpArrowKey(data) && options.length > 0) {
+            this.state.isTypingCustom = false;
+            this.state.inputBuffer = '';
+            this.state.selectedIndex = Math.max(0, this.state.selectedIndex - 1);
+            return { type: 'continue' };
+        }
+        if (this.isDownArrowKey(data)) {
+            // Custom is last option, down arrow does nothing
+            return { type: 'continue' };
+        }
+        if (this.isEnterKey(data)) {
+            if (this.submitAnswer()) {
+                this.state.warningMessage = '';
+                this.nextQuestion();
+            }
+            return { type: 'continue' };
+        }
+        if (this.isBackspaceKey(data)) {
+            this.state.inputBuffer = this.state.inputBuffer.slice(0, -1);
+            return { type: 'continue' };
+        }
+        // Printable character
+        const char = this.getPrintableChar(data);
+        if (char) {
+            this.state.inputBuffer += char;
+        }
+        return { type: 'continue' };
     }
-    // Footer with instructions
-    const currentQ = state.isOnSubmitTab ? null : questions[state.currentQuestion];
-    lines.push(...renderFooter(state.isTypingCustom, currentQ?.multiSelect === true, state.isOnSubmitTab));
-    // Warning message if present
-    if (state.warningMessage) {
-        lines.push('');
-        lines.push(s.warning(` ⚠ ${state.warningMessage}`));
+    handleNavigationKey(data) {
+        const optionCount = this.getOptionCount();
+        const currentQ = this.questions[this.state.currentQuestion];
+        const isMultiSelect = currentQ.multiSelect === true;
+        const options = currentQ.options ?? [];
+        const allowCustom = currentQ.allowCustom !== false;
+        const customIndex = options.length;
+        if (this.isEscapeKey(data)) {
+            return { type: 'close', result: this.getResult() };
+        }
+        if (this.isUpArrowKey(data)) {
+            this.state.selectedIndex = Math.max(0, this.state.selectedIndex - 1);
+            if (!isMultiSelect && allowCustom && this.state.selectedIndex === customIndex) {
+                this.state.isTypingCustom = true;
+            }
+            return { type: 'continue' };
+        }
+        if (this.isDownArrowKey(data)) {
+            this.state.selectedIndex = Math.min(optionCount - 1, this.state.selectedIndex + 1);
+            if (!isMultiSelect && allowCustom && this.state.selectedIndex === customIndex) {
+                this.state.isTypingCustom = true;
+            }
+            return { type: 'continue' };
+        }
+        if (this.isLeftArrowKey(data)) {
+            this.prevQuestion();
+            return { type: 'continue' };
+        }
+        if (this.isRightArrowKey(data) || this.isTabKey(data)) {
+            this.nextQuestion();
+            return { type: 'continue' };
+        }
+        if (this.isSpaceKey(data) && isMultiSelect) {
+            if (this.state.multiSelections.has(this.state.selectedIndex)) {
+                this.state.multiSelections.delete(this.state.selectedIndex);
+            }
+            else {
+                this.state.multiSelections.add(this.state.selectedIndex);
+            }
+            return { type: 'continue' };
+        }
+        if (this.isEnterKey(data)) {
+            if (this.submitAnswer()) {
+                this.state.warningMessage = '';
+                this.nextQuestion();
+            }
+            return { type: 'continue' };
+        }
+        // Number keys 1-9
+        if (data.length === 1 && data[0] >= 0x31 && data[0] <= 0x39) {
+            const numIndex = data[0] - 0x31;
+            if (numIndex < optionCount) {
+                this.state.selectedIndex = numIndex;
+                if (!isMultiSelect) {
+                    if (this.submitAnswer()) {
+                        this.state.warningMessage = '';
+                        this.nextQuestion();
+                    }
+                }
+            }
+        }
+        return { type: 'continue' };
     }
-    // Bottom border to close the overlay
-    lines.push(border);
-    // Pad with empty lines to maintain consistent height (prevents cursor drift)
-    while (lines.length < targetLineCount) {
-        lines.push('');
+    // ===========================================================================
+    // Private: Helper Methods
+    // ===========================================================================
+    getResult() {
+        const skipped = this.questions.filter((q) => !(q.id in this.state.answers)).map((q) => q.id);
+        return {
+            answers: this.state.answers,
+            skipped,
+        };
     }
-    // Render all lines (use write + join like config-overlay to match clearLinesAbove behavior)
-    terminal.write(lines.join('\n'));
-    debugLog(`render done: newLines=${String(lines.length)}, optionCount=${String(questions[state.currentQuestion].options?.length ?? 0)}`);
-    return lines.length;
-}
-// =============================================================================
-// Main Export
-// =============================================================================
-/**
- * Show the ask user overlay
- */
-export async function showAskUserOverlay(options) {
-    const { questions, context } = options;
-    // Check if first question should auto-start in typing mode
-    // (no options, custom allowed, single-select)
-    const firstQ = questions[0];
-    const firstQAutoType = (firstQ.options?.length ?? 0) === 0 &&
-        firstQ.allowCustom !== false &&
-        firstQ.multiSelect !== true;
-    const state = {
-        currentQuestion: 0,
-        selectedIndex: 0,
-        inputBuffer: '',
-        isTypingCustom: firstQAutoType,
-        answers: {},
-        multiSelections: new Set(),
-        cancelled: false,
-        warningMessage: '',
-        isOnSubmitTab: false,
-    };
-    let lineCount = 0;
-    let maxLineCount = 0; // Track max lines ever rendered to ensure full clearing
-    // NOTE: Footer is already paused by the caller (index.ts handler calls sharedState.pauseFooter)
-    // Do NOT call pauseForOverlay() here - it causes double-pause issues
-    // The caller's pause already clears the footer from screen
-    // Ensure we start from a fresh line (like config-overlay does)
-    terminal.writeLine('');
-    terminal.hideCursor();
-    const wasRawMode = process.stdin.isRaw;
-    terminal.enableRawMode();
-    // Initial render (no re-render needed - matches config-overlay pattern)
-    lineCount = render(questions, state, context, 0);
-    maxLineCount = Math.max(maxLineCount, lineCount);
-    // Helper: Get option count for current question
-    const getOptionCount = () => {
-        const q = questions[state.currentQuestion];
+    getOptionCount() {
+        const q = this.questions[this.state.currentQuestion];
         const optionCount = q.options?.length ?? 0;
         const allowCustom = q.allowCustom !== false;
         return allowCustom ? optionCount + 1 : optionCount;
-    };
-    // Helper: Restore state from existing answer for current question
-    const restoreFromAnswer = () => {
-        const q = questions[state.currentQuestion];
+    }
+    getAnswerInfo(question) {
+        const options = question.options ?? [];
+        const isMultiSelect = question.multiSelect === true;
+        const answeredOptions = new Set();
+        let customAnswerValue = '';
+        if (question.id in this.state.answers) {
+            const existingAnswer = this.state.answers[question.id];
+            if (isMultiSelect && Array.isArray(existingAnswer)) {
+                for (const ans of existingAnswer) {
+                    const idx = options.indexOf(ans);
+                    if (idx >= 0) {
+                        answeredOptions.add(idx);
+                    }
+                    else {
+                        customAnswerValue = ans;
+                    }
+                }
+            }
+            else if (typeof existingAnswer === 'string') {
+                const idx = options.indexOf(existingAnswer);
+                if (idx >= 0) {
+                    answeredOptions.add(idx);
+                }
+                else {
+                    customAnswerValue = existingAnswer;
+                }
+            }
+        }
+        return { answeredOptions, customAnswerValue };
+    }
+    restoreFromAnswer() {
+        const q = this.questions[this.state.currentQuestion];
         const options = q.options ?? [];
         const isMultiSelect = q.multiSelect === true;
         const allowCustom = q.allowCustom !== false;
         // Reset state first
-        state.selectedIndex = 0;
-        state.inputBuffer = '';
-        state.isTypingCustom = false;
-        state.multiSelections.clear();
-        if (!(q.id in state.answers)) {
+        this.state.selectedIndex = 0;
+        this.state.inputBuffer = '';
+        this.state.isTypingCustom = false;
+        this.state.multiSelections.clear();
+        if (!(q.id in this.state.answers)) {
             // No existing answer - check if we should auto-type
-            // (no options, custom allowed, single-select)
             if (options.length === 0 && allowCustom && !isMultiSelect) {
-                state.isTypingCustom = true;
+                this.state.isTypingCustom = true;
             }
             return;
         }
-        const existingAnswer = state.answers[q.id];
+        const existingAnswer = this.state.answers[q.id];
         if (isMultiSelect && Array.isArray(existingAnswer)) {
-            // Multi-select: restore all selected options
             for (const answer of existingAnswer) {
                 const idx = options.indexOf(answer);
                 if (idx >= 0) {
-                    state.multiSelections.add(idx);
+                    this.state.multiSelections.add(idx);
                 }
                 else {
-                    // Custom answer - add to custom index and set buffer
-                    state.multiSelections.add(options.length);
-                    state.inputBuffer = answer;
+                    this.state.multiSelections.add(options.length);
+                    this.state.inputBuffer = answer;
                 }
             }
-            // Set selectedIndex to first selected item
-            if (state.multiSelections.size > 0) {
-                state.selectedIndex = Math.min(...state.multiSelections);
+            if (this.state.multiSelections.size > 0) {
+                this.state.selectedIndex = Math.min(...this.state.multiSelections);
             }
         }
         else if (typeof existingAnswer === 'string') {
-            // Single select: find which option was selected
             const idx = options.indexOf(existingAnswer);
             if (idx >= 0) {
-                state.selectedIndex = idx;
+                this.state.selectedIndex = idx;
             }
             else {
-                // Custom answer
-                state.selectedIndex = options.length; // Custom option index
-                state.inputBuffer = existingAnswer;
-                // Don't enter typing mode - just show the value
+                this.state.selectedIndex = options.length;
+                this.state.inputBuffer = existingAnswer;
             }
         }
-    };
-    // Helper: Navigate to next question or Submit tab
-    const nextQuestion = () => {
-        if (state.isOnSubmitTab) {
-            // Already on Submit tab, do nothing
+    }
+    nextQuestion() {
+        if (this.state.isOnSubmitTab) {
             return;
         }
-        if (state.currentQuestion < questions.length - 1) {
-            // Move to next question
-            debugLog(`nextQuestion: ${String(state.currentQuestion)} -> ${String(state.currentQuestion + 1)}, lineCount=${String(lineCount)}`);
-            state.currentQuestion++;
-            restoreFromAnswer();
+        if (this.state.currentQuestion < this.questions.length - 1) {
+            this.state.currentQuestion++;
+            this.restoreFromAnswer();
         }
         else {
             // On last question - move to Submit tab
-            debugLog(`nextQuestion: moving to Submit tab, lineCount=${String(lineCount)}`);
-            state.isOnSubmitTab = true;
-            // IMPORTANT: Clear typing mode when entering Submit tab
-            // Otherwise, Enter key is captured by typing mode handler instead of Submit handler
-            state.isTypingCustom = false;
-            state.inputBuffer = '';
-        }
-    };
-    // Helper: Navigate to previous question (or from Submit tab to last question)
-    const prevQuestion = () => {
-        if (state.isOnSubmitTab) {
-            // Move from Submit tab back to last question
-            debugLog(`prevQuestion: leaving Submit tab to question ${String(questions.length - 1)}`);
-            state.isOnSubmitTab = false;
-            restoreFromAnswer();
+            this.state.isOnSubmitTab = true;
+            this.state.isTypingCustom = false;
+            this.state.inputBuffer = '';
+        }
+    }
+    prevQuestion() {
+        if (this.state.isOnSubmitTab) {
+            this.state.isOnSubmitTab = false;
+            this.restoreFromAnswer();
             return;
         }
-        if (state.currentQuestion > 0) {
-            debugLog(`prevQuestion: ${String(state.currentQuestion)} -> ${String(state.currentQuestion - 1)}, lineCount=${String(lineCount)}`);
-            state.currentQuestion--;
-            restoreFromAnswer();
-        }
-    };
-    // Helper: Get list of unanswered question indices
-    const getUnansweredIndices = () => {
-        const unanswered = [];
-        for (let i = 0; i < questions.length; i++) {
-            if (!(questions[i].id in state.answers)) {
-                unanswered.push(i);
-            }
-        }
-        return unanswered;
-    };
-    // Helper: Check if all questions are answered and either complete or navigate to first unanswered
-    // Returns true if all complete and we should resolve, false if navigated to unanswered
-    const tryComplete = () => {
-        const unanswered = getUnansweredIndices();
+        if (this.state.currentQuestion > 0) {
+            this.state.currentQuestion--;
+            this.restoreFromAnswer();
+        }
+    }
+    tryComplete() {
+        const unanswered = this.questions.filter((q) => !(q.id in this.state.answers));
         if (unanswered.length === 0) {
-            // All questions answered - can complete
-            state.warningMessage = '';
+            this.state.warningMessage = '';
             return true;
         }
         // Navigate to first unanswered question and show warning
-        const firstUnanswered = unanswered[0];
-        const unansweredCount = unanswered.length;
-        state.warningMessage = `${String(unansweredCount)} question${unansweredCount > 1 ? 's' : ''} unanswered. Please answer all questions.`;
-        state.currentQuestion = firstUnanswered;
-        restoreFromAnswer();
+        const firstUnansweredIndex = this.questions.findIndex((q) => !(q.id in this.state.answers));
+        this.state.warningMessage = `${String(unanswered.length)} question${unanswered.length > 1 ? 's' : ''} unanswered. Please answer all questions.`;
+        this.state.currentQuestion = firstUnansweredIndex;
+        this.state.isOnSubmitTab = false;
+        this.restoreFromAnswer();
         return false;
-    };
-    // Helper: Submit answer for current question
-    const submitAnswer = () => {
-        const q = questions[state.currentQuestion];
+    }
+    submitAnswer() {
+        const q = this.questions[this.state.currentQuestion];
         const options = q.options ?? [];
         const allowCustom = q.allowCustom !== false;
         const isMultiSelect = q.multiSelect === true;
         const customIndex = options.length;
         if (isMultiSelect) {
-            // Multi-select: gather selected options
             const selectedAnswers = [];
-            for (const idx of state.multiSelections) {
+            for (const idx of this.state.multiSelections) {
                 if (idx < options.length) {
                     selectedAnswers.push(options[idx]);
                 }
             }
-            // Include custom if selected and typed
-            if (state.multiSelections.has(customIndex) && state.inputBuffer.trim()) {
-                selectedAnswers.push(state.inputBuffer.trim());
+            if (this.state.multiSelections.has(customIndex) && this.state.inputBuffer.trim()) {
+                selectedAnswers.push(this.state.inputBuffer.trim());
             }
             if (selectedAnswers.length > 0) {
-                state.answers[q.id] = selectedAnswers;
+                this.state.answers[q.id] = selectedAnswers;
                 return true;
             }
-            return false; // Nothing selected
+            return false;
         }
         else {
-            // Single select
-            if (state.isTypingCustom) {
-                const custom = state.inputBuffer.trim();
+            if (this.state.isTypingCustom) {
+                const custom = this.state.inputBuffer.trim();
                 if (custom) {
-                    state.answers[q.id] = custom;
+                    this.state.answers[q.id] = custom;
                     return true;
                 }
-                return false; // Empty custom
+                return false;
             }
-            else if (state.selectedIndex < options.length) {
-                state.answers[q.id] = options[state.selectedIndex];
+            else if (this.state.selectedIndex < options.length) {
+                this.state.answers[q.id] = options[this.state.selectedIndex];
                 return true;
             }
-            else if (allowCustom && state.selectedIndex === customIndex) {
-                // Enter custom input mode
-                state.isTypingCustom = true;
-                return false; // Don't advance yet
+            else if (allowCustom && this.state.selectedIndex === customIndex) {
+                this.state.isTypingCustom = true;
+                return false;
             }
         }
         return false;
-    };
-    return new Promise((resolve) => {
-        const cleanup = () => {
-            debugLog(`cleanup: clearing maxLineCount=${String(maxLineCount)}`);
-            // Clear the overlay - use maxLineCount to ensure full clearing
-            terminal.clearLinesAbove(maxLineCount);
-            terminal.writeLine('');
-            terminal.showCursor();
-            if (!wasRawMode) {
-                terminal.disableRawMode();
-            }
-            process.stdin.removeListener('data', handleData);
-            // NOTE: Footer resume is handled by the caller (index.ts) in the finally block
-        };
-        const handleData = (data) => {
-            onData(data);
-        };
-        const onData = (data) => {
-            const isEscape = data.length === 1 && data[0] === 0x1b;
-            const isUpArrow = data.length === 3 && data[0] === 0x1b && data[1] === 0x5b && data[2] === 0x41;
-            const isDownArrow = data.length === 3 && data[0] === 0x1b && data[1] === 0x5b && data[2] === 0x42;
-            const isLeftArrow = data.length === 3 && data[0] === 0x1b && data[1] === 0x5b && data[2] === 0x44;
-            const isRightArrow = data.length === 3 && data[0] === 0x1b && data[1] === 0x5b && data[2] === 0x43;
-            const isCtrlC = data.length === 1 && data[0] === 0x03;
-            const isEnter = data.length === 1 && (data[0] === 0x0d || data[0] === 0x0a);
-            const isBackspace = data.length === 1 && (data[0] === 0x7f || data[0] === 0x08);
-            const isTab = data.length === 1 && data[0] === 0x09;
-            const isSpace = data.length === 1 && data[0] === 0x20;
-            // Helper to get skipped questions
-            const getSkipped = () => questions.filter((q) => !(q.id in state.answers)).map((q) => q.id);
-            // Ctrl+C always cancels
-            if (isCtrlC) {
-                cleanup();
-                state.cancelled = true;
-                resolve({
-                    answers: state.answers,
-                    skipped: getSkipped(),
-                });
-                return;
-            }
-            // Submit tab takes priority over typing mode
-            // (This is a safeguard - nextQuestion() should already clear isTypingCustom)
-            if (state.isOnSubmitTab) {
-                // On Submit tab - handle special navigation
-                if (isEscape) {
-                    // Cancel overlay
-                    cleanup();
-                    resolve({
-                        answers: state.answers,
-                        skipped: getSkipped(),
-                    });
-                    return;
-                }
-                else if (isLeftArrow || isTab) {
-                    // Go back to last question
-                    prevQuestion();
-                }
-                else if (isEnter) {
-                    // Try to submit - check completeness
-                    if (tryComplete()) {
-                        cleanup();
-                        resolve({
-                            answers: state.answers,
-                            skipped: getSkipped(),
-                        });
-                        return;
-                    }
-                    // tryComplete sets warning and navigates to first unanswered
-                }
-                // Re-render and return early
-                lineCount = render(questions, state, context, maxLineCount, maxLineCount);
-                maxLineCount = Math.max(maxLineCount, lineCount);
-                return;
-            }
-            // If typing custom input
-            if (state.isTypingCustom) {
-                const currentQ = questions[state.currentQuestion];
-                const options = currentQ.options ?? [];
-                if (isEscape) {
-                    // Cancel custom input
-                    state.isTypingCustom = false;
-                    state.inputBuffer = '';
-                }
-                else if (isUpArrow && options.length > 0) {
-                    // Exit typing mode and navigate up (only if there are other options)
-                    state.isTypingCustom = false;
-                    state.inputBuffer = '';
-                    state.selectedIndex = Math.max(0, state.selectedIndex - 1);
-                }
-                else if (isDownArrow) {
-                    // Custom is last option, so down arrow does nothing
-                    // But we handle it to be consistent
-                }
-                else if (isEnter) {
-                    // Submit custom input
-                    if (submitAnswer()) {
-                        // Clear warning on successful submit
-                        state.warningMessage = '';
-                        // Move to next question (or Submit tab if on last question)
-                        nextQuestion();
-                    }
-                }
-                else if (isBackspace) {
-                    state.inputBuffer = state.inputBuffer.slice(0, -1);
-                }
-                else if (data.length === 1 && data[0] >= 0x20 && data[0] < 0x7f) {
-                    // Printable character
-                    state.inputBuffer += String.fromCharCode(data[0]);
-                }
-            }
-            else {
-                // Navigation mode - on a question (Submit tab is handled earlier)
-                const optionCount = getOptionCount();
-                const currentQ = questions[state.currentQuestion];
-                const isMultiSelect = currentQ.multiSelect === true;
-                const options = currentQ.options ?? [];
-                const allowCustom = currentQ.allowCustom !== false;
-                const customIndex = options.length;
-                if (isEscape) {
-                    // Cancel overlay
-                    cleanup();
-                    resolve({
-                        answers: state.answers,
-                        skipped: getSkipped(),
-                    });
-                    return;
-                }
-                else if (isUpArrow) {
-                    state.selectedIndex = Math.max(0, state.selectedIndex - 1);
-                    // Auto-enable typing when navigating to custom option (single-select only)
-                    if (!isMultiSelect && allowCustom && state.selectedIndex === customIndex) {
-                        state.isTypingCustom = true;
-                    }
-                }
-                else if (isDownArrow) {
-                    state.selectedIndex = Math.min(optionCount - 1, state.selectedIndex + 1);
-                    // Auto-enable typing when navigating to custom option (single-select only)
-                    if (!isMultiSelect && allowCustom && state.selectedIndex === customIndex) {
-                        state.isTypingCustom = true;
-                    }
-                }
-                else if (isLeftArrow) {
-                    prevQuestion();
-                }
-                else if (isRightArrow || isTab) {
-                    // Tab or right arrow: move to next question (or Submit tab)
-                    nextQuestion();
-                }
-                else if (isSpace && isMultiSelect) {
-                    // Toggle multi-select
-                    if (state.multiSelections.has(state.selectedIndex)) {
-                        state.multiSelections.delete(state.selectedIndex);
-                    }
-                    else {
-                        state.multiSelections.add(state.selectedIndex);
-                    }
-                }
-                else if (isEnter) {
-                    const submitted = submitAnswer();
-                    if (submitted) {
-                        // Clear warning on successful submit
-                        state.warningMessage = '';
-                        // Move to next question (or Submit tab)
-                        nextQuestion();
-                    }
-                }
-                else if (data.length === 1 && data[0] >= 0x31 && data[0] <= 0x39) {
-                    // Number keys 1-9
-                    const numIndex = data[0] - 0x31; // 0-indexed
-                    if (numIndex < optionCount) {
-                        state.selectedIndex = numIndex;
-                        if (!isMultiSelect) {
-                            // Auto-select for single select
-                            const submitted = submitAnswer();
-                            if (submitted) {
-                                // Clear warning on successful submit
-                                state.warningMessage = '';
-                                // Move to next question (or Submit tab)
-                                nextQuestion();
-                            }
-                        }
-                    }
-                }
-            }
-            // Re-render - use maxLineCount for both clearing AND target height to prevent cursor drift
-            lineCount = render(questions, state, context, maxLineCount, maxLineCount);
-            maxLineCount = Math.max(maxLineCount, lineCount);
-        };
-        process.stdin.on('data', handleData);
-    });
+    }
+}
+// =============================================================================
+// Main Export
+// =============================================================================
+/**
+ * Show the ask user overlay
+ */
+export async function showAskUserOverlay(options) {
+    const overlay = new AskUserOverlayImpl(options);
+    return overlay.show();
 }