@butlerw/vellum 0.1.0

package/src/tui/components/common/VirtualizedList/hooks/useScrollAnchor.ts

@@ -0,0 +1,290 @@
+/**
+ * useScrollAnchor Hook
+ *
+ * Manages scroll position as an anchor (index + offset) for stability
+ * during content changes. This approach is more robust than pure pixel-based
+ * scrolling when items resize or new items are added.
+ *
+ * @module tui/components/common/VirtualizedList/hooks/useScrollAnchor
+ */
+
+import { useCallback, useLayoutEffect, useRef, useState } from "react";
+import { SCROLL_TO_ITEM_END, type ScrollAnchor } from "../types.js";
+
+/**
+ * Props for the useScrollAnchor hook.
+ */
+export interface UseScrollAnchorProps {
+  /** Number of data items */
+  readonly dataLength: number;
+  /** Array of cumulative offsets for each item */
+  readonly offsets: readonly number[];
+  /** Array of measured or estimated heights */
+  readonly heights: readonly number[];
+  /** Total height of all content */
+  readonly totalHeight: number;
+  /** Height of the visible container */
+  readonly containerHeight: number;
+  /** Initial scroll index */
+  readonly initialScrollIndex?: number;
+  /** Initial offset within the scroll index */
+  readonly initialScrollOffsetInIndex?: number;
+}
+
+/**
+ * Return type for the useScrollAnchor hook.
+ */
+export interface UseScrollAnchorReturn {
+  /** Current scroll anchor */
+  readonly scrollAnchor: ScrollAnchor;
+  /** Set the scroll anchor directly */
+  readonly setScrollAnchor: (anchor: ScrollAnchor) => void;
+  /** Whether currently sticking to bottom (auto-scroll enabled) */
+  readonly isStickingToBottom: boolean;
+  /** Set sticking to bottom state */
+  readonly setIsStickingToBottom: (value: boolean) => void;
+  /** Computed pixel scroll position from anchor */
+  readonly scrollTop: number;
+  /** Get anchor for a given scroll position */
+  readonly getAnchorForScrollTop: (scrollTop: number) => ScrollAnchor;
+}
+
+/**
+ * Find the last index where predicate returns true.
+ */
+function findLastIndex<T>(
+  array: readonly T[],
+  predicate: (value: T, index: number) => boolean
+): number {
+  for (let i = array.length - 1; i >= 0; i--) {
+    const item = array[i];
+    if (item !== undefined && predicate(item, i)) {
+      return i;
+    }
+  }
+  return -1;
+}
+
+/**
+ * Hook for managing scroll position as an anchor.
+ *
+ * @param props - Configuration for scroll anchor behavior
+ * @returns Scroll anchor state and utilities
+ */
+export function useScrollAnchor(props: UseScrollAnchorProps): UseScrollAnchorReturn {
+  const {
+    dataLength,
+    offsets,
+    heights,
+    totalHeight,
+    containerHeight,
+    initialScrollIndex,
+    initialScrollOffsetInIndex,
+  } = props;
+
+  // Initialize scroll anchor based on initial props
+  const [scrollAnchor, setScrollAnchor] = useState<ScrollAnchor>(() => {
+    const scrollToEnd =
+      initialScrollIndex === SCROLL_TO_ITEM_END ||
+      (typeof initialScrollIndex === "number" &&
+        initialScrollIndex >= dataLength - 1 &&
+        initialScrollOffsetInIndex === SCROLL_TO_ITEM_END);
+
+    if (scrollToEnd) {
+      return {
+        index: dataLength > 0 ? dataLength - 1 : 0,
+        offset: SCROLL_TO_ITEM_END,
+      };
+    }
+
+    if (typeof initialScrollIndex === "number") {
+      return {
+        index: Math.max(0, Math.min(dataLength - 1, initialScrollIndex)),
+        offset: initialScrollOffsetInIndex ?? 0,
+      };
+    }
+
+    return { index: 0, offset: 0 };
+  });
+
+  // Track whether we're sticking to bottom (auto-scroll)
+  const [isStickingToBottom, setIsStickingToBottom] = useState(() => {
+    const scrollToEnd =
+      initialScrollIndex === SCROLL_TO_ITEM_END ||
+      (typeof initialScrollIndex === "number" &&
+        initialScrollIndex >= dataLength - 1 &&
+        initialScrollOffsetInIndex === SCROLL_TO_ITEM_END);
+    return scrollToEnd;
+  });
+
+  // Track if initial scroll has been set
+  const isInitialScrollSet = useRef(false);
+
+  // Convert scroll position to anchor
+  // FIX: Added bounds validation to prevent invalid anchor indices
+  const getAnchorForScrollTop = useCallback(
+    (scrollTop: number): ScrollAnchor => {
+      // Handle edge cases
+      if (dataLength === 0) {
+        return { index: 0, offset: 0 };
+      }
+      if (scrollTop <= 0) {
+        return { index: 0, offset: 0 };
+      }
+
+      const index = findLastIndex(offsets, (offset) => offset <= scrollTop);
+      if (index === -1) {
+        return { index: 0, offset: 0 };
+      }
+
+      // FIX: Ensure index is within valid bounds
+      const safeIndex = Math.max(0, Math.min(dataLength - 1, index));
+      const offsetValue = offsets[safeIndex] ?? 0;
+      const itemHeight = heights[safeIndex] ?? 0;
+
+      // FIX: Clamp offset to be within the item's height
+      const rawOffset = scrollTop - offsetValue;
+      const safeOffset = Math.max(0, Math.min(itemHeight, rawOffset));
+
+      return { index: safeIndex, offset: safeOffset };
+    },
+    [offsets, dataLength, heights]
+  );
+
+  // Compute pixel scroll position from anchor
+  const scrollTop = (() => {
+    const offset = offsets[scrollAnchor.index];
+    if (typeof offset !== "number") {
+      return 0;
+    }
+
+    if (scrollAnchor.offset === SCROLL_TO_ITEM_END) {
+      const itemHeight = heights[scrollAnchor.index] ?? 0;
+      return Math.max(0, offset + itemHeight - containerHeight);
+    }
+
+    return Math.max(0, offset + scrollAnchor.offset);
+  })();
+
+  // Track previous values for auto-scroll logic
+  const prevDataLength = useRef(dataLength);
+  const prevTotalHeight = useRef(totalHeight);
+  const prevScrollTop = useRef(scrollTop);
+  const prevContainerHeight = useRef(containerHeight);
+
+  // Handle auto-scroll and anchor adjustments
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: Scroll anchor logic with multiple edge cases
+  useLayoutEffect(() => {
+    const contentPreviouslyFit = prevTotalHeight.current <= prevContainerHeight.current;
+    const wasScrolledToBottomPixels =
+      prevScrollTop.current >= prevTotalHeight.current - prevContainerHeight.current - 1;
+    const wasAtBottom = contentPreviouslyFit || wasScrolledToBottomPixels;
+
+    // If the user was at the bottom, they are now sticking
+    if (wasAtBottom && scrollTop >= prevScrollTop.current) {
+      setIsStickingToBottom(true);
+    }
+
+    const listGrew = dataLength > prevDataLength.current;
+    const containerChanged = prevContainerHeight.current !== containerHeight;
+    // Detect content height growth (triggers during streaming output)
+    const contentHeightGrew = totalHeight > prevTotalHeight.current;
+
+    // Scroll to end conditions:
+    // 1. List grew AND we were already at the bottom (or sticking)
+    // 2. We are sticking to bottom AND container size changed
+    // 3. We are sticking to bottom AND content height grew (streaming content)
+    if (
+      (listGrew && (isStickingToBottom || wasAtBottom)) ||
+      (isStickingToBottom && containerChanged) ||
+      (isStickingToBottom && contentHeightGrew)
+    ) {
+      setScrollAnchor({
+        index: dataLength > 0 ? dataLength - 1 : 0,
+        offset: SCROLL_TO_ITEM_END,
+      });
+      if (!isStickingToBottom) {
+        setIsStickingToBottom(true);
+      }
+    }
+    // List shrunk or scroll position is invalid
+    else if (
+      (scrollAnchor.index >= dataLength || scrollTop > totalHeight - containerHeight) &&
+      dataLength > 0
+    ) {
+      const newScrollTop = Math.max(0, totalHeight - containerHeight);
+      setScrollAnchor(getAnchorForScrollTop(newScrollTop));
+    } else if (dataLength === 0) {
+      // List is empty, reset to top
+      setScrollAnchor({ index: 0, offset: 0 });
+    }
+
+    // Update refs for next render
+    prevDataLength.current = dataLength;
+    prevTotalHeight.current = totalHeight;
+    prevScrollTop.current = scrollTop;
+    prevContainerHeight.current = containerHeight;
+  }, [
+    dataLength,
+    totalHeight,
+    scrollTop,
+    containerHeight,
+    scrollAnchor.index,
+    getAnchorForScrollTop,
+    isStickingToBottom,
+  ]);
+
+  // Handle initial scroll position
+  useLayoutEffect(() => {
+    if (
+      isInitialScrollSet.current ||
+      offsets.length <= 1 ||
+      totalHeight <= 0 ||
+      containerHeight <= 0
+    ) {
+      return;
+    }
+
+    if (typeof initialScrollIndex === "number") {
+      const scrollToEnd =
+        initialScrollIndex === SCROLL_TO_ITEM_END ||
+        (initialScrollIndex >= dataLength - 1 && initialScrollOffsetInIndex === SCROLL_TO_ITEM_END);
+
+      if (scrollToEnd) {
+        setScrollAnchor({
+          index: dataLength - 1,
+          offset: SCROLL_TO_ITEM_END,
+        });
+        setIsStickingToBottom(true);
+        isInitialScrollSet.current = true;
+        return;
+      }
+
+      const index = Math.max(0, Math.min(dataLength - 1, initialScrollIndex));
+      const offset = initialScrollOffsetInIndex ?? 0;
+      const newScrollTop = (offsets[index] ?? 0) + offset;
+
+      const clampedScrollTop = Math.max(0, Math.min(totalHeight - containerHeight, newScrollTop));
+
+      setScrollAnchor(getAnchorForScrollTop(clampedScrollTop));
+      isInitialScrollSet.current = true;
+    }
+  }, [
+    initialScrollIndex,
+    initialScrollOffsetInIndex,
+    offsets,
+    totalHeight,
+    containerHeight,
+    getAnchorForScrollTop,
+    dataLength,
+  ]);
+
+  return {
+    scrollAnchor,
+    setScrollAnchor,
+    isStickingToBottom,
+    setIsStickingToBottom,
+    scrollTop,
+    getAnchorForScrollTop,
+  };
+}

package/src/tui/components/common/VirtualizedList/hooks/useVirtualization.ts

@@ -0,0 +1,340 @@
+/**
+ * useVirtualization Hook
+ *
+ * Manages height calculations, measurement, and visible range computation
+ * for virtualized list rendering.
+ *
+ * @module tui/components/common/VirtualizedList/hooks/useVirtualization
+ */
+
+import type { DOMElement } from "ink";
+import { measureElement } from "ink";
+import { useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+
+/**
+ * Props for the useVirtualization hook.
+ */
+export interface UseVirtualizationProps {
+  /** Number of data items */
+  readonly dataLength: number;
+  /** Function or fixed value for estimated item height */
+  readonly estimatedItemHeight: number | ((index: number) => number);
+  /** Current scroll position in pixels */
+  readonly scrollTop: number;
+  /** Height of the visible container */
+  readonly containerHeight: number;
+}
+
+/**
+ * Minimum viewport dimensions to prevent degenerate cases.
+ */
+export const MIN_VIEWPORT_HEIGHT = 8;
+export const MIN_VIEWPORT_WIDTH = 20;
+
+/**
+ * Return type for the useVirtualization hook.
+ */
+export interface UseVirtualizationReturn {
+  /** Array of measured or estimated heights */
+  readonly heights: readonly number[];
+  /** Array of cumulative offsets */
+  readonly offsets: readonly number[];
+  /** Total height of all content */
+  readonly totalHeight: number;
+  /** First visible item index */
+  readonly startIndex: number;
+  /** Last visible item index */
+  readonly endIndex: number;
+  /** Height of spacer above visible items */
+  readonly topSpacerHeight: number;
+  /** Height of spacer below visible items */
+  readonly bottomSpacerHeight: number;
+  /** Ref callback for item elements */
+  readonly itemRefCallback: (index: number, el: DOMElement | null) => void;
+  /** Ref for the container element */
+  readonly containerRef: React.RefObject<DOMElement | null>;
+  /** Measured container height */
+  readonly measuredContainerHeight: number;
+  /** True if the last item exceeds viewport height (needs clipping) */
+  readonly isOversize: boolean;
+}
+
+/**
+ * Find the last index where predicate returns true.
+ */
+function findLastIndex<T>(
+  array: readonly T[],
+  predicate: (value: T, index: number) => boolean
+): number {
+  for (let i = array.length - 1; i >= 0; i--) {
+    const item = array[i];
+    if (item !== undefined && predicate(item, i)) {
+      return i;
+    }
+  }
+  return -1;
+}
+
+/**
+ * Minimum valid height for any item to prevent invisible/zero-height items
+ */
+const MIN_ITEM_HEIGHT = 1;
+
+/**
+ * Get estimated height for an index using the estimator.
+ * FIX: Always returns at least MIN_ITEM_HEIGHT to prevent zero/negative heights
+ * that can cause infinite scroll loops or invisible items.
+ */
+function getEstimatedHeight(
+  estimator: number | ((index: number) => number),
+  index: number
+): number {
+  const estimated = typeof estimator === "function" ? estimator(index) : estimator;
+  // FIX: Ensure height is always valid (positive integer)
+  return Math.max(MIN_ITEM_HEIGHT, Math.round(estimated));
+}
+
+/**
+ * Hook for managing virtualization state.
+ *
+ * @param props - Configuration for virtualization
+ * @returns Virtualization state and utilities
+ */
+export function useVirtualization(props: UseVirtualizationProps): UseVirtualizationReturn {
+  const { dataLength, estimatedItemHeight, scrollTop, containerHeight } = props;
+
+  // Apply minimum viewport clamping to prevent degenerate cases
+  const safeContainerHeight = Math.max(MIN_VIEWPORT_HEIGHT, containerHeight);
+
+  // Container ref for measuring viewport
+  const containerRef = useRef<DOMElement | null>(null);
+  const [measuredContainerHeight, setMeasuredContainerHeight] = useState(safeContainerHeight);
+
+  // Item refs for measurement
+  const itemRefs = useRef<Array<DOMElement | null>>([]);
+
+  // Heights cache - measured or estimated
+  const [heights, setHeights] = useState<number[]>(() => {
+    const initial: number[] = [];
+    for (let i = 0; i < dataLength; i++) {
+      initial[i] = getEstimatedHeight(estimatedItemHeight, i);
+    }
+    return initial;
+  });
+
+  // Calculate offsets and total height
+  const { totalHeight, offsets } = useMemo(() => {
+    const offsets: number[] = [0];
+    let totalHeight = 0;
+    for (let i = 0; i < dataLength; i++) {
+      const height = heights[i] ?? getEstimatedHeight(estimatedItemHeight, i);
+      totalHeight += height;
+      offsets.push(totalHeight);
+    }
+    return { totalHeight, offsets };
+  }, [heights, dataLength, estimatedItemHeight]);
+
+  // Sync heights array with data length changes
+  useEffect(() => {
+    setHeights((prevHeights) => {
+      if (dataLength === prevHeights.length) {
+        return prevHeights;
+      }
+
+      const newHeights = [...prevHeights];
+      if (dataLength < prevHeights.length) {
+        // Shrink
+        newHeights.length = dataLength;
+      } else {
+        // Grow - add estimated heights for new items
+        for (let i = prevHeights.length; i < dataLength; i++) {
+          newHeights[i] = getEstimatedHeight(estimatedItemHeight, i);
+        }
+      }
+      return newHeights;
+    });
+  }, [dataLength, estimatedItemHeight]);
+
+  // Calculate visible range with OVERFLOW GUARD
+  // This ensures we NEVER render more items than fit in the viewport
+  // FIX: Improved off-by-one handling - findLastIndex returns the index where offset <= scrollTop
+  // We don't need to subtract 1; that was causing negative indices and blank areas
+  const foundStartIndex = findLastIndex(offsets, (offset) => offset <= scrollTop);
+  // If no offset found (scrollTop < 0 or empty), start at 0
+  // Otherwise use the found index directly (no -1 subtraction)
+  const rawStartIndex = Math.max(0, foundStartIndex === -1 ? 0 : foundStartIndex);
+
+  const endIndexOffset = offsets.findIndex((offset) => offset > scrollTop + safeContainerHeight);
+  // FIX: Handle edge case where no offset exceeds viewport - show all remaining items
+  const rawEndIndex =
+    endIndexOffset === -1
+      ? dataLength - 1
+      : Math.min(dataLength - 1, Math.max(0, endIndexOffset - 1));
+
+  // FRAME HEIGHT GUARD: Calculate safe render range to prevent overflow
+  // Simplified version: no isOversize (ClippedMessage doesn't exist yet)
+  // Always show at least MIN_ITEMS_TO_SHOW to prevent content disappearing
+  const { startIndex, endIndex } = useMemo(() => {
+    // CRITICAL FIX: Always render at least one item if data exists
+    // Previous logic returned empty range causing blank screen
+    if (dataLength === 0) {
+      return { startIndex: 0, endIndex: -1 };
+    }
+
+    // Ensure we have valid indices even if raw calculation failed
+    const safeRawEndIndex = rawEndIndex < 0 ? dataLength - 1 : rawEndIndex;
+    const safeRawStartIndex = Math.min(rawStartIndex, safeRawEndIndex);
+
+    // Safety: ensure we have valid container height
+    const effectiveContainerHeight = Math.max(MIN_VIEWPORT_HEIGHT, safeContainerHeight);
+
+    // If raw range is small enough, just use it directly (don't over-optimize)
+    const rawCount = safeRawEndIndex - safeRawStartIndex + 1;
+    if (rawCount <= 3) {
+      return { startIndex: safeRawStartIndex, endIndex: safeRawEndIndex };
+    }
+
+    // For larger ranges, do soft trimming but always keep at least 2 items
+    let totalRenderedHeight = 0;
+    let safeStartIndex = safeRawEndIndex;
+    const MIN_ITEMS_TO_SHOW = 2;
+
+    for (let i = safeRawEndIndex; i >= safeRawStartIndex; i--) {
+      const itemHeight = heights[i] ?? getEstimatedHeight(estimatedItemHeight, i);
+      // Use actual height, not capped - let Ink handle overflow
+
+      const itemCount = safeRawEndIndex - safeStartIndex + 1;
+      if (
+        totalRenderedHeight + itemHeight > effectiveContainerHeight &&
+        itemCount >= MIN_ITEMS_TO_SHOW
+      ) {
+        // Would overflow AND we have minimum items - stop
+        break;
+      }
+
+      totalRenderedHeight += itemHeight;
+      safeStartIndex = i;
+    }
+
+    return { startIndex: safeStartIndex, endIndex: safeRawEndIndex };
+  }, [rawStartIndex, rawEndIndex, heights, safeContainerHeight, estimatedItemHeight, dataLength]);
+
+  // isOversize is kept for API compatibility but always false
+  // (ClippedMessage doesn't exist yet, so we can't handle oversize items)
+  const isOversize = false;
+
+  // Calculate spacer heights
+  const topSpacerHeight = offsets[startIndex] ?? 0;
+  const bottomSpacerHeight = totalHeight - (offsets[endIndex + 1] ?? totalHeight);
+
+  // Item ref callback for measurement
+  const itemRefCallback = (index: number, el: DOMElement | null) => {
+    itemRefs.current[index] = el;
+  };
+
+  // Track previous values to avoid unnecessary measurements
+  const prevStartIndexRef = useRef(startIndex);
+  const prevEndIndexRef = useRef(endIndex);
+  const prevDataLengthRef = useRef(dataLength);
+
+  // Periodic measurement tick to catch dynamic content height changes
+  // This ensures collapsible content like ThinkingBlock gets re-measured when expanded
+  const [measureTick, setMeasureTick] = useState(0);
+  const REMEASURE_INTERVAL_MS = 250; // Check every 250ms for height changes
+
+  // Set up periodic measurement timer
+  useEffect(() => {
+    const timer = setInterval(() => {
+      setMeasureTick((t) => t + 1);
+    }, REMEASURE_INTERVAL_MS);
+    return () => clearInterval(timer);
+  }, []);
+
+  // Measure container and visible items when visible range changes or on periodic tick
+  // FIX: Added proper dependency array to prevent measuring on every single render
+  // which was causing extreme CPU usage and frame drops
+  // FIX2: Added periodic re-measurement to catch dynamic content changes (ThinkingBlock expand/collapse)
+  // FIX3: Enhanced detection for significant height changes (>5px threshold) to catch collapsible content
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: Item measurement logic with height tracking
+  // biome-ignore lint/correctness/useExhaustiveDependencies: measureTick intentionally triggers periodic re-measurement
+  useLayoutEffect(() => {
+    // Check if we actually need to re-measure
+    const rangeChanged =
+      prevStartIndexRef.current !== startIndex ||
+      prevEndIndexRef.current !== endIndex ||
+      prevDataLengthRef.current !== dataLength;
+
+    prevStartIndexRef.current = startIndex;
+    prevEndIndexRef.current = endIndex;
+    prevDataLengthRef.current = dataLength;
+
+    // Measure container
+    if (containerRef.current) {
+      const height = Math.round(measureElement(containerRef.current).height);
+      if (measuredContainerHeight !== height && height > 0) {
+        setMeasuredContainerHeight(height);
+      }
+    }
+
+    // FIX3: Check for significant height changes in visible items
+    // This catches ThinkingBlock expand/collapse which can cause large height deltas
+    const HEIGHT_CHANGE_THRESHOLD = 5; // pixels
+    let forceRemeasure = false;
+
+    for (let i = startIndex; i <= endIndex; i++) {
+      const itemRef = itemRefs.current[i];
+      if (itemRef) {
+        const currentHeight = Math.round(measureElement(itemRef).height);
+        const cachedHeight = heights[i] ?? 0;
+        if (Math.abs(currentHeight - cachedHeight) > HEIGHT_CHANGE_THRESHOLD) {
+          forceRemeasure = true;
+          break;
+        }
+      }
+    }
+
+    // Measure visible items when:
+    // 1. Range changed (scroll/data update)
+    // 2. Initial mount (heights.length === 0)
+    // 3. measureTick changed (periodic check for dynamic content)
+    // 4. FIX3: Significant height change detected (forceRemeasure)
+    // Note: measureTick is in deps, so this runs periodically
+    if (!rangeChanged && heights.length > 0 && !forceRemeasure) {
+      // No changes needed - skip expensive remeasurement
+      return;
+    }
+
+    // Measure visible items
+    let newHeights: number[] | null = null;
+    for (let i = startIndex; i <= endIndex; i++) {
+      const itemRef = itemRefs.current[i];
+      if (itemRef) {
+        const height = Math.round(measureElement(itemRef).height);
+        // Only update if height actually changed and is valid
+        if (height > 0 && height !== heights[i]) {
+          if (!newHeights) {
+            newHeights = [...heights];
+          }
+          newHeights[i] = height;
+        }
+      }
+    }
+    if (newHeights) {
+      setHeights(newHeights);
+    }
+  }, [startIndex, endIndex, dataLength, heights, measuredContainerHeight, measureTick]);
+
+  return {
+    heights,
+    offsets,
+    totalHeight,
+    startIndex,
+    endIndex,
+    topSpacerHeight,
+    bottomSpacerHeight,
+    itemRefCallback,
+    containerRef,
+    measuredContainerHeight,
+    isOversize,
+  };
+}

package/src/tui/components/common/VirtualizedList/index.ts

@@ -0,0 +1,30 @@
+/**
+ * VirtualizedList Component
+ *
+ * A high-performance virtualized list for terminal UIs that only
+ * renders visible items. Ported from Gemini CLI.
+ *
+ * @module tui/components/common/VirtualizedList
+ */
+
+export {
+  type UseBatchedScrollReturn,
+  type UseScrollAnchorProps,
+  type UseScrollAnchorReturn,
+  type UseVirtualizationProps,
+  type UseVirtualizationReturn,
+  useBatchedScroll,
+  useScrollAnchor,
+  useVirtualization,
+} from "./hooks/index.js";
+
+export {
+  type HeightCache,
+  SCROLL_TO_ITEM_END,
+  type ScrollAnchor,
+} from "./types.js";
+export {
+  VirtualizedList,
+  type VirtualizedListProps,
+  type VirtualizedListRef,
+} from "./VirtualizedList.js";