@butlerw/vellum 0.1.0

package/src/tui/hooks/useSidebarPanelData.ts

@@ -0,0 +1,115 @@
+/**
+ * Sidebar panel data loaders.
+ *
+ * The MemoryPanel and TodoPanel are presentational components; the data is loaded
+ * by the app shell. This hook provides:
+ * - initial loading
+ * - refresh on panel open
+ * - refresh after relevant tool executions
+ */
+
+import type { MemoryEntry } from "@vellum/core";
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { TodoItemData } from "../components/TodoItem.js";
+import type { ToolExecution } from "../context/ToolsContext.js";
+
+export type SidebarContent = "todo" | "memory" | "tools" | "mcp" | "help" | "snapshots";
+
+export type SidebarPanelDataOptions = {
+  readonly sidebarVisible: boolean;
+  readonly sidebarContent: SidebarContent;
+  readonly executions: readonly ToolExecution[];
+
+  readonly loadTodos: () => Promise<readonly TodoItemData[]>;
+  readonly loadMemories: () => Promise<readonly MemoryEntry[]>;
+};
+
+export type SidebarPanelData = {
+  readonly todoItems: readonly TodoItemData[];
+  readonly memoryEntries: readonly MemoryEntry[];
+  readonly refreshTodos: () => void;
+  readonly refreshMemories: () => void;
+};
+
+export function getLastCompletedToolExecutionId(
+  executions: readonly ToolExecution[]
+): string | undefined {
+  for (let i = executions.length - 1; i >= 0; i -= 1) {
+    const exec = executions[i];
+    if (exec?.status === "complete") return exec.id;
+  }
+  return undefined;
+}
+
+export function shouldRefreshFromToolExecution(execution: ToolExecution | undefined): {
+  readonly refreshTodos: boolean;
+  readonly refreshMemories: boolean;
+} {
+  const toolName = execution?.toolName;
+  if (!toolName) return { refreshTodos: false, refreshMemories: false };
+
+  return {
+    refreshTodos: toolName === "todo_manage",
+    refreshMemories: toolName === "save_memory" || toolName === "recall_memory",
+  };
+}
+
+export function useSidebarPanelData(options: SidebarPanelDataOptions): SidebarPanelData {
+  const { sidebarVisible, sidebarContent, executions, loadTodos, loadMemories } = options;
+
+  const [todoItems, setTodoItems] = useState<readonly TodoItemData[]>([]);
+  const [memoryEntries, setMemoryEntries] = useState<readonly MemoryEntry[]>([]);
+
+  const refreshTodos = useCallback(() => {
+    void loadTodos()
+      .then(setTodoItems)
+      .catch(() => {
+        setTodoItems([]);
+      });
+  }, [loadTodos]);
+
+  const refreshMemories = useCallback(() => {
+    void loadMemories()
+      .then(setMemoryEntries)
+      .catch(() => {
+        setMemoryEntries([]);
+      });
+  }, [loadMemories]);
+
+  // Initial load (best-effort).
+  useEffect(() => {
+    refreshTodos();
+    refreshMemories();
+  }, [refreshMemories, refreshTodos]);
+
+  // Refresh when the relevant panel is opened.
+  useEffect(() => {
+    if (!sidebarVisible) return;
+
+    if (sidebarContent === "todo") {
+      refreshTodos();
+    }
+
+    if (sidebarContent === "memory") {
+      refreshMemories();
+    }
+  }, [refreshMemories, refreshTodos, sidebarContent, sidebarVisible]);
+
+  // Refresh when relevant tool executions complete.
+  const lastHandledExecutionIdRef = useRef<string | undefined>(undefined);
+
+  useEffect(() => {
+    const executionId = getLastCompletedToolExecutionId(executions);
+    if (!executionId || executionId === lastHandledExecutionIdRef.current) return;
+
+    const execution = executions.find((e) => e.id === executionId);
+    const decision = shouldRefreshFromToolExecution(execution);
+
+    if (decision.refreshTodos) refreshTodos();
+    if (decision.refreshMemories) refreshMemories();
+
+    lastHandledExecutionIdRef.current = executionId;
+  }, [executions, refreshMemories, refreshTodos]);
+
+  return { todoItems, memoryEntries, refreshTodos, refreshMemories };
+}

package/src/tui/hooks/useSmoothScroll.ts

@@ -0,0 +1,202 @@
+/**
+ * Smooth Scroll Hook
+ *
+ * Provides smooth animated scrolling with easing functions.
+ * Uses setInterval-based updates (terminal-safe, no requestAnimationFrame).
+ *
+ * @module tui/hooks/useSmoothScroll
+ */
+
+import { useCallback, useRef, useState } from "react";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Easing function type: maps progress (0-1) to eased value (0-1)
+ */
+export type EasingFunction = (t: number) => number;
+
+/**
+ * Configuration for smooth scroll behavior
+ */
+export interface SmoothScrollConfig {
+  /** Animation duration in ms (default: 150) */
+  readonly duration?: number;
+  /** Easing function (default: easeOutCubic) */
+  readonly easing?: EasingFunction;
+  /** Frame interval in ms (default: 16 ~= 60fps) */
+  readonly frameInterval?: number;
+}
+
+/**
+ * Return type for useSmoothScroll hook
+ */
+export interface UseSmoothScrollReturn {
+  /** Current interpolated scroll position */
+  readonly position: number;
+  /** Whether currently animating */
+  readonly isAnimating: boolean;
+  /** Start smooth scroll to target position */
+  readonly scrollTo: (target: number) => void;
+  /** Immediately jump to position (cancel any animation) */
+  readonly jumpTo: (target: number) => void;
+  /** Cancel current animation */
+  readonly cancel: () => void;
+}
+
+// =============================================================================
+// Easing Functions
+// =============================================================================
+
+/**
+ * Standard easing functions for scroll animations
+ */
+export const easings = {
+  /** Linear - no easing */
+  linear: (t: number): number => t,
+
+  /** Ease out cubic - fast start, slow end (default) */
+  easeOutCubic: (t: number): number => 1 - (1 - t) ** 3,
+
+  /** Ease out quad - gentler ease out */
+  easeOutQuad: (t: number): number => 1 - (1 - t) ** 2,
+
+  /** Ease in out quad - smooth both ends */
+  easeInOutQuad: (t: number): number => (t < 0.5 ? 2 * t * t : 1 - (-2 * t + 2) ** 2 / 2),
+
+  /** Ease out expo - very fast start */
+  easeOutExpo: (t: number): number => (t === 1 ? 1 : 1 - 2 ** (-10 * t)),
+} as const;
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+const DEFAULT_CONFIG: Required<SmoothScrollConfig> = {
+  duration: 150,
+  easing: easings.easeOutCubic,
+  frameInterval: 16, // ~60fps
+};
+
+// =============================================================================
+// Hook
+// =============================================================================
+
+/**
+ * Hook for smooth animated scrolling
+ *
+ * @param initialPosition - Starting scroll position
+ * @param config - Optional animation configuration
+ * @returns Smooth scroll state and controls
+ *
+ * @example
+ * ```tsx
+ * const { position, scrollTo, isAnimating } = useSmoothScroll(0);
+ *
+ * // Smooth scroll to line 50
+ * scrollTo(50);
+ *
+ * // Use position for rendering
+ * <VirtualizedList offsetFromBottom={position} />
+ * ```
+ */
+export function useSmoothScroll(
+  initialPosition: number,
+  config: SmoothScrollConfig = {}
+): UseSmoothScrollReturn {
+  // Merge config with defaults
+  const { duration, easing, frameInterval } = { ...DEFAULT_CONFIG, ...config };
+
+  // State
+  const [position, setPosition] = useState(initialPosition);
+  const [isAnimating, setIsAnimating] = useState(false);
+
+  // Refs for animation state
+  const animationRef = useRef<ReturnType<typeof setInterval> | null>(null);
+  const startPositionRef = useRef(initialPosition);
+  const targetPositionRef = useRef(initialPosition);
+  const startTimeRef = useRef(0);
+
+  /**
+   * Cancel any running animation
+   */
+  const cancel = useCallback(() => {
+    if (animationRef.current) {
+      clearInterval(animationRef.current);
+      animationRef.current = null;
+    }
+    setIsAnimating(false);
+  }, []);
+
+  /**
+   * Immediately jump to position (no animation)
+   */
+  const jumpTo = useCallback(
+    (target: number) => {
+      cancel();
+      setPosition(target);
+      startPositionRef.current = target;
+      targetPositionRef.current = target;
+    },
+    [cancel]
+  );
+
+  /**
+   * Start smooth scroll to target position
+   */
+  const scrollTo = useCallback(
+    (target: number) => {
+      // Cancel any existing animation
+      cancel();
+
+      // Get current position as start
+      const start = position;
+
+      // Skip animation if already at target or very close
+      if (Math.abs(target - start) < 0.5) {
+        setPosition(target);
+        return;
+      }
+
+      // Store animation parameters
+      startPositionRef.current = start;
+      targetPositionRef.current = target;
+      startTimeRef.current = Date.now();
+
+      setIsAnimating(true);
+
+      // Animation tick
+      const tick = () => {
+        const elapsed = Date.now() - startTimeRef.current;
+        const progress = Math.min(elapsed / duration, 1);
+        const easedProgress = easing(progress);
+
+        const newPosition =
+          startPositionRef.current +
+          (targetPositionRef.current - startPositionRef.current) * easedProgress;
+
+        setPosition(newPosition);
+
+        if (progress >= 1) {
+          // Animation complete - snap to exact target
+          setPosition(targetPositionRef.current);
+          cancel();
+        }
+      };
+
+      // Start animation loop
+      animationRef.current = setInterval(tick, frameInterval);
+    },
+    [cancel, position, duration, easing, frameInterval]
+  );
+
+  return {
+    position,
+    isAnimating,
+    scrollTo,
+    jumpTo,
+    cancel,
+  };
+}

package/src/tui/hooks/useSnapshots.ts

@@ -0,0 +1,300 @@
+/**
+ * useSnapshots Hook
+ *
+ * Provides access to the Snapshot system for managing file state checkpoints.
+ * Uses the shadow Git repository in .vellum/.git-shadow/ for tracking.
+ *
+ * @module tui/hooks/useSnapshots
+ */
+
+import { Snapshot, SnapshotError, SnapshotErrorCode, type SnapshotInfo } from "@vellum/core";
+import { useCallback, useEffect, useRef, useState } from "react";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Result of a restore operation.
+ */
+export interface RestoreResult {
+  /** Whether the restore succeeded */
+  readonly success: boolean;
+  /** List of files restored */
+  readonly files: readonly string[];
+  /** Error message if failed */
+  readonly error?: string;
+}
+
+/**
+ * Return type for the useSnapshots hook.
+ */
+export interface UseSnapshotsResult {
+  /** List of available snapshots (newest first) */
+  readonly snapshots: readonly SnapshotInfo[];
+  /** Whether snapshots are currently loading */
+  readonly isLoading: boolean;
+  /** Error message if any operation failed */
+  readonly error: string | null;
+  /** Whether the snapshot system is initialized */
+  readonly isInitialized: boolean;
+  /** Refresh the list of snapshots */
+  readonly refresh: () => Promise<void>;
+  /** Restore files to a specific snapshot */
+  readonly restore: (hash: string) => Promise<RestoreResult>;
+  /** Get diff between current state and a snapshot */
+  readonly diff: (hash: string) => Promise<string>;
+  /** Take a new snapshot */
+  readonly take: (message?: string) => Promise<string>;
+  /** Initialize the snapshot system if needed */
+  readonly initialize: () => Promise<boolean>;
+}
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/** Maximum number of snapshots to show */
+const MAX_SNAPSHOTS = 10;
+
+// =============================================================================
+// Hook Implementation
+// =============================================================================
+
+/**
+ * Hook for managing file state snapshots.
+ *
+ * Provides methods to list, create, restore, and diff snapshots.
+ * The snapshot system uses a shadow Git repository to track file states
+ * independently of the user's main repository.
+ *
+ * @param workingDir - The working directory path (defaults to cwd)
+ * @returns Snapshot management functions and state
+ *
+ * @example
+ * ```tsx
+ * function SnapshotPanel() {
+ *   const {
+ *     snapshots,
+ *     isLoading,
+ *     error,
+ *     refresh,
+ *     restore,
+ *     take
+ *   } = useSnapshots();
+ *
+ *   if (isLoading) return <Text>Loading...</Text>;
+ *
+ *   return (
+ *     <Box flexDirection="column">
+ *       {snapshots.map(s => (
+ *         <Text key={s.hash}>{s.hash.slice(0, 7)} - {s.message}</Text>
+ *       ))}
+ *     </Box>
+ *   );
+ * }
+ * ```
+ */
+export function useSnapshots(workingDir?: string): UseSnapshotsResult {
+  const resolvedDir = workingDir ?? process.cwd();
+
+  // State
+  const [snapshots, setSnapshots] = useState<readonly SnapshotInfo[]>([]);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [isInitialized, setIsInitialized] = useState(false);
+
+  // Ref to track if we're mounted
+  const mountedRef = useRef(true);
+
+  /**
+   * Initialize the snapshot system.
+   */
+  const initialize = useCallback(async (): Promise<boolean> => {
+    try {
+      const result = await Snapshot.init(resolvedDir);
+      if (result.ok) {
+        if (mountedRef.current) {
+          setIsInitialized(true);
+        }
+        return true;
+      }
+      if (mountedRef.current) {
+        setError(result.error.message);
+      }
+      return false;
+    } catch (err) {
+      if (mountedRef.current) {
+        setError(err instanceof Error ? err.message : "Failed to initialize snapshots");
+      }
+      return false;
+    }
+  }, [resolvedDir]);
+
+  /**
+   * Refresh the list of snapshots.
+   */
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: Snapshot refresh requires multiple state checks and error handling paths
+  const refresh = useCallback(async (): Promise<void> => {
+    if (!mountedRef.current) return;
+
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      // Check if initialized
+      const initialized = await Snapshot.isInitialized(resolvedDir);
+      if (!initialized) {
+        if (mountedRef.current) {
+          setSnapshots([]);
+          setIsInitialized(false);
+          setIsLoading(false);
+        }
+        return;
+      }
+
+      if (mountedRef.current) {
+        setIsInitialized(true);
+      }
+
+      // List snapshots
+      const result = await Snapshot.listSnapshots(resolvedDir);
+
+      if (!mountedRef.current) return;
+
+      if (result.ok) {
+        // Limit to MAX_SNAPSHOTS
+        setSnapshots(result.value.slice(0, MAX_SNAPSHOTS));
+      } else {
+        // Handle not initialized error gracefully
+        if (result.error.code === SnapshotErrorCode.NOT_INITIALIZED) {
+          setSnapshots([]);
+          setIsInitialized(false);
+        } else {
+          setError(result.error.message);
+        }
+      }
+    } catch (err) {
+      if (mountedRef.current) {
+        setError(err instanceof Error ? err.message : "Failed to load snapshots");
+      }
+    } finally {
+      if (mountedRef.current) {
+        setIsLoading(false);
+      }
+    }
+  }, [resolvedDir]);
+
+  /**
+   * Restore files to a specific snapshot.
+   */
+  const restore = useCallback(
+    async (hash: string): Promise<RestoreResult> => {
+      try {
+        const result = await Snapshot.restore(resolvedDir, hash);
+
+        if (result.ok) {
+          // Refresh after successful restore
+          void refresh();
+          return {
+            success: true,
+            files: result.value,
+          };
+        }
+
+        return {
+          success: false,
+          files: [],
+          error: result.error.message,
+        };
+      } catch (err) {
+        return {
+          success: false,
+          files: [],
+          error: err instanceof Error ? err.message : "Failed to restore snapshot",
+        };
+      }
+    },
+    [resolvedDir, refresh]
+  );
+
+  /**
+   * Get diff between current state and a snapshot.
+   */
+  const diff = useCallback(
+    async (hash: string): Promise<string> => {
+      try {
+        const result = await Snapshot.diff(resolvedDir, hash);
+
+        if (result.ok) {
+          return result.value || "(no changes)";
+        }
+
+        return `Error: ${result.error.message}`;
+      } catch (err) {
+        return `Error: ${err instanceof Error ? err.message : "Failed to get diff"}`;
+      }
+    },
+    [resolvedDir]
+  );
+
+  /**
+   * Take a new snapshot.
+   */
+  const take = useCallback(
+    async (message?: string): Promise<string> => {
+      try {
+        // Ensure initialized
+        const initialized = await Snapshot.isInitialized(resolvedDir);
+        if (!initialized) {
+          const initResult = await Snapshot.init(resolvedDir);
+          if (!initResult.ok) {
+            throw new SnapshotError(initResult.error.message, SnapshotErrorCode.OPERATION_FAILED);
+          }
+          if (mountedRef.current) {
+            setIsInitialized(true);
+          }
+        }
+
+        // Track all files
+        const result = await Snapshot.track(resolvedDir, [], message ?? "Manual checkpoint");
+
+        if (result.ok) {
+          // Refresh after successful snapshot
+          void refresh();
+          return result.value;
+        }
+
+        throw new SnapshotError(result.error.message, result.error.code);
+      } catch (err) {
+        if (err instanceof SnapshotError) {
+          throw err;
+        }
+        throw new Error(err instanceof Error ? err.message : "Failed to take snapshot");
+      }
+    },
+    [resolvedDir, refresh]
+  );
+
+  // Initial load
+  useEffect(() => {
+    mountedRef.current = true;
+    void refresh();
+
+    return () => {
+      mountedRef.current = false;
+    };
+  }, [refresh]);
+
+  return {
+    snapshots,
+    isLoading,
+    error,
+    isInitialized,
+    refresh,
+    restore,
+    diff,
+    take,
+    initialize,
+  };
+}

package/src/tui/hooks/useStateAndRef.ts

@@ -0,0 +1,50 @@
+/**
+ * useStateAndRef Hook
+ *
+ * Combines useState and useRef to provide both reactive state and
+ * a stable ref for use in callbacks without stale closures.
+ *
+ * Pattern from Gemini CLI - solves the problem where callbacks
+ * capture stale state values.
+ *
+ * @module tui/hooks/useStateAndRef
+ */
+
+import { useCallback, useRef, useState } from "react";
+
+/**
+ * Combines useState and useRef to provide both reactive state and
+ * a stable ref for use in callbacks without stale closures.
+ *
+ * Pattern from Gemini CLI - solves the problem where callbacks
+ * capture stale state values.
+ *
+ * @example
+ * const [messages, messagesRef, setMessages] = useStateAndRef<Message[]>([]);
+ *
+ * // In callbacks, read from ref for latest value:
+ * const handleText = useCallback((text) => {
+ *   const current = messagesRef.current; // Always latest
+ *   setMessages([...current, { text }]);
+ * }, []); // Empty deps = stable callback
+ *
+ * @param initialValue - Initial state value
+ * @returns Tuple of [state, ref, setState]
+ */
+export function useStateAndRef<T>(
+  initialValue: T
+): readonly [T, React.RefObject<T>, (newValue: T | ((prev: T) => T)) => void] {
+  const [state, setState] = useState<T>(initialValue);
+  const ref = useRef<T>(initialValue);
+
+  const setStateAndRef = useCallback((newValue: T | ((prev: T) => T)) => {
+    const resolved =
+      typeof newValue === "function" ? (newValue as (prev: T) => T)(ref.current) : newValue;
+    ref.current = resolved;
+    setState(resolved);
+  }, []);
+
+  return [state, ref, setStateAndRef] as const;
+}
+
+export default useStateAndRef;