@butlerw/vellum 0.1.0

package/src/tui/context/AppContext.tsx

@@ -0,0 +1,349 @@
+/**
+ * Application Context and State Management
+ *
+ * Provides global application state for the Vellum TUI including
+ * mode, loading state, error handling, and focus management.
+ *
+ * @module tui/context/AppContext
+ */
+
+import React, {
+  createContext,
+  type Dispatch,
+  type ReactNode,
+  useCallback,
+  useContext,
+  useMemo,
+  useReducer,
+} from "react";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Application mode representing the current operational state
+ */
+export type AppMode = "idle" | "loading" | "streaming" | "waiting" | "error";
+
+/**
+ * Focusable areas in the TUI
+ */
+export type FocusedArea = "input" | "messages" | "tools" | "status";
+
+/**
+ * Application state interface
+ */
+export interface AppState {
+  /** Current application mode */
+  readonly mode: AppMode;
+  /** Whether the application is in a loading state */
+  readonly loading: boolean;
+  /** Current error, if any */
+  readonly error: Error | null;
+  /** Whether vim mode is enabled for input */
+  readonly vimMode: boolean;
+  /** Currently focused area of the UI */
+  readonly focusedArea: FocusedArea;
+}
+
+/**
+ * Initial application state
+ */
+const initialState: AppState = {
+  mode: "idle",
+  loading: false,
+  error: null,
+  vimMode: false,
+  focusedArea: "input",
+};
+
+// =============================================================================
+// Actions (Discriminated Union)
+// =============================================================================
+
+/**
+ * Set the application mode
+ */
+export interface SetModeAction {
+  readonly type: "SET_MODE";
+  readonly mode: AppMode;
+}
+
+/**
+ * Set the loading state
+ */
+export interface SetLoadingAction {
+  readonly type: "SET_LOADING";
+  readonly loading: boolean;
+}
+
+/**
+ * Set an error
+ */
+export interface SetErrorAction {
+  readonly type: "SET_ERROR";
+  readonly error: Error | null;
+}
+
+/**
+ * Toggle vim mode
+ */
+export interface ToggleVimModeAction {
+  readonly type: "TOGGLE_VIM_MODE";
+}
+
+/**
+ * Set vim mode explicitly
+ */
+export interface SetVimModeAction {
+  readonly type: "SET_VIM_MODE";
+  readonly vimMode: boolean;
+}
+
+/**
+ * Set the focused area
+ */
+export interface SetFocusedAreaAction {
+  readonly type: "SET_FOCUSED_AREA";
+  readonly focusedArea: FocusedArea;
+}
+
+/**
+ * Reset the application state to initial values
+ */
+export interface ResetAction {
+  readonly type: "RESET";
+}
+
+/**
+ * Discriminated union of all application actions
+ */
+export type AppAction =
+  | SetModeAction
+  | SetLoadingAction
+  | SetErrorAction
+  | ToggleVimModeAction
+  | SetVimModeAction
+  | SetFocusedAreaAction
+  | ResetAction;
+
+// =============================================================================
+// Reducer
+// =============================================================================
+
+/**
+ * Application state reducer
+ *
+ * @param state - Current application state
+ * @param action - Action to apply
+ * @returns New application state
+ */
+function appReducer(state: AppState, action: AppAction): AppState {
+  switch (action.type) {
+    case "SET_MODE":
+      return {
+        ...state,
+        mode: action.mode,
+        // Automatically update loading based on mode
+        loading: action.mode === "loading" || action.mode === "streaming",
+        // Clear error when transitioning away from error state
+        error: action.mode === "error" ? state.error : null,
+      };
+
+    case "SET_LOADING":
+      return {
+        ...state,
+        loading: action.loading,
+      };
+
+    case "SET_ERROR":
+      return {
+        ...state,
+        error: action.error,
+        mode: action.error !== null ? "error" : state.mode,
+      };
+
+    case "TOGGLE_VIM_MODE":
+      return {
+        ...state,
+        vimMode: !state.vimMode,
+      };
+
+    case "SET_VIM_MODE":
+      return {
+        ...state,
+        vimMode: action.vimMode,
+      };
+
+    case "SET_FOCUSED_AREA":
+      return {
+        ...state,
+        focusedArea: action.focusedArea,
+      };
+
+    case "RESET":
+      return initialState;
+
+    default:
+      // Exhaustive check - TypeScript will error if a case is missing
+      return state;
+  }
+}
+
+// =============================================================================
+// Context
+// =============================================================================
+
+/**
+ * Context value interface
+ */
+export interface AppContextValue {
+  /** Current application state */
+  readonly state: AppState;
+  /** Dispatch function for state updates */
+  readonly dispatch: Dispatch<AppAction>;
+  /** Reset state to initial values */
+  readonly reset: () => void;
+}
+
+/**
+ * React context for application state
+ *
+ * Initialized as undefined to detect usage outside provider
+ */
+const AppContext = createContext<AppContextValue | undefined>(undefined);
+
+// =============================================================================
+// Hook
+// =============================================================================
+
+/**
+ * Hook to access the application state and dispatch
+ *
+ * Must be used within an AppProvider component.
+ *
+ * @returns The current app context value with state, dispatch, and reset
+ * @throws Error if used outside AppProvider
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { state, dispatch, reset } = useApp();
+ *
+ *   // Read state
+ *   if (state.loading) {
+ *     return <Text>Loading...</Text>;
+ *   }
+ *
+ *   // Dispatch actions
+ *   const handleStart = () => {
+ *     dispatch({ type: 'SET_MODE', mode: 'loading' });
+ *   };
+ *
+ *   // Reset to initial state
+ *   const handleReset = () => reset();
+ *
+ *   return <Box>...</Box>;
+ * }
+ * ```
+ */
+export function useApp(): AppContextValue {
+  const context = useContext(AppContext);
+
+  if (context === undefined) {
+    throw new Error(
+      "useApp must be used within an AppProvider. " +
+        "Ensure your component is wrapped in <AppProvider>."
+    );
+  }
+
+  return context;
+}
+
+// =============================================================================
+// Provider Props
+// =============================================================================
+
+/**
+ * Props for the AppProvider component
+ */
+export interface AppProviderProps {
+  /**
+   * Initial state overrides
+   *
+   * Partial state that will be merged with the default initial state
+   */
+  readonly initialState?: Partial<AppState>;
+
+  /**
+   * Children to render within the app context
+   */
+  readonly children: ReactNode;
+}
+
+// =============================================================================
+// Provider Component
+// =============================================================================
+
+/**
+ * Application state provider component
+ *
+ * Provides application state context to all child components, enabling
+ * access to the current state and dispatch via the useApp hook.
+ *
+ * @example
+ * ```tsx
+ * // Using default initial state
+ * <AppProvider>
+ *   <App />
+ * </AppProvider>
+ *
+ * // Using custom initial state
+ * <AppProvider initialState={{ vimMode: true }}>
+ *   <App />
+ * </AppProvider>
+ * ```
+ */
+export function AppProvider({
+  initialState: initialStateOverrides,
+  children,
+}: AppProviderProps): React.JSX.Element {
+  // State management with useReducer
+  // Initial state is computed once via lazy initializer
+  const [state, dispatch] = useReducer(
+    appReducer,
+    initialStateOverrides,
+    (overrides): AppState => ({
+      ...initialState,
+      ...overrides,
+    })
+  );
+
+  /**
+   * Reset state to initial values
+   */
+  const reset = useCallback((): void => {
+    dispatch({ type: "RESET" });
+  }, []);
+
+  /**
+   * Memoized context value
+   */
+  const contextValue = useMemo<AppContextValue>(
+    () => ({
+      state,
+      dispatch,
+      reset,
+    }),
+    [state, reset]
+  );
+
+  return <AppContext value={contextValue}>{children}</AppContext>;
+}
+
+// =============================================================================
+// Exports
+// =============================================================================
+
+export { AppContext, initialState };

package/src/tui/context/BracketedPasteContext.tsx

@@ -0,0 +1,372 @@
+/**
+ * Bracketed Paste Context
+ *
+ * React context for managing bracketed paste mode state and providing
+ * paste event callbacks to child components.
+ *
+ * @module tui/context/BracketedPasteContext
+ */
+
+import { useStdin } from "ink";
+import type { ReactNode } from "react";
+import { createContext, useCallback, useContext, useEffect, useRef, useState } from "react";
+import {
+  disableBracketedPaste,
+  enableBracketedPaste,
+  PASTE_END,
+  PASTE_START,
+} from "../utils/bracketedPaste.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Handler function for paste events
+ */
+export type PasteHandler = (content: string) => void;
+
+/**
+ * Context value for bracketed paste
+ */
+interface BracketedPasteContextValue {
+  /**
+   * Register a paste event handler
+   * @returns Unsubscribe function
+   */
+  subscribe: (handler: PasteHandler) => () => void;
+
+  /**
+   * Whether a paste operation is currently in progress
+   */
+  isPasting: boolean;
+}
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/** Timeout for incomplete paste sequences (30 seconds) */
+const PASTE_TIMEOUT_MS = 30_000;
+
+// =============================================================================
+// Context
+// =============================================================================
+
+const BracketedPasteContext = createContext<BracketedPasteContextValue | null>(null);
+
+// =============================================================================
+// Provider
+// =============================================================================
+
+interface BracketedPasteProviderProps {
+  children: ReactNode;
+  /**
+   * Whether bracketed paste should be enabled
+   * @default true
+   */
+  enabled?: boolean;
+}
+
+/**
+ * Provider component that enables bracketed paste mode and dispatches
+ * paste events to subscribers.
+ *
+ * This provider intercepts stdin data events to detect paste sequences
+ * before Ink's useInput processes them. When a paste is detected, the
+ * content is buffered and dispatched as a single event to all subscribers.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   return (
+ *     <BracketedPasteProvider>
+ *       <MyComponents />
+ *     </BracketedPasteProvider>
+ *   );
+ * }
+ * ```
+ */
+export function BracketedPasteProvider({ children, enabled = true }: BracketedPasteProviderProps) {
+  const { stdin } = useStdin();
+  const [isPasting, setIsPasting] = useState(false);
+
+  // Subscribers for paste events
+  const subscribersRef = useRef<Set<PasteHandler>>(new Set());
+
+  // Buffer for accumulating paste content
+  const pasteBufferRef = useRef<string>("");
+
+  // Timeout handle for incomplete pastes
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  // Track paste state without triggering re-renders (for emit override)
+  const isPastingRef = useRef(false);
+
+  /**
+   * Subscribe to paste events
+   */
+  const subscribe = useCallback((handler: PasteHandler) => {
+    subscribersRef.current.add(handler);
+    return () => {
+      subscribersRef.current.delete(handler);
+    };
+  }, []);
+
+  /**
+   * Dispatch paste content to all subscribers
+   */
+  const dispatchPaste = useCallback((content: string) => {
+    if (content.length === 0) return;
+
+    for (const handler of subscribersRef.current) {
+      try {
+        handler(content);
+      } catch {
+        // Ignore handler errors
+      }
+    }
+  }, []);
+
+  /**
+   * Clear paste state
+   */
+  const clearPasteState = useCallback(() => {
+    isPastingRef.current = false;
+    setIsPasting(false);
+    pasteBufferRef.current = "";
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+    }
+  }, []);
+
+  /**
+   * Handle paste start sequence found in data
+   */
+  const handlePasteStart = useCallback(
+    (afterStart: string) => {
+      isPastingRef.current = true;
+      setIsPasting(true);
+      pasteBufferRef.current = "";
+
+      // Set timeout for incomplete paste
+      if (timeoutRef.current) clearTimeout(timeoutRef.current);
+      timeoutRef.current = setTimeout(() => {
+        if (pasteBufferRef.current.length > 0) {
+          dispatchPaste(pasteBufferRef.current);
+        }
+        clearPasteState();
+      }, PASTE_TIMEOUT_MS);
+
+      // Check if paste end is in this chunk
+      const endIdx = afterStart.indexOf(PASTE_END);
+      if (endIdx !== -1) {
+        // Complete paste in single data event
+        dispatchPaste(afterStart.slice(0, endIdx));
+        clearPasteState();
+      } else {
+        // Partial paste - buffer content
+        pasteBufferRef.current = afterStart;
+      }
+    },
+    [dispatchPaste, clearPasteState]
+  );
+
+  /**
+   * Handle data while paste is in progress
+   */
+  const handlePasteInProgress = useCallback(
+    (str: string) => {
+      const endIdx = str.indexOf(PASTE_END);
+      if (endIdx !== -1) {
+        // Found end - complete the paste
+        dispatchPaste(pasteBufferRef.current + str.slice(0, endIdx));
+        clearPasteState();
+      } else {
+        // Still pasting - accumulate
+        pasteBufferRef.current += str;
+      }
+    },
+    [dispatchPaste, clearPasteState]
+  );
+
+  /**
+   * Set up stdin listener for paste detection with emit override.
+   * This intercepts data events BEFORE they reach Ink, preventing
+   * paste sequences from triggering character-by-character rendering.
+   *
+   * In test environments (non-TTY), we fall back to prependListener which
+   * is less complete but doesn't interfere with test mocks.
+   */
+  useEffect(() => {
+    if (!enabled || !stdin) return;
+
+    // Check if this is a real TTY (not a test mock)
+    // In tests, stdin is often a mock that doesn't support emit override well
+    const isRealTty = stdin.isTTY === true && typeof stdin.setRawMode === "function";
+
+    // Enable bracketed paste mode (only for real TTYs)
+    if (isRealTty) {
+      enableBracketedPaste();
+    }
+
+    if (isRealTty) {
+      // Real TTY: Use emit override for complete blocking
+      const originalEmit = stdin.emit.bind(stdin);
+
+      /**
+       * Override emit to intercept and block paste data.
+       * This ensures paste sequences never reach Ink's input handlers.
+       */
+      // biome-ignore lint/suspicious/noExplicitAny: stdin.emit has complex overloaded signature
+      // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: Paste sequence state machine with multiple transitions
+      (stdin as any).emit = (event: string | symbol, ...args: unknown[]): boolean => {
+        // Only intercept 'data' events
+        if (event !== "data") {
+          return originalEmit(event, ...args);
+        }
+
+        const data = args[0];
+        const str = typeof data === "string" ? data : (data as Buffer).toString("utf8");
+
+        // Check for paste start
+        const startIdx = str.indexOf(PASTE_START);
+        if (startIdx !== -1 && !isPastingRef.current) {
+          // Found paste start - handle it and block from Ink
+          // Extract any data before the paste sequence (let it through)
+          const beforePaste = str.slice(0, startIdx);
+          if (beforePaste.length > 0) {
+            originalEmit("data", beforePaste);
+          }
+          // Process paste start (this sets isPastingRef.current = true)
+          handlePasteStart(str.slice(startIdx + PASTE_START.length));
+          // Block the paste data from reaching Ink
+          return true;
+        }
+
+        // If we're in a paste, accumulate and block
+        if (isPastingRef.current) {
+          handlePasteInProgress(str);
+          // Block paste data from reaching Ink
+          return true;
+        }
+
+        // Normal data - pass through to Ink
+        return originalEmit(event, ...args);
+      };
+
+      // Cleanup for real TTY
+      return () => {
+        // biome-ignore lint/suspicious/noExplicitAny: restoring original emit
+        (stdin as any).emit = originalEmit;
+        clearPasteState();
+        disableBracketedPaste();
+      };
+    }
+
+    // Test environment: Use prependListener (less complete but test-compatible)
+    const handleData = (data: Buffer | string) => {
+      const str = typeof data === "string" ? data : data.toString("utf8");
+
+      // Check for paste start
+      const startIdx = str.indexOf(PASTE_START);
+      if (startIdx !== -1 && !isPastingRef.current) {
+        handlePasteStart(str.slice(startIdx + PASTE_START.length));
+        return;
+      }
+
+      // If we're in a paste, look for end or accumulate
+      if (isPastingRef.current) {
+        handlePasteInProgress(str);
+      }
+    };
+
+    stdin.prependListener("data", handleData);
+
+    return () => {
+      stdin.removeListener("data", handleData);
+      clearPasteState();
+    };
+  }, [enabled, stdin, handlePasteStart, handlePasteInProgress, clearPasteState]);
+
+  // Handle process exit signals
+  useEffect(() => {
+    if (!enabled) return;
+
+    const cleanup = () => {
+      disableBracketedPaste();
+    };
+
+    process.on("SIGINT", cleanup);
+    process.on("SIGTERM", cleanup);
+    process.on("exit", cleanup);
+
+    return () => {
+      process.off("SIGINT", cleanup);
+      process.off("SIGTERM", cleanup);
+      process.off("exit", cleanup);
+    };
+  }, [enabled]);
+
+  const value: BracketedPasteContextValue = {
+    subscribe,
+    isPasting,
+  };
+
+  return <BracketedPasteContext.Provider value={value}>{children}</BracketedPasteContext.Provider>;
+}
+
+// =============================================================================
+// Hook
+// =============================================================================
+
+/**
+ * Hook to access the bracketed paste context.
+ *
+ * @throws Error if used outside of BracketedPasteProvider
+ */
+export function useBracketedPasteContext(): BracketedPasteContextValue {
+  const context = useContext(BracketedPasteContext);
+  if (!context) {
+    throw new Error("useBracketedPasteContext must be used within BracketedPasteProvider");
+  }
+  return context;
+}
+
+/**
+ * Hook to subscribe to paste events.
+ *
+ * The provided callback will be called whenever a paste operation completes.
+ * The callback receives the full pasted content as a single string.
+ *
+ * @example
+ * ```tsx
+ * function MyInput({ value, onChange }) {
+ *   // Handle paste events
+ *   usePasteHandler((pastedText) => {
+ *     onChange(value + pastedText);
+ *   });
+ *
+ *   return <Text>{value}</Text>;
+ * }
+ * ```
+ */
+export function usePasteHandler(handler: PasteHandler): void {
+  const context = useContext(BracketedPasteContext);
+
+  useEffect(() => {
+    if (!context) return;
+    return context.subscribe(handler);
+  }, [context, handler]);
+}
+
+/**
+ * Hook to check if a paste operation is in progress.
+ *
+ * @returns true if paste is in progress, false otherwise, or undefined if outside provider
+ */
+export function useIsPasting(): boolean {
+  const context = useContext(BracketedPasteContext);
+  return context?.isPasting ?? false;
+}