@butlerw/vellum 0.1.0

package/src/tui/components/Messages/StreamingText.tsx

@@ -0,0 +1,216 @@
+/**
+ * StreamingText Component (T019)
+ *
+ * Displays text content with an animated blinking cursor while streaming.
+ * Supports optional typewriter effect for smoother character-by-character display.
+ * The cursor is removed when streaming completes, and an optional callback
+ * is invoked.
+ *
+ * @module tui/components/Messages/StreamingText
+ */
+
+import { Text } from "ink";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { useAnimation } from "../../context/AnimationContext.js";
+import { sanitize } from "../../utils/textSanitizer.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Props for the StreamingText component.
+ */
+export interface StreamingTextProps {
+  /** The text content to display */
+  readonly content: string;
+  /** Whether the text is currently streaming */
+  readonly isStreaming: boolean;
+  /** Character to use for the cursor (default: '▊') */
+  readonly cursorChar?: string;
+  /** Whether the cursor should blink (default: true) */
+  readonly cursorBlink?: boolean;
+  /** Callback invoked when streaming completes */
+  readonly onComplete?: () => void;
+  /** Enable typewriter effect for smoother display (default: true) */
+  readonly typewriterEffect?: boolean;
+  /** Delay between characters in ms when typewriter is enabled (default: 8) */
+  readonly typewriterSpeed?: number;
+}
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/** Default cursor character */
+const DEFAULT_CURSOR_CHAR = "▊";
+
+/** Default typewriter speed (characters per interval) */
+const DEFAULT_TYPEWRITER_SPEED_MS = 8;
+
+/** Characters to release per tick for faster catch-up */
+const CHARS_PER_TICK = 3;
+
+// =============================================================================
+// Main Component
+// =============================================================================
+
+/**
+ * StreamingText displays text with an animated cursor while streaming.
+ *
+ * Features:
+ * - Displays text content
+ * - Shows blinking cursor at end while streaming
+ * - Removes cursor when streaming completes
+ * - Supports cursor customization (character and blink behavior)
+ * - Optional typewriter effect for smoother display
+ * - Calls onComplete callback when isStreaming changes to false
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <StreamingText
+ *   content={text}
+ *   isStreaming={isTyping}
+ * />
+ *
+ * // With completion callback
+ * <StreamingText
+ *   content={text}
+ *   isStreaming={isTyping}
+ *   onComplete={() => enableInput()}
+ * />
+ *
+ * // Custom cursor
+ * <StreamingText
+ *   content={text}
+ *   isStreaming={isTyping}
+ *   cursorChar="_"
+ *   cursorBlink={false}
+ * />
+ *
+ * // With typewriter effect
+ * <StreamingText
+ *   content={text}
+ *   isStreaming={isTyping}
+ *   typewriterEffect={true}
+ *   typewriterSpeed={10}
+ * />
+ * ```
+ */
+export function StreamingText({
+  content,
+  isStreaming,
+  cursorChar = DEFAULT_CURSOR_CHAR,
+  cursorBlink = true,
+  onComplete,
+  typewriterEffect = true,
+  typewriterSpeed = DEFAULT_TYPEWRITER_SPEED_MS,
+}: StreamingTextProps): React.JSX.Element {
+  // Track cursor visibility for blinking effect
+  const [cursorVisible, setCursorVisible] = useState(true);
+
+  // Track previous streaming state to detect completion
+  const prevIsStreamingRef = useRef<boolean | null>(null);
+
+  // Track if this is the initial mount (for immediate display when not streaming)
+  const isInitialMountRef = useRef(true);
+
+  // Typewriter effect state - initialize to full length if not streaming on mount
+  const [displayedLength, setDisplayedLength] = useState(() => (isStreaming ? 0 : content.length));
+  const prevContentLengthRef = useRef(content.length);
+
+  // Handle typewriter effect - gradually reveal characters
+  useEffect(() => {
+    // Skip typewriter if disabled
+    if (!typewriterEffect) {
+      setDisplayedLength(content.length);
+      return;
+    }
+
+    // When streaming stops, immediately show all content
+    if (!isStreaming) {
+      setDisplayedLength(content.length);
+      return;
+    }
+
+    // Mark initial mount as complete
+    isInitialMountRef.current = false;
+
+    // If we're caught up, nothing to do
+    if (displayedLength >= content.length) {
+      return;
+    }
+
+    // Release characters progressively
+    const timer = setTimeout(() => {
+      setDisplayedLength((prev) => {
+        // Release multiple chars per tick for faster catch-up when behind
+        const behind = content.length - prev;
+        const charsToRelease = behind > 20 ? Math.min(behind, CHARS_PER_TICK * 3) : CHARS_PER_TICK;
+        return Math.min(prev + charsToRelease, content.length);
+      });
+    }, typewriterSpeed);
+
+    return () => clearTimeout(timer);
+  }, [content.length, displayedLength, isStreaming, typewriterEffect, typewriterSpeed]);
+
+  // Reset displayed length when content is cleared (new message)
+  useEffect(() => {
+    if (content.length < prevContentLengthRef.current) {
+      // Content was reset (new message started)
+      setDisplayedLength(0);
+    }
+    prevContentLengthRef.current = content.length;
+  }, [content.length]);
+
+  // Use global animation context for cursor blink to prevent flickering
+  const { frame, isPaused } = useAnimation();
+
+  // Derive cursor visibility from animation frame instead of independent timer
+  // This prevents competing setIntervals from causing flicker
+  const derivedCursorVisible = useMemo(() => {
+    // Always show cursor when not streaming or blink disabled
+    if (!isStreaming || !cursorBlink) return true;
+    // Show cursor when animation is paused (e.g., input focused)
+    if (isPaused) return true;
+    // Toggle every ~4 frames (~500ms blink cycle at 120ms/200ms tick rate)
+    return Math.floor(frame / 4) % 2 === 0;
+  }, [frame, isPaused, isStreaming, cursorBlink]);
+
+  // Sync local state with derived value for compatibility with existing logic
+  useEffect(() => {
+    setCursorVisible(derivedCursorVisible);
+  }, [derivedCursorVisible]);
+
+  // Handle streaming completion callback
+  useEffect(() => {
+    // Only trigger callback if we were previously streaming and now we're not
+    // Skip on initial mount (prevIsStreamingRef.current is null)
+    if (prevIsStreamingRef.current === true && !isStreaming) {
+      onComplete?.();
+    }
+
+    // Update ref after callback logic
+    prevIsStreamingRef.current = isStreaming;
+  }, [isStreaming, onComplete]);
+
+  // Sanitize content (normalize line endings, strip dangerous ANSI)
+  const sanitizedContent = useMemo(() => sanitize(content), [content]);
+
+  // Determine what text to display
+  const displayText = typewriterEffect
+    ? sanitizedContent.slice(0, displayedLength)
+    : sanitizedContent;
+
+  // Determine cursor to display (show cursor while typewriter is still catching up)
+  const showCursor = isStreaming || (typewriterEffect && displayedLength < sanitizedContent.length);
+  const cursor = showCursor && cursorVisible ? cursorChar : "";
+
+  return (
+    <Text wrap="wrap">
+      {displayText}
+      {cursor}
+    </Text>
+  );
+}

package/src/tui/components/Messages/ThinkingBlock.tsx

@@ -0,0 +1,408 @@
+/**
+ * ThinkingBlock Component
+ *
+ * Displays thinking/reasoning content from extended thinking models
+ * with collapsible UI, duration display, and streaming indicator.
+ *
+ * Features:
+ * - Collapsible: Toggle between collapsed (1-line summary) and expanded view
+ * - Duration display: Shows how long thinking took (e.g., "Thought for 3.2s")
+ * - Streaming indicator: Shows spinner while thinking is in progress
+ * - Character count: Shows length in collapsed mode (e.g., "[...] (1,234 chars)")
+ * - Keyboard toggle: 't' key to toggle expand/collapse
+ * - Visual distinction: Box border to separate from main content
+ * - Tool calls: Optional inline display of tool calls within thinking block
+ *
+ * @module tui/components/Messages/ThinkingBlock
+ */
+
+import { Box, Text } from "ink";
+import type React from "react";
+import { useMemo } from "react";
+import { useAnimationFrame } from "../../context/AnimationContext.js";
+import type { ToolCallInfo } from "../../context/MessagesContext.js";
+import { useCollapsible } from "../../hooks/useCollapsible.js";
+import type { ThinkingDisplayMode } from "../../i18n/index.js";
+import { useTheme } from "../../theme/index.js";
+import { SPINNER_STYLES, Spinner } from "../common/Spinner.js";
+
+// Spinner frames for tool call status
+const TOOL_SPINNER_FRAMES = ["-", "\\", "|", "/"];
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Props for the ThinkingBlock component.
+ */
+export interface ThinkingBlockProps {
+  /** Thinking/reasoning content to display */
+  readonly content: string;
+  /** Duration of thinking in milliseconds (optional) */
+  readonly durationMs?: number;
+  /** Whether thinking is still in progress (shows spinner) */
+  readonly isStreaming?: boolean;
+  /** Whether initially collapsed (default: true) */
+  readonly initialCollapsed?: boolean;
+  /** Unique ID for state persistence (optional) */
+  readonly persistenceId?: string;
+  /** Enable keyboard toggle with 't' key (default: false to avoid conflicts) */
+  readonly enableKeyboardToggle?: boolean;
+  /** Maximum lines to show in collapsed preview (default: 1) */
+  readonly collapsedPreviewLines?: number;
+  /** Maximum characters to show in collapsed preview (default: 80) */
+  readonly collapsedPreviewChars?: number;
+  /** Show character count in header (default: true) */
+  readonly showCharCount?: boolean;
+  /** Callback when toggle state changes */
+  readonly onToggle?: (collapsed: boolean) => void;
+  /** Tool calls to display inline within the thinking block */
+  readonly toolCalls?: readonly ToolCallInfo[];
+  /**
+   * Display mode for thinking content.
+   * - "full": Show content (default, can expand/collapse)
+   * - "compact": Only show header, no content preview, cannot expand
+   */
+  readonly displayMode?: ThinkingDisplayMode;
+}
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+/**
+ * Format character count for display.
+ */
+function formatCharCount(count: number): string {
+  if (count < 1000) {
+    return `${count} chars`;
+  }
+  const k = count / 1000;
+  return k >= 10 ? `${Math.round(k)}K chars` : `${k.toFixed(1)}K chars`;
+}
+
+/**
+ * Format duration in milliseconds to human-readable string.
+ */
+function formatThinkingDuration(ms: number): string {
+  if (ms < 1000) {
+    return `${ms}ms`;
+  }
+  const seconds = ms / 1000;
+  if (seconds < 60) {
+    return `${seconds.toFixed(1)}s`;
+  }
+  const minutes = Math.floor(seconds / 60);
+  const remainingSeconds = (seconds % 60).toFixed(0);
+  return `${minutes}m ${remainingSeconds}s`;
+}
+
+/**
+ * Get a preview of the content for collapsed mode.
+ */
+function getPreview(content: string, maxLines: number, maxChars: number): string {
+  if (!content) return "";
+
+  // Split by newlines and take first N lines
+  const lines = content.split("\n").slice(0, maxLines);
+  let preview = lines.join(" ").trim();
+
+  // Truncate to max chars
+  if (preview.length > maxChars) {
+    preview = `${preview.slice(0, maxChars - 3)}...`;
+  }
+
+  return preview;
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * ThinkingBlock - Collapsible display for model thinking/reasoning content.
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <ThinkingBlock content="Let me think about this..." />
+ *
+ * // With streaming indicator
+ * <ThinkingBlock
+ *   content={thinkingContent}
+ *   isStreaming={true}
+ * />
+ *
+ * // With duration and keyboard toggle
+ * <ThinkingBlock
+ *   content={thinkingContent}
+ *   durationMs={3200}
+ *   enableKeyboardToggle
+ * />
+ *
+ * // Initially expanded
+ * <ThinkingBlock
+ *   content={thinkingContent}
+ *   initialCollapsed={false}
+ * />
+ * ```
+ */
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: ThinkingBlock UI inherently complex due to multiple render modes
+export function ThinkingBlock({
+  content,
+  durationMs,
+  isStreaming = false,
+  initialCollapsed = true,
+  persistenceId,
+  enableKeyboardToggle = false,
+  collapsedPreviewLines = 1,
+  collapsedPreviewChars = 80,
+  showCharCount = true,
+  onToggle,
+  toolCalls,
+  displayMode = "full",
+}: ThinkingBlockProps): React.JSX.Element | null {
+  const { theme } = useTheme();
+
+  // Animation frame for tool call spinners
+  const frameIndex = useAnimationFrame(TOOL_SPINNER_FRAMES);
+
+  // In compact mode, force collapsed and disable keyboard toggle
+  const isCompactMode = displayMode === "compact";
+  const effectiveInitialCollapsed = isCompactMode ? true : initialCollapsed;
+  const effectiveKeyboardToggle = isCompactMode ? false : enableKeyboardToggle;
+
+  const { isCollapsed, toggle: _toggle } = useCollapsible({
+    initialCollapsed: effectiveInitialCollapsed,
+    toggleKey: effectiveKeyboardToggle ? "t" : undefined,
+    keyboardEnabled: effectiveKeyboardToggle,
+    persistenceId,
+    onToggle,
+  });
+
+  // In compact mode, always show as collapsed (never expandable)
+  const effectiveIsCollapsed = isCompactMode ? true : isCollapsed;
+
+  // Theme colors
+  const thinkingColor = theme.colors.warning ?? "yellow";
+  const mutedColor = theme.semantic.text.muted;
+  const borderColor = theme.colors.warning ?? "yellow";
+  const accentColor = theme.colors.accent ?? "cyan";
+  const successColor = theme.colors.success ?? "green";
+  const errorColor = theme.colors.error ?? "red";
+
+  // Memoized values
+  const charCount = useMemo(() => content.length, [content]);
+  const preview = useMemo(
+    () => getPreview(content, collapsedPreviewLines, collapsedPreviewChars),
+    [content, collapsedPreviewLines, collapsedPreviewChars]
+  );
+
+  // Don't render if no content
+  if (!content && !isStreaming) {
+    return null;
+  }
+
+  // Build header text
+  const headerParts: string[] = [];
+
+  // Status icon and text
+  if (isStreaming) {
+    headerParts.push("Thinking");
+  } else if (durationMs !== undefined && durationMs > 0) {
+    headerParts.push(`Thought for ${formatThinkingDuration(durationMs)}`);
+  } else {
+    headerParts.push("Thought");
+  }
+
+  // Character count (when collapsed or streaming)
+  if (showCharCount && charCount > 0 && (effectiveIsCollapsed || isStreaming)) {
+    headerParts.push(`(${formatCharCount(charCount)})`);
+  }
+
+  // Toggle hint (not shown in compact mode since it's not toggleable)
+  if (!isStreaming && !isCompactMode) {
+    headerParts.push(effectiveIsCollapsed ? "[expand ▼]" : "[collapse ▲]");
+  }
+
+  return (
+    <Box
+      flexDirection="column"
+      marginLeft={2}
+      marginTop={0}
+      marginBottom={0}
+      borderStyle="round"
+      borderColor={borderColor}
+      paddingX={1}
+      borderLeft
+      borderRight={false}
+      borderTop={false}
+      borderBottom={false}
+    >
+      {/* Header row with toggle */}
+      <Box flexDirection="row" alignItems="center">
+        {/* Streaming spinner */}
+        {isStreaming && (
+          <>
+            <Spinner color={thinkingColor} frames={SPINNER_STYLES.dots} />
+            <Text> </Text>
+          </>
+        )}
+
+        {/* Icon */}
+        <Text color={thinkingColor}>[...] </Text>
+
+        {/* Header text - clickable area concept (visual only in TUI) */}
+        <Text
+          color={thinkingColor}
+          dimColor={!isStreaming}
+          italic
+          // In terminal, we can't have onClick, but visual cue
+        >
+          {headerParts.join(" ")}
+        </Text>
+
+        {/* Keyboard hint */}
+        {effectiveKeyboardToggle && !isStreaming && (
+          <Text color={mutedColor} dimColor>
+            {" "}
+            (press 't')
+          </Text>
+        )}
+      </Box>
+
+      {/* Content area - In compact mode, don't show any content (no preview) */}
+      {isCompactMode ? null : effectiveIsCollapsed ? (
+        // Collapsed: show preview only
+        content && (
+          <Box marginLeft={2} marginTop={0}>
+            <Text color={mutedColor} dimColor wrap="truncate">
+              {preview}
+            </Text>
+          </Box>
+        )
+      ) : (
+        // Expanded: show full content
+        <Box marginLeft={2} marginTop={0} flexDirection="column">
+          <Text color={thinkingColor} dimColor wrap="wrap">
+            {content}
+          </Text>
+        </Box>
+      )}
+
+      {/* Tool calls (when present) */}
+      {toolCalls && toolCalls.length > 0 && (
+        <Box marginLeft={2} marginTop={0} flexDirection="column">
+          {toolCalls.map((toolCall) => {
+            // Determine status indicator and color
+            let statusIcon: string;
+            let statusColor: string;
+
+            switch (toolCall.status) {
+              case "running":
+              case "pending":
+                statusIcon = TOOL_SPINNER_FRAMES[frameIndex] ?? "-";
+                statusColor = accentColor;
+                break;
+              case "completed":
+                statusIcon = "+";
+                statusColor = successColor;
+                break;
+              case "error":
+                statusIcon = "x";
+                statusColor = errorColor;
+                break;
+              default:
+                statusIcon = "o";
+                statusColor = mutedColor;
+            }
+
+            return (
+              <Box key={toolCall.id} flexDirection="row">
+                <Text color={statusColor}>{statusIcon}</Text>
+                <Text> </Text>
+                <Text color={accentColor} bold>
+                  {toolCall.name}
+                </Text>
+                {toolCall.status === "error" && toolCall.error && (
+                  <Text color={errorColor} dimColor>
+                    {" "}
+                    — {toolCall.error}
+                  </Text>
+                )}
+              </Box>
+            );
+          })}
+        </Box>
+      )}
+    </Box>
+  );
+}
+
+// =============================================================================
+// Compact Variant
+// =============================================================================
+
+/**
+ * Props for the CompactThinkingIndicator component.
+ */
+export interface CompactThinkingIndicatorProps {
+  /** Duration of thinking in milliseconds */
+  readonly durationMs?: number;
+  /** Whether thinking is still in progress */
+  readonly isStreaming?: boolean;
+  /** Character count to display */
+  readonly charCount?: number;
+}
+
+/**
+ * CompactThinkingIndicator - Minimal inline thinking status.
+ *
+ * Use this when you just want to show that thinking occurred
+ * without the full collapsible content.
+ *
+ * @example
+ * ```tsx
+ * <CompactThinkingIndicator durationMs={3200} charCount={1500} />
+ * // Renders: 💭 Thought for 3.2s (1.5K chars)
+ * ```
+ */
+export function CompactThinkingIndicator({
+  durationMs,
+  isStreaming = false,
+  charCount,
+}: CompactThinkingIndicatorProps): React.JSX.Element {
+  const { theme } = useTheme();
+  const thinkingColor = theme.colors.warning ?? "yellow";
+
+  const parts: string[] = ["[...]"];
+
+  if (isStreaming) {
+    parts.push("Thinking...");
+  } else if (durationMs !== undefined && durationMs > 0) {
+    parts.push(`Thought for ${formatThinkingDuration(durationMs)}`);
+  } else {
+    parts.push("Thought");
+  }
+
+  if (charCount !== undefined && charCount > 0) {
+    parts.push(`(${formatCharCount(charCount)})`);
+  }
+
+  return (
+    <Box flexDirection="row" alignItems="center">
+      {isStreaming && (
+        <>
+          <Spinner color={thinkingColor} frames={SPINNER_STYLES.dots} />
+          <Text> </Text>
+        </>
+      )}
+      <Text color={thinkingColor} dimColor italic>
+        {parts.join(" ")}
+      </Text>
+    </Box>
+  );
+}
+
+export default ThinkingBlock;