@butlerw/vellum 0.1.0

package/src/tui/hooks/useLineBuffer.ts

@@ -0,0 +1,356 @@
+/**
+ * Line Buffer Hook
+ *
+ * Pre-wraps messages into line arrays for efficient scroll calculations.
+ * Uses a ring buffer to limit memory usage with very long conversations.
+ *
+ * Key features:
+ * - Pre-wraps text at specified terminal width
+ * - Caches wrap results by message ID + width
+ * - Ring buffer discards oldest entries when maxLines exceeded
+ * - O(1) line range queries via index lookup
+ *
+ * @module tui/hooks/useLineBuffer
+ */
+
+import { useMemo, useRef } from "react";
+import stringWidth from "string-width";
+import type { Message } from "../context/MessagesContext.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * A single entry in the line buffer representing one message's wrapped lines.
+ */
+export interface LineBufferEntry {
+  /** Original message ID */
+  readonly messageId: string;
+  /** Pre-wrapped lines (each line fits within wrapWidth) */
+  readonly lines: readonly string[];
+  /** Width used for wrapping (for cache invalidation) */
+  readonly wrapWidth: number;
+}
+
+/**
+ * State returned by useLineBuffer hook.
+ */
+export interface LineBufferState {
+  /** All entries in the buffer */
+  readonly entries: readonly LineBufferEntry[];
+  /** Total line count across all entries */
+  readonly totalLines: number;
+  /**
+   * Get lines in range [start, end).
+   * Uses 0-based line indexing across all messages.
+   */
+  getVisibleLines(start: number, end: number): string[];
+}
+
+/**
+ * Options for useLineBuffer hook.
+ */
+export interface UseLineBufferOptions {
+  /** Terminal width for wrapping */
+  readonly width: number;
+  /** Max lines to keep (ring buffer). Default: 10000 */
+  readonly maxLines?: number;
+  /** Content padding to subtract from width. Default: 4 */
+  readonly contentPadding?: number;
+}
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/** Default maximum lines to keep in buffer */
+const DEFAULT_MAX_LINES = 10000;
+
+/** Default content padding for wrapping */
+const DEFAULT_CONTENT_PADDING = 4;
+
+// =============================================================================
+// Pure Functions
+// =============================================================================
+
+/**
+ * Wrap a single line of text to fit within a given width.
+ * Uses string-width for accurate CJK/Emoji/ANSI handling.
+ *
+ * @param text - Text to wrap (single logical line, no newlines)
+ * @param width - Maximum display width per line
+ * @returns Array of wrapped lines
+ */
+export function wrapLine(text: string, width: number): string[] {
+  const safeWidth = Math.max(1, width);
+
+  // Empty or whitespace-only lines
+  if (!text || text.trim().length === 0) {
+    return [text || ""];
+  }
+
+  const result: string[] = [];
+  let currentLine = "";
+  let currentWidth = 0;
+
+  // Process character by character for accurate width handling
+  // This handles CJK (2-width), emoji, and combining characters correctly
+  const chars = [...text]; // Spread to handle multi-byte chars
+
+  for (const char of chars) {
+    const charWidth = stringWidth(char);
+
+    // Would adding this char exceed the width?
+    if (currentWidth + charWidth > safeWidth && currentLine.length > 0) {
+      result.push(currentLine);
+      currentLine = char;
+      currentWidth = charWidth;
+    } else {
+      currentLine += char;
+      currentWidth += charWidth;
+    }
+  }
+
+  // Don't forget the last line
+  if (currentLine.length > 0) {
+    result.push(currentLine);
+  }
+
+  // Handle edge case: empty result
+  if (result.length === 0) {
+    result.push("");
+  }
+
+  return result;
+}
+
+/**
+ * Wrap multi-line text (with \n) to fit within width.
+ *
+ * @param text - Text to wrap (may contain newlines)
+ * @param width - Maximum display width per line
+ * @returns Array of wrapped lines
+ */
+export function wrapText(text: string, width: number): string[] {
+  if (!text) {
+    return [""];
+  }
+
+  const lines = text.split("\n");
+  const result: string[] = [];
+
+  for (const line of lines) {
+    const wrapped = wrapLine(line, width);
+    result.push(...wrapped);
+  }
+
+  return result;
+}
+
+/**
+ * Extract displayable content from a message for line buffering.
+ *
+ * @param message - Message to extract content from
+ * @returns Combined text content (content + thinking + tool info)
+ */
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: Message content extraction with multiple optional fields
+function extractMessageContent(message: Message): string {
+  const parts: string[] = [];
+
+  // Message header line
+  const role =
+    message.role === "user" ? "You" : message.role === "assistant" ? "Vellum" : message.role;
+  parts.push(`${role}:`);
+
+  // Thinking content (if present)
+  if (message.thinking && message.thinking.length > 0) {
+    parts.push("  Thinking...");
+    // Indent thinking content
+    const thinkingLines = message.thinking.split("\n");
+    for (const line of thinkingLines) {
+      parts.push(`    ${line}`);
+    }
+  }
+
+  // Main content
+  if (message.content) {
+    const contentLines = message.content.split("\n");
+    for (const line of contentLines) {
+      parts.push(`  ${line}`);
+    }
+  } else if (!message.isStreaming) {
+    parts.push("  (empty)");
+  }
+
+  // Tool calls (simplified representation)
+  if (message.toolCalls && message.toolCalls.length > 0) {
+    for (const tool of message.toolCalls) {
+      const status = tool.status === "completed" ? "+" : tool.status === "error" ? "x" : "-";
+      parts.push(`  ${status} ${tool.name}`);
+    }
+  }
+
+  return parts.join("\n");
+}
+
+/**
+ * Create a LineBufferEntry for a message.
+ *
+ * @param message - Message to wrap
+ * @param width - Terminal width
+ * @param contentPadding - Padding to subtract from width
+ * @returns LineBufferEntry with wrapped lines
+ */
+function createEntry(message: Message, width: number, contentPadding: number): LineBufferEntry {
+  const contentWidth = Math.max(10, width - contentPadding);
+  const content = extractMessageContent(message);
+  const lines = wrapText(content, contentWidth);
+
+  return {
+    messageId: message.id,
+    lines,
+    wrapWidth: width,
+  };
+}
+
+// =============================================================================
+// Cache Key Generation
+// =============================================================================
+
+/**
+ * Generate a cache key for a message + width combination.
+ */
+function getCacheKey(messageId: string, width: number): string {
+  return `${messageId}:${width}`;
+}
+
+// =============================================================================
+// Hook Implementation
+// =============================================================================
+
+/**
+ * useLineBuffer - Pre-wraps messages into line arrays for efficient scrolling.
+ *
+ * This hook maintains a cache of wrapped lines per message, re-wrapping only
+ * when width changes or new messages arrive. Uses a ring buffer to limit
+ * memory usage.
+ *
+ * @example
+ * ```tsx
+ * const lineBuffer = useLineBuffer(messages, {
+ *   width: terminalWidth,
+ *   maxLines: 5000,
+ * });
+ *
+ * // Get visible lines for current scroll position
+ * const visibleLines = lineBuffer.getVisibleLines(
+ *   scrollState.offsetFromBottom,
+ *   scrollState.offsetFromBottom + viewportHeight
+ * );
+ * ```
+ *
+ * @param messages - Array of messages to buffer
+ * @param options - Buffer configuration options
+ * @returns LineBufferState with entries and query methods
+ */
+export function useLineBuffer(
+  messages: readonly Message[],
+  options: UseLineBufferOptions
+): LineBufferState {
+  const { width, maxLines = DEFAULT_MAX_LINES, contentPadding = DEFAULT_CONTENT_PADDING } = options;
+
+  // Cache for wrapped entries: Map<cacheKey, LineBufferEntry>
+  const cacheRef = useRef<Map<string, LineBufferEntry>>(new Map());
+
+  // Compute entries with memoization
+  const entries = useMemo(() => {
+    const cache = cacheRef.current;
+    const result: LineBufferEntry[] = [];
+    let totalLineCount = 0;
+
+    // Build entries, using cache when available
+    for (const message of messages) {
+      const cacheKey = getCacheKey(message.id, width);
+      let entry = cache.get(cacheKey);
+
+      // Cache miss or width changed - recompute
+      if (!entry || entry.wrapWidth !== width) {
+        entry = createEntry(message, width, contentPadding);
+        cache.set(cacheKey, entry);
+      }
+
+      result.push(entry);
+      totalLineCount += entry.lines.length;
+    }
+
+    // Ring buffer: trim oldest entries if exceeding maxLines
+    while (totalLineCount > maxLines && result.length > 1) {
+      const removed = result.shift();
+      if (removed) {
+        totalLineCount -= removed.lines.length;
+        // Clean cache for removed entry
+        cache.delete(getCacheKey(removed.messageId, width));
+      }
+    }
+
+    // Clean stale cache entries (messages no longer in list)
+    const activeKeys = new Set(result.map((e) => getCacheKey(e.messageId, width)));
+    for (const key of cache.keys()) {
+      if (!activeKeys.has(key)) {
+        cache.delete(key);
+      }
+    }
+
+    return result;
+  }, [messages, width, maxLines, contentPadding]);
+
+  // Compute total lines
+  const totalLines = useMemo(() => {
+    return entries.reduce((sum, entry) => sum + entry.lines.length, 0);
+  }, [entries]);
+
+  // Build line index for O(1) range queries
+  // lineIndex[i] = { entryIndex, lineOffset } for global line i
+  const lineIndex = useMemo(() => {
+    const index: Array<{ entryIndex: number; lineOffset: number }> = [];
+    let entryIdx = 0;
+    for (const entry of entries) {
+      for (let lineOffset = 0; lineOffset < entry.lines.length; lineOffset++) {
+        index.push({ entryIndex: entryIdx, lineOffset });
+      }
+      entryIdx++;
+    }
+    return index;
+  }, [entries]);
+
+  // Get visible lines in range [start, end)
+  const getVisibleLines = useMemo(() => {
+    return (start: number, end: number): string[] => {
+      const result: string[] = [];
+      const safeStart = Math.max(0, start);
+      const safeEnd = Math.min(totalLines, end);
+
+      for (let i = safeStart; i < safeEnd; i++) {
+        const loc = lineIndex[i];
+        if (loc) {
+          const entry = entries[loc.entryIndex];
+          if (entry) {
+            const line = entry.lines[loc.lineOffset];
+            if (line !== undefined) {
+              result.push(line);
+            }
+          }
+        }
+      }
+
+      return result;
+    };
+  }, [entries, lineIndex, totalLines]);
+
+  return {
+    entries,
+    totalLines,
+    getVisibleLines,
+  };
+}

package/src/tui/hooks/useMentionAutocomplete.ts

@@ -0,0 +1,235 @@
+/**
+ * useMentionAutocomplete Hook
+ *
+ * Manages @ mention autocomplete state and logic.
+ * Detects @ patterns in input and provides suggestions for types or values.
+ *
+ * @module tui/hooks/useMentionAutocomplete
+ */
+
+import {
+  MENTION_PARTIAL_REGEX,
+  MENTION_VALUE_PARTIAL_REGEX,
+  type MentionType,
+  mentionRequiresValue,
+} from "@vellum/shared";
+import { useCallback, useMemo } from "react";
+import type { MentionAutocompleteMode } from "../components/Input/MentionAutocomplete.js";
+import { useFileSuggestions } from "./useFileSuggestions.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * State of the mention autocomplete system.
+ */
+export interface MentionAutocompleteState {
+  /** Whether autocomplete should be visible */
+  readonly visible: boolean;
+  /** Whether autocomplete should capture keyboard input */
+  readonly active: boolean;
+  /** Current mode: type selection or value completion */
+  readonly mode: MentionAutocompleteMode;
+  /** The detected mention type (in value mode) */
+  readonly mentionType: MentionType | null;
+  /** The partial input to filter against */
+  readonly filterText: string;
+  /** Start position of the mention in the input */
+  readonly mentionStart: number;
+}
+
+/**
+ * Options for useMentionAutocomplete.
+ */
+export interface UseMentionAutocompleteOptions {
+  /** Current working directory for file suggestions */
+  readonly cwd: string;
+}
+
+/**
+ * Result of the useMentionAutocomplete hook.
+ */
+export interface UseMentionAutocompleteResult {
+  /** Current autocomplete state */
+  readonly state: MentionAutocompleteState;
+  /** File suggestions (for file/folder mentions) */
+  readonly fileSuggestions: ReturnType<typeof useFileSuggestions>;
+  /** Handle selection of a type or value */
+  readonly handleSelect: (value: string, mode: MentionAutocompleteMode) => string;
+  /** Get completed input value after selection */
+  readonly getCompletedValue: (
+    currentValue: string,
+    selectedValue: string,
+    mode: MentionAutocompleteMode
+  ) => string;
+}
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+/**
+ * Detect @ mention pattern in input and determine autocomplete state.
+ */
+function detectMentionPattern(value: string): MentionAutocompleteState {
+  const defaultState: MentionAutocompleteState = {
+    visible: false,
+    active: false,
+    mode: "type",
+    mentionType: null,
+    filterText: "",
+    mentionStart: -1,
+  };
+
+  if (!value.includes("@")) {
+    return defaultState;
+  }
+
+  // Check for @type: pattern (value mode)
+  const valueMatch = value.match(MENTION_VALUE_PARTIAL_REGEX);
+  if (valueMatch) {
+    const mentionType = valueMatch[1] as MentionType;
+    const partialValue = valueMatch[2] || "";
+    const fullMatch = valueMatch[0];
+    const mentionStart = value.lastIndexOf(fullMatch);
+
+    return {
+      visible: true,
+      active: true,
+      mode: "value",
+      mentionType,
+      filterText: partialValue,
+      mentionStart,
+    };
+  }
+
+  // Check for @ or @partial pattern (type mode)
+  const typeMatch = value.match(MENTION_PARTIAL_REGEX);
+  if (typeMatch) {
+    const partialType = typeMatch[1] || "";
+    const atIndex = value.lastIndexOf("@");
+
+    // Check if @ is at start or after whitespace
+    if (atIndex === 0 || /\s/.test(value[atIndex - 1] || "")) {
+      return {
+        visible: true,
+        active: true,
+        mode: "type",
+        mentionType: null,
+        filterText: partialType,
+        mentionStart: atIndex,
+      };
+    }
+  }
+
+  return defaultState;
+}
+
+// =============================================================================
+// Hook Implementation
+// =============================================================================
+
+/**
+ * Hook to manage @ mention autocomplete.
+ *
+ * @param inputValue - Current input value
+ * @param options - Configuration options
+ * @returns Autocomplete state and handlers
+ *
+ * @example
+ * ```tsx
+ * const { state, fileSuggestions, handleSelect } = useMentionAutocomplete(
+ *   inputValue,
+ *   { cwd: "/project" }
+ * );
+ *
+ * if (state.visible) {
+ *   return (
+ *     <MentionAutocomplete
+ *       mode={state.mode}
+ *       input={state.filterText}
+ *       mentionType={state.mentionType}
+ *       fileSuggestions={fileSuggestions.suggestions}
+ *       onSelect={(v, m) => setValue(handleSelect(v, m))}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export function useMentionAutocomplete(
+  inputValue: string,
+  options: UseMentionAutocompleteOptions
+): UseMentionAutocompleteResult {
+  // Detect mention pattern in input
+  const state = useMemo(() => detectMentionPattern(inputValue), [inputValue]);
+
+  // Get file suggestions when in value mode for file/folder types
+  const shouldLoadFiles =
+    state.visible &&
+    state.mode === "value" &&
+    (state.mentionType === "file" || state.mentionType === "folder");
+
+  const fileSuggestions = useFileSuggestions(shouldLoadFiles ? state.filterText : "", {
+    cwd: options.cwd,
+    includeFiles: state.mentionType === "file",
+    includeDirectories: true, // Always include directories for navigation
+  });
+
+  /**
+   * Get the completed input value after a selection.
+   */
+  const getCompletedValue = useCallback(
+    (currentValue: string, selectedValue: string, mode: MentionAutocompleteMode): string => {
+      if (state.mentionStart === -1) return currentValue;
+
+      const beforeMention = currentValue.slice(0, state.mentionStart);
+
+      if (mode === "type") {
+        // Type was selected, build the mention prefix
+        const needsValue = mentionRequiresValue(selectedValue as MentionType);
+        if (needsValue) {
+          // Add colon and prepare for value input
+          return `${beforeMention}@${selectedValue}:`;
+        }
+        // Standalone mention, add space
+        return `${beforeMention}@${selectedValue} `;
+      }
+
+      // Value was selected
+      if (state.mentionType) {
+        // Check if selected value is a directory
+        const isDir = fileSuggestions.suggestions.find(
+          (s) => s.path === selectedValue
+        )?.isDirectory;
+
+        if (isDir) {
+          // Directory selected, allow further navigation
+          return `${beforeMention}@${state.mentionType}:${selectedValue}/`;
+        }
+        // File selected, complete the mention
+        return `${beforeMention}@${state.mentionType}:${selectedValue} `;
+      }
+
+      return currentValue;
+    },
+    [state.mentionStart, state.mentionType, fileSuggestions.suggestions]
+  );
+
+  /**
+   * Handle selection and return the new input value.
+   */
+  const handleSelect = useCallback(
+    (selectedValue: string, mode: MentionAutocompleteMode): string => {
+      return getCompletedValue(inputValue, selectedValue, mode);
+    },
+    [inputValue, getCompletedValue]
+  );
+
+  return {
+    state,
+    fileSuggestions,
+    handleSelect,
+    getCompletedValue,
+  };
+}