@butlerw/vellum 0.1.0

package/src/tui/hooks/useAlternateBuffer.ts

@@ -0,0 +1,398 @@
+/**
+ * useAlternateBuffer Hook (T043)
+ *
+ * React hook for terminal alternate screen buffer management.
+ * Provides functionality similar to how vim and other full-screen terminal
+ * applications switch between the main and alternate screen buffers.
+ *
+ * The alternate screen buffer allows the TUI to render without affecting
+ * the user's existing terminal scrollback history, and cleanly restores
+ * the original buffer when the application exits.
+ *
+ * @module @vellum/cli
+ */
+
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import { getActiveStdout } from "../buffered-stdout.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Options for the useAlternateBuffer hook.
+ */
+export interface UseAlternateBufferOptions {
+  /** Whether alternate buffer mode is enabled (default: true) */
+  readonly enabled?: boolean;
+  /** Whether to constrain the render height (default: false) */
+  readonly constrainHeight?: boolean;
+  /** Maximum height when constrainHeight is true (default: terminal rows) */
+  readonly maxHeight?: number;
+  /** Enable viewport calculation for availableHeight (default: false) */
+  readonly withViewport?: boolean;
+  /** Lines reserved for input area (default: 3) */
+  readonly inputReserve?: number;
+  /** Lines reserved for status bar (default: 1) */
+  readonly statusReserve?: number;
+  /** Debounce delay for resize events in ms (default: 100) */
+  readonly resizeDebounce?: number;
+}
+
+/**
+ * Return value of useAlternateBuffer hook.
+ */
+export interface UseAlternateBufferReturn {
+  /** Whether currently in alternate buffer mode */
+  readonly isAlternate: boolean;
+  /** Enable alternate buffer mode */
+  readonly enable: () => void;
+  /** Disable alternate buffer mode and restore original buffer */
+  readonly disable: () => void;
+  /** Toggle between main and alternate buffer */
+  readonly toggle: () => void;
+  /** Current effective height (constrained or terminal height) */
+  readonly height: number;
+  /** Current terminal width */
+  readonly width: number;
+  /** Available height for content (height - inputReserve - statusReserve) */
+  readonly availableHeight: number;
+  /** Whether resize is currently being debounced */
+  readonly isResizing: boolean;
+}
+
+// =============================================================================
+// ANSI Escape Sequences
+// =============================================================================
+
+/**
+ * ANSI escape sequence to switch to alternate screen buffer.
+ * This is the standard DEC private mode 1049.
+ */
+const ENTER_ALTERNATE_BUFFER = "\x1b[?1049h";
+
+/**
+ * ANSI escape sequence to switch back to main screen buffer.
+ * This restores the cursor position and screen contents.
+ */
+const EXIT_ALTERNATE_BUFFER = "\x1b[?1049l";
+
+/**
+ * ANSI escape sequence to clear the screen.
+ */
+const CLEAR_SCREEN = "\x1b[2J";
+
+/**
+ * ANSI escape sequence to move cursor to home position (top-left).
+ */
+const CURSOR_HOME = "\x1b[H";
+
+/**
+ * ANSI escape sequence to disable line wrapping.
+ * Prevents cursor flickering in VS Code terminal.
+ */
+const DISABLE_LINE_WRAPPING = "\x1b[?7l";
+
+/**
+ * ANSI escape sequence to enable line wrapping.
+ * Restores normal terminal behavior on exit.
+ */
+const ENABLE_LINE_WRAPPING = "\x1b[?7h";
+
+// =============================================================================
+// Input Reserve Calculation
+// =============================================================================
+
+/**
+ * Calculate the lines to reserve for input area based on mode.
+ * Use this to get correct inputReserve value for useAlternateBuffer.
+ *
+ * @param multiline - Whether the input is multiline
+ * @param minHeight - Minimum height for multiline input (default: 5)
+ * @returns Number of lines to reserve for input
+ */
+export function calculateInputReserve(multiline: boolean, minHeight = 5): number {
+  const border = 2; // Top and bottom border
+  if (multiline) {
+    return minHeight + border; // 5 + 2 = 7 for default multiline
+  }
+  return 3; // Single line with border
+}
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+/**
+ * Get the current terminal height.
+ * Falls back to a reasonable default if unavailable.
+ */
+function getTerminalHeight(): number {
+  return process.stdout.rows || 24;
+}
+
+/**
+ * Get the current terminal width.
+ * Falls back to a reasonable default if unavailable.
+ */
+function getTerminalWidth(): number {
+  return process.stdout.columns || 80;
+}
+
+/**
+ * Write raw data to stdout.
+ * Handles potential write errors gracefully.
+ * Uses getActiveStdout() to ensure synchronized output when BufferedStdout is active.
+ */
+function writeToStdout(data: string): void {
+  try {
+    getActiveStdout().write(data);
+  } catch {
+    // Silently ignore write errors (e.g., if stdout is closed)
+  }
+}
+
+/**
+ * Enter the alternate screen buffer.
+ */
+function enterAlternateBuffer(): void {
+  // No-op: Ink manages alternate buffer switching at render entry.
+  // Keeping this hook side-effect free avoids double buffer switching/clearing.
+  void ENTER_ALTERNATE_BUFFER;
+  void DISABLE_LINE_WRAPPING;
+  void CLEAR_SCREEN;
+  void CURSOR_HOME;
+}
+
+/**
+ * Exit the alternate screen buffer.
+ */
+function exitAlternateBuffer(): void {
+  // No-op: Ink manages alternate buffer switching at render entry.
+  void ENABLE_LINE_WRAPPING;
+  void EXIT_ALTERNATE_BUFFER;
+}
+
+// =============================================================================
+// Hook Implementation
+// =============================================================================
+
+/**
+ * Hook for managing terminal alternate screen buffer.
+ *
+ * The alternate screen buffer is a separate buffer that full-screen terminal
+ * applications (like vim, less, htop) use to render their UI without affecting
+ * the user's existing terminal scrollback history.
+ *
+ * When enabled, this hook:
+ * 1. Switches to the alternate screen buffer
+ * 2. Clears the screen and positions the cursor at the top
+ * 3. Provides height constraints for TUI rendering
+ * 4. Automatically restores the original buffer on unmount
+ *
+ * @param options - Configuration options
+ * @returns Object containing buffer state and control functions
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const { isAlternate, height, enable, disable } = useAlternateBuffer({
+ *     enabled: true,
+ *     constrainHeight: true,
+ *     maxHeight: 40
+ *   });
+ *
+ *   return (
+ *     <Box height={height}>
+ *       <Text>TUI Content (height: {height})</Text>
+ *     </Box>
+ *   );
+ * }
+ * ```
+ */
+export function useAlternateBuffer(
+  options: UseAlternateBufferOptions = {}
+): UseAlternateBufferReturn {
+  const {
+    enabled = true,
+    constrainHeight = false,
+    maxHeight,
+    withViewport = false,
+    inputReserve = 7, // Default for multiline (minHeight 5 + border 2)
+    statusReserve = 1,
+    resizeDebounce = 100,
+  } = options;
+
+  // Track whether we're currently in alternate buffer mode
+  const [isAlternate, setIsAlternate] = useState(false);
+
+  // Track terminal dimensions
+  const [terminalHeight, setTerminalHeight] = useState(getTerminalHeight);
+  const [terminalWidth, setTerminalWidth] = useState(getTerminalWidth);
+
+  // Track resize debounce state
+  const [isResizing, setIsResizing] = useState(false);
+  const resizeTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  // Ref to track if we've already cleaned up (prevent double cleanup)
+  const cleanedUpRef = useRef(false);
+
+  // Ref to track current alternate state (for cleanup)
+  const isAlternateRef = useRef(false);
+
+  /**
+   * Enable alternate buffer mode.
+   */
+  const enable = useCallback(() => {
+    if (!isAlternateRef.current) {
+      enterAlternateBuffer();
+      isAlternateRef.current = true;
+      setIsAlternate(true);
+    }
+  }, []);
+
+  /**
+   * Disable alternate buffer mode and restore original buffer.
+   */
+  const disable = useCallback(() => {
+    if (isAlternateRef.current) {
+      exitAlternateBuffer();
+      isAlternateRef.current = false;
+      setIsAlternate(false);
+    }
+  }, []);
+
+  /**
+   * Toggle between main and alternate buffer.
+   */
+  const toggle = useCallback(() => {
+    if (isAlternateRef.current) {
+      disable();
+    } else {
+      enable();
+    }
+  }, [enable, disable]);
+
+  /**
+   * Calculate the effective height based on constraints.
+   */
+  const height = constrainHeight
+    ? Math.min(terminalHeight, maxHeight ?? terminalHeight)
+    : terminalHeight;
+
+  /**
+   * Calculate available height for content (when withViewport is enabled).
+   * Ensure minimum of 8 lines to prevent degenerate rendering cases.
+   */
+  const MIN_AVAILABLE_HEIGHT = 8;
+  const availableHeight = withViewport
+    ? Math.max(MIN_AVAILABLE_HEIGHT, height - inputReserve - statusReserve)
+    : height;
+
+  // Handle terminal resize events with debounce
+  useEffect(() => {
+    const handleResize = (): void => {
+      if (resizeDebounce > 0) {
+        setIsResizing(true);
+        if (resizeTimerRef.current) {
+          clearTimeout(resizeTimerRef.current);
+        }
+        resizeTimerRef.current = setTimeout(() => {
+          setTerminalHeight(getTerminalHeight());
+          setTerminalWidth(getTerminalWidth());
+          setIsResizing(false);
+        }, resizeDebounce);
+      } else {
+        setTerminalHeight(getTerminalHeight());
+        setTerminalWidth(getTerminalWidth());
+      }
+    };
+
+    process.stdout.on("resize", handleResize);
+
+    return () => {
+      process.stdout.off("resize", handleResize);
+      if (resizeTimerRef.current) {
+        clearTimeout(resizeTimerRef.current);
+      }
+    };
+  }, [resizeDebounce]);
+
+  // Auto-enable alternate buffer when hook mounts (if enabled option is true)
+  useEffect(() => {
+    if (enabled && !cleanedUpRef.current) {
+      enable();
+    }
+
+    // Cleanup on unmount
+    return () => {
+      if (!cleanedUpRef.current) {
+        cleanedUpRef.current = true;
+        if (isAlternateRef.current) {
+          exitAlternateBuffer();
+          isAlternateRef.current = false;
+        }
+      }
+    };
+  }, [enabled, enable]);
+
+  // Handle process exit signals to ensure buffer is restored
+  useEffect(() => {
+    const handleExit = (): void => {
+      if (!cleanedUpRef.current && isAlternateRef.current) {
+        cleanedUpRef.current = true;
+        exitAlternateBuffer();
+      }
+    };
+
+    // Handle various exit signals
+    process.on("exit", handleExit);
+    process.on("SIGINT", handleExit);
+    process.on("SIGTERM", handleExit);
+    process.on("SIGHUP", handleExit);
+
+    return () => {
+      process.off("exit", handleExit);
+      process.off("SIGINT", handleExit);
+      process.off("SIGTERM", handleExit);
+      process.off("SIGHUP", handleExit);
+    };
+  }, []);
+
+  return {
+    isAlternate,
+    enable,
+    disable,
+    toggle,
+    height,
+    width: terminalWidth,
+    availableHeight,
+    isResizing,
+  };
+}
+
+// =============================================================================
+// Utility Exports
+// =============================================================================
+
+/**
+ * Raw ANSI sequences for direct use if needed.
+ */
+export const ANSI = {
+  ENTER_ALTERNATE_BUFFER,
+  EXIT_ALTERNATE_BUFFER,
+  CLEAR_SCREEN,
+  CURSOR_HOME,
+} as const;
+
+/**
+ * Utility functions for manual buffer management.
+ */
+export const bufferUtils = {
+  getTerminalHeight,
+  getTerminalWidth,
+  enterAlternateBuffer,
+  exitAlternateBuffer,
+  writeToStdout,
+} as const;

package/src/tui/hooks/useAnimatedScrollbar.ts

@@ -0,0 +1,241 @@
+/**
+ * Animated Scrollbar Hook
+ *
+ * Provides animated scrollbar visibility with fade in/out effects based on
+ * scroll activity. Inspired by Gemini CLI's useAnimatedScrollbar.
+ *
+ * Features:
+ * - Scrollbar color fades in/out based on activity
+ * - Color interpolation (bright → dim over time)
+ * - Flash callback for focus events
+ * - Activity tracking (scrolling triggers visibility)
+ *
+ * @module tui/hooks/useAnimatedScrollbar
+ */
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { interpolateColor } from "../components/Banner/ShimmerText.js";
+import { useTheme } from "../theme/index.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Animation phase for the scrollbar fade effect
+ */
+type AnimationPhase = "idle" | "fade-in" | "visible" | "fade-out";
+
+/**
+ * Configuration for animated scrollbar behavior
+ */
+export interface AnimatedScrollbarConfig {
+  /** Duration of fade-in animation in ms (default: 200) */
+  readonly fadeInDuration?: number;
+  /** Duration scrollbar stays fully visible in ms (default: 1000) */
+  readonly visibleDuration?: number;
+  /** Duration of fade-out animation in ms (default: 300) */
+  readonly fadeOutDuration?: number;
+  /** Frame rate for animation updates in ms (default: 33 ~= 30fps) */
+  readonly frameInterval?: number;
+}
+
+/**
+ * Return type for useAnimatedScrollbar hook
+ */
+export interface UseAnimatedScrollbarReturn {
+  /** Current scrollbar color (interpolated based on animation state) */
+  readonly scrollbarColor: string;
+  /** Track color (dimmed version) */
+  readonly trackColor: string;
+  /** Manually trigger a flash animation */
+  readonly flashScrollbar: () => void;
+  /** Wrapper that calls scrollBy and triggers animation */
+  readonly scrollByWithAnimation: (delta: number) => void;
+  /** Current animation phase for debugging */
+  readonly phase: AnimationPhase;
+}
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+const DEFAULT_CONFIG: Required<AnimatedScrollbarConfig> = {
+  fadeInDuration: 200,
+  visibleDuration: 1000,
+  fadeOutDuration: 300,
+  frameInterval: 33, // ~30fps
+};
+
+// =============================================================================
+// Hook
+// =============================================================================
+
+/**
+ * Hook for animated scrollbar visibility effects
+ *
+ * @param isFocused - Whether the scrollable area is focused
+ * @param scrollBy - Function to scroll by a delta amount
+ * @param config - Optional animation configuration
+ * @returns Animated scrollbar state and controls
+ *
+ * @example
+ * ```tsx
+ * const { scrollbarColor, scrollByWithAnimation } = useAnimatedScrollbar(
+ *   isFocused,
+ *   (delta) => scrollController.scrollBy(delta)
+ * );
+ *
+ * // In ScrollIndicator
+ * <Text color={scrollbarColor}>█</Text>
+ * ```
+ */
+export function useAnimatedScrollbar(
+  isFocused: boolean,
+  scrollBy: (delta: number) => void,
+  config: AnimatedScrollbarConfig = {}
+): UseAnimatedScrollbarReturn {
+  const { theme } = useTheme();
+
+  // Merge config with defaults
+  const { fadeInDuration, visibleDuration, fadeOutDuration, frameInterval } = {
+    ...DEFAULT_CONFIG,
+    ...config,
+  };
+
+  // Colors from theme
+  const activeColor = theme.semantic.text.muted;
+  const dimColor = theme.semantic.border.muted;
+  const trackColorTheme = theme.semantic.border.default;
+
+  // State
+  const [scrollbarColor, setScrollbarColor] = useState(dimColor);
+  const [phase, setPhase] = useState<AnimationPhase>("idle");
+
+  // Refs for animation state
+  const colorRef = useRef(scrollbarColor);
+  const animationFrame = useRef<ReturnType<typeof setInterval> | null>(null);
+  const timeout = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const isAnimatingRef = useRef(false);
+  const wasFocusedRef = useRef(isFocused);
+
+  // Keep colorRef in sync
+  colorRef.current = scrollbarColor;
+
+  /**
+   * Cleanup all timers and animation state
+   */
+  const cleanup = useCallback(() => {
+    if (animationFrame.current) {
+      clearInterval(animationFrame.current);
+      animationFrame.current = null;
+    }
+    if (timeout.current) {
+      clearTimeout(timeout.current);
+      timeout.current = null;
+    }
+    isAnimatingRef.current = false;
+  }, []);
+
+  /**
+   * Flash the scrollbar (fade in → visible → fade out)
+   */
+  const flashScrollbar = useCallback(() => {
+    cleanup();
+    isAnimatingRef.current = true;
+
+    const startColor = colorRef.current;
+
+    // Validate colors exist
+    if (!activeColor || !dimColor) {
+      return;
+    }
+
+    // Phase 1: Fade In
+    setPhase("fade-in");
+    let startTime = Date.now();
+
+    const animateFadeIn = () => {
+      const elapsed = Date.now() - startTime;
+      const progress = Math.min(elapsed / fadeInDuration, 1);
+
+      setScrollbarColor(interpolateColor(startColor, activeColor, progress));
+
+      if (progress >= 1) {
+        if (animationFrame.current) {
+          clearInterval(animationFrame.current);
+          animationFrame.current = null;
+        }
+
+        // Phase 2: Stay visible
+        setPhase("visible");
+        timeout.current = setTimeout(() => {
+          // Phase 3: Fade Out
+          setPhase("fade-out");
+          startTime = Date.now();
+
+          const animateFadeOut = () => {
+            const elapsed = Date.now() - startTime;
+            const progress = Math.min(elapsed / fadeOutDuration, 1);
+
+            setScrollbarColor(interpolateColor(activeColor, dimColor, progress));
+
+            if (progress >= 1) {
+              cleanup();
+              setPhase("idle");
+            }
+          };
+
+          animationFrame.current = setInterval(animateFadeOut, frameInterval);
+        }, visibleDuration);
+      }
+    };
+
+    animationFrame.current = setInterval(animateFadeIn, frameInterval);
+  }, [
+    cleanup,
+    activeColor,
+    dimColor,
+    fadeInDuration,
+    visibleDuration,
+    fadeOutDuration,
+    frameInterval,
+  ]);
+
+  /**
+   * Handle focus changes - flash on focus gain
+   */
+  useEffect(() => {
+    if (isFocused && !wasFocusedRef.current) {
+      // Gained focus - flash scrollbar
+      flashScrollbar();
+    } else if (!isFocused && wasFocusedRef.current) {
+      // Lost focus - immediately dim
+      cleanup();
+      setScrollbarColor(dimColor);
+      setPhase("idle");
+    }
+    wasFocusedRef.current = isFocused;
+
+    return cleanup;
+  }, [isFocused, flashScrollbar, cleanup, dimColor]);
+
+  /**
+   * Scroll with animation - wraps scrollBy and triggers flash
+   */
+  const scrollByWithAnimation = useCallback(
+    (delta: number) => {
+      scrollBy(delta);
+      flashScrollbar();
+    },
+    [scrollBy, flashScrollbar]
+  );
+
+  return {
+    scrollbarColor,
+    trackColor: trackColorTheme,
+    flashScrollbar,
+    scrollByWithAnimation,
+    phase,
+  };
+}