@compilr-dev/cli 0.4.0 → 0.5.0

package/dist/ui/tutorial-overlay.js

@@ -3,9 +3,10 @@
  *
  * Interactive tutorial that guides users through the compilr.dev workflow.
  * Supports guided sequential tour and topic-based navigation.
+ * Refactored to use BaseOverlay + ScreenStack.
  */
 import * as terminal from './terminal.js';
-import { getStyles } from '../themes/index.js';
+import { BaseOverlay, BaseScreen, ScreenStack, stay, pushScreen, popScreen, closeOverlay, isEscape, isEnter, isCtrlC, isClose, isNavigateUp, isNavigateDown, isLeftArrow, isRightArrow, isVimLeft, isVimRight, isBackspace, } from './base/index.js';
 // =============================================================================
 // Helper
 // =============================================================================
@@ -16,16 +17,10 @@ function stripAnsi(str) {
     // eslint-disable-next-line no-control-regex
     return str.replace(/\x1B\[[0-9;]*[a-zA-Z]/g, '');
 }
-function getBorder() {
-    const s = getStyles();
-    const cols = terminal.getTerminalWidth();
-    return s.muted('─'.repeat(Math.max(1, cols - 1)));
-}
 // =============================================================================
 // Content
 // =============================================================================
-function buildTopics() {
-    const s = getStyles();
+function buildTopics(s) {
     return [
         // =========================================================================
         // Topic 1: Workflow Overview
@@ -80,20 +75,42 @@ function buildTopics() {
                         '',
                         `  The development workflow has five main stages:`,
                         '',
-                        `    ${s.primary('/init')}      Set up your project structure`,
-                        `               Creates COMPILR.md, backlog.md, and configuration`,
+                        `    ${s.primary('/new')}      Set up your project structure`,
+                        `               Creates project in database with configuration`,
                         '',
                         `    ${s.primary('/design')}    Gather requirements and create a PRD`,
-                        `               Comprehensive planning through conversation`,
+                        `               Documents stored in database for persistence`,
                         '',
                         `    ${s.primary('/backlog')}   Manage your work items`,
-                        `               Prioritize, track status, break down tasks`,
+                        `               Track status, prioritize, break down tasks`,
                         '',
                         `    ${s.primary('/build')}     Implement features from the backlog`,
                         `               AI-assisted coding with your approval`,
                         '',
-                        `    ${s.secondary('Iterate')}     Refine and improve continuously`,
-                        `               Use /refine, /arch, /prd to evolve the project`,
+                        `    ${s.primary('/workflow')}  Check progress and next steps`,
+                        `               See where you are and what's next`,
+                        '',
+                    ],
+                },
+                {
+                    title: 'Project Management',
+                    lines: [
+                        '',
+                        `  ${s.secondary('Track Your Progress')}`,
+                        '',
+                        `  ${s.primaryBold('/projects')}`,
+                        `    View all your projects in one place.`,
+                        `    Filter by status: Active, Paused, Completed, Archived.`,
+                        `    Switch between projects or open project directories.`,
+                        '',
+                        `  ${s.primaryBold('/workflow')}`,
+                        `    See your current project's workflow status.`,
+                        `    Shows which phases are complete and what's next.`,
+                        `    Quick actions to jump to the right command.`,
+                        '',
+                        `  ${s.primaryBold('/docs')}`,
+                        `    Browse documents created during design.`,
+                        `    View PRDs, architecture docs, and notes.`,
                         '',
                     ],
                 },
@@ -108,16 +125,15 @@ function buildTopics() {
             description: 'Setting up a new project',
             pages: [
                 {
-                    title: '/init Command',
+                    title: '/new Command',
                     lines: [
                         '',
-                        `  ${s.primaryBold('/init')} creates your project foundation through an 8-step wizard.`,
+                        `  ${s.primaryBold('/new')} creates your project foundation through an 8-step wizard.`,
                         '',
                         `  ${s.secondary('What it creates:')}`,
                         '',
-                        `    ${s.success('+')} Project directory with proper structure`,
+                        `    ${s.success('+')} ${s.primary('Project in database')} - Tracked for easy management`,
                         `    ${s.success('+')} ${s.primary('COMPILR.md')} - Context file for the AI assistant`,
-                        `    ${s.success('+')} ${s.primary('backlog.md')} - Work item tracking`,
                         `    ${s.success('+')} ${s.primary('.compilr/config.json')} - Project configuration`,
                         `    ${s.success('+')} Tech stack setup based on your choices`,
                         '',
@@ -125,26 +141,26 @@ function buildTopics() {
                         `    - Project name and description`,
                         `    - Project type (web, api, cli, fullstack)`,
                         `    - Tech stack preferences`,
-                        `    - Documentation setup (single or two repos)`,
+                        `    - Workflow mode (flexible or guided)`,
                         '',
                     ],
                 },
                 {
-                    title: '/init - Setup Options',
+                    title: '/new - Database Tracking',
                     lines: [
                         '',
-                        `  ${s.secondary('Single Repository Setup')}`,
-                        `    Everything in one directory: code, docs, and backlog.`,
-                        `    Best for: small projects, personal projects, quick starts.`,
+                        `  ${s.secondary('Project Database')}`,
+                        `    All projects are tracked in a local SQLite database.`,
+                        `    This enables: multi-project switching, progress tracking,`,
+                        `    and persistent work item management.`,
                         '',
-                        `  ${s.secondary('Two Repository Setup')}`,
-                        `    Separate repository for documentation and planning.`,
-                        `    Best for: team projects, complex projects, when you want`,
-                        `    to keep planning separate from code.`,
+                        `  ${s.secondary('View Your Projects')}`,
+                        `    Use ${s.primary('/projects')} to see all your projects.`,
+                        `    Use ${s.primary('/workflow')} to see current project status.`,
                         '',
-                        `  ${s.muted('Tip: Run /init in an empty directory to start fresh.')}`,
+                        `  ${s.muted('Tip: Run /new in an empty directory to start fresh.')}`,
                         '',
-                        `  After /init completes, the AI reads your COMPILR.md to understand`,
+                        `  After /new completes, the AI reads your COMPILR.md to understand`,
                         `  your project context. You're ready for the next step: ${s.primary('/design')}`,
                         '',
                     ],
@@ -191,19 +207,18 @@ function buildTopics() {
                         `  ${s.secondary('What /design creates:')}`,
                         '',
                         `    ${s.success('+')} ${s.primary('Product Requirements Document (PRD)')}`,
-                        `       A comprehensive document capturing your vision,`,
-                        `       features, technical requirements, and constraints.`,
+                        `       Stored in the database for persistence.`,
+                        `       Use ${s.primary('/docs')} to view it anytime.`,
                         '',
                         `    ${s.success('+')} ${s.primary('5-15 Backlog Items')}`,
-                        `       Auto-generated from your requirements,`,
-                        `       ready to be built with /build.`,
+                        `       Stored in database with status tracking.`,
+                        `       Use ${s.primary('/backlog')} to manage them.`,
                         '',
                         `    ${s.success('+')} ${s.primary('Clear Acceptance Criteria')}`,
                         `       Each backlog item has defined done criteria`,
                         `       so you know when it's complete.`,
                         '',
                         `  ${s.muted('Best for: serious projects that need thorough planning upfront.')}`,
-                        `  ${s.muted('Expect: 30+ minute conversation to capture everything.')}`,
                         '',
                     ],
                 },
@@ -336,11 +351,11 @@ function buildTopics() {
                         '',
                         `  Items move through three statuses:`,
                         '',
-                        `    ${s.warning('pending')}        Not started yet`,
+                        `    ${s.warning('backlog')}       Not started yet`,
                         `         ${s.muted('↓')}`,
                         `    ${s.primary('in-progress')}    Currently being worked on`,
                         `         ${s.muted('↓')}`,
-                        `    ${s.success('done')}           Completed`,
+                        `    ${s.success('completed')}      Done!`,
                         '',
                         `  ${s.secondary('Item Types:')}`,
                         `    ${s.muted('Feature')}      New functionality to build`,
@@ -348,7 +363,7 @@ function buildTopics() {
                         `    ${s.muted('Tech-Debt')}    Code improvements needed`,
                         `    ${s.muted('Chore')}        Maintenance tasks`,
                         '',
-                        `  Items are stored in ${s.primary('backlog.md')} and can also be edited manually.`,
+                        `  Items are stored in the ${s.primary('database')} and persist across sessions.`,
                         '',
                     ],
                 },
@@ -568,6 +583,29 @@ function buildTopics() {
                         '',
                     ],
                 },
+                {
+                    title: 'Anchors - Persistent Context',
+                    lines: [
+                        '',
+                        `  ${s.secondary('Anchors')} are critical pieces of information that survive`,
+                        `  context compaction. They're always included at the top of context.`,
+                        '',
+                        `  ${s.primaryBold('/anchors')}`,
+                        `    View and manage your anchors.`,
+                        `    Add, edit, or remove persistent context.`,
+                        '',
+                        `  ${s.secondary('When to use anchors:')}`,
+                        `    ${s.muted('+')} Project context that must never be forgotten`,
+                        `    ${s.muted('+')} Key architectural decisions`,
+                        `    ${s.muted('+')} User preferences for code style`,
+                        `    ${s.muted('+')} Important constraints or requirements`,
+                        '',
+                        `  ${s.secondary('Scope:')}`,
+                        `    ${s.primary('Global')}   - Persists across all projects`,
+                        `    ${s.primary('Project')}  - Specific to current project`,
+                        '',
+                    ],
+                },
             ],
         },
         // =========================================================================
@@ -624,7 +662,7 @@ function buildTopics() {
                     title: 'Best Practices',
                     lines: [
                         '',
-                        `  ${s.primary('1.')} Start with ${s.primaryBold('/init')}, then ${s.primaryBold('/design')} or ${s.primaryBold('/sketch')}`,
+                        `  ${s.primary('1.')} Start with ${s.primaryBold('/new')}, then ${s.primaryBold('/design')} or ${s.primaryBold('/sketch')}`,
                         `     Don't skip planning - it pays off later.`,
                         '',
                         `  ${s.primary('2.')} Keep backlog items small and focused`,
@@ -646,291 +684,351 @@ function buildTopics() {
     ];
 }
 // =============================================================================
-// Rendering
+// Screens
 // =============================================================================
-function renderWelcome(state, previousLineCount) {
-    const s = getStyles();
-    const lines = [];
-    const border = getBorder();
-    if (previousLineCount > 0) {
-        terminal.clearLinesAbove(previousLineCount);
+/**
+ * Welcome screen - shows entry options (guided tour or topic list)
+ */
+class WelcomeScreen extends BaseScreen {
+    state;
+    styles;
+    topics;
+    selectedIndex = 0;
+    constructor(state, styles, topics) {
+        super();
+        this.state = state;
+        this.styles = styles;
+        this.topics = topics;
     }
-    lines.push(border);
-    lines.push(` ${s.primaryBold('compilr.dev Tutorial')}`);
-    lines.push('');
-    lines.push(`  Learn the AI-powered development workflow that takes you`);
-    lines.push(`  from idea to implementation with structure and discipline.`);
-    lines.push('');
-    lines.push(`  This tutorial covers: initialization, design, backlog`);
-    lines.push(`  management, building, configuration, and best practices.`);
-    lines.push('');
-    lines.push(`  ${s.muted('How would you like to explore?')}`);
-    lines.push('');
-    const options = [
-        { label: 'Start Guided Tour', desc: 'Step-by-step walkthrough (recommended)' },
-        { label: 'Jump to Topic', desc: 'Go directly to a specific topic' },
-    ];
-    for (let i = 0; i < options.length; i++) {
-        const opt = options[i];
-        const selected = i === state.welcomeIndex;
-        const prefix = selected ? s.primary(' ❯ ') : '   ';
-        const label = selected ? s.primary(opt.label) : opt.label;
-        const desc = s.muted(opt.desc);
-        lines.push(`${prefix}${label.padEnd(22)} ${desc}`);
+    render() {
+        const s = this.styles;
+        const cols = terminal.getTerminalWidth();
+        const border = s.muted('─'.repeat(Math.max(1, cols - 1)));
+        const lines = [];
+        lines.push(border);
+        lines.push(` ${s.primaryBold('compilr.dev Tutorial')}`);
+        lines.push('');
+        lines.push(`  Learn the AI-powered development workflow that takes you`);
+        lines.push(`  from idea to implementation with structure and discipline.`);
+        lines.push('');
+        lines.push(`  This tutorial covers: initialization, design, backlog`);
+        lines.push(`  management, building, configuration, and best practices.`);
+        lines.push('');
+        lines.push(`  ${s.muted('How would you like to explore?')}`);
+        lines.push('');
+        const options = [
+            { label: 'Start Guided Tour', desc: 'Step-by-step walkthrough (recommended)' },
+            { label: 'Jump to Topic', desc: 'Go directly to a specific topic' },
+        ];
+        for (let i = 0; i < options.length; i++) {
+            const opt = options[i];
+            const selected = i === this.selectedIndex;
+            const prefix = selected ? s.primary(' ❯ ') : '   ';
+            const label = selected ? s.primary(opt.label) : opt.label;
+            const desc = s.muted(opt.desc);
+            lines.push(`${prefix}${label.padEnd(22)} ${desc}`);
+        }
+        lines.push('');
+        lines.push(border);
+        lines.push(s.muted(' ↑↓/jk Navigate · Enter Select · q/Esc Exit'));
+        return lines;
+    }
+    handleKey(data) {
+        // Close keys
+        if (isCtrlC(data) || isClose(data)) {
+            return closeOverlay({ completed: false });
+        }
+        // Navigation
+        if (isNavigateUp(data) && this.selectedIndex > 0) {
+            this.selectedIndex--;
+            return stay();
+        }
+        if (isNavigateDown(data) && this.selectedIndex < 1) {
+            this.selectedIndex++;
+            return stay();
+        }
+        // Enter - select option
+        if (isEnter(data)) {
+            if (this.selectedIndex === 0) {
+                // Guided mode
+                this.state.isGuidedMode = true;
+                this.state.currentTopicIndex = 0;
+                this.state.currentPageIndex = 0;
+                return pushScreen(new ViewingScreen(this.state, this.styles, this.topics));
+            }
+            else {
+                // Topic list mode
+                return pushScreen(new TopicListScreen(this.state, this.styles, this.topics));
+            }
+        }
+        return stay(false);
     }
-    lines.push('');
-    lines.push(border);
-    lines.push(s.muted(' ↑↓ Navigate · Enter Select · Esc Exit'));
-    terminal.write(lines.join('\n'));
-    return lines.length;
 }
-function renderTopicList(state, topics, previousLineCount) {
-    const s = getStyles();
-    const lines = [];
-    const border = getBorder();
-    if (previousLineCount > 0) {
-        terminal.clearLinesAbove(previousLineCount);
+/**
+ * Topic list screen - shows all topics to choose from
+ */
+class TopicListScreen extends BaseScreen {
+    state;
+    styles;
+    topics;
+    constructor(state, styles, topics) {
+        super();
+        this.state = state;
+        this.styles = styles;
+        this.topics = topics;
+    }
+    render() {
+        const s = this.styles;
+        const cols = terminal.getTerminalWidth();
+        const border = s.muted('─'.repeat(Math.max(1, cols - 1)));
+        const lines = [];
+        lines.push(border);
+        lines.push(` ${s.primaryBold('Tutorial Topics')}`);
+        lines.push('');
+        for (let i = 0; i < this.topics.length; i++) {
+            const topic = this.topics[i];
+            const selected = i === this.state.topicListIndex;
+            const prefix = selected ? s.primary(' ❯ ') : '   ';
+            const name = selected ? s.primary(topic.name) : topic.name;
+            const desc = s.muted(topic.description);
+            const pages = s.muted(`(${String(topic.pages.length)} ${topic.pages.length === 1 ? 'page' : 'pages'})`);
+            lines.push(`${prefix}${name.padEnd(26)} ${desc.padEnd(30)} ${pages}`);
+        }
+        lines.push('');
+        lines.push(border);
+        lines.push(s.muted(' ↑↓/jk Navigate · Enter View · q/Esc Close'));
+        return lines;
     }
-    lines.push(border);
-    lines.push(` ${s.primaryBold('Tutorial Topics')}`);
-    lines.push('');
-    for (let i = 0; i < topics.length; i++) {
-        const topic = topics[i];
-        const selected = i === state.topicListIndex;
-        const prefix = selected ? s.primary(' ❯ ') : '   ';
-        const name = selected ? s.primary(topic.name) : topic.name;
-        const desc = s.muted(topic.description);
-        const pages = s.muted(`(${String(topic.pages.length)} ${topic.pages.length === 1 ? 'page' : 'pages'})`);
-        lines.push(`${prefix}${name.padEnd(26)} ${desc.padEnd(30)} ${pages}`);
+    handleKey(data) {
+        // Ctrl+C or q closes overlay
+        if (isCtrlC(data)) {
+            return closeOverlay({ completed: false });
+        }
+        // Escape goes back to welcome
+        if (isEscape(data)) {
+            return popScreen();
+        }
+        // Navigation
+        if (isNavigateUp(data) && this.state.topicListIndex > 0) {
+            this.state.topicListIndex--;
+            return stay();
+        }
+        if (isNavigateDown(data) && this.state.topicListIndex < this.topics.length - 1) {
+            this.state.topicListIndex++;
+            return stay();
+        }
+        // Enter - view topic
+        if (isEnter(data)) {
+            this.state.isGuidedMode = false;
+            this.state.currentTopicIndex = this.state.topicListIndex;
+            this.state.currentPageIndex = 0;
+            return pushScreen(new ViewingScreen(this.state, this.styles, this.topics));
+        }
+        return stay(false);
     }
-    lines.push('');
-    lines.push(border);
-    lines.push(s.muted(' ↑↓ Navigate · Enter View · Esc Back'));
-    terminal.write(lines.join('\n'));
-    return lines.length;
 }
-function renderPage(state, topics, previousLineCount) {
-    const s = getStyles();
-    const lines = [];
-    const border = getBorder();
-    if (previousLineCount > 0) {
-        terminal.clearLinesAbove(previousLineCount);
+/**
+ * Viewing screen - shows a page from a topic with navigation
+ */
+class ViewingScreen extends BaseScreen {
+    state;
+    styles;
+    topics;
+    constructor(state, styles, topics) {
+        super();
+        this.state = state;
+        this.styles = styles;
+        this.topics = topics;
+    }
+    render() {
+        const s = this.styles;
+        const cols = terminal.getTerminalWidth();
+        const border = s.muted('─'.repeat(Math.max(1, cols - 1)));
+        const lines = [];
+        const topic = this.topics[this.state.currentTopicIndex];
+        const page = topic.pages[this.state.currentPageIndex];
+        const totalPages = topic.pages.length;
+        // Calculate overall progress for guided mode
+        let progressText = `[${String(this.state.currentPageIndex + 1)}/${String(totalPages)}]`;
+        if (this.state.isGuidedMode) {
+            let totalPagesAll = 0;
+            let currentPageAll = 0;
+            for (let i = 0; i < this.topics.length; i++) {
+                if (i < this.state.currentTopicIndex) {
+                    currentPageAll += this.topics[i].pages.length;
+                }
+                else if (i === this.state.currentTopicIndex) {
+                    currentPageAll += this.state.currentPageIndex + 1;
+                }
+                totalPagesAll += this.topics[i].pages.length;
+            }
+            progressText = `[${String(currentPageAll)}/${String(totalPagesAll)}]`;
+        }
+        // Header - calculate padding to right-align progress indicator
+        const titleStyled = s.primaryBold(page.title);
+        const progressStyled = s.muted(progressText);
+        const titleLen = stripAnsi(titleStyled).length + 1; // +1 for leading space
+        const progressLen = stripAnsi(progressStyled).length;
+        const padding = Math.max(1, cols - titleLen - progressLen - 2); // -2 for margins
+        lines.push(border);
+        lines.push(` ${titleStyled}${' '.repeat(padding)}${progressStyled}`);
+        lines.push('');
+        // Content
+        for (const line of page.lines) {
+            lines.push(line);
+        }
+        // Pad to consistent height
+        while (lines.length < 20) {
+            lines.push('');
+        }
+        // Navigation footer
+        lines.push(border);
+        if (this.state.isGuidedMode) {
+            lines.push(s.muted(' ←/→/hl Navigate · Esc Exit Tour'));
+        }
+        else {
+            lines.push(s.muted(' ←/→/hl Navigate · Esc Back to Topics'));
+        }
+        return lines;
     }
-    const topic = topics[state.currentTopicIndex];
-    const page = topic.pages[state.currentPageIndex];
-    const totalPages = topic.pages.length;
-    // Calculate overall progress for guided mode
-    let progressText = `[${String(state.currentPageIndex + 1)}/${String(totalPages)}]`;
-    if (state.isGuidedMode) {
-        let totalPagesAll = 0;
-        let currentPageAll = 0;
-        for (let i = 0; i < topics.length; i++) {
-            if (i < state.currentTopicIndex) {
-                currentPageAll += topics[i].pages.length;
+    handleKey(data) {
+        // Ctrl+C closes overlay
+        if (isCtrlC(data)) {
+            return closeOverlay({ completed: false });
+        }
+        const topic = this.topics[this.state.currentTopicIndex];
+        const totalPages = topic.pages.length;
+        // Escape goes back
+        if (isEscape(data)) {
+            return popScreen();
+        }
+        // Previous page (left arrow, h, or backspace)
+        if (isLeftArrow(data) || isVimLeft(data) || isBackspace(data)) {
+            if (this.state.currentPageIndex > 0) {
+                this.state.currentPageIndex--;
+                return stay();
             }
-            else if (i === state.currentTopicIndex) {
-                currentPageAll += state.currentPageIndex + 1;
+            else if (this.state.isGuidedMode && this.state.currentTopicIndex > 0) {
+                this.state.currentTopicIndex--;
+                this.state.currentPageIndex = this.topics[this.state.currentTopicIndex].pages.length - 1;
+                return stay();
+            }
+            return stay(false);
+        }
+        // Next page (right arrow, l, or enter)
+        if (isRightArrow(data) || isVimRight(data) || isEnter(data)) {
+            if (this.state.currentPageIndex < totalPages - 1) {
+                this.state.currentPageIndex++;
+                return stay();
+            }
+            else if (this.state.isGuidedMode) {
+                if (this.state.currentTopicIndex < this.topics.length - 1) {
+                    this.state.currentTopicIndex++;
+                    this.state.currentPageIndex = 0;
+                    return stay();
+                }
+                else {
+                    // End of guided tour - show complete screen
+                    return pushScreen(new CompleteScreen(this.styles));
+                }
             }
-            totalPagesAll += topics[i].pages.length;
+            return stay(false);
         }
-        progressText = `[${String(currentPageAll)}/${String(totalPagesAll)}]`;
+        return stay(false);
     }
-    // Header - calculate padding to right-align progress indicator
-    const titleStyled = s.primaryBold(page.title);
-    const progressStyled = s.muted(progressText);
-    const titleLen = stripAnsi(titleStyled).length + 1; // +1 for leading space
-    const progressLen = stripAnsi(progressStyled).length;
-    const cols = terminal.getTerminalWidth();
-    const padding = Math.max(1, cols - titleLen - progressLen - 2); // -2 for margins
-    lines.push(border);
-    lines.push(` ${titleStyled}${' '.repeat(padding)}${progressStyled}`);
-    lines.push('');
-    // Content
-    for (const line of page.lines) {
-        lines.push(line);
+}
+/**
+ * Complete screen - shows completion message
+ */
+class CompleteScreen extends BaseScreen {
+    styles;
+    constructor(styles) {
+        super();
+        this.styles = styles;
     }
-    // Pad to consistent height
-    while (lines.length < 20) {
+    render() {
+        const s = this.styles;
+        const cols = terminal.getTerminalWidth();
+        const border = s.muted('─'.repeat(Math.max(1, cols - 1)));
+        const lines = [];
+        lines.push(border);
+        lines.push(` ${s.success('Tutorial Complete!')}`);
         lines.push('');
+        lines.push(`  You've learned the compilr.dev workflow!`);
+        lines.push('');
+        lines.push(`  ${s.secondary('Key commands to remember:')}`);
+        lines.push('');
+        lines.push(`    ${s.primary('/new')}       Start a new project`);
+        lines.push(`    ${s.primary('/design')}     Plan your requirements`);
+        lines.push(`    ${s.primary('/backlog')}    Manage your work items`);
+        lines.push(`    ${s.primary('/build')}      Implement features`);
+        lines.push(`    ${s.primary('/help')}       See all commands`);
+        lines.push('');
+        lines.push(`  ${s.secondary('Ready to start?')}`);
+        lines.push(`  Try ${s.primary('/new')} in a new directory!`);
+        lines.push('');
+        lines.push(border);
+        lines.push(s.muted(' Press any key to exit...'));
+        return lines;
     }
-    // Navigation footer
-    lines.push(border);
-    if (state.isGuidedMode) {
-        lines.push(s.muted(' ←/→ Navigate · Esc Exit Tour'));
-    }
-    else {
-        lines.push(s.muted(' ←/→ Navigate · Esc Back to Topics'));
+    handleKey(_data) {
+        // Any key closes the overlay with completed = true
+        return closeOverlay({ completed: true });
     }
-    terminal.write(lines.join('\n'));
-    return lines.length;
 }
-function renderComplete(previousLineCount) {
-    const s = getStyles();
-    const lines = [];
-    const border = getBorder();
-    if (previousLineCount > 0) {
-        terminal.clearLinesAbove(previousLineCount);
+// =============================================================================
+// Overlay Class
+// =============================================================================
+class TutorialOverlay extends BaseOverlay {
+    screenStack;
+    topics;
+    constructor() {
+        super({
+            lineCount: 0,
+            maxLineCount: 0,
+            topicListIndex: 0,
+            currentTopicIndex: 0,
+            currentPageIndex: 0,
+            isGuidedMode: false,
+        });
+        this.topics = buildTopics(this.styles);
+        this.screenStack = new ScreenStack();
+        this.screenStack.push(new WelcomeScreen(this.state, this.styles, this.topics));
     }
-    lines.push(border);
-    lines.push(` ${s.success('Tutorial Complete!')}`);
-    lines.push('');
-    lines.push(`  You've learned the compilr.dev workflow!`);
-    lines.push('');
-    lines.push(`  ${s.secondary('Key commands to remember:')}`);
-    lines.push('');
-    lines.push(`    ${s.primary('/init')}       Start a new project`);
-    lines.push(`    ${s.primary('/design')}     Plan your requirements`);
-    lines.push(`    ${s.primary('/backlog')}    Manage your work items`);
-    lines.push(`    ${s.primary('/build')}      Implement features`);
-    lines.push(`    ${s.primary('/help')}       See all commands`);
-    lines.push('');
-    lines.push(`  ${s.secondary('Ready to start?')}`);
-    lines.push(`  Try ${s.primary('/init')} in a new directory!`);
-    lines.push('');
-    lines.push(border);
-    lines.push(s.muted(' Press any key to exit...'));
-    terminal.write(lines.join('\n'));
-    return lines.length;
-}
-function render(state, topics, previousLineCount) {
-    switch (state.mode) {
-        case 'welcome':
-            return renderWelcome(state, previousLineCount);
-        case 'topic-list':
-            return renderTopicList(state, topics, previousLineCount);
-        case 'viewing':
-            return renderPage(state, topics, previousLineCount);
-        case 'complete':
-            return renderComplete(previousLineCount);
+    render() {
+        const screen = this.screenStack.current();
+        return screen?.render() ?? [];
+    }
+    handleKey(data) {
+        const screen = this.screenStack.current();
+        if (!screen) {
+            this.close({ completed: false });
+            return;
+        }
+        const result = screen.handleKey(data);
+        switch (result.action) {
+            case 'stay':
+                if (result.render) {
+                    this.update();
+                }
+                break;
+            case 'push':
+                this.screenStack.push(result.screen);
+                this.update();
+                break;
+            case 'pop':
+                this.screenStack.pop();
+                this.update();
+                break;
+            case 'close':
+                this.close(result.result);
+                break;
+        }
     }
 }
 // =============================================================================
-// Main Export
+// Export Function (Backward Compatible)
 // =============================================================================
 export async function showTutorialOverlay() {
-    const topics = buildTopics();
-    const state = {
-        mode: 'welcome',
-        welcomeIndex: 0,
-        topicListIndex: 0,
-        currentTopicIndex: 0,
-        currentPageIndex: 0,
-        isGuidedMode: false,
-    };
-    let lineCount = 0;
-    lineCount = render(state, topics, lineCount);
-    return new Promise((resolve) => {
-        const stdin = process.stdin;
-        stdin.setRawMode(true);
-        stdin.resume();
-        const cleanup = () => {
-            stdin.removeListener('data', handleKey);
-            stdin.setRawMode(false);
-            stdin.pause();
-            terminal.clearLinesAbove(lineCount);
-        };
-        const handleKey = (data) => {
-            const key = data.toString();
-            const isEscape = key === '\x1B' && data.length === 1;
-            const isEnter = key === '\r' || key === '\n';
-            const isUpArrow = key === '\x1B[A';
-            const isDownArrow = key === '\x1B[B';
-            const isLeftArrow = key === '\x1B[D';
-            const isRightArrow = key === '\x1B[C';
-            const isCtrlC = key === '\x03';
-            if (isCtrlC) {
-                cleanup();
-                resolve({ completed: false });
-                return;
-            }
-            switch (state.mode) {
-                case 'welcome': {
-                    if (isEscape) {
-                        cleanup();
-                        resolve({ completed: false });
-                        return;
-                    }
-                    if (isUpArrow && state.welcomeIndex > 0) {
-                        state.welcomeIndex--;
-                    }
-                    else if (isDownArrow && state.welcomeIndex < 1) {
-                        state.welcomeIndex++;
-                    }
-                    else if (isEnter) {
-                        if (state.welcomeIndex === 0) {
-                            state.isGuidedMode = true;
-                            state.currentTopicIndex = 0;
-                            state.currentPageIndex = 0;
-                            state.mode = 'viewing';
-                        }
-                        else {
-                            state.mode = 'topic-list';
-                        }
-                    }
-                    break;
-                }
-                case 'topic-list': {
-                    if (isEscape) {
-                        state.mode = 'welcome';
-                    }
-                    else if (isUpArrow && state.topicListIndex > 0) {
-                        state.topicListIndex--;
-                    }
-                    else if (isDownArrow && state.topicListIndex < topics.length - 1) {
-                        state.topicListIndex++;
-                    }
-                    else if (isEnter) {
-                        state.isGuidedMode = false;
-                        state.currentTopicIndex = state.topicListIndex;
-                        state.currentPageIndex = 0;
-                        state.mode = 'viewing';
-                    }
-                    break;
-                }
-                case 'viewing': {
-                    const topic = topics[state.currentTopicIndex];
-                    const totalPages = topic.pages.length;
-                    if (isEscape) {
-                        if (state.isGuidedMode) {
-                            state.mode = 'welcome';
-                        }
-                        else {
-                            state.mode = 'topic-list';
-                        }
-                    }
-                    else if (isLeftArrow || key === '\x7F') {
-                        if (state.currentPageIndex > 0) {
-                            state.currentPageIndex--;
-                        }
-                        else if (state.isGuidedMode && state.currentTopicIndex > 0) {
-                            state.currentTopicIndex--;
-                            state.currentPageIndex = topics[state.currentTopicIndex].pages.length - 1;
-                        }
-                    }
-                    else if (isRightArrow || isEnter) {
-                        if (state.currentPageIndex < totalPages - 1) {
-                            state.currentPageIndex++;
-                        }
-                        else if (state.isGuidedMode) {
-                            if (state.currentTopicIndex < topics.length - 1) {
-                                state.currentTopicIndex++;
-                                state.currentPageIndex = 0;
-                            }
-                            else {
-                                state.mode = 'complete';
-                            }
-                        }
-                    }
-                    break;
-                }
-                case 'complete': {
-                    cleanup();
-                    resolve({ completed: true });
-                    return;
-                }
-            }
-            lineCount = render(state, topics, lineCount);
-        };
-        stdin.on('data', handleKey);
-    });
+    return new TutorialOverlay().show();
 }