@nathapp/nax 0.18.1

package/src/tui/components/CostOverlay.tsx

@@ -0,0 +1,118 @@
+/**
+ * CostOverlay — modal-style overlay showing cost breakdown per story.
+ *
+ * Shown when c is pressed, dismissed with Esc.
+ */
+
+import { Box, Text } from "ink";
+import type { StoryDisplayState } from "../types";
+
+/**
+ * Props for CostOverlay component.
+ */
+export interface CostOverlayProps {
+  /** Whether the overlay is visible */
+  visible?: boolean;
+  /** All stories with cost data */
+  stories?: StoryDisplayState[];
+  /** Total accumulated cost */
+  totalCost?: number;
+}
+
+/**
+ * Format cost as USD with 4 decimal places.
+ */
+function formatCost(cost: number): string {
+  return `$${cost.toFixed(4)}`;
+}
+
+/**
+ * CostOverlay component.
+ *
+ * Displays a modal-style overlay with cost breakdown per story.
+ * Shows story ID, status, and cost incurred.
+ *
+ * @example
+ * ```tsx
+ * const [showCost, setShowCost] = useState(false);
+ *
+ * <CostOverlay
+ *   visible={showCost}
+ *   stories={state.stories}
+ *   totalCost={state.totalCost}
+ * />
+ * ```
+ */
+export function CostOverlay({ visible = false, stories = [], totalCost = 0 }: CostOverlayProps) {
+  if (!visible) {
+    return null;
+  }
+
+  // Only show stories that have been executed (cost > 0 or status !== pending)
+  const executedStories = stories.filter((s) => (s.cost && s.cost > 0) || s.status !== "pending");
+
+  return (
+    <Box flexDirection="column" borderStyle="double" borderColor="cyan" paddingX={2} paddingY={1} minWidth={60}>
+      <Box paddingBottom={1}>
+        <Text bold color="cyan">
+          Cost Breakdown
+        </Text>
+      </Box>
+
+      {/* Header row */}
+      <Box paddingBottom={1} borderBottom borderColor="gray">
+        <Box width={12}>
+          <Text bold>Story ID</Text>
+        </Box>
+        <Box width={12}>
+          <Text bold>Status</Text>
+        </Box>
+        <Box width={12}>
+          <Text bold>Cost</Text>
+        </Box>
+      </Box>
+
+      {/* Story rows */}
+      <Box flexDirection="column" paddingY={1}>
+        {executedStories.length > 0 ? (
+          executedStories.map((story) => (
+            <Box key={story.story.id}>
+              <Box width={12}>
+                <Text>{story.story.id}</Text>
+              </Box>
+              <Box width={12}>
+                <Text color={story.status === "passed" ? "green" : story.status === "failed" ? "red" : undefined}>
+                  {story.status}
+                </Text>
+              </Box>
+              <Box width={12}>
+                <Text>{formatCost(story.cost || 0)}</Text>
+              </Box>
+            </Box>
+          ))
+        ) : (
+          <Text dimColor>No stories executed yet</Text>
+        )}
+      </Box>
+
+      {/* Total row */}
+      <Box paddingTop={1} borderTop borderColor="gray">
+        <Box width={24}>
+          <Text bold>Total Cost:</Text>
+        </Box>
+        <Box width={12}>
+          <Text bold color="cyan">
+            {formatCost(totalCost)}
+          </Text>
+        </Box>
+      </Box>
+
+      {/* Footer */}
+      <Box justifyContent="center" paddingTop={1} borderTop borderColor="gray">
+        <Text dimColor>
+          Press <Text color="yellow">Esc</Text> to close
+        </Text>
+      </Box>
+    </Box>
+  );
+}

package/src/tui/components/HelpOverlay.tsx

@@ -0,0 +1,107 @@
+/**
+ * HelpOverlay — modal-style overlay listing all keybindings.
+ *
+ * Shown when ? is pressed, dismissed with Esc.
+ */
+
+import { Box, Text } from "ink";
+
+/**
+ * Props for HelpOverlay component.
+ */
+export interface HelpOverlayProps {
+  /** Whether the overlay is visible */
+  visible?: boolean;
+}
+
+/**
+ * HelpOverlay component.
+ *
+ * Displays a modal-style overlay with keybinding reference.
+ * Centered on screen with a border.
+ *
+ * @example
+ * ```tsx
+ * const [showHelp, setShowHelp] = useState(false);
+ *
+ * <HelpOverlay visible={showHelp} />
+ *
+ * // Close with Esc or by toggling state
+ * ```
+ */
+export function HelpOverlay({ visible = false }: HelpOverlayProps) {
+  if (!visible) {
+    return null;
+  }
+
+  return (
+    <Box flexDirection="column" borderStyle="double" borderColor="cyan" paddingX={2} paddingY={1}>
+      <Box paddingBottom={1}>
+        <Text bold color="cyan">
+          Keyboard Shortcuts
+        </Text>
+      </Box>
+
+      {/* Stories panel shortcuts */}
+      <Box flexDirection="column" paddingBottom={1}>
+        <Text dimColor>Stories Panel (default):</Text>
+        <Text>
+          {" "}
+          <Text color="yellow">p</Text> — Pause after current story
+        </Text>
+        <Text>
+          {" "}
+          <Text color="yellow">a</Text> — Abort run
+        </Text>
+        <Text>
+          {" "}
+          <Text color="yellow">s</Text> — Skip current story
+        </Text>
+        <Text>
+          {" "}
+          <Text color="yellow">Tab</Text> — Toggle focus to Agent panel
+        </Text>
+        <Text>
+          {" "}
+          <Text color="yellow">q</Text> — Quit TUI
+        </Text>
+        <Text>
+          {" "}
+          <Text color="yellow">?</Text> — Show this help
+        </Text>
+        <Text>
+          {" "}
+          <Text color="yellow">c</Text> — Show cost breakdown
+        </Text>
+        <Text>
+          {" "}
+          <Text color="yellow">r</Text> — Retry last failed story
+        </Text>
+        <Text>
+          {" "}
+          <Text color="yellow">Esc</Text> — Close overlay
+        </Text>
+      </Box>
+
+      {/* Agent panel shortcuts */}
+      <Box flexDirection="column" paddingBottom={1}>
+        <Text dimColor>Agent Panel (when focused):</Text>
+        <Text>
+          {" "}
+          <Text color="yellow">Ctrl+]</Text> — Escape back to Stories panel
+        </Text>
+        <Text>
+          {" "}
+          <Text dimColor>All other keys</Text> — Forwarded to agent PTY
+        </Text>
+      </Box>
+
+      {/* Footer */}
+      <Box justifyContent="center" paddingTop={1} borderTop borderColor="gray">
+        <Text dimColor>
+          Press <Text color="yellow">Esc</Text> to close
+        </Text>
+      </Box>
+    </Box>
+  );
+}

package/src/tui/components/StatusBar.tsx

@@ -0,0 +1,63 @@
+/**
+ * StatusBar — displays current story and pipeline stage information.
+ */
+
+import { Box, Text } from "ink";
+import type { UserStory } from "../../prd/types";
+
+/**
+ * Props for StatusBar component.
+ */
+export interface StatusBarProps {
+  /** Current story being executed */
+  currentStory?: UserStory;
+  /** Current pipeline stage */
+  currentStage?: string;
+  /** Model tier for current story */
+  modelTier?: string;
+  /** Test strategy for current story */
+  testStrategy?: string;
+}
+
+/**
+ * StatusBar component.
+ *
+ * Displays a single line showing the current story ID, stage, model tier, and test strategy.
+ *
+ * @example
+ * ```tsx
+ * <StatusBar
+ *   currentStory={story}
+ *   currentStage="execution"
+ *   modelTier="balanced"
+ *   testStrategy="single-session"
+ * />
+ * ```
+ */
+export function StatusBar({ currentStory, currentStage, modelTier, testStrategy }: StatusBarProps) {
+  if (!currentStory) {
+    return (
+      <Box paddingX={1} borderStyle="single" borderColor="gray">
+        <Text dimColor>Idle</Text>
+      </Box>
+    );
+  }
+
+  const storyInfo = `Story ${currentStory.id}`;
+  const stageInfo = currentStage ? ` · ${currentStage}` : "";
+  const tierInfo = modelTier ? ` · ${modelTier}` : "";
+  const strategyInfo = testStrategy ? ` · ${testStrategy}` : "";
+
+  return (
+    <Box paddingX={1} borderStyle="single" borderColor="gray">
+      <Text>
+        <Text bold>{storyInfo}</Text>
+        <Text dimColor>
+          {stageInfo}
+          {tierInfo}
+          {strategyInfo}
+        </Text>
+      </Text>
+    </Box>
+  );
+}

package/src/tui/components/StoriesPanel.tsx

@@ -0,0 +1,177 @@
+/**
+ * StoriesPanel — displays story list with status icons, cost, and elapsed time.
+ *
+ * Supports scrolling for >15 stories and compact mode for single-column layout.
+ */
+
+import { Box, Text } from "ink";
+import { useEffect, useState } from "react";
+import { COMPACT_MAX_VISIBLE_STORIES, MAX_VISIBLE_STORIES } from "../hooks/useLayout";
+import type { StoryDisplayState } from "../types";
+
+/**
+ * Props for StoriesPanel component.
+ */
+export interface StoriesPanelProps {
+  /** Stories to display */
+  stories: StoryDisplayState[];
+  /** Total cost accumulated */
+  totalCost: number;
+  /** Elapsed time in milliseconds */
+  elapsedMs: number;
+  /** Panel width (columns) */
+  width?: number;
+  /** Compact mode (fewer details, for single-column layout) */
+  compact?: boolean;
+  /** Maximum height in rows (for single-column mode) */
+  maxHeight?: number;
+}
+
+/**
+ * Get status icon for a story.
+ */
+function getStatusIcon(status: StoryDisplayState["status"]): string {
+  switch (status) {
+    case "pending":
+      return "⬚";
+    case "running":
+      return "🔄";
+    case "passed":
+      return "✅";
+    case "failed":
+      return "❌";
+    case "skipped":
+      return "⏭️";
+    case "retrying":
+      return "🔁";
+    case "paused":
+      return "⏸️";
+  }
+}
+
+/**
+ * Format elapsed time as mm:ss.
+ */
+function formatElapsedTime(ms: number): string {
+  const totalSeconds = Math.floor(ms / 1000);
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  return `${minutes}m ${seconds}s`;
+}
+
+/**
+ * StoriesPanel component.
+ *
+ * Displays all stories with status icons, routing info, cost total, and elapsed time.
+ * Supports scrolling for >15 stories (or >8 in compact mode) and shows scroll indicators.
+ *
+ * @example
+ * ```tsx
+ * <StoriesPanel
+ *   stories={storyStates}
+ *   totalCost={0.42}
+ *   elapsedMs={263000}
+ *   width={30}
+ *   compact={false}
+ * />
+ * ```
+ */
+export function StoriesPanel({ stories, totalCost, elapsedMs, width, compact = false, maxHeight }: StoriesPanelProps) {
+  // Determine max visible stories based on mode
+  const maxVisible = compact ? COMPACT_MAX_VISIBLE_STORIES : MAX_VISIBLE_STORIES;
+  const needsScrolling = stories.length > maxVisible;
+
+  // Scroll position (0-indexed offset)
+  const [scrollOffset, setScrollOffset] = useState(0);
+
+  // Auto-scroll to keep the current running story in view
+  useEffect(() => {
+    const runningIndex = stories.findIndex((s) => s.status === "running");
+    if (runningIndex !== -1 && needsScrolling) {
+      // If running story is outside the visible window, scroll to it
+      if (runningIndex < scrollOffset) {
+        setScrollOffset(runningIndex);
+      } else if (runningIndex >= scrollOffset + maxVisible) {
+        setScrollOffset(runningIndex - maxVisible + 1);
+      }
+    }
+  }, [stories, scrollOffset, maxVisible, needsScrolling]);
+
+  // Get visible stories (either all or a scrolled window)
+  const visibleStories = needsScrolling ? stories.slice(scrollOffset, scrollOffset + maxVisible) : stories;
+
+  const canScrollUp = scrollOffset > 0;
+  const canScrollDown = scrollOffset + maxVisible < stories.length;
+
+  return (
+    <Box flexDirection="column" width={width} height={maxHeight} borderStyle="single" borderColor="gray">
+      {/* Header */}
+      <Box paddingX={1} borderStyle="single" borderBottom borderColor="gray">
+        <Text bold>Stories</Text>
+        {needsScrolling && <Text dimColor> ({stories.length} total)</Text>}
+      </Box>
+
+      {/* Scroll indicator (top) */}
+      {needsScrolling && canScrollUp && (
+        <Box paddingX={1}>
+          <Text dimColor>▲ {scrollOffset} more above</Text>
+        </Box>
+      )}
+
+      {/* Story list */}
+      <Box flexDirection="column" paddingX={1} paddingY={1} flexGrow={1}>
+        {visibleStories.map((s) => {
+          const icon = getStatusIcon(s.status);
+
+          if (compact) {
+            // Compact mode: just icon and ID
+            return (
+              <Box key={s.story.id}>
+                <Text>
+                  {icon} {s.story.id}
+                </Text>
+              </Box>
+            );
+          }
+
+          // Normal mode: icon, ID, and routing info
+          const routing = s.routing ? ` ${s.routing.complexity.slice(0, 3)} ${s.routing.modelTier}` : "";
+          return (
+            <Box key={s.story.id}>
+              <Text>
+                {icon} {s.story.id}
+                <Text dimColor>{routing}</Text>
+              </Text>
+            </Box>
+          );
+        })}
+      </Box>
+
+      {/* Scroll indicator (bottom) */}
+      {needsScrolling && canScrollDown && (
+        <Box paddingX={1}>
+          <Text dimColor>▼ {stories.length - scrollOffset - maxVisible} more below</Text>
+        </Box>
+      )}
+
+      {/* Footer — Cost and time */}
+      <Box flexDirection="column" paddingX={1} paddingY={1} borderStyle="single" borderTop borderColor="gray">
+        {!compact && (
+          <>
+            <Text>
+              Cost: <Text color="green">${totalCost.toFixed(4)}</Text>
+            </Text>
+            <Text>
+              Time: <Text color="cyan">{formatElapsedTime(elapsedMs)}</Text>
+            </Text>
+          </>
+        )}
+        {compact && (
+          <Text>
+            ${totalCost.toFixed(2)} · {formatElapsedTime(elapsedMs)}
+          </Text>
+        )}
+      </Box>
+    </Box>
+  );
+}

package/src/tui/hooks/useKeyboard.ts

@@ -0,0 +1,142 @@
+/**
+ * useKeyboard hook — handle keyboard shortcuts for TUI controls.
+ *
+ * Listens for keyboard input when agent panel is NOT focused and dispatches
+ * actions like PAUSE/ABORT/SKIP to the queue file.
+ *
+ * When agent panel IS focused, only Ctrl+] escapes back to TUI controls.
+ */
+
+import { useInput } from "ink";
+import type { UserStory } from "../../prd/types";
+import { PanelFocus } from "../types";
+
+/**
+ * Keyboard action types.
+ */
+export type KeyboardAction =
+  | { type: "PAUSE" }
+  | { type: "ABORT" }
+  | { type: "SKIP"; storyId: string }
+  | { type: "TOGGLE_FOCUS" }
+  | { type: "ESCAPE_AGENT" }
+  | { type: "QUIT" }
+  | { type: "SHOW_HELP" }
+  | { type: "SHOW_COST" }
+  | { type: "RETRY" }
+  | { type: "CLOSE_OVERLAY" };
+
+/**
+ * Props for useKeyboard hook.
+ */
+export interface UseKeyboardProps {
+  /** Current panel focus state */
+  focus: PanelFocus;
+  /** Current story being executed (for SKIP command) */
+  currentStory?: UserStory;
+  /** Callback when an action is triggered */
+  onAction: (action: KeyboardAction) => void;
+  /** Disable keyboard handling (e.g., during confirmation dialogs) */
+  disabled?: boolean;
+}
+
+/**
+ * Hook for handling keyboard shortcuts.
+ *
+ * Keybindings (when Stories panel is focused):
+ * - p: PAUSE after current story
+ * - a: ABORT run
+ * - s: SKIP current story
+ * - Tab: Toggle focus between Stories and Agent panels
+ * - q: Quit TUI
+ * - ?: Show help overlay
+ * - c: Show cost breakdown overlay
+ * - r: Retry last failed story
+ * - Esc: Close overlay
+ *
+ * When Agent panel is focused:
+ * - Ctrl+]: Escape back to TUI controls
+ * - All other keys: Forwarded to PTY (handled elsewhere)
+ *
+ * @example
+ * ```tsx
+ * const [focus, setFocus] = useState(PanelFocus.Stories);
+ * const [showHelp, setShowHelp] = useState(false);
+ *
+ * useKeyboard({
+ *   focus,
+ *   currentStory: state.currentStory,
+ *   onAction: (action) => {
+ *     if (action.type === "TOGGLE_FOCUS") {
+ *       setFocus(prev => prev === PanelFocus.Stories ? PanelFocus.Agent : PanelFocus.Stories);
+ *     } else if (action.type === "SHOW_HELP") {
+ *       setShowHelp(true);
+ *     } else if (action.type === "PAUSE") {
+ *       writeQueueCommand({ type: "PAUSE" });
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export function useKeyboard({ focus, currentStory, onAction, disabled = false }: UseKeyboardProps): void {
+  useInput((input, key) => {
+    // If disabled, don't process any input
+    if (disabled) {
+      return;
+    }
+
+    // When Agent panel is focused, only Ctrl+] escapes back to TUI
+    if (focus === PanelFocus.Agent) {
+      // Ctrl+] is key.ctrl === true and input === ']'
+      if (key.ctrl && input === "]") {
+        onAction({ type: "ESCAPE_AGENT" });
+      }
+      // All other input is routed to PTY (handled by caller)
+      return;
+    }
+
+    // Stories panel is focused — handle TUI shortcuts
+    // Tab key toggles focus
+    if (key.tab) {
+      onAction({ type: "TOGGLE_FOCUS" });
+      return;
+    }
+
+    // Esc closes overlays
+    if (key.escape) {
+      onAction({ type: "CLOSE_OVERLAY" });
+      return;
+    }
+
+    // Character-based shortcuts
+    switch (input.toLowerCase()) {
+      case "p":
+        onAction({ type: "PAUSE" });
+        break;
+      case "a":
+        onAction({ type: "ABORT" });
+        break;
+      case "s":
+        // Skip requires a current story
+        if (currentStory) {
+          onAction({ type: "SKIP", storyId: currentStory.id });
+        }
+        break;
+      case "q":
+        onAction({ type: "QUIT" });
+        break;
+      case "?":
+        onAction({ type: "SHOW_HELP" });
+        break;
+      case "c":
+        onAction({ type: "SHOW_COST" });
+        break;
+      case "r":
+        onAction({ type: "RETRY" });
+        break;
+      default:
+        // Ignore unrecognized keys
+        break;
+    }
+  });
+}