@pellux/goodvibes-tui 0.28.0 → 1.0.0

package/src/renderer/fullscreen-primitives.ts

@@ -1,24 +1,30 @@
 import type { Line } from '../types/grid.ts';
 import { createEmptyLine, createStyledCell } from '../types/grid.ts';
 import { getDisplayWidth } from '../utils/terminal-width.ts';
-import { GLYPHS, UI_TONES } from './ui-primitives.ts';
+import { GLYPHS } from './ui-primitives.ts';
+import { resolveUiTones } from './theme.ts';
+
+// FULLSCREEN_PALETTE is built from the mode-resolved chrome tones
+// (resolveUiTones) rather than the static UI_TONES constant — WO-001 single
+// read path. Mode is fixed to 'dark' until the terminal-bg-probe lands.
+const TONES = resolveUiTones('dark');
 
 export const FULLSCREEN_PALETTE = {
-  border: '#64748b',
-  title: '#67e8f9',
-  subtitle: '#93c5fd',
-  text: '#e2e8f0',
-  muted: '#94a3b8',
-  dim: '#64748b',
-  selectedBg: '#223049',
-  categoryBg: '#141b25',
-  contextBg: '#121923',
-  controlsBg: '#0f141d',
-  footerBg: '#111827',
-  good: UI_TONES.state.good,
-  warn: UI_TONES.state.warn,
-  bad: UI_TONES.state.bad,
-  info: UI_TONES.state.info,
+  border: TONES.border,
+  title: TONES.accent.browser,
+  subtitle: TONES.accent.conversation,
+  text: TONES.fg.primary,
+  muted: TONES.fg.muted,
+  dim: TONES.border,
+  selectedBg: TONES.bg.selected,
+  categoryBg: TONES.bg.section,
+  contextBg: TONES.bg.surface,
+  controlsBg: TONES.bg.base,
+  footerBg: TONES.bg.footer,
+  good: TONES.state.good,
+  warn: TONES.state.warn,
+  bad: TONES.state.bad,
+  info: TONES.state.info,
 } as const;
 
 export type FullscreenTextStyle = Partial<Omit<Line[number], 'char'>>;
@@ -101,7 +107,7 @@ export function drawHorizontalRule(line: Line, startX: number, endX: number, fg:
   }
 }
 
-export function clipDisplay(text: string, width: number): string {
+function clipDisplay(text: string, width: number): string {
   if (width <= 0) return '';
   let used = 0;
   let output = '';

package/src/renderer/fullscreen-workspace.ts

@@ -13,14 +13,9 @@ import {
 } from './fullscreen-primitives.ts';
 
 export {
-  borderLine,
   clamp,
-  contentLine,
-  fillRange,
-  makeLine,
   padDisplay,
   stableWindow,
-  writeText,
 } from './fullscreen-primitives.ts';
 export { FULLSCREEN_PALETTE as WORKSPACE_PALETTE } from './fullscreen-primitives.ts';
 
@@ -63,12 +58,12 @@ export interface FullscreenWorkspaceMetrics {
   readonly controlRows: number;
 }
 
-export function drawVertical(line: Line, x: number, bg = ''): void {
+function drawVertical(line: Line, x: number, bg = ''): void {
   if (x <= 0 || x >= line.length - 1) return;
   drawVerticalRule(line, x, WORKSPACE_PALETTE.border, bg);
 }
 
-export function drawHorizontalRange(line: Line, startX: number, endX: number, bg = ''): void {
+function drawHorizontalRange(line: Line, startX: number, endX: number, bg = ''): void {
   drawHorizontalRule(line, Math.max(1, startX), Math.min(line.length - 2, endX), WORKSPACE_PALETTE.border, bg);
 }
 

package/src/renderer/help-overlay.ts

@@ -10,6 +10,7 @@ import type { SlashCommand } from '../input/command-registry.ts';
 import type { KeybindingsManager } from '../input/keybindings.ts';
 import { getOverlaySurfaceMetrics } from './overlay-viewport.ts';
 import { getVisibleWindow } from './surface-layout.ts';
+import { formatHints } from './hint-grammar.ts';
 import { logger } from '@pellux/goodvibes-sdk/platform/utils';
 
 function toModalSections(rows: readonly string[]): import('./modal-factory.ts').ModalSection[] {
@@ -40,7 +41,28 @@ export function renderHelpOverlay(
 ): Line[] {
   const kb = (action: Parameters<typeof keybindingsManager.getComboLabel>[0]) => keybindingsManager.getComboLabel(action);
 
-  const hasCommand = (name: string): boolean => Boolean(commands?.some((command) => command.name === name || (command.aliases ?? []).includes(name)));
+  const hasCommand = (name: string): boolean => {
+    if (!commands) return false;
+    for (const command of commands) {
+      // A broken plugin may expose a throwing `aliases` getter; skip it rather
+      // than crash the overlay (mirrors the Quick Start traversal guard below).
+      try {
+        if (command.name === name || (command.aliases ?? []).includes(name)) return true;
+      } catch { /* skip this command */ }
+    }
+    return false;
+  };
+
+  const shortcutLine = (label: string, desc: string): string => `  ${label.padEnd(20)}  ${desc}`;
+
+  // Enumerate EVERY workspace/panel binding straight from the live keybindings
+  // table so each rebindable action (including user overrides) is discoverable
+  // here and stays in lockstep with /keybindings. Any action id prefixed
+  // `panel-` is a workspace affordance.
+  const panelBindingRows: string[] = keybindingsManager
+    .getAll()
+    .filter((entry) => entry.action.startsWith('panel-'))
+    .map((entry) => shortcutLine(keybindingsManager.getComboLabel(entry.action), entry.description));
 
   // Keyboard shortcut sections
   const shortcutRows: string[] = [
@@ -59,9 +81,20 @@ export function renderHelpOverlay(
     '',
     '  Overlays And Panels',
     '  ' + '\u2500'.repeat(40),
-    `  ${'?'.padEnd(20)}  Toggle help`,
-    `  ${'/shortcuts'.padEnd(20)}  Full keyboard shortcuts`,
-    `  ${kb('panel-picker').padEnd(20)}  Open or focus the panel workspace`,
+    shortcutLine('?', 'Toggle help'),
+    shortcutLine('/shortcuts', 'Full keyboard shortcuts'),
+    shortcutLine('Tab', 'Swap focus between input and workspace'),
+    ...panelBindingRows,
+    '',
+    // The shared in-panel contract every workspace panel honors. These are not
+    // rebindable global actions \u2014 they are the common controls a focused panel
+    // interprets \u2014 so they are documented here rather than pulled from getAll().
+    '  In-Panel Controls',
+    '  ' + '\u2500'.repeat(40),
+    shortcutLine('j / k', 'Move selection down / up'),
+    shortcutLine('g / G', 'Jump to top / bottom'),
+    shortcutLine('Enter / Esc', 'Activate / dismiss or leave panel'),
+    shortcutLine('/', 'Filter the list'),
     '',
   ];
 
@@ -109,7 +142,33 @@ export function renderHelpOverlay(
     }
   }
 
+  // Essentials \u2014 the handful of commands worth memorizing, listed first and
+  // filtered to what the live registry actually exposes.
+  const ESSENTIAL_COMMANDS: Array<[name: string, desc: string]> = [
+    ['model',       'Select provider or model'],
+    ['sessions',    'Browse and resume saved sessions'],
+    ['save',        'Save the current session'],
+    ['compact',     'Compact the conversation history'],
+    ['clear',       'Clear the conversation'],
+    ['keybindings', 'List and customize key bindings'],
+    ['panel',       'Open, focus, or manage panels'],
+  ];
+
   const commandRows: string[] = [];
+  // Track command names already surfaced in a curated group so the exhaustive
+  // list below does not repeat them.
+  const seen = new Set<string>();
+
+  const essentialRows: string[] = [];
+  for (const [name, desc] of ESSENTIAL_COMMANDS) {
+    if (!hasCommand(name)) continue;
+    seen.add(name);
+    essentialRows.push(`  ${`/${name}`.padEnd(18)}  ${desc}`);
+  }
+  if (essentialRows.length > 0) {
+    commandRows.push('  Essentials', '  ' + '\u2500'.repeat(40), ...essentialRows, '');
+  }
+
   if (quickStartRows.length > 0) {
     commandRows.push('  Quick Start', '  ' + '\u2500'.repeat(40), ...quickStartRows, '');
   }
@@ -117,18 +176,18 @@ export function renderHelpOverlay(
   if (commands && commands.length > 0) {
     commandRows.push('', '  Available Slash Commands', '  ' + '\u2500'.repeat(40));
     const preferred = ['setup', 'cockpit', 'settings', 'provider', 'subscription', 'marketplace', 'remote', 'sandbox', 'security', 'policy', 'incident', 'knowledge', 'hooks', 'orchestration', 'communication', 'tasks'];
-    const seen = new Set<string>();
     for (const name of preferred) {
       const cmd = commands.find((entry) => entry.name === name);
-      if (!cmd) continue;
+      if (!cmd || seen.has(cmd.name)) continue;
       seen.add(cmd.name);
       const nameCol = `/${cmd.name}`.padEnd(18);
       commandRows.push(`  ${nameCol}  ${cmd.description}`);
     }
+    // No command cap: the overlay windows and scrolls (getVisibleWindow below),
+    // so the full remaining registry is listed rather than truncated at 24.
     const remainder = [...commands]
       .filter((cmd) => !seen.has(cmd.name))
-      .sort((a, b) => a.name.localeCompare(b.name))
-      .slice(0, 24);
+      .sort((a, b) => a.name.localeCompare(b.name));
     if (remainder.length > 0) {
       commandRows.push('', '  More Commands', '  ' + '\u2500'.repeat(40));
       for (const cmd of remainder) {
@@ -163,15 +222,19 @@ export function renderHelpOverlay(
       width: metrics.boxWidth,
       margin: metrics.margin,
       targetContentRows: metrics.contentRows,
-      tabs: [
-        { label: 'Overview', active: true },
-        { label: 'Commands' },
-      ],
+      // Single tab: the old second 'Commands' tab had no switch handler (Left/
+      // Right did nothing), so it was a dead affordance. The overlay is one
+      // scrolling surface, so it advertises exactly one tab.
+      tabs: [{ label: 'Overview', active: true }],
       sections: toModalSections(visibleRows),
       helpers: allRows.length > maxVisible
         ? [{ content: `[${window.start + 1}-${Math.min(allRows.length, clampedOffset + visibleRows.length)} of ${allRows.length}]` }]
         : undefined,
-      hints: ['? or Esc Close', 'Up/Down Scroll'],
+      hints: [formatHints([
+        { key: 'Up/Down', verb: 'Scroll' },
+        { key: '?', verb: 'Help' },
+        { key: 'Esc', verb: 'Close' },
+      ])],
     },
     width,
   );
@@ -236,6 +299,17 @@ export function renderShortcutsOverlay(
     row(kb('panel-picker'), 'Open / focus / hide panel workspace'),
     row(kb('panel-tab-next'), 'Next workspace panel tab'),
     row(kb('panel-tab-prev'), 'Previous workspace panel tab'),
+    row(`${kb('panel-tab-1')}\u2026${kb('panel-tab-9')}`, 'Jump to workspace tab 1-9'),
+    row(kb('panel-focus-toggle'), 'Swap focus between top / bottom pane'),
+    row(kb('panel-close'), 'Close active panel'),
+    row(kb('panel-close-all'), 'Close all panels'),
+    row(kb('panel-ops'), 'Open the Ops Control panel'),
+    '',
+    '  In-Panel Controls',
+    '  ' + '\u2500'.repeat(40),
+    row('j / k', 'Move selection down / up'),
+    row('g / G', 'Jump to top / bottom'),
+    row('/', 'Filter the list'),
     '',
     `  Config: /keybindings to list and customize`,
   ];
@@ -261,7 +335,10 @@ export function renderShortcutsOverlay(
       helpers: allRows.length > maxVisible
         ? [{ content: `[${window.start + 1}-${Math.min(allRows.length, clampedOffset + visibleRows.length)} of ${allRows.length}]` }]
         : undefined,
-      hints: ['Esc Close', 'Up/Down Scroll'],
+      hints: [formatHints([
+        { key: 'Up/Down', verb: 'Scroll' },
+        { key: 'Esc', verb: 'Close' },
+      ])],
     },
     width,
   );

package/src/renderer/hint-grammar.ts

@@ -0,0 +1,52 @@
+/**
+ * hint-grammar.ts — the single hint-bar grammar for every overlay footer.
+ *
+ * WO-151: one grammar across the model picker, settings modal, help/shortcuts
+ * overlays, and ModalFactory variants so footers stop drifting into three
+ * different dialects (verbless brackets, prose sentences, ad-hoc separators).
+ *
+ * The grammar is:
+ *   - each hint renders as `[Key] Verb` (a bracketed key followed by its verb),
+ *   - hints are joined by a middle-dot separator (` · `),
+ *   - any Escape hint is always sorted last (the conventional "way out").
+ *
+ * State segments that are not key hints (e.g. `Filter: All`) can be appended
+ * verbatim via {@link joinHints}; they are never reordered.
+ */
+
+/** A single key hint. `verb` may be omitted for a bare key affordance. */
+export interface HintSpec {
+  key: string;
+  verb?: string;
+}
+
+/** The canonical separator between hint segments. */
+export const HINT_SEPARATOR = ' · ';
+
+function isEscapeHint(spec: HintSpec): boolean {
+  return spec.key.trim().toLowerCase() === 'esc';
+}
+
+/** Render one hint as `[Key] Verb` (or `[Key]` when it has no verb). */
+function formatHint(spec: HintSpec): string {
+  return spec.verb ? `[${spec.key}] ${spec.verb}` : `[${spec.key}]`;
+}
+
+/**
+ * Format a list of key hints into a single footer string using the shared
+ * grammar. Escape hints are moved to the end (stable for everything else).
+ */
+export function formatHints(specs: readonly HintSpec[]): string {
+  // Stable partition: non-escape hints keep their order, escape hints trail.
+  const ordered = [...specs].sort((a, b) => Number(isEscapeHint(a)) - Number(isEscapeHint(b)));
+  return ordered.map(formatHint).join(HINT_SEPARATOR);
+}
+
+/**
+ * Join already-rendered segments (hint bars, state tags) with the shared
+ * separator, dropping empties. Order is preserved — use this to append state
+ * indicators after a {@link formatHints} bar.
+ */
+export function joinHints(...segments: Array<string | null | undefined>): string {
+  return segments.filter((s): s is string => !!s && s.length > 0).join(HINT_SEPARATOR);
+}

package/src/renderer/history-search-overlay.ts

@@ -1,27 +1,15 @@
 import type { Line } from '../types/grid.ts';
-import { getDisplayWidth } from '../utils/terminal-width.ts';
+import { fitDisplay, getDisplayWidth } from '../utils/terminal-width.ts';
 import type { HistorySearch } from '../input/input-history.ts';
 import { createBottomBarLine, writeBottomBarText } from './bottom-bar.ts';
+import { formatHints } from './hint-grammar.ts';
 
 /**
  * Truncate `text` to at most `maxWidth` display columns, then pad with spaces
  * to exactly `maxWidth` columns. CJK/emoji wide characters count as 2 columns.
  */
 function truncateToWidth(text: string, maxWidth: number): string {
-  let usedWidth = 0;
-  let result = '';
-  let i = 0;
-  while (i < text.length) {
-    const code = text.codePointAt(i)!;
-    const charLen = code > 0xFFFF ? 2 : 1;
-    const charWidth = getDisplayWidth(text.slice(i, i + charLen));
-    if (usedWidth + charWidth > maxWidth) break;
-    result += text.slice(i, i + charLen);
-    usedWidth += charWidth;
-    i += charLen;
-  }
-  // Pad to exactly maxWidth columns with spaces
-  return result + ' '.repeat(maxWidth - usedWidth);
+  return fitDisplay(text, maxWidth, '');
 }
 
 /**
@@ -49,7 +37,13 @@ export function renderHistorySearchOverlay(
 
   // Build the display string
   const label = prefix + queryPart;
-  const full = truncateToWidth(label + matchText, width);
+  const hints = formatHints([
+    { key: 'Ctrl+R/↑', verb: 'Older' },
+    { key: 'Ctrl+S/↓', verb: 'Newer' },
+    { key: 'Enter', verb: 'Accept' },
+    { key: 'Esc', verb: 'Cancel' },
+  ]);
+  const full = truncateToWidth(`${label}${matchText}  ${hints}`, width);
 
   const line = createBottomBarLine(width, { fg: '#000000', bg: '#00ffcc' });
   writeBottomBarText(line, 0, width, full, { fg: '#000000', bg: '#00ffcc' });

package/src/renderer/layout.ts

@@ -1,4 +1,4 @@
-import { GLYPHS } from './ui-primitives.ts';
+import { GLYPHS, SPINNER_FRAMES, UI_TONES } from './ui-primitives.ts';
 
 /**
  * Layout constants — single source of truth for margins and content width.
@@ -14,19 +14,19 @@ export const LAYOUT = {
 
 export const TOOL_STATUS = {
   SUCCESS_ICON: GLYPHS.status.success,
-  SPINNER_FRAMES: ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'],
+  SPINNER_FRAMES,
   FAIL_ICON: GLYPHS.status.failure,
   PENDING_ICON: GLYPHS.status.pending,
   TOOL_NAME_PAD: 8,
 } as const;
 
 export const COLORS = {
-  DIM_TEXT: '244',
+  DIM_TEXT: UI_TONES.fg.dim,
 } as const;
 
 export const BORDERS = {
-  THINKING: { char: '▌', color: '#9945FF' },
-  ERROR:    { char: '▌', color: '#ef4444' },
-  WARNING:  { char: '▌', color: '#eab308' },
-  INFO:     { char: '▌', color: '#22d3ee' },
+  THINKING: { char: '▌', color: UI_TONES.state.reasoning },
+  ERROR:    { char: '▌', color: UI_TONES.state.bad },
+  WARNING:  { char: '▌', color: UI_TONES.state.warn },
+  INFO:     { char: '▌', color: UI_TONES.state.info },
 } as const;

package/src/renderer/markdown.ts

@@ -310,7 +310,15 @@ function renderTable(rows: string[], width: number, indent: number): Line[] {
       for (const ch of text) {
         const cw = getDisplayWidth(ch);
         if (w + cw > maxW) {
-          // Truncate with ellipsis
+          // Truncate with ellipsis. If the last cell pushed is a wide-glyph
+          // placeholder (the empty second column of a 2-wide character),
+          // overwriting it in place would leave the wide glyph's first
+          // column dangling next to the ellipsis with no placeholder cell \u2014
+          // step back one more cell so the ellipsis replaces the actual
+          // glyph, not its placeholder.
+          if (cells.length > 0 && cells[cells.length - 1].char === '' && cells.length > 1) {
+            cells.pop();
+          }
           if (cells.length > 0) cells[cells.length - 1] = createStyledCell('\u2026', cells[cells.length - 1]);
           return cells;
         }

package/src/renderer/modal-factory.ts

@@ -8,7 +8,9 @@ import {
   putOverlayText,
 } from './overlay-box.ts';
 import { getOverlayMaxWidth } from './overlay-viewport.ts';
-import { GLYPHS, UI_TONES } from './ui-primitives.ts';
+import { GLYPHS } from './ui-primitives.ts';
+import { resolveUiTones } from './theme.ts';
+import { HINT_SEPARATOR } from './hint-grammar.ts';
 
 // ── Helpers ──────────────────────────────────────────────────────────────────
 
@@ -90,19 +92,24 @@ export interface ModalConfig {
 
 // ── Defaults ─────────────────────────────────────────────────────────────────
 
+// DEFAULT_STYLE is built from the mode-resolved chrome tones (resolveUiTones)
+// rather than the static UI_TONES constant — WO-001 single read path. Mode is
+// fixed to 'dark' until the terminal-bg-probe lands.
+const TONES = resolveUiTones('dark');
+
 const DEFAULT_STYLE: Required<ModalStyle> = {
-  titleFg: UI_TONES.fg.primary,
-  borderFg: UI_TONES.fg.dim,
-  hintFg: UI_TONES.fg.muted,
-  selectedFg: UI_TONES.fg.primary,
-  selectedBg: UI_TONES.bg.selected,
-  textFg: UI_TONES.fg.primary,
-  accentFg: UI_TONES.state.info,
-  titleRowFg: UI_TONES.fg.secondary,
-  titleBg: UI_TONES.bg.title,
-  sectionBg: UI_TONES.bg.section,
-  inputBg: UI_TONES.bg.input,
-  surfaceBg: UI_TONES.bg.surface,
+  titleFg: TONES.fg.primary,
+  borderFg: TONES.fg.dim,
+  hintFg: TONES.fg.muted,
+  selectedFg: TONES.fg.primary,
+  selectedBg: TONES.bg.selected,
+  textFg: TONES.fg.primary,
+  accentFg: TONES.state.info,
+  titleRowFg: TONES.fg.secondary,
+  titleBg: TONES.bg.title,
+  sectionBg: TONES.bg.section,
+  inputBg: TONES.bg.input,
+  surfaceBg: TONES.bg.surface,
 };
 
 // ── ModalFactory ─────────────────────────────────────────────────────────────
@@ -182,9 +189,10 @@ export class ModalFactory {
       }
     }
 
-    // Footer / hint bar
+    // Footer / hint bar. Hint segments join with the shared middle-dot grammar
+    // separator (WO-151) so every modal footer reads as one dialect.
     const hintStr = config.hints
-      ? config.hints.join('  ')
+      ? config.hints.join(HINT_SEPARATOR)
       : (config.footer ?? '');
     lines.push(ModalFactory.renderHints(boxW, margin, hintStr, terminalWidth, style));