cli-menu-kit 0.1.26 → 0.2.0

package/dist/core/virtual-scroll.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * Virtual scrolling utilities for rendering large lists efficiently
+ * by only displaying a visible window of items.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculateVirtualScroll = calculateVirtualScroll;
+/**
+ * Calculate visible range for virtual scrolling based on line count.
+ *
+ * This function maintains a stable viewport height by calculating which items
+ * to display based on their actual line count, not just item count. This prevents
+ * height jumping when items have varying heights (e.g., separators with descriptions).
+ *
+ * Algorithm:
+ * 1. Calculate total lines needed for all items
+ * 2. If total <= targetLines, show everything (no scrolling)
+ * 3. Otherwise, create a window centered on cursor:
+ *    - Start from cursor position
+ *    - Expand downward until reaching target or end
+ *    - Expand upward to fill remaining space
+ *    - Expand downward again if space remains
+ *
+ * @example
+ * ```typescript
+ * const result = calculateVirtualScroll({
+ *   items: menuOptions,
+ *   cursorIndex: 10,
+ *   targetLines: 30,
+ *   getItemLineCount: (item, index) => {
+ *     if (item.type === 'separator') {
+ *       return 1 + (item.description ? 1 : 0) + (index > 0 ? 1 : 0);
+ *     }
+ *     return 1;
+ *   }
+ * });
+ *
+ * // Render only visible items
+ * for (let i = result.visibleStart; i < result.visibleEnd; i++) {
+ *   renderItem(items[i]);
+ * }
+ * ```
+ */
+function calculateVirtualScroll(options) {
+    const { items, cursorIndex, targetLines, getItemLineCount } = options;
+    // Validate inputs
+    if (items.length === 0) {
+        return {
+            visibleStart: 0,
+            visibleEnd: 0,
+            actualLines: 0,
+            isScrolled: false,
+            hasItemsBefore: false,
+            hasItemsAfter: false
+        };
+    }
+    if (cursorIndex < 0 || cursorIndex >= items.length) {
+        throw new Error(`cursorIndex ${cursorIndex} is out of bounds [0, ${items.length})`);
+    }
+    // Calculate total lines for all items
+    const estimatedTotalLines = items.reduce((sum, item, idx) => {
+        return sum + getItemLineCount(item, idx);
+    }, 0);
+    // If content fits within target, show everything
+    if (estimatedTotalLines <= targetLines) {
+        return {
+            visibleStart: 0,
+            visibleEnd: items.length,
+            actualLines: estimatedTotalLines,
+            isScrolled: false,
+            hasItemsBefore: false,
+            hasItemsAfter: false
+        };
+    }
+    // Virtual scrolling: maintain constant line count
+    let visibleStart = cursorIndex;
+    let visibleEnd = cursorIndex + 1;
+    let currentLines = getItemLineCount(items[cursorIndex], cursorIndex);
+    // Phase 1: Expand downward from cursor
+    while (visibleEnd < items.length && currentLines < targetLines) {
+        const nextLines = getItemLineCount(items[visibleEnd], visibleEnd);
+        if (currentLines + nextLines <= targetLines) {
+            currentLines += nextLines;
+            visibleEnd++;
+        }
+        else {
+            break;
+        }
+    }
+    // Phase 2: Expand upward to fill remaining space
+    while (visibleStart > 0 && currentLines < targetLines) {
+        const prevLines = getItemLineCount(items[visibleStart - 1], visibleStart - 1);
+        if (currentLines + prevLines <= targetLines) {
+            visibleStart--;
+            currentLines += prevLines;
+        }
+        else {
+            break;
+        }
+    }
+    // Phase 3: Try expanding downward again if space remains
+    while (visibleEnd < items.length && currentLines < targetLines) {
+        const nextLines = getItemLineCount(items[visibleEnd], visibleEnd);
+        if (currentLines + nextLines <= targetLines) {
+            currentLines += nextLines;
+            visibleEnd++;
+        }
+        else {
+            break;
+        }
+    }
+    return {
+        visibleStart,
+        visibleEnd,
+        actualLines: currentLines,
+        isScrolled: true,
+        hasItemsBefore: visibleStart > 0,
+        hasItemsAfter: visibleEnd < items.length
+    };
+}

package/dist/i18n/languages/en.js

@@ -9,7 +9,10 @@ exports.en = {
         selectPrompt: 'Enter option or use ↑↓ to select, press Enter to confirm',
         multiSelectPrompt: 'Space to toggle, Enter to confirm',
         confirmPrompt: 'Press Enter to confirm',
-        selectedCount: 'selected'
+        selectedCount: 'selected',
+        yes: 'Yes',
+        no: 'No',
+        scrollIndicator: 'Item {current}/{total} | ↑↓ Scroll for more'
     },
     hints: {
         arrows: '↑↓ Arrow keys',

package/dist/i18n/languages/zh.js

@@ -9,7 +9,10 @@ exports.zh = {
         selectPrompt: '输入选项或用↑↓选择,回车确认',
         multiSelectPrompt: '空格选中/取消,回车确认',
         confirmPrompt: '回车确认',
-        selectedCount: '项已选'
+        selectedCount: '项已选',
+        yes: '是',
+        no: '否',
+        scrollIndicator: '第 {current}/{total} 项 | ↑↓ 滚动查看更多'
     },
     hints: {
         arrows: '↑↓ 方向键',

package/dist/i18n/registry.d.ts

@@ -13,11 +13,12 @@ export declare function getCurrentLanguage(): LanguageCode;
  */
 export declare function setLanguage(lang: LanguageCode): void;
 /**
- * Get translation for a key path
+ * Get translation for a key path with optional parameter substitution
  * @param keyPath - Dot-separated key path (e.g., 'menus.selectPrompt')
- * @returns Translated string
+ * @param params - Optional parameters for string interpolation (e.g., { current: '1', total: '10' })
+ * @returns Translated string with parameters substituted
  */
-export declare function t(keyPath: string): string;
+export declare function t(keyPath: string, params?: Record<string, string>): string;
 /**
  * Register a new language
  * @param code - Language code

package/dist/i18n/registry.js

@@ -39,11 +39,12 @@ function setLanguage(lang) {
     registry.current = lang;
 }
 /**
- * Get translation for a key path
+ * Get translation for a key path with optional parameter substitution
  * @param keyPath - Dot-separated key path (e.g., 'menus.selectPrompt')
- * @returns Translated string
+ * @param params - Optional parameters for string interpolation (e.g., { current: '1', total: '10' })
+ * @returns Translated string with parameters substituted
  */
-function t(keyPath) {
+function t(keyPath, params) {
     const keys = keyPath.split('.');
     const langMap = registry.languages[registry.current];
     let value = langMap;
@@ -56,7 +57,14 @@ function t(keyPath) {
             return keyPath; // Return key path as fallback
         }
     }
-    return typeof value === 'string' ? value : keyPath;
+    let result = typeof value === 'string' ? value : keyPath;
+    // Substitute parameters if provided
+    if (params) {
+        for (const [key, val] of Object.entries(params)) {
+            result = result.replace(new RegExp(`\\{${key}\\}`, 'g'), val);
+        }
+    }
+    return result;
 }
 /**
  * Register a new language

package/dist/i18n/types.d.ts

@@ -14,6 +14,9 @@ export interface LanguageMap {
         multiSelectPrompt: string;
         confirmPrompt: string;
         selectedCount: string;
+        yes: string;
+        no: string;
+        scrollIndicator: string;
     };
     hints: {
         arrows: string;

package/dist/index.d.ts

@@ -4,20 +4,21 @@
  */
 export { menuAPI as menu, inputAPI as input, wizardAPI as wizard } from './api.js';
 export { default } from './api.js';
-export { showRadioMenu, showCheckboxMenu, showBooleanMenu } from './components/menus/index.js';
+export { renderPage, type PageLayoutConfig, type HeaderConfig as PageHeaderConfig, type MainAreaConfig, type FooterConfig } from './page-layout.js';
+export { createFullHeaderComponent, createSimpleHeaderComponent, createSectionHeaderComponent, createHintsComponent, createTableComponent, createListComponent, createSummaryTableComponent, createRadioMenuComponent, createInputPromptComponent } from './component-factories.js';
+export { showRadioMenu, showCheckboxMenu, showCheckboxTableMenu, showBooleanMenu } from './components/menus/index.js';
 export { showTextInput, showNumberInput, showLanguageSelector, showModifyField } from './components/inputs/index.js';
-export { renderSimpleHeader, renderSectionHeader, renderAsciiHeader, createSimpleHeader, createSectionHeader, createAsciiHeader, renderProgressIndicator, renderStageHeader, renderStageSeparator, createProgressIndicator, createStageHeader, createStageSeparator, renderMessage, showSuccess, showError, showWarning, showInfo, showQuestion, createMessage, renderSummaryTable, createSummaryTable, createSimpleSummary, renderHeader, type HeaderConfig } from './components/display/index.js';
+export { renderSimpleHeader, renderSectionHeader, renderAsciiHeader, createSimpleHeader, createSectionHeader, createAsciiHeader, renderProgressIndicator, renderStageHeader, renderStageSeparator, createProgressIndicator, createStageHeader, createStageSeparator, renderMessage, showSuccess, showError, showWarning, showInfo, showQuestion, createMessage, renderSummaryTable, createSummaryTable, createSimpleSummary, renderHeader, type HeaderConfig, renderHintsComponent, createHints, generateMenuHints, generateInputHints, HintTypes, type HintsConfig, renderTable, createTable, type TableConfig, type TableColumn, renderList, createList, createBulletList, createNumberedList, type ListConfig, type ListItem } from './components/display/index.js';
 export { runWizard, createWizard, WizardConfig, WizardStep, WizardResult } from './features/wizard.js';
 export { registerCommand, unregisterCommand, clearCustomCommands, isCommand, parseCommand, handleCommand, getAvailableCommands, showCommandHelp } from './features/commands.js';
 export { getCurrentLanguage, setLanguage, t, registerLanguage, getAvailableLanguages, getCurrentLanguageMap } from './i18n/registry.js';
 export { colors, uiColors, defaultUIColors, getUIColors, setUIColors, resetUIColors, createGradient, applyGradient, colorize } from './core/colors.js';
-export type { MenuLayout, LayoutElement, LayoutVisibility, LayoutSpacing } from './types/layout.types.js';
 export type { MenuOption, BaseMenuConfig, RadioMenuConfig, CheckboxMenuConfig, BooleanMenuConfig, RadioMenuResult, CheckboxMenuResult, BooleanMenuResult } from './types/menu.types.js';
 export type { BaseInputConfig, TextInputConfig, NumberInputConfig, LanguageSelectorConfig, ModifyFieldConfig, TextInputResult, NumberInputResult, LanguageSelectorResult, ModifyFieldResult } from './types/input.types.js';
 export type { HeaderType, SimpleHeaderConfig, AsciiHeaderConfig, ProgressConfig, MessageType, MessageConfig, SummaryTableConfig } from './types/display.types.js';
 export type { LanguageCode, LanguageMap, I18nRegistry } from './i18n/types.js';
 export { KEY_CODES } from './core/keyboard.js';
-export { LAYOUT_PRESETS } from './types/layout.types.js';
+export { calculateVirtualScroll, type VirtualScrollOptions, type VirtualScrollResult } from './core/virtual-scroll.js';
 export * from './types';
 export * from './components';
 export * from './menu-core';

package/dist/index.js

@@ -21,8 +21,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getCurrentLanguageMap = exports.getAvailableLanguages = exports.registerLanguage = exports.t = exports.setLanguage = exports.getCurrentLanguage = exports.showCommandHelp = exports.getAvailableCommands = exports.handleCommand = exports.parseCommand = exports.isCommand = exports.clearCustomCommands = exports.unregisterCommand = exports.registerCommand = exports.createWizard = exports.runWizard = exports.renderHeader = exports.createSimpleSummary = exports.createSummaryTable = exports.renderSummaryTable = exports.createMessage = exports.showQuestion = exports.showInfo = exports.showWarning = exports.showError = exports.showSuccess = exports.renderMessage = exports.createStageSeparator = exports.createStageHeader = exports.createProgressIndicator = exports.renderStageSeparator = exports.renderStageHeader = exports.renderProgressIndicator = exports.createAsciiHeader = exports.createSectionHeader = exports.createSimpleHeader = exports.renderAsciiHeader = exports.renderSectionHeader = exports.renderSimpleHeader = exports.showModifyField = exports.showLanguageSelector = exports.showNumberInput = exports.showTextInput = exports.showBooleanMenu = exports.showCheckboxMenu = exports.showRadioMenu = exports.default = exports.wizard = exports.input = exports.menu = void 0;
-exports.LAYOUT_PRESETS = exports.KEY_CODES = exports.colorize = exports.applyGradient = exports.createGradient = exports.resetUIColors = exports.setUIColors = exports.getUIColors = exports.defaultUIColors = exports.uiColors = exports.colors = void 0;
+exports.HintTypes = exports.generateInputHints = exports.generateMenuHints = exports.createHints = exports.renderHintsComponent = exports.renderHeader = exports.createSimpleSummary = exports.createSummaryTable = exports.renderSummaryTable = exports.createMessage = exports.showQuestion = exports.showInfo = exports.showWarning = exports.showError = exports.showSuccess = exports.renderMessage = exports.createStageSeparator = exports.createStageHeader = exports.createProgressIndicator = exports.renderStageSeparator = exports.renderStageHeader = exports.renderProgressIndicator = exports.createAsciiHeader = exports.createSectionHeader = exports.createSimpleHeader = exports.renderAsciiHeader = exports.renderSectionHeader = exports.renderSimpleHeader = exports.showModifyField = exports.showLanguageSelector = exports.showNumberInput = exports.showTextInput = exports.showBooleanMenu = exports.showCheckboxTableMenu = exports.showCheckboxMenu = exports.showRadioMenu = exports.createInputPromptComponent = exports.createRadioMenuComponent = exports.createSummaryTableComponent = exports.createListComponent = exports.createTableComponent = exports.createHintsComponent = exports.createSectionHeaderComponent = exports.createSimpleHeaderComponent = exports.createFullHeaderComponent = exports.renderPage = exports.default = exports.wizard = exports.input = exports.menu = void 0;
+exports.calculateVirtualScroll = exports.KEY_CODES = exports.colorize = exports.applyGradient = exports.createGradient = exports.resetUIColors = exports.setUIColors = exports.getUIColors = exports.defaultUIColors = exports.uiColors = exports.colors = exports.getCurrentLanguageMap = exports.getAvailableLanguages = exports.registerLanguage = exports.t = exports.setLanguage = exports.getCurrentLanguage = exports.showCommandHelp = exports.getAvailableCommands = exports.handleCommand = exports.parseCommand = exports.isCommand = exports.clearCustomCommands = exports.unregisterCommand = exports.registerCommand = exports.createWizard = exports.runWizard = exports.createNumberedList = exports.createBulletList = exports.createList = exports.renderList = exports.createTable = exports.renderTable = void 0;
 // Export unified API
 var api_js_1 = require("./api.js");
 Object.defineProperty(exports, "menu", { enumerable: true, get: function () { return api_js_1.menuAPI; } });
@@ -30,10 +30,25 @@ Object.defineProperty(exports, "input", { enumerable: true, get: function () { r
 Object.defineProperty(exports, "wizard", { enumerable: true, get: function () { return api_js_1.wizardAPI; } });
 var api_js_2 = require("./api.js");
 Object.defineProperty(exports, "default", { enumerable: true, get: function () { return __importDefault(api_js_2).default; } });
+// Export Page Layout (Simple Configuration API)
+var page_layout_js_1 = require("./page-layout.js");
+Object.defineProperty(exports, "renderPage", { enumerable: true, get: function () { return page_layout_js_1.renderPage; } });
+// Export Component Factories (Legacy - for backward compatibility)
+var component_factories_js_1 = require("./component-factories.js");
+Object.defineProperty(exports, "createFullHeaderComponent", { enumerable: true, get: function () { return component_factories_js_1.createFullHeaderComponent; } });
+Object.defineProperty(exports, "createSimpleHeaderComponent", { enumerable: true, get: function () { return component_factories_js_1.createSimpleHeaderComponent; } });
+Object.defineProperty(exports, "createSectionHeaderComponent", { enumerable: true, get: function () { return component_factories_js_1.createSectionHeaderComponent; } });
+Object.defineProperty(exports, "createHintsComponent", { enumerable: true, get: function () { return component_factories_js_1.createHintsComponent; } });
+Object.defineProperty(exports, "createTableComponent", { enumerable: true, get: function () { return component_factories_js_1.createTableComponent; } });
+Object.defineProperty(exports, "createListComponent", { enumerable: true, get: function () { return component_factories_js_1.createListComponent; } });
+Object.defineProperty(exports, "createSummaryTableComponent", { enumerable: true, get: function () { return component_factories_js_1.createSummaryTableComponent; } });
+Object.defineProperty(exports, "createRadioMenuComponent", { enumerable: true, get: function () { return component_factories_js_1.createRadioMenuComponent; } });
+Object.defineProperty(exports, "createInputPromptComponent", { enumerable: true, get: function () { return component_factories_js_1.createInputPromptComponent; } });
 // Export menu components
 var index_js_1 = require("./components/menus/index.js");
 Object.defineProperty(exports, "showRadioMenu", { enumerable: true, get: function () { return index_js_1.showRadioMenu; } });
 Object.defineProperty(exports, "showCheckboxMenu", { enumerable: true, get: function () { return index_js_1.showCheckboxMenu; } });
+Object.defineProperty(exports, "showCheckboxTableMenu", { enumerable: true, get: function () { return index_js_1.showCheckboxTableMenu; } });
 Object.defineProperty(exports, "showBooleanMenu", { enumerable: true, get: function () { return index_js_1.showBooleanMenu; } });
 // Export input components
 var index_js_2 = require("./components/inputs/index.js");
@@ -66,6 +81,17 @@ Object.defineProperty(exports, "renderSummaryTable", { enumerable: true, get: fu
 Object.defineProperty(exports, "createSummaryTable", { enumerable: true, get: function () { return index_js_3.createSummaryTable; } });
 Object.defineProperty(exports, "createSimpleSummary", { enumerable: true, get: function () { return index_js_3.createSimpleSummary; } });
 Object.defineProperty(exports, "renderHeader", { enumerable: true, get: function () { return index_js_3.renderHeader; } });
+Object.defineProperty(exports, "renderHintsComponent", { enumerable: true, get: function () { return index_js_3.renderHintsComponent; } });
+Object.defineProperty(exports, "createHints", { enumerable: true, get: function () { return index_js_3.createHints; } });
+Object.defineProperty(exports, "generateMenuHints", { enumerable: true, get: function () { return index_js_3.generateMenuHints; } });
+Object.defineProperty(exports, "generateInputHints", { enumerable: true, get: function () { return index_js_3.generateInputHints; } });
+Object.defineProperty(exports, "HintTypes", { enumerable: true, get: function () { return index_js_3.HintTypes; } });
+Object.defineProperty(exports, "renderTable", { enumerable: true, get: function () { return index_js_3.renderTable; } });
+Object.defineProperty(exports, "createTable", { enumerable: true, get: function () { return index_js_3.createTable; } });
+Object.defineProperty(exports, "renderList", { enumerable: true, get: function () { return index_js_3.renderList; } });
+Object.defineProperty(exports, "createList", { enumerable: true, get: function () { return index_js_3.createList; } });
+Object.defineProperty(exports, "createBulletList", { enumerable: true, get: function () { return index_js_3.createBulletList; } });
+Object.defineProperty(exports, "createNumberedList", { enumerable: true, get: function () { return index_js_3.createNumberedList; } });
 // Export features
 var wizard_js_1 = require("./features/wizard.js");
 Object.defineProperty(exports, "runWizard", { enumerable: true, get: function () { return wizard_js_1.runWizard; } });
@@ -101,8 +127,8 @@ Object.defineProperty(exports, "colorize", { enumerable: true, get: function ()
 // Export core utilities (for advanced users)
 var keyboard_js_1 = require("./core/keyboard.js");
 Object.defineProperty(exports, "KEY_CODES", { enumerable: true, get: function () { return keyboard_js_1.KEY_CODES; } });
-var layout_types_js_1 = require("./types/layout.types.js");
-Object.defineProperty(exports, "LAYOUT_PRESETS", { enumerable: true, get: function () { return layout_types_js_1.LAYOUT_PRESETS; } });
+var virtual_scroll_js_1 = require("./core/virtual-scroll.js");
+Object.defineProperty(exports, "calculateVirtualScroll", { enumerable: true, get: function () { return virtual_scroll_js_1.calculateVirtualScroll; } });
 // Legacy exports (for backward compatibility)
 __exportStar(require("./types"), exports);
 __exportStar(require("./components"), exports);

package/dist/layout.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Page Layout V2 - Component-Based Architecture with Fixed Regions
+ *
+ * Core Principles:
+ * 1. Complete component decoupling
+ * 2. Fixed-height regions (Header/Footer fixed, Main fills rest)
+ * 3. Components return string arrays (lines)
+ * 4. Diff-based rendering - only update changed regions
+ * 5. Two-phase execution: render (non-blocking) + interact (blocking)
+ */
+import { ScreenManager, Rect } from './core/screen-manager.js';
+import { HintManager } from './core/hint-manager.js';
+export declare const screenManager: ScreenManager;
+export declare const hintManager: HintManager;
+export { ScreenManager, HintManager, Rect };
+/**
+ * Component interface - components return lines instead of writing to stdout
+ */
+export interface Component {
+    /** Component type identifier */
+    type: string;
+    /** Region ID for this component */
+    regionId: string;
+    /** Render function - returns lines to display */
+    render: (rect: Rect) => string[] | Promise<string[]>;
+    /** Optional interact function - handles user input (blocking) */
+    interact?: () => void | Promise<void>;
+    /** Optional component-specific configuration */
+    config?: any;
+}
+/**
+ * Layout configuration with fixed heights
+ */
+export interface Layout {
+    header: Rect;
+    main: Rect;
+    footerHints: Rect;
+    footerPrompt: Rect;
+}
+/**
+ * Compute layout based on terminal size
+ */
+export declare function computeLayout(rows?: number, cols?: number): Layout;
+/**
+ * Area configuration
+ */
+export interface AreaConfig {
+    components: Component[];
+}
+/**
+ * Page layout configuration
+ */
+export interface PageLayoutConfigV2 {
+    header?: AreaConfig;
+    mainArea?: AreaConfig;
+    footer?: AreaConfig;
+}
+/**
+ * Render complete page with fixed-region architecture
+ *
+ * Phase 1: Render all components (non-blocking)
+ * Phase 2: Handle interactions (blocking)
+ */
+export declare function renderPageV2(config: PageLayoutConfigV2): Promise<void>;
+/**
+ * Helper to create a custom component
+ */
+export declare function createCustomComponent(type: string, regionId: string, render: (rect: Rect) => string[] | Promise<string[]>, interact?: () => void | Promise<void>): Component;

package/dist/layout.js

@@ -0,0 +1,134 @@
+"use strict";
+/**
+ * Page Layout V2 - Component-Based Architecture with Fixed Regions
+ *
+ * Core Principles:
+ * 1. Complete component decoupling
+ * 2. Fixed-height regions (Header/Footer fixed, Main fills rest)
+ * 3. Components return string arrays (lines)
+ * 4. Diff-based rendering - only update changed regions
+ * 5. Two-phase execution: render (non-blocking) + interact (blocking)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HintManager = exports.ScreenManager = exports.hintManager = exports.screenManager = void 0;
+exports.computeLayout = computeLayout;
+exports.renderPageV2 = renderPageV2;
+exports.createCustomComponent = createCustomComponent;
+const screen_manager_js_1 = require("./core/screen-manager.js");
+Object.defineProperty(exports, "ScreenManager", { enumerable: true, get: function () { return screen_manager_js_1.ScreenManager; } });
+const hint_manager_js_1 = require("./core/hint-manager.js");
+Object.defineProperty(exports, "HintManager", { enumerable: true, get: function () { return hint_manager_js_1.HintManager; } });
+// Global instances
+exports.screenManager = new screen_manager_js_1.ScreenManager();
+exports.hintManager = new hint_manager_js_1.HintManager();
+/**
+ * Compute layout based on terminal size
+ */
+function computeLayout(rows, cols) {
+    const termRows = rows || process.stdout.rows || 24;
+    const termCols = cols || process.stdout.columns || 80;
+    const headerHeight = 13; // Fixed header height (6 ASCII art + title + desc + separator)
+    const footerHintsHeight = 1; // Fixed hints height
+    const footerPromptHeight = 1; // Fixed prompt height
+    const mainHeight = Math.max(1, termRows - headerHeight - footerHintsHeight - footerPromptHeight);
+    return {
+        header: { top: 1, left: 1, width: termCols, height: headerHeight },
+        main: { top: 1 + headerHeight, left: 1, width: termCols, height: mainHeight },
+        footerHints: { top: 1 + headerHeight + mainHeight, left: 1, width: termCols, height: footerHintsHeight },
+        footerPrompt: { top: 1 + headerHeight + mainHeight + footerHintsHeight, left: 1, width: termCols, height: footerPromptHeight }
+    };
+}
+/**
+ * Render complete page with fixed-region architecture
+ *
+ * Phase 1: Render all components (non-blocking)
+ * Phase 2: Handle interactions (blocking)
+ */
+async function renderPageV2(config) {
+    // Enter alt screen
+    exports.screenManager.enter();
+    // Compute layout
+    const layout = computeLayout();
+    // Register regions
+    if (config.header?.components) {
+        for (const component of config.header.components) {
+            exports.screenManager.registerRegion(component.regionId, layout.header);
+        }
+    }
+    if (config.mainArea?.components) {
+        for (const component of config.mainArea.components) {
+            exports.screenManager.registerRegion(component.regionId, layout.main);
+        }
+    }
+    if (config.footer?.components) {
+        for (const component of config.footer.components) {
+            // Map components to their specific footer regions
+            if (component.type === 'hints') {
+                exports.screenManager.registerRegion(component.regionId, layout.footerHints);
+            }
+            else if (component.type === 'prompt') {
+                exports.screenManager.registerRegion(component.regionId, layout.footerPrompt);
+            }
+        }
+    }
+    // Phase 1: Initial render
+    const renderComponent = async (component, rect) => {
+        const lines = await component.render(rect);
+        exports.screenManager.renderRegion(component.regionId, lines);
+    };
+    if (config.header?.components) {
+        for (const component of config.header.components) {
+            await renderComponent(component, layout.header);
+        }
+    }
+    if (config.mainArea?.components) {
+        for (const component of config.mainArea.components) {
+            await renderComponent(component, layout.main);
+        }
+    }
+    if (config.footer?.components) {
+        for (const component of config.footer.components) {
+            const rect = component.type === 'hints' ? layout.footerHints : layout.footerPrompt;
+            await renderComponent(component, rect);
+        }
+    }
+    // Setup hint manager listener
+    exports.hintManager.on('change', (text) => {
+        const hintsComponent = config.footer?.components.find(c => c.type === 'hints');
+        if (hintsComponent) {
+            exports.screenManager.renderRegion(hintsComponent.regionId, [text]);
+        }
+    });
+    // Handle terminal resize
+    process.stdout.on('resize', () => {
+        const newLayout = computeLayout();
+        exports.screenManager.invalidateAll();
+        // Re-register and re-render all regions
+        // (Implementation can be enhanced to avoid code duplication)
+    });
+    // Phase 2: Handle interactions
+    const interactiveComponents = [];
+    if (config.header?.components) {
+        interactiveComponents.push(...config.header.components.filter(c => c.interact));
+    }
+    if (config.mainArea?.components) {
+        interactiveComponents.push(...config.mainArea.components.filter(c => c.interact));
+    }
+    if (config.footer?.components) {
+        interactiveComponents.push(...config.footer.components.filter(c => c.interact));
+    }
+    // Execute interact phase
+    for (const component of interactiveComponents) {
+        if (component.interact) {
+            await component.interact();
+        }
+    }
+    // Exit alt screen
+    exports.screenManager.exit();
+}
+/**
+ * Helper to create a custom component
+ */
+function createCustomComponent(type, regionId, render, interact) {
+    return { type, regionId, render, interact };
+}

package/dist/page-layout.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Page Layout System - Simple Configuration API
+ * Architecture: Header + Main Area + Footer
+ *
+ * This is the simple, configuration-based API that users want.
+ * Just pass config objects, no need to create components manually.
+ */
+/**
+ * Header configuration
+ */
+export interface HeaderConfig {
+    type: 'simple' | 'section' | 'full' | 'none';
+    text?: string;
+    width?: number;
+    asciiArt?: string[];
+    title?: string;
+    description?: string;
+    version?: string;
+    url?: string;
+    menuTitle?: string;
+}
+/**
+ * Main Area configuration
+ */
+export interface MainAreaConfig {
+    type: 'menu' | 'display' | 'interactive';
+    menu?: {
+        options: any[];
+        allowLetterKeys?: boolean;
+        allowNumberKeys?: boolean;
+        preserveOnSelect?: boolean;
+    };
+    render?: () => void | Promise<void>;
+}
+/**
+ * Footer configuration
+ */
+export interface FooterConfig {
+    menu?: {
+        options: any[];
+        allowLetterKeys?: boolean;
+        allowNumberKeys?: boolean;
+        preserveOnSelect?: boolean;
+    };
+    ask?: {
+        question: string;
+        defaultValue?: boolean;
+        horizontal?: boolean;
+    };
+    input?: {
+        prompt: string;
+        defaultValue?: string;
+        allowEmpty?: boolean;
+    };
+    hints?: string[];
+}
+/**
+ * Complete page layout configuration
+ */
+export interface PageLayoutConfig {
+    header?: HeaderConfig;
+    mainArea: MainAreaConfig;
+    footer?: FooterConfig;
+}
+/**
+ * Render complete page with simple configuration API
+ *
+ * @example
+ * ```typescript
+ * const result = await renderPage({
+ *   header: {
+ *     type: 'full',
+ *     asciiArt: ['...'],
+ *     title: 'My App',
+ *     description: 'Description',
+ *     version: '1.0.0'
+ *   },
+ *   mainArea: {
+ *     type: 'menu',
+ *     menu: {
+ *       options: ['Option 1', 'Option 2'],
+ *       allowLetterKeys: true,
+ *       allowNumberKeys: true
+ *     }
+ *   },
+ *   footer: {
+ *     hints: ['↑↓ Navigate', 'Enter Confirm']
+ *   }
+ * });
+ * ```
+ */
+export declare function renderPage(config: PageLayoutConfig): Promise<any>;