@butlerw/vellum 0.1.0

package/src/tui/components/Banner/TypeWriterGradient.tsx

@@ -0,0 +1,321 @@
+/**
+ * TypeWriterGradient Component
+ *
+ * Renders text with a typewriter effect where characters appear one by one,
+ * each colored according to its position in a gradient.
+ * Shows a blinking cursor at the end during typing.
+ *
+ * @module tui/components/Banner/TypeWriterGradient
+ */
+
+import { Box, Text } from "ink";
+import type React from "react";
+import { memo, useEffect, useMemo, useRef, useState } from "react";
+import { useAnimation } from "../../context/AnimationContext.js";
+import { interpolateColor } from "./ShimmerText.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Typing mode for the typewriter effect.
+ * - 'line': Reveal one line at a time (faster for multi-line ASCII art)
+ * - 'char': Reveal one character at a time (classic typewriter feel)
+ */
+export type TypeWriterMode = "line" | "char";
+
+/**
+ * Props for the TypeWriterGradient component.
+ */
+export interface TypeWriterGradientProps {
+  /** Text content to display with typewriter effect */
+  readonly text: string;
+  /** Speed: chars/sec for 'char' mode, lines/sec for 'line' mode (default: 3000 chars/sec or 50 lines/sec) */
+  readonly speed?: number;
+  /** Gradient colors array (start to end) */
+  readonly colors: readonly string[];
+  /** Callback when typing completes */
+  readonly onComplete?: () => void;
+  /** Whether to show blinking cursor (default: true) */
+  readonly showCursor?: boolean;
+  /** Initial delay before typing starts in ms (default: 100) */
+  readonly initialDelay?: number;
+  /** Typing mode: 'line' for fast multi-line reveal, 'char' for classic typewriter (default: 'line') */
+  readonly mode?: TypeWriterMode;
+}
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/** Default typing speed for char mode (chars per second) - very fast for ASCII art */
+const DEFAULT_CHAR_SPEED = 5000;
+
+/** Default typing speed for line mode (lines per second) */
+const DEFAULT_LINE_SPEED = 50;
+
+/** Frame interval for chunk-based typing (targeting ~60fps) */
+const FRAME_INTERVAL_MS = 16;
+
+/** Cursor character */
+const CURSOR_CHAR = "█";
+
+// =============================================================================
+// Color Calculation
+// =============================================================================
+
+/**
+ * Build interpolated gradient steps for smoother color transitions.
+ */
+function buildGradientSteps(colors: readonly string[], stepsPerSegment: number): string[] {
+  if (colors.length === 0) return [];
+  if (colors.length === 1) return [colors[0] ?? "#000000"];
+
+  const steps: string[] = [];
+
+  for (let i = 0; i < colors.length - 1; i += 1) {
+    const start = colors[i] ?? "#000000";
+    const end = colors[i + 1] ?? start;
+    for (let step = 0; step < stepsPerSegment; step += 1) {
+      const t = step / stepsPerSegment;
+      steps.push(interpolateColor(start, end, t));
+    }
+  }
+
+  steps.push(colors[colors.length - 1] ?? "#000000");
+  return steps;
+}
+
+/**
+ * Get color for a character based on its position in the total text.
+ * Uses interpolated gradient for smooth transitions.
+ */
+function getCharColor(charIndex: number, totalChars: number, gradientSteps: string[]): string {
+  if (totalChars <= 1 || gradientSteps.length === 0) {
+    return gradientSteps[0] ?? "#FFFFFF";
+  }
+
+  // Map character position (0 to totalChars-1) to gradient position (0 to 1)
+  const position = charIndex / (totalChars - 1);
+  const stepIndex = Math.min(
+    Math.floor(position * (gradientSteps.length - 1)),
+    gradientSteps.length - 1
+  );
+
+  return gradientSteps[stepIndex] ?? gradientSteps[0] ?? "#FFFFFF";
+}
+
+// =============================================================================
+// Sub-Components
+// =============================================================================
+
+/**
+ * Single colored character.
+ * Memoized to prevent unnecessary re-renders.
+ */
+interface ColoredCharProps {
+  readonly char: string;
+  readonly color: string;
+}
+
+const ColoredChar = memo(function ColoredChar({
+  char,
+  color,
+}: ColoredCharProps): React.JSX.Element {
+  return <Text color={color}>{char}</Text>;
+});
+
+/**
+ * Blinking cursor component.
+ */
+interface CursorProps {
+  readonly visible: boolean;
+  readonly color: string;
+}
+
+const Cursor = memo(function Cursor({ visible, color }: CursorProps): React.JSX.Element | null {
+  if (!visible) return null;
+  return <Text color={color}>{CURSOR_CHAR}</Text>;
+});
+
+// =============================================================================
+// Main Component
+// =============================================================================
+
+/**
+ * TypeWriterGradient displays text with a typewriter effect.
+ *
+ * Characters appear one by one from left to right, with each character
+ * colored according to its position in the provided gradient.
+ * A blinking cursor appears at the end during typing.
+ *
+ * @example
+ * ```tsx
+ * <TypeWriterGradient
+ *   text={asciiArt}
+ *   speed={200}
+ *   colors={['#8B4513', '#DAA520', '#FFD700']}
+ *   showCursor
+ *   onComplete={() => setTypingDone(true)}
+ * />
+ * ```
+ */
+export const TypeWriterGradient = memo(function TypeWriterGradient({
+  text,
+  speed,
+  colors,
+  onComplete,
+  showCursor = true,
+  initialDelay = 100,
+  mode = "line",
+}: TypeWriterGradientProps): React.JSX.Element {
+  // Split text into lines upfront for line mode
+  const allLines = useMemo(() => text.split("\n"), [text]);
+  const totalLines = allLines.length;
+  const totalChars = text.length;
+
+  // Resolve speed based on mode
+  const effectiveSpeed = speed ?? (mode === "line" ? DEFAULT_LINE_SPEED : DEFAULT_CHAR_SPEED);
+
+  // State for visible content (lines for line mode, chars for char mode)
+  const [visibleCount, setVisibleCount] = useState(0);
+  const [cursorVisible, setCursorVisible] = useState(true);
+  const [isComplete, setIsComplete] = useState(false);
+
+  // Refs for cleanup
+  const typingIntervalRef = useRef<ReturnType<typeof setInterval> | null>(null);
+  const initialDelayRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const completeCalledRef = useRef(false);
+
+  // Pre-compute gradient steps for performance
+  const gradientSteps = useMemo(() => buildGradientSteps(colors, 8), [colors]);
+
+  // Total items to reveal (lines or chars depending on mode)
+  const totalItems = mode === "line" ? totalLines : totalChars;
+
+  // Typing effect with chunk-based rendering
+  useEffect(() => {
+    // Clear any existing intervals
+    if (typingIntervalRef.current) {
+      clearInterval(typingIntervalRef.current);
+    }
+    if (initialDelayRef.current) {
+      clearTimeout(initialDelayRef.current);
+    }
+
+    // Start after initial delay
+    initialDelayRef.current = setTimeout(() => {
+      // Calculate items per frame for chunk-based typing
+      // For line mode: speed=50 lines/sec at 60fps = ~0.8 lines/frame (at least 1)
+      // For char mode: speed=3000 chars/sec at 60fps = ~48 chars/frame
+      const itemsPerFrame = Math.max(1, Math.ceil(effectiveSpeed / (1000 / FRAME_INTERVAL_MS)));
+
+      typingIntervalRef.current = setInterval(() => {
+        setVisibleCount((prev) => {
+          const next = prev + itemsPerFrame;
+
+          // Check completion
+          if (next >= totalItems) {
+            if (typingIntervalRef.current) {
+              clearInterval(typingIntervalRef.current);
+              typingIntervalRef.current = null;
+            }
+            setIsComplete(true);
+            if (!completeCalledRef.current) {
+              completeCalledRef.current = true;
+              // Small delay before calling onComplete to let final render happen
+              setTimeout(() => onComplete?.(), 50);
+            }
+            return totalItems;
+          }
+
+          return next;
+        });
+      }, FRAME_INTERVAL_MS);
+    }, initialDelay);
+
+    return () => {
+      if (typingIntervalRef.current) {
+        clearInterval(typingIntervalRef.current);
+      }
+      if (initialDelayRef.current) {
+        clearTimeout(initialDelayRef.current);
+      }
+    };
+  }, [effectiveSpeed, totalItems, initialDelay, onComplete]);
+
+  // Use global animation context for cursor blink to prevent flickering
+  const { frame, isPaused } = useAnimation();
+
+  // Derive cursor visibility from animation frame instead of independent timer
+  const derivedCursorVisible = useMemo(() => {
+    if (!showCursor || isComplete) return false;
+    // Show cursor when animation is paused (e.g., input focused)
+    if (isPaused) return true;
+    // Toggle every ~4 frames (~500ms blink cycle)
+    return Math.floor(frame / 4) % 2 === 0;
+  }, [frame, isPaused, showCursor, isComplete]);
+
+  // Sync local state with derived value
+  useEffect(() => {
+    setCursorVisible(derivedCursorVisible);
+  }, [derivedCursorVisible]);
+
+  // Build visible lines based on mode
+  const visibleLines = useMemo(() => {
+    if (mode === "line") {
+      // Line mode: show complete lines up to visibleCount
+      return allLines.slice(0, visibleCount);
+    }
+    // Char mode: slice text and split into lines
+    const visibleText = text.slice(0, visibleCount);
+    return visibleText.split("\n");
+  }, [mode, allLines, text, visibleCount]);
+
+  // Calculate visible char count for gradient positioning
+  const visibleCharCount = useMemo(() => {
+    if (mode === "line") {
+      // Sum chars in visible lines + newlines
+      return visibleLines.reduce((acc, line, idx) => acc + line.length + (idx > 0 ? 1 : 0), 0);
+    }
+    return visibleCount;
+  }, [mode, visibleLines, visibleCount]);
+
+  // Get cursor color (color at current position)
+  const cursorColor = useMemo(() => {
+    if (visibleCharCount === 0) return gradientSteps[0] ?? "#FFD700";
+    return getCharColor(visibleCharCount - 1, totalChars, gradientSteps);
+  }, [visibleCharCount, totalChars, gradientSteps]);
+
+  return (
+    <Box flexDirection="column">
+      {visibleLines.map((line, lineIndex) => {
+        // Calculate character offset for this line (for gradient coloring)
+        const lineStartIndex = visibleLines
+          .slice(0, lineIndex)
+          .reduce((acc, l) => acc + l.length + 1, 0);
+        const isLastLine = lineIndex === visibleLines.length - 1;
+        const lineKey = `line-${lineIndex}`;
+
+        return (
+          <Box key={lineKey} flexDirection="row">
+            {line.split("").map((char, charIndex) => {
+              const globalIndex = lineStartIndex + charIndex;
+              const color = getCharColor(globalIndex, totalChars, gradientSteps);
+              const charKey = `char-${globalIndex}`;
+
+              return <ColoredChar key={charKey} char={char} color={color} />;
+            })}
+            {/* Show cursor at end of last line during typing */}
+            {isLastLine && showCursor && !isComplete && (
+              <Cursor visible={cursorVisible} color={cursorColor} />
+            )}
+          </Box>
+        );
+      })}
+    </Box>
+  );
+});
+
+export default TypeWriterGradient;

package/src/tui/components/Banner/index.ts

@@ -0,0 +1,61 @@
+/**
+ * Banner Module
+ *
+ * Exports all banner-related components for the Vellum CLI.
+ *
+ * @module tui/components/Banner
+ */
+
+// ASCII Art definitions
+export {
+  ASCII_VARIANTS,
+  type AsciiVariant,
+  SCROLL_BOTTOM,
+  SCROLL_TOP,
+  selectAsciiArt,
+  VELLUM_LARGE,
+  VELLUM_MEDIUM,
+  VELLUM_MINIMAL,
+  VELLUM_SMALL,
+} from "./AsciiArt.js";
+
+// Main Banner component
+export {
+  Banner,
+  type BannerProps,
+  CompactBanner,
+  HeaderBanner,
+  type HeaderBannerProps,
+  MinimalBanner,
+} from "./Banner.js";
+// Shimmer context for shared timer
+export {
+  ShimmerProvider,
+  type ShimmerProviderProps,
+  useIsInShimmerProvider,
+  useSharedShimmer,
+} from "./ShimmerContext.js";
+
+// Shimmer text component
+export {
+  BannerShimmerText,
+  type BannerShimmerTextProps,
+  interpolateColor,
+  MultiLineShimmer,
+  type MultiLineShimmerProps,
+} from "./ShimmerText.js";
+
+// TypeWriter gradient component
+export {
+  TypeWriterGradient,
+  type TypeWriterGradientProps,
+  type TypeWriterMode,
+} from "./TypeWriterGradient.js";
+
+// Shimmer animation hook
+export {
+  calculateShimmerIntensity,
+  type ShimmerConfig,
+  type ShimmerState,
+  useShimmer,
+} from "./useShimmer.js";

package/src/tui/components/Banner/useShimmer.ts

@@ -0,0 +1,241 @@
+/**
+ * useShimmer Hook
+ *
+ * Provides smooth shimmer/glow animation effect with customizable parameters.
+ * Uses cosine function for smooth transitions.
+ *
+ * @module tui/components/Banner/useShimmer
+ */
+
+import { useEffect, useRef, useState } from "react";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Configuration options for the shimmer animation.
+ */
+export interface ShimmerConfig {
+  /** Duration of one complete shimmer cycle in milliseconds (default: 3000) */
+  readonly cycleDuration?: number;
+  /** Update interval in milliseconds (default: 100) */
+  readonly updateInterval?: number;
+  /** Whether animation is enabled (default: true) */
+  readonly enabled?: boolean;
+  /** Maximum number of cycles before stopping (undefined = infinite) */
+  readonly maxCycles?: number;
+  /** Callback when max cycles reached */
+  readonly onComplete?: () => void;
+}
+
+/**
+ * Return value from the useShimmer hook.
+ */
+export interface ShimmerState {
+  /** Current position of shimmer (0 to 1) */
+  readonly position: number;
+  /** Current intensity at shimmer center (0 to 1) */
+  readonly intensity: number;
+  /** Whether shimmer is currently active */
+  readonly isActive: boolean;
+  /** Pause the shimmer animation */
+  readonly pause: () => void;
+  /** Resume the shimmer animation */
+  readonly resume: () => void;
+  /** Current cycle count (0-based) */
+  readonly cycleCount: number;
+  /** Whether max cycles completed */
+  readonly isComplete: boolean;
+}
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/** Default shimmer cycle duration (3 seconds - slower for smoother effect) */
+const DEFAULT_CYCLE_DURATION = 3000;
+
+/** Default update interval (100ms = 10fps for smoother motion without aggressive redraws) */
+const DEFAULT_UPDATE_INTERVAL = resolveDefaultUpdateInterval();
+
+const SHIMMER_DEBUG_ENABLED =
+  process.env.VELLUM_TUI_SHIMMER_DEBUG === "1" || process.env.VELLUM_TUI_SHIMMER_DEBUG === "true";
+
+function resolveDefaultUpdateInterval(): number {
+  const intervalOverride = Number(process.env.VELLUM_TUI_SHIMMER_INTERVAL_MS);
+  if (Number.isFinite(intervalOverride) && intervalOverride > 0) {
+    return Math.round(intervalOverride);
+  }
+
+  const fpsOverride = Number(process.env.VELLUM_TUI_SHIMMER_FPS);
+  if (Number.isFinite(fpsOverride) && fpsOverride > 0) {
+    return Math.max(16, Math.round(1000 / fpsOverride));
+  }
+
+  return 100;
+}
+
+function debugShimmer(message: string): void {
+  if (!SHIMMER_DEBUG_ENABLED) return;
+  process.stderr.write(`[shimmer] ${message}\n`);
+}
+
+// =============================================================================
+// Hook Implementation
+// =============================================================================
+
+/**
+ * Hook for creating smooth shimmer animations.
+ *
+ * The shimmer effect sweeps from left to right using a cosine function
+ * for smooth acceleration and deceleration at the edges.
+ *
+ * @example
+ * ```tsx
+ * const { position, intensity } = useShimmer({ cycleDuration: 2000 });
+ *
+ * // Use position (0-1) to determine where shimmer highlight is
+ * // Use intensity (0-1) to determine brightness at that position
+ * ```
+ */
+export function useShimmer(config: ShimmerConfig = {}): ShimmerState {
+  const {
+    cycleDuration = DEFAULT_CYCLE_DURATION,
+    updateInterval = DEFAULT_UPDATE_INTERVAL,
+    enabled = true,
+    maxCycles,
+    onComplete,
+  } = config;
+
+  const [position, setPosition] = useState(0);
+  const [isActive, setIsActive] = useState(enabled);
+  const [cycleCount, setCycleCount] = useState(0);
+  const [isComplete, setIsComplete] = useState(false);
+
+  const positionRef = useRef(0);
+  const cycleCountRef = useRef(0);
+  const lastTickRef = useRef<number | null>(null);
+  const lastDebugRef = useRef<number>(0);
+
+  // Track onComplete callback in ref to avoid effect re-runs
+  const onCompleteRef = useRef(onComplete);
+  onCompleteRef.current = onComplete;
+
+  useEffect(() => {
+    if (!isActive || isComplete) return;
+
+    lastTickRef.current = Date.now();
+
+    const timer = setInterval(() => {
+      const now = Date.now();
+      const lastTick = lastTickRef.current ?? now;
+      lastTickRef.current = now;
+
+      const deltaMs = now - lastTick;
+      const step = deltaMs / cycleDuration;
+      let nextPosition = positionRef.current + step;
+
+      if (nextPosition >= 1) {
+        const cyclesCompleted = Math.floor(nextPosition);
+        const updatedCycleCount = cycleCountRef.current + cyclesCompleted;
+        cycleCountRef.current = updatedCycleCount;
+        setCycleCount(updatedCycleCount);
+
+        if (maxCycles !== undefined && updatedCycleCount >= maxCycles) {
+          clearInterval(timer);
+          setIsActive(false);
+          setIsComplete(true);
+          // Set final position to a nice resting state (golden ratio position)
+          positionRef.current = 0.618;
+          setPosition(0.618);
+          onCompleteRef.current?.();
+          return;
+        }
+
+        nextPosition = nextPosition % 1;
+      }
+
+      positionRef.current = nextPosition;
+      setPosition(nextPosition);
+
+      if (SHIMMER_DEBUG_ENABLED) {
+        const lastDebug = lastDebugRef.current;
+        if (now - lastDebug >= 1000) {
+          lastDebugRef.current = now;
+          debugShimmer(
+            `deltaMs=${deltaMs.toFixed(1)} position=${nextPosition.toFixed(3)} cycle=${cycleCountRef.current}`
+          );
+        }
+      }
+    }, updateInterval);
+
+    return () => clearInterval(timer);
+  }, [isActive, cycleDuration, updateInterval, maxCycles, isComplete]);
+
+  useEffect(() => {
+    if (enabled && !isComplete) {
+      setIsActive(true);
+      return;
+    }
+
+    if (!enabled) {
+      setIsActive(false);
+    }
+  }, [enabled, isComplete]);
+
+  // Calculate intensity using cosine for smooth falloff
+  // Peak intensity at current position, smoothly fading around it
+  const intensity = Math.cos(position * Math.PI * 2 - Math.PI) * 0.5 + 0.5;
+
+  const pause = () => setIsActive(false);
+  const resume = () => {
+    if (!isComplete) setIsActive(true);
+  };
+
+  return {
+    position,
+    intensity,
+    isActive,
+    pause,
+    resume,
+    cycleCount,
+    isComplete,
+  };
+}
+
+/**
+ * Calculate shimmer intensity at a specific character position.
+ *
+ * @param charIndex - Index of the character (0-based)
+ * @param totalChars - Total number of characters
+ * @param shimmerPosition - Current shimmer position (0-1)
+ * @param shimmerWidth - Width of shimmer effect (0-1, default 0.15)
+ * @returns Intensity value from 0 to 1
+ */
+export function calculateShimmerIntensity(
+  charIndex: number,
+  totalChars: number,
+  shimmerPosition: number,
+  shimmerWidth: number = 0.15
+): number {
+  if (totalChars === 0) return 0;
+
+  // Normalize character position to 0-1 range
+  const charPosition = charIndex / totalChars;
+
+  // Calculate distance from shimmer center
+  const distance = Math.abs(charPosition - shimmerPosition);
+
+  // Handle wrap-around (shimmer at edge affects chars on opposite side)
+  const wrappedDistance = Math.min(distance, 1 - distance);
+
+  // If outside shimmer width, no effect
+  if (wrappedDistance > shimmerWidth) return 0;
+
+  // Cosine falloff for smooth intensity gradient
+  const normalizedDistance = wrappedDistance / shimmerWidth;
+  const intensity = Math.cos(normalizedDistance * Math.PI * 0.5);
+
+  return Math.max(0, intensity);
+}

package/src/tui/components/ChatView.tsx

@@ -0,0 +1,11 @@
+import { Box } from "ink";
+
+// Define props for the ChatView component based on what will be moved from app.tsx
+
+export function ChatView() {
+  return (
+    <Box flexDirection="column" flexGrow={1}>
+      {/* MessageList and EnhancedCommandInput will be moved here */}
+    </Box>
+  );
+}