@butlerw/vellum 0.1.0

package/src/tui/hooks/__tests__/useLineBuffer.test.ts

@@ -0,0 +1,295 @@
+/**
+ * useLineBuffer Hook Tests
+ *
+ * Tests for the line buffer hook that pre-wraps messages for scrolling.
+ *
+ * @module tui/hooks/__tests__/useLineBuffer.test
+ */
+
+import { describe, expect, it } from "vitest";
+import { wrapLine, wrapText } from "../useLineBuffer.js";
+
+// =============================================================================
+// Pure Function Tests
+// =============================================================================
+
+describe("wrapLine", () => {
+  describe("basic wrapping", () => {
+    it("should return single line when text fits", () => {
+      const result = wrapLine("hello", 10);
+      expect(result).toEqual(["hello"]);
+    });
+
+    it("should wrap text that exceeds width", () => {
+      const result = wrapLine("hello world", 5);
+      expect(result).toEqual(["hello", " worl", "d"]);
+    });
+
+    it("should handle empty string", () => {
+      const result = wrapLine("", 10);
+      expect(result).toEqual([""]);
+    });
+
+    it("should handle whitespace-only string", () => {
+      const result = wrapLine("   ", 10);
+      expect(result).toEqual(["   "]);
+    });
+
+    it("should handle single character", () => {
+      const result = wrapLine("a", 10);
+      expect(result).toEqual(["a"]);
+    });
+
+    it("should handle exact width match", () => {
+      const result = wrapLine("hello", 5);
+      expect(result).toEqual(["hello"]);
+    });
+
+    it("should handle minimum width of 1", () => {
+      const result = wrapLine("abc", 0);
+      // Width 0 should be treated as 1
+      expect(result).toEqual(["a", "b", "c"]);
+    });
+  });
+
+  describe("CJK and special characters", () => {
+    it("should handle CJK characters (2-width)", () => {
+      // 中文 = 4 display width (2 chars * 2 width each)
+      const result = wrapLine("中文测试", 4);
+      // Each CJK char is 2 width, so 4 width fits 2 chars
+      expect(result).toEqual(["中文", "测试"]);
+    });
+
+    it("should wrap mixed ASCII and CJK", () => {
+      // "ab中" = 2 + 2 = 4 width
+      const result = wrapLine("ab中文", 4);
+      expect(result).toEqual(["ab中", "文"]);
+    });
+  });
+
+  describe("edge cases", () => {
+    it("should handle very long line", () => {
+      const longText = "a".repeat(100);
+      const result = wrapLine(longText, 10);
+      expect(result.length).toBe(10);
+      expect(result.every((line) => line.length === 10)).toBe(true);
+    });
+
+    it("should handle width of 1", () => {
+      const result = wrapLine("abc", 1);
+      expect(result).toEqual(["a", "b", "c"]);
+    });
+  });
+});
+
+describe("wrapText", () => {
+  describe("multi-line wrapping", () => {
+    it("should preserve existing newlines", () => {
+      const result = wrapText("hello\nworld", 20);
+      expect(result).toEqual(["hello", "world"]);
+    });
+
+    it("should wrap each line independently", () => {
+      const result = wrapText("hello world\nfoo bar", 5);
+      expect(result).toEqual(["hello", " worl", "d", "foo b", "ar"]);
+    });
+
+    it("should handle empty lines", () => {
+      const result = wrapText("hello\n\nworld", 20);
+      expect(result).toEqual(["hello", "", "world"]);
+    });
+
+    it("should handle empty string", () => {
+      const result = wrapText("", 20);
+      expect(result).toEqual([""]);
+    });
+
+    it("should handle string with only newlines", () => {
+      const result = wrapText("\n\n", 20);
+      expect(result).toEqual(["", "", ""]);
+    });
+  });
+
+  describe("combined scenarios", () => {
+    it("should handle complex multi-line text", () => {
+      const text = "First line that is very long\nShort\n\nLast";
+      const result = wrapText(text, 10);
+      expect(result).toEqual(["First line", " that is v", "ery long", "Short", "", "Last"]);
+    });
+  });
+});
+
+// =============================================================================
+// Hook Integration Tests (using renderHook pattern simulation)
+// =============================================================================
+
+describe("useLineBuffer logic", () => {
+  // Simulate the createEntry logic for testing
+  function createEntry(
+    messageId: string,
+    content: string,
+    width: number,
+    padding = 4
+  ): { messageId: string; lines: string[]; wrapWidth: number } {
+    const contentWidth = Math.max(10, width - padding);
+    const lines = wrapText(content, contentWidth);
+    return { messageId, lines, wrapWidth: width };
+  }
+
+  describe("basic buffering", () => {
+    it("should create entry with wrapped lines", () => {
+      const entry = createEntry("msg1", "hello world", 20);
+      expect(entry.messageId).toBe("msg1");
+      expect(entry.wrapWidth).toBe(20);
+      expect(entry.lines.length).toBeGreaterThan(0);
+    });
+
+    it("should wrap content at correct width", () => {
+      // Width 20 - padding 4 = 16 char content width
+      const entry = createEntry("msg1", "a".repeat(32), 20);
+      // 32 chars at 16 width = 2 lines
+      expect(entry.lines.length).toBe(2);
+    });
+  });
+
+  describe("width change detection", () => {
+    it("should re-wrap when width changes", () => {
+      const entry1 = createEntry("msg1", "a".repeat(30), 20); // 16 char width -> 2 lines
+      const entry2 = createEntry("msg1", "a".repeat(30), 40); // 36 char width -> 1 line
+
+      expect(entry1.wrapWidth).toBe(20);
+      expect(entry2.wrapWidth).toBe(40);
+      expect(entry1.lines.length).toBeGreaterThan(entry2.lines.length);
+    });
+  });
+
+  describe("getVisibleLines logic", () => {
+    it("should return correct range of lines", () => {
+      const entries = [
+        createEntry("msg1", "line1\nline2", 80),
+        createEntry("msg2", "line3\nline4", 80),
+      ];
+
+      // Flatten all lines
+      const allLines = entries.flatMap((e) => e.lines);
+
+      // Simulate getVisibleLines(1, 3) - lines at index 1 and 2
+      const visible = allLines.slice(1, 3);
+      expect(visible.length).toBe(2);
+    });
+
+    it("should handle out-of-bounds range gracefully", () => {
+      const entries = [createEntry("msg1", "hello", 80)];
+      const allLines = entries.flatMap((e) => e.lines);
+
+      // Request range beyond available lines
+      const start = Math.max(0, -5);
+      const end = Math.min(allLines.length, 100);
+      const visible = allLines.slice(start, end);
+
+      expect(visible.length).toBeLessThanOrEqual(allLines.length);
+    });
+
+    it("should return empty array for invalid range", () => {
+      const entries = [createEntry("msg1", "hello", 80)];
+      const allLines = entries.flatMap((e) => e.lines);
+
+      // Start >= end should return empty
+      const start = 5;
+      const end = Math.min(allLines.length, start);
+      const visible = allLines.slice(start, end);
+
+      expect(visible).toEqual([]);
+    });
+  });
+
+  describe("ring buffer logic", () => {
+    it("should limit total lines to maxLines", () => {
+      const maxLines = 10;
+      const entries: Array<{ messageId: string; lines: string[]; wrapWidth: number }> = [];
+      let totalLineCount = 0;
+
+      // Create entries that exceed maxLines
+      for (let i = 0; i < 5; i++) {
+        const entry = createEntry(`msg${i}`, "line1\nline2\nline3", 80);
+        entries.push(entry);
+        totalLineCount += entry.lines.length;
+      }
+
+      // Simulate ring buffer trimming
+      while (totalLineCount > maxLines && entries.length > 1) {
+        const removed = entries.shift();
+        if (removed) {
+          totalLineCount -= removed.lines.length;
+        }
+      }
+
+      expect(totalLineCount).toBeLessThanOrEqual(maxLines);
+    });
+
+    it("should always keep at least one entry", () => {
+      const maxLines = 1;
+      const entries = [createEntry("msg1", "line1\nline2\nline3\nline4\nline5", 80)];
+      let totalLineCount = entries.reduce((sum, e) => sum + e.lines.length, 0);
+
+      // Even with maxLines=1, we should keep the one entry
+      while (totalLineCount > maxLines && entries.length > 1) {
+        const removed = entries.shift();
+        if (removed) {
+          totalLineCount -= removed.lines.length;
+        }
+      }
+
+      expect(entries.length).toBe(1);
+    });
+  });
+
+  describe("total lines calculation", () => {
+    it("should sum all entry line counts", () => {
+      const entries = [
+        createEntry("msg1", "a\nb", 80), // 2 lines
+        createEntry("msg2", "c\nd\ne", 80), // 3 lines
+      ];
+
+      const totalLines = entries.reduce((sum, e) => sum + e.lines.length, 0);
+      expect(totalLines).toBe(5);
+    });
+
+    it("should handle empty entries", () => {
+      const entries = [createEntry("msg1", "", 80), createEntry("msg2", "hello", 80)];
+
+      const totalLines = entries.reduce((sum, e) => sum + e.lines.length, 0);
+      expect(totalLines).toBeGreaterThan(0);
+    });
+  });
+});
+
+// =============================================================================
+// Performance Tests
+// =============================================================================
+
+describe("performance characteristics", () => {
+  it("should handle large content efficiently", () => {
+    const largeContent = "x".repeat(10000);
+    const start = performance.now();
+
+    const result = wrapText(largeContent, 80);
+
+    const duration = performance.now() - start;
+    // Use relaxed threshold for CI environments where performance varies
+    expect(duration).toBeLessThan(500);
+    expect(result.length).toBeGreaterThan(100);
+  });
+
+  it("should handle many small lines efficiently", () => {
+    const manyLines = Array(1000).fill("short line").join("\n");
+    const start = performance.now();
+
+    const result = wrapText(manyLines, 80);
+
+    const duration = performance.now() - start;
+    // Use relaxed threshold for CI environments where performance varies
+    expect(duration).toBeLessThan(500);
+    expect(result.length).toBe(1000);
+  });
+});

package/src/tui/hooks/__tests__/useModeController.test.ts

@@ -0,0 +1,137 @@
+/**
+ * useModeController Hook Tests (T010)
+ *
+ * Tests the core mode selection logic extracted from the hook.
+ *
+ * @module tui/hooks/__tests__/useModeController.test
+ */
+
+import { describe, expect, it } from "vitest";
+import type {
+  ModeControllerConfig,
+  ModeControllerState,
+  ModeReason,
+  RenderMode,
+} from "../useModeController.js";
+
+// Extract pure logic from the hook for testing (mirrors hook internals)
+function computeModeState(
+  availableHeight: number,
+  totalContentHeight: number,
+  config: ModeControllerConfig = {}
+): ModeControllerState {
+  const staticMultiplier = config.staticMultiplier ?? 1.2;
+  const virtualMultiplier = config.virtualMultiplier ?? 5.0;
+  const minWindowSize = config.minWindowSize ?? 10;
+  const maxWindowSizeRatio = config.maxWindowSizeRatio ?? 0.8;
+  const forceMode = config.forceMode;
+
+  const staticThreshold = Math.max(1, availableHeight * staticMultiplier);
+  const virtualThreshold = Math.max(1, availableHeight * virtualMultiplier);
+  const windowSize = Math.max(minWindowSize, Math.floor(availableHeight * maxWindowSizeRatio));
+  const isAutoMode = !forceMode;
+
+  if (forceMode) {
+    return {
+      mode: forceMode,
+      windowSize,
+      modeReason: "forced",
+      staticThreshold,
+      virtualThreshold,
+      isAutoMode,
+    };
+  }
+
+  let mode: RenderMode;
+  let modeReason: ModeReason;
+  if (totalContentHeight <= staticThreshold) {
+    mode = "static";
+    modeReason = "content-fits";
+  } else if (totalContentHeight <= virtualThreshold) {
+    mode = "windowed";
+    modeReason = "content-exceeds-viewport";
+  } else {
+    mode = "virtualized";
+    modeReason = "content-very-large";
+  }
+
+  return { mode, windowSize, modeReason, staticThreshold, virtualThreshold, isAutoMode };
+}
+
+describe("useModeController (core logic)", () => {
+  describe("default mode selection", () => {
+    it("selects static for small content", () => {
+      const result = computeModeState(20, 10);
+      expect(result.mode).toBe("static");
+      expect(result.modeReason).toBe("content-fits");
+    });
+
+    it("selects windowed for medium content", () => {
+      const result = computeModeState(20, 50);
+      expect(result.mode).toBe("windowed");
+      expect(result.modeReason).toBe("content-exceeds-viewport");
+    });
+
+    it("selects virtualized for large content", () => {
+      const result = computeModeState(20, 200);
+      expect(result.mode).toBe("virtualized");
+      expect(result.modeReason).toBe("content-very-large");
+    });
+  });
+
+  describe("threshold calculations", () => {
+    it("computes staticThreshold = availableHeight * 1.2", () => {
+      const result = computeModeState(100, 50);
+      expect(result.staticThreshold).toBe(120);
+    });
+
+    it("computes virtualThreshold = availableHeight * 5.0", () => {
+      const result = computeModeState(100, 50);
+      expect(result.virtualThreshold).toBe(500);
+    });
+  });
+
+  describe("forceMode override", () => {
+    it("forces windowed mode when configured", () => {
+      const result = computeModeState(20, 10, { forceMode: "windowed" });
+      expect(result.mode).toBe("windowed");
+      expect(result.modeReason).toBe("forced");
+      expect(result.isAutoMode).toBe(false);
+    });
+
+    it("returns isAutoMode true when not forced", () => {
+      const result = computeModeState(20, 10);
+      expect(result.isAutoMode).toBe(true);
+    });
+  });
+
+  describe("config overrides", () => {
+    it("applies minWindowSize", () => {
+      const result = computeModeState(10, 50, { minWindowSize: 15 });
+      expect(result.windowSize).toBe(15);
+    });
+
+    it("applies maxWindowSizeRatio", () => {
+      const result = computeModeState(100, 50, { maxWindowSizeRatio: 0.5 });
+      expect(result.windowSize).toBe(50);
+    });
+
+    it("applies custom staticMultiplier and virtualMultiplier", () => {
+      const result = computeModeState(100, 50, { staticMultiplier: 2.0, virtualMultiplier: 10.0 });
+      expect(result.staticThreshold).toBe(200);
+      expect(result.virtualThreshold).toBe(1000);
+    });
+  });
+
+  describe("modeReason content", () => {
+    it("includes reason for static mode", () => {
+      const result = computeModeState(20, 10);
+      expect(result.modeReason).toBe("content-fits");
+    });
+
+    it("includes reason for virtualized mode", () => {
+      const result = computeModeState(20, 200);
+      expect(result.modeReason).toBe("content-very-large");
+    });
+  });
+});

package/src/tui/hooks/__tests__/useModeShortcuts.test.tsx

@@ -0,0 +1,142 @@
+/**
+ * useModeShortcuts Hook Tests (T046)
+ *
+ * Focus: ensure mode switching goes through ModeManager (including spec confirmation).
+ */
+
+import type { CodingMode, ModeManager } from "@vellum/core";
+import { createModeManager } from "@vellum/core";
+import { render } from "ink-testing-library";
+import type React from "react";
+import { describe, expect, it, vi } from "vitest";
+import { type UseModeShortcutsReturn, useModeShortcuts } from "../useModeShortcuts.js";
+
+// =============================================================================
+// Test Harness
+// =============================================================================
+
+interface TestHarnessProps {
+  readonly modeManager: ModeManager | null;
+  readonly enabled?: boolean;
+  readonly onHookReturn: (hookReturn: UseModeShortcutsReturn) => void;
+  readonly onModeSwitch?: (mode: CodingMode, success: boolean) => void;
+  readonly onError?: (mode: CodingMode, error: string) => void;
+}
+
+function TestHarness({
+  modeManager,
+  enabled,
+  onHookReturn,
+  onModeSwitch,
+  onError,
+}: TestHarnessProps): React.ReactElement {
+  const hookReturn = useModeShortcuts({ modeManager, enabled, onModeSwitch, onError });
+  onHookReturn(hookReturn);
+  return null as unknown as React.ReactElement;
+}
+
+function renderUseModeShortcutsHook(options: Omit<TestHarnessProps, "onHookReturn">) {
+  let hookReturn: UseModeShortcutsReturn | null = null;
+
+  const { rerender, unmount } = render(
+    <TestHarness
+      modeManager={options.modeManager}
+      enabled={options.enabled}
+      onModeSwitch={options.onModeSwitch}
+      onError={options.onError}
+      onHookReturn={(r) => {
+        hookReturn = r;
+      }}
+    />
+  );
+
+  return {
+    get current() {
+      if (!hookReturn) {
+        throw new Error("Hook return not initialized");
+      }
+      return hookReturn;
+    },
+    rerender: (next: Omit<TestHarnessProps, "onHookReturn">) => {
+      rerender(
+        <TestHarness
+          modeManager={next.modeManager}
+          enabled={next.enabled}
+          onModeSwitch={next.onModeSwitch}
+          onError={next.onError}
+          onHookReturn={(r) => {
+            hookReturn = r;
+          }}
+        />
+      );
+    },
+    unmount,
+  };
+}
+
+// =============================================================================
+// Tests
+// =============================================================================
+
+describe("useModeShortcuts", () => {
+  it("switches mode through ModeManager", async () => {
+    const manager = createModeManager({ initialMode: "vibe", requireSpecConfirmation: true });
+    const onModeSwitch = vi.fn();
+    const onError = vi.fn();
+
+    const result = renderUseModeShortcutsHook({
+      modeManager: manager,
+      enabled: true,
+      onModeSwitch,
+      onError,
+    });
+
+    const success = await result.current.switchMode("plan");
+
+    expect(success).toBe(true);
+    expect(manager.getCurrentMode()).toBe("plan");
+    expect(onModeSwitch).toHaveBeenCalledWith("plan", true);
+    expect(onError).not.toHaveBeenCalled();
+  });
+
+  it("does not bypass spec confirmation when required", async () => {
+    const manager = createModeManager({ initialMode: "vibe", requireSpecConfirmation: true });
+    const onModeSwitch = vi.fn();
+    const onError = vi.fn();
+
+    const result = renderUseModeShortcutsHook({
+      modeManager: manager,
+      enabled: true,
+      onModeSwitch,
+      onError,
+    });
+
+    const success = await result.current.switchMode("spec");
+
+    // When spec confirmation is required, ModeManager should not immediately switch.
+    expect(success).toBe(false);
+    expect(manager.getCurrentMode()).toBe("vibe");
+    expect(manager.isPendingSpecConfirmation()).toBe(true);
+    expect(onModeSwitch).toHaveBeenCalledWith("spec", false);
+    expect(onError).toHaveBeenCalled();
+  });
+
+  it("is inactive when disabled or manager is null", async () => {
+    const onModeSwitch = vi.fn();
+    const onError = vi.fn();
+
+    const result = renderUseModeShortcutsHook({
+      modeManager: null,
+      enabled: true,
+      onModeSwitch,
+      onError,
+    });
+
+    expect(result.current.isActive).toBe(false);
+
+    const success = await result.current.switchMode("plan");
+    expect(success).toBe(false);
+    expect(onModeSwitch).not.toHaveBeenCalled();
+    expect(onError).toHaveBeenCalled();
+  });
+});