free-coding-models 0.3.19 → 0.3.22

package/src/command-palette.js

@@ -1,64 +1,200 @@
 /**
  * @file command-palette.js
  * @description Command palette registry and fuzzy search helpers for the main TUI.
+ *          Now supports hierarchical categories with expandable/collapsible groups.
  *
  * @functions
- *   → `buildCommandPaletteEntries` — builds the current command list with dynamic provider/tier context
+ *   → `buildCommandPaletteTree` — builds the hierarchical command tree with categories and subcategories
+ *   → `flattenCommandTree` — converts tree to flat list for filtering (respects expansion state)
  *   → `fuzzyMatchCommand` — scores a query against one string and returns match positions
  *   → `filterCommandPaletteEntries` — returns sorted command matches for a query
  *
- * @exports { COMMAND_CATEGORY_ORDER, buildCommandPaletteEntries, fuzzyMatchCommand, filterCommandPaletteEntries }
+ * @exports { buildCommandPaletteTree, flattenCommandTree, fuzzyMatchCommand, filterCommandPaletteEntries }
  *
  * @see src/key-handler.js
  * @see src/overlays.js
  */
 
-export const COMMAND_CATEGORY_ORDER = ['Filters', 'Sort', 'Pages', 'Actions']
-
-const COMMANDS = [
-  // 📖 Filters
-  { id: 'filter-tier-all', category: 'Filters', label: 'Filter tiers: all', shortcut: 'T', keywords: ['filter', 'tier', 'all'] },
-  { id: 'filter-tier-splus', category: 'Filters', label: 'Filter tiers: S+', shortcut: null, keywords: ['filter', 'tier', 's+'] },
-  { id: 'filter-tier-s', category: 'Filters', label: 'Filter tiers: S', shortcut: null, keywords: ['filter', 'tier', 's'] },
-  { id: 'filter-tier-aplus', category: 'Filters', label: 'Filter tiers: A+', shortcut: null, keywords: ['filter', 'tier', 'a+'] },
-  { id: 'filter-tier-a', category: 'Filters', label: 'Filter tiers: A', shortcut: null, keywords: ['filter', 'tier', 'a'] },
-  { id: 'filter-tier-aminus', category: 'Filters', label: 'Filter tiers: A-', shortcut: null, keywords: ['filter', 'tier', 'a-'] },
-  { id: 'filter-tier-bplus', category: 'Filters', label: 'Filter tiers: B+', shortcut: null, keywords: ['filter', 'tier', 'b+'] },
-  { id: 'filter-tier-b', category: 'Filters', label: 'Filter tiers: B', shortcut: null, keywords: ['filter', 'tier', 'b'] },
-  { id: 'filter-tier-c', category: 'Filters', label: 'Filter tiers: C', shortcut: null, keywords: ['filter', 'tier', 'c'] },
-  { id: 'filter-provider-cycle', category: 'Filters', label: 'Filter provider: cycle', shortcut: 'D', keywords: ['filter', 'provider', 'origin'] },
-  { id: 'filter-configured-toggle', category: 'Filters', label: 'Toggle configured-only models', shortcut: 'E', keywords: ['filter', 'configured', 'keys'] },
-
-  // 📖 Sorting
-  { id: 'sort-rank', category: 'Sort', label: 'Sort by rank', shortcut: 'R', keywords: ['sort', 'rank'] },
-  { id: 'sort-tier', category: 'Sort', label: 'Sort by tier', shortcut: null, keywords: ['sort', 'tier'] },
-  { id: 'sort-provider', category: 'Sort', label: 'Sort by provider', shortcut: 'O', keywords: ['sort', 'origin', 'provider'] },
-  { id: 'sort-model', category: 'Sort', label: 'Sort by model name', shortcut: 'M', keywords: ['sort', 'model', 'name'] },
-  { id: 'sort-latest-ping', category: 'Sort', label: 'Sort by latest ping', shortcut: 'L', keywords: ['sort', 'latest', 'ping'] },
-  { id: 'sort-avg-ping', category: 'Sort', label: 'Sort by average ping', shortcut: 'A', keywords: ['sort', 'avg', 'average', 'ping'] },
-  { id: 'sort-swe', category: 'Sort', label: 'Sort by SWE score', shortcut: 'S', keywords: ['sort', 'swe', 'score'] },
-  { id: 'sort-ctx', category: 'Sort', label: 'Sort by context window', shortcut: 'C', keywords: ['sort', 'context', 'ctx'] },
-  { id: 'sort-health', category: 'Sort', label: 'Sort by health', shortcut: 'H', keywords: ['sort', 'health', 'condition'] },
-  { id: 'sort-verdict', category: 'Sort', label: 'Sort by verdict', shortcut: 'V', keywords: ['sort', 'verdict'] },
-  { id: 'sort-stability', category: 'Sort', label: 'Sort by stability', shortcut: 'B', keywords: ['sort', 'stability'] },
-  { id: 'sort-uptime', category: 'Sort', label: 'Sort by uptime', shortcut: 'U', keywords: ['sort', 'uptime'] },
-
-  // 📖 Pages / overlays
-  { id: 'open-settings', category: 'Pages', label: 'Open settings', shortcut: 'P', keywords: ['settings', 'config', 'api key'] },
-  { id: 'open-help', category: 'Pages', label: 'Open help', shortcut: 'K', keywords: ['help', 'shortcuts', 'hotkeys'] },
-  { id: 'open-changelog', category: 'Pages', label: 'Open changelog', shortcut: 'N', keywords: ['changelog', 'release'] },
-  { id: 'open-feedback', category: 'Pages', label: 'Open feedback', shortcut: 'I', keywords: ['feedback', 'bug', 'request'] },
-  { id: 'open-recommend', category: 'Pages', label: 'Open smart recommend', shortcut: 'Q', keywords: ['recommend', 'best model'] },
-  { id: 'open-install-endpoints', category: 'Pages', label: 'Open install endpoints', shortcut: 'Y', keywords: ['install', 'endpoints', 'providers'] },
-
-  // 📖 Actions
-  { id: 'action-cycle-theme', category: 'Actions', label: 'Cycle theme', shortcut: 'G', keywords: ['theme', 'dark', 'light', 'auto'] },
-  { id: 'action-cycle-tool-mode', category: 'Actions', label: 'Cycle tool mode', shortcut: 'Z', keywords: ['tool', 'mode', 'launcher'] },
-  { id: 'action-cycle-ping-mode', category: 'Actions', label: 'Cycle ping mode', shortcut: 'W', keywords: ['ping', 'cadence', 'speed', 'slow'] },
-  { id: 'action-toggle-favorite', category: 'Actions', label: 'Toggle favorite on selected model', shortcut: 'F', keywords: ['favorite', 'star'] },
-  { id: 'action-reset-view', category: 'Actions', label: 'Reset view settings', shortcut: 'Shift+R', keywords: ['reset', 'view', 'sort', 'filters'] },
+// 📖 Base command tree template (will be enhanced with dynamic model list)
+const BASE_COMMAND_TREE = [
+  {
+    id: 'filters',
+    label: 'Filters',
+    icon: '🔍',
+    children: [
+      {
+        id: 'filter-tier',
+        label: 'Filter by tier',
+        icon: '📊',
+        children: [
+          { id: 'filter-tier-all', label: 'All tiers', tier: null, shortcut: 'T', description: 'Show all models', keywords: ['filter', 'tier', 'all'] },
+          { id: 'filter-tier-splus', label: 'S+ tier', tier: 'S+', description: 'Best coding models', keywords: ['filter', 'tier', 's+'] },
+          { id: 'filter-tier-s', label: 'S tier', tier: 'S', description: 'Excellent models', keywords: ['filter', 'tier', 's'] },
+          { id: 'filter-tier-aplus', label: 'A+ tier', tier: 'A+', description: 'Very good models', keywords: ['filter', 'tier', 'a+'] },
+          { id: 'filter-tier-a', label: 'A tier', tier: 'A', description: 'Good models', keywords: ['filter', 'tier', 'a'] },
+          { id: 'filter-tier-aminus', label: 'A- tier', tier: 'A-', description: 'Solid models', keywords: ['filter', 'tier', 'a-'] },
+          { id: 'filter-tier-bplus', label: 'B+ tier', tier: 'B+', description: 'Fair models', keywords: ['filter', 'tier', 'b+'] },
+          { id: 'filter-tier-b', label: 'B tier', tier: 'B', description: 'Basic models', keywords: ['filter', 'tier', 'b'] },
+          { id: 'filter-tier-c', label: 'C tier', tier: 'C', description: 'Limited models', keywords: ['filter', 'tier', 'c'] },
+        ]
+      },
+      {
+        id: 'filter-provider',
+        label: 'Filter by provider',
+        icon: '🏢',
+        children: [
+          { id: 'filter-provider-cycle', label: 'Cycle provider', shortcut: 'D', description: 'Switch between providers', keywords: ['filter', 'provider', 'origin'] },
+          { id: 'filter-provider-all', label: 'All providers', providerKey: null, description: 'Show all providers', keywords: ['filter', 'provider', 'all'] },
+          { id: 'filter-provider-nvidia', label: 'NVIDIA NIM', providerKey: 'nvidiaNim', description: 'NVIDIA models', keywords: ['filter', 'provider', 'nvidia', 'nim'] },
+          { id: 'filter-provider-groq', label: 'Groq', providerKey: 'groq', description: 'Groq models', keywords: ['filter', 'provider', 'groq'] },
+          { id: 'filter-provider-cerebras', label: 'Cerebras', providerKey: 'cerebras', description: 'Cerebras models', keywords: ['filter', 'provider', 'cerebras'] },
+          { id: 'filter-provider-sambanova', label: 'SambaNova', providerKey: 'sambanova', description: 'SambaNova models', keywords: ['filter', 'provider', 'sambanova'] },
+          { id: 'filter-provider-openrouter', label: 'OpenRouter', providerKey: 'openrouter', description: 'OpenRouter models', keywords: ['filter', 'provider', 'openrouter'] },
+          { id: 'filter-provider-together', label: 'Together AI', providerKey: 'together', description: 'Together models', keywords: ['filter', 'provider', 'together'] },
+          { id: 'filter-provider-deepinfra', label: 'DeepInfra', providerKey: 'deepinfra', description: 'DeepInfra models', keywords: ['filter', 'provider', 'deepinfra'] },
+          { id: 'filter-provider-fireworks', label: 'Fireworks AI', providerKey: 'fireworks', description: 'Fireworks models', keywords: ['filter', 'provider', 'fireworks'] },
+          { id: 'filter-provider-hyperbolic', label: 'Hyperbolic', providerKey: 'hyperbolic', description: 'Hyperbolic models', keywords: ['filter', 'provider', 'hyperbolic'] },
+          { id: 'filter-provider-google', label: 'Google AI', providerKey: 'google', description: 'Google models', keywords: ['filter', 'provider', 'google'] },
+          { id: 'filter-provider-huggingface', label: 'Hugging Face', providerKey: 'huggingface', description: 'Hugging Face models', keywords: ['filter', 'provider', 'huggingface'] },
+        ]
+      },
+      {
+        id: 'filter-model',
+        label: 'Filter by model',
+        icon: '🤖',
+        children: []
+      },
+      {
+        id: 'filter-other',
+        label: 'Other filters',
+        icon: '⚙️',
+        children: [
+          { id: 'filter-configured-toggle', label: 'Toggle configured-only', shortcut: 'E', description: 'Show only configured providers', keywords: ['filter', 'configured', 'keys'] },
+        ]
+      },
+    ]
+  },
+  {
+    id: 'sort',
+    label: 'Sort',
+    icon: '📶',
+    children: [
+      { id: 'sort-rank', label: 'Sort by rank', shortcut: 'R', description: 'Rank by SWE score', keywords: ['sort', 'rank'] },
+      { id: 'sort-tier', label: 'Sort by tier', description: 'Group by quality tier', keywords: ['sort', 'tier'] },
+      { id: 'sort-provider', label: 'Sort by provider', shortcut: 'O', description: 'Group by provider', keywords: ['sort', 'origin', 'provider'] },
+      { id: 'sort-model', label: 'Sort by model', shortcut: 'M', description: 'Alphabetical order', keywords: ['sort', 'model', 'name'] },
+      { id: 'sort-latest-ping', label: 'Sort by latest ping', shortcut: 'L', description: 'Recent response time', keywords: ['sort', 'latest', 'ping'] },
+      { id: 'sort-avg-ping', label: 'Sort by avg ping', shortcut: 'A', description: 'Average response time', keywords: ['sort', 'avg', 'average', 'ping'] },
+      { id: 'sort-swe', label: 'Sort by SWE score', shortcut: 'S', description: 'Coding ability score', keywords: ['sort', 'swe', 'score'] },
+      { id: 'sort-ctx', label: 'Sort by context', shortcut: 'C', description: 'Context window size', keywords: ['sort', 'context', 'ctx'] },
+      { id: 'sort-health', label: 'Sort by health', shortcut: 'H', description: 'Current model status', keywords: ['sort', 'health', 'condition'] },
+      { id: 'sort-verdict', label: 'Sort by verdict', shortcut: 'V', description: 'Overall assessment', keywords: ['sort', 'verdict'] },
+      { id: 'sort-stability', label: 'Sort by stability', shortcut: 'B', description: 'Reliability score', keywords: ['sort', 'stability'] },
+      { id: 'sort-uptime', label: 'Sort by uptime', shortcut: 'U', description: 'Success rate', keywords: ['sort', 'uptime'] },
+    ]
+  },
+  // 📖 Pages - directly at root level, not in submenu
+  { id: 'open-settings', label: 'Settings', shortcut: 'P', icon: '⚙️', type: 'page', description: 'API keys and preferences', keywords: ['settings', 'config', 'api key'] },
+  { id: 'open-help', label: 'Help', shortcut: 'K', icon: '❓', type: 'page', description: 'Show all shortcuts', keywords: ['help', 'shortcuts', 'hotkeys'] },
+  { id: 'open-changelog', label: 'Changelog', shortcut: 'N', icon: '📋', type: 'page', description: 'Version history', keywords: ['changelog', 'release'] },
+  { id: 'open-feedback', label: 'Feedback', shortcut: 'I', icon: '📝', type: 'page', description: 'Report bugs or requests', keywords: ['feedback', 'bug', 'request'] },
+  { id: 'open-recommend', label: 'Smart recommend', shortcut: 'Q', icon: '🎯', type: 'page', description: 'Find best model for task', keywords: ['recommend', 'best model'] },
+  { id: 'open-install-endpoints', label: 'Install endpoints', icon: '🔌', type: 'page', description: 'Install provider catalogs', keywords: ['install', 'endpoints', 'providers'] },
+  // 📖 Actions - directly at root level, not in submenu
+  { id: 'action-cycle-theme', label: 'Cycle theme', shortcut: 'G', icon: '🌗', type: 'action', description: 'Switch dark/light/auto', keywords: ['theme', 'dark', 'light', 'auto'] },
+  { id: 'action-cycle-tool-mode', label: 'Target Tool', shortcut: 'Z', icon: '🔄', type: 'action', description: 'Change target AI Coding CLI Tool.', keywords: ['tool', 'mode', 'launcher', 'target'] },
+  { id: 'action-cycle-ping-mode', label: 'Cycle ping mode', shortcut: 'W', icon: '⚡', type: 'action', description: 'Adjust ping speed', keywords: ['ping', 'cadence', 'speed', 'slow'] },
+  { id: 'action-toggle-favorite', label: 'Toggle favorite', shortcut: 'F', icon: '⭐', type: 'action', description: 'Pin to favorites', keywords: ['favorite', 'star'] },
+  { id: 'action-reset-view', label: 'Reset view', shortcut: 'Shift+R', icon: '🔄', type: 'action', description: 'Reset filters and sort', keywords: ['reset', 'view', 'sort', 'filters'] },
 ]
 
+/**
+ * 📖 Build the command palette tree with dynamic model filters.
+ * @param {Array} visibleModels - Optional list of visible models to create model filter entries
+ * @returns {Array} The command tree with model filters added
+ */
+export function buildCommandPaletteTree(visibleModels = []) {
+  // 📖 Clone the base tree
+  const tree = JSON.parse(JSON.stringify(BASE_COMMAND_TREE))
+  
+  // 📖 Find the filter-model category and add dynamic model entries
+  const filterModelCategory = tree.find(cat => cat.id === 'filters')
+    ?.children.find(sub => sub.id === 'filter-model')
+  
+  if (filterModelCategory && Array.isArray(visibleModels) && visibleModels.length > 0) {
+    // 📖 Add top 20 most-used or most relevant models
+    const topModels = visibleModels
+      .filter(m => !m.hidden && m.status !== 'noauth')
+      .slice(0, 20)
+    
+    for (const model of topModels) {
+      filterModelCategory.children.push({
+        id: `filter-model-${model.providerKey}-${model.modelId}`,
+        label: model.label,
+        modelId: model.modelId,
+        providerKey: model.providerKey,
+        keywords: ['filter', 'model', model.label.toLowerCase(), model.modelId.toLowerCase()],
+      })
+    }
+  }
+  
+  return tree
+}
+
+/**
+ * 📖 Flatten the command tree into a list, respecting which nodes are expanded.
+ * @param {Array} tree - The command tree
+ * @param {Set} expandedIds - Set of IDs that are expanded
+ * @returns {Array} Flat list with type markers ('category' | 'subcategory' | 'command' | 'page' | 'action')
+ */
+export function flattenCommandTree(tree, expandedIds = new Set()) {
+  const result = []
+  
+  function traverse(nodes, depth = 0) {
+    for (const node of nodes) {
+      // 📖 Check if this is a direct page/action (not in a submenu)
+      if (node.type === 'page' || node.type === 'action') {
+        result.push({
+          ...node,
+          type: node.type,
+          depth: 0,
+          hasChildren: false,
+          isExpanded: false,
+        })
+        continue
+      }
+      
+      const isExpanded = expandedIds.has(node.id)
+      const hasChildren = Array.isArray(node.children) && node.children.length > 0
+      
+      if (hasChildren) {
+        result.push({
+          ...node,
+          type: depth === 0 ? 'category' : 'subcategory',
+          depth,
+          hasChildren,
+          isExpanded,
+        })
+        
+        if (isExpanded) {
+          traverse(node.children, depth + 1)
+        }
+      } else {
+        result.push({
+          ...node,
+          type: 'command',
+          depth,
+          hasChildren: false,
+          isExpanded: false,
+        })
+      }
+    }
+  }
+  
+  traverse(tree)
+  return result
+}
+
 const ID_TO_TIER = {
   'filter-tier-all': null,
   'filter-tier-splus': 'S+',
@@ -71,11 +207,31 @@ const ID_TO_TIER = {
   'filter-tier-c': 'C',
 }
 
-export function buildCommandPaletteEntries() {
-  return COMMANDS.map((entry) => ({
-    ...entry,
-    tierValue: Object.prototype.hasOwnProperty.call(ID_TO_TIER, entry.id) ? ID_TO_TIER[entry.id] : undefined,
-  }))
+/**
+ * 📖 Legacy function for backward compatibility - builds flat list from tree.
+ * 📖 Expands all categories so every command is searchable by fuzzyMatchCommand.
+ * @param {Array} visibleModels - Optional list of visible models for model filter entries
+ */
+export function buildCommandPaletteEntries(visibleModels = []) {
+  const tree = buildCommandPaletteTree(visibleModels)
+  // 📖 Collect every node id that has children so flattenCommandTree traverses into them.
+  const allIds = new Set()
+  function collectIds(nodes) {
+    for (const n of nodes) {
+      allIds.add(n.id)
+      if (Array.isArray(n.children)) collectIds(n.children)
+    }
+  }
+  collectIds(tree)
+  const flat = flattenCommandTree(tree, allIds)
+  return flat.map((entry) => {
+    // 📖 Copy tier and providerKey properties to tierValue for backward compatibility
+    const result = { ...entry }
+    if (entry.tier !== undefined) {
+      result.tierValue = entry.tier
+    }
+    return result
+  })
 }
 
 /**
@@ -126,15 +282,20 @@ export function fuzzyMatchCommand(query, text) {
 
 /**
  * 📖 Filter and rank command palette entries by fuzzy score.
- * @param {Array<{ id: string, label: string, category: string, keywords?: string[] }>} entries
+ * Now handles hierarchical structure with expandable categories.
+ * @param {Array} flatEntries - Flattened command tree entries
  * @param {string} query
- * @returns {Array<{ id: string, label: string, category: string, shortcut?: string|null, keywords?: string[], score: number, matchPositions: number[] }>}
+ * @returns {Array} Sorted and filtered entries with match scores
  */
-export function filterCommandPaletteEntries(entries, query) {
+export function filterCommandPaletteEntries(flatEntries, query) {
   const normalizedQuery = (query || '').trim()
+  
+  if (!normalizedQuery) {
+    return flatEntries
+  }
 
   const ranked = []
-  for (const entry of entries) {
+  for (const entry of flatEntries) {
     const labelMatch = fuzzyMatchCommand(normalizedQuery, entry.label)
     let bestScore = labelMatch.score
     let matchPositions = labelMatch.positions
@@ -145,7 +306,6 @@ export function filterCommandPaletteEntries(entries, query) {
         const keywordMatch = fuzzyMatchCommand(normalizedQuery, keyword)
         if (!keywordMatch.matched) continue
         matched = true
-        // 📖 Keyword matches should rank below direct label matches.
         const keywordScore = Math.max(1, keywordMatch.score - 7)
         if (keywordScore > bestScore) {
           bestScore = keywordScore
@@ -158,11 +318,24 @@ export function filterCommandPaletteEntries(entries, query) {
     ranked.push({ ...entry, score: bestScore, matchPositions })
   }
 
+  // Auto-expand categories that contain matches
+  const result = []
+  const idsToExpand = new Set()
+  
+  // First pass: mark all categories containing matched items
+  for (const entry of ranked) {
+    if (entry.type === 'command' && entry.matchPositions) {
+      // Find parent categories
+      let current = result.find(r => r.id === entry.id)
+      if (current) {
+        idsToExpand.add(entry.parentId)
+      }
+    }
+  }
+
   ranked.sort((a, b) => {
     if (b.score !== a.score) return b.score - a.score
-    const aCat = COMMAND_CATEGORY_ORDER.indexOf(a.category)
-    const bCat = COMMAND_CATEGORY_ORDER.indexOf(b.category)
-    if (aCat !== bCat) return aCat - bCat
+    if (a.depth !== b.depth) return a.depth - b.depth
     return a.label.localeCompare(b.label)
   })
 

package/src/config.js

@@ -209,7 +209,6 @@ function normalizeSettingsSection(settings) {
   return {
     ...safeSettings,
     hideUnconfiguredModels: typeof safeSettings.hideUnconfiguredModels === 'boolean' ? safeSettings.hideUnconfiguredModels : true,
-    disableWidthsWarning: safeSettings.disableWidthsWarning === true,
     theme: ['dark', 'light', 'auto'].includes(safeSettings.theme) ? safeSettings.theme : 'auto',
   }
 }
@@ -230,7 +229,6 @@ function normalizeProfileSettings(settings) {
   return {
     ..._emptyProfileSettings(),
     ...safeSettings,
-    disableWidthsWarning: safeSettings.disableWidthsWarning === true,
     theme: ['dark', 'light', 'auto'].includes(safeSettings.theme) ? safeSettings.theme : 'auto',
   }
 }
@@ -843,7 +841,6 @@ export function _emptyProfileSettings() {
     pingInterval: 10000,  // 📖 default ms between pings in the steady "normal" mode
     hideUnconfiguredModels: true, // 📖 true = default to providers that are actually configured
     preferredToolMode: 'opencode', // 📖 remember the last Z-selected launcher across app restarts
-    disableWidthsWarning: false, // 📖 Disable widths warning (default off)
     theme: 'auto',        // 📖 'auto' follows the terminal/OS theme, override with 'dark' or 'light' if needed
   }
 }

package/src/constants.js

@@ -17,6 +17,7 @@
  *   - `CELL_W` is derived from `COL_MS` and used by `msCell` / `spinCell`.
  *   - `TABLE_HEADER_LINES` + `TABLE_FOOTER_LINES` = `TABLE_FIXED_LINES` must stay in sync
  *     with the actual number of lines rendered by `renderTable()` in bin/.
+ *   - `WIDTH_WARNING_MIN_COLS` controls when the narrow-terminal startup warning appears.
  *   - Overlay background colours (chalk.bgRgb) make each overlay panel visually distinct.
  *
  * @functions
@@ -30,6 +31,7 @@
  *   FRAMES, TIER_CYCLE,
  *   SETTINGS_OVERLAY_BG, HELP_OVERLAY_BG, RECOMMEND_OVERLAY_BG, LOG_OVERLAY_BG,
  *   OVERLAY_PANEL_WIDTH,
+ *   WIDTH_WARNING_MIN_COLS,
  *   TABLE_HEADER_LINES, TABLE_FOOTER_LINES, TABLE_FIXED_LINES,
  *   msCell, spinCell
  *
@@ -83,6 +85,9 @@ export const LOG_OVERLAY_BG       = chalk.bgRgb(0, 0, 0)  // 📖 Dark blue-gree
 // 📖 tint fills the panel consistently regardless of content length.
 export const OVERLAY_PANEL_WIDTH = 116
 
+// 📖 Narrow-terminal warning appears only below this width.
+export const WIDTH_WARNING_MIN_COLS = 80
+
 // 📖 Table row-budget constants — must stay in sync with renderTable()'s actual output.
 // 📖 If this drifts, model rows overflow and can push the title row out of view.
 export const TABLE_HEADER_LINES = 4  // 📖 title, spacer, column headers, separator