@nexus-ai-fs/tui 0.9.18

package/src/shared/hooks/use-keyboard.ts

@@ -0,0 +1,58 @@
+/**
+ * Keyboard navigation hook wrapping OpenTUI's useKeyboard.
+ *
+ * Provides a simple key-name -> handler abstraction with cleanup on unmount.
+ */
+
+import { useCallback, useRef } from "react";
+import { useKeyboard as useOpenTuiKeyboard } from "@opentui/react";
+import type { KeyEvent } from "@opentui/core";
+
+export type KeyHandler = () => void;
+export type KeyBindings = Readonly<Record<string, KeyHandler>>;
+export type UnhandledKeyHandler = (key: string) => void;
+
+/**
+ * Register keyboard shortcut handlers.
+ *
+ * Key format matches OpenTUI key event names:
+ * - Letters: "a", "b", ..., "z"
+ * - Numbers: "1", "2", "3"
+ * - Navigation: "up", "down", "left", "right"
+ * - Actions: "return", "escape", "tab", "space", "backspace"
+ * - Modified keys: prefix with "ctrl+" or "shift+" (e.g. "ctrl+c")
+ *
+ * Bindings are cleaned up automatically on unmount.
+ *
+ * @param bindings - Map of key names to handler functions
+ * @param onUnhandled - Optional handler for keys not in the bindings map.
+ *   Receives the raw key name. Useful for text input mode where any
+ *   printable character should be captured.
+ */
+export function useKeyboard(
+  bindings: KeyBindings,
+  onUnhandled?: UnhandledKeyHandler,
+): void {
+  const bindingsRef = useRef(bindings);
+  bindingsRef.current = bindings;
+
+  const onUnhandledRef = useRef(onUnhandled);
+  onUnhandledRef.current = onUnhandled;
+
+  const handler = useCallback((key: KeyEvent) => {
+    // Build normalized key string
+    let keyStr = key.name;
+    if (key.ctrl) keyStr = `ctrl+${keyStr}`;
+    if (key.shift) keyStr = `shift+${keyStr}`;
+    if (key.meta) keyStr = `meta+${keyStr}`;
+
+    const fn = bindingsRef.current[keyStr];
+    if (fn) {
+      fn();
+    } else if (onUnhandledRef.current) {
+      onUnhandledRef.current(key.name);
+    }
+  }, []);
+
+  useOpenTuiKeyboard(handler);
+}

package/src/shared/hooks/use-list-navigation.ts

@@ -0,0 +1,106 @@
+/**
+ * Shared list navigation logic.
+ *
+ * Pure helper functions for cursor-in-list navigation used across all panels.
+ * These are extracted from the repeated j/k/gg/G pattern to ensure consistency.
+ *
+ * For React integration, panels use these helpers within their useKeyboard bindings.
+ *
+ * @see Issue #3066 Architecture Decision 6A
+ */
+
+// =============================================================================
+// Pure navigation helpers
+// =============================================================================
+
+/**
+ * Clamp an index to valid range [0, length - 1].
+ * Returns 0 for empty lists.
+ */
+export function clampIndex(index: number, length: number): number {
+  if (length <= 0) return 0;
+  return Math.max(0, Math.min(length - 1, index));
+}
+
+/**
+ * Move index by delta, clamping to valid range.
+ *
+ * @param current - Current selected index
+ * @param delta - Movement (+1 = down, -1 = up, +10 = page down, etc.)
+ * @param length - Total number of items
+ */
+export function moveIndex(current: number, delta: number, length: number): number {
+  return clampIndex(current + delta, length);
+}
+
+/**
+ * Jump to the first item (gg in vim).
+ */
+export function jumpToStart(): number {
+  return 0;
+}
+
+/**
+ * Jump to the last item (G in vim).
+ */
+export function jumpToEnd(length: number): number {
+  if (length <= 0) return 0;
+  return length - 1;
+}
+
+// =============================================================================
+// Keybinding builder
+// =============================================================================
+
+export interface ListNavigationOptions {
+  /** Get the current selected index. */
+  readonly getIndex: () => number;
+  /** Set the new selected index. */
+  readonly setIndex: (index: number) => void;
+  /** Get the current list length. */
+  readonly getLength: () => number;
+  /** Called when Enter is pressed on the selected item. */
+  readonly onSelect?: (index: number) => void;
+}
+
+/**
+ * Build keyboard bindings for standard list navigation.
+ *
+ * Returns a Record<string, () => void> suitable for useKeyboard().
+ * Panels merge these with their own panel-specific bindings.
+ *
+ * Includes: j/k (move), up/down (move), gg/G (jump), Enter (select)
+ */
+export function listNavigationBindings(
+  options: ListNavigationOptions,
+): Record<string, () => void> {
+  const { getIndex, setIndex, getLength, onSelect } = options;
+
+  const move = (delta: number) => () => {
+    setIndex(moveIndex(getIndex(), delta, getLength()));
+  };
+
+  const bindings: Record<string, () => void> = {
+    j: move(1),
+    k: move(-1),
+    down: move(1),
+    up: move(-1),
+  };
+
+  // g = jump to start, G (shift+g) = jump to end
+  bindings["g"] = () => setIndex(jumpToStart());
+  bindings["shift+g"] = () => setIndex(jumpToEnd(getLength()));
+
+  if (onSelect) {
+    bindings["return"] = () => onSelect(getIndex());
+  }
+
+  return bindings;
+}
+
+/**
+ * Render prefix for a list item: `> ` for selected, `  ` for others.
+ */
+export function selectionPrefix(index: number, selectedIndex: number): string {
+  return index === selectedIndex ? "> " : "  ";
+}

package/src/shared/hooks/use-swr.ts

@@ -0,0 +1,117 @@
+/**
+ * Generic stale-while-revalidate hook for data fetching.
+ *
+ * - Immediately returns cached data if available (even if stale)
+ * - Triggers background revalidation if data is stale
+ * - Reports loading/error states
+ * - Aborts in-flight requests on key change or unmount (Issue #3102)
+ */
+
+import { useState, useEffect, useRef, useCallback } from "react";
+import { LruCache } from "../utils/lru-cache.js";
+
+interface SwrOptions {
+  /** Time in ms before cached data is considered stale. Default: 30000 */
+  readonly ttlMs?: number;
+  /** Whether to fetch immediately on mount. Default: true */
+  readonly enabled?: boolean;
+}
+
+interface SwrResult<T> {
+  readonly data: T | undefined;
+  readonly error: Error | undefined;
+  readonly isLoading: boolean;
+  readonly isStale: boolean;
+  readonly mutate: () => void;
+}
+
+// =============================================================================
+// Module-level cache shared across hook instances (Decision 7A)
+// =============================================================================
+
+/** @internal Exported for testing LRU behavior */
+export const swrCache = new LruCache(200);
+
+export function useSwr<T>(
+  key: string,
+  fetcher: (signal: AbortSignal) => Promise<T>,
+  options?: SwrOptions,
+): SwrResult<T> {
+  const ttlMs = options?.ttlMs ?? 30_000;
+  const enabled = options?.enabled ?? true;
+
+  const [data, setData] = useState<T | undefined>(() => {
+    const cached = swrCache.get(key) as { data: T; fetchedAt: number } | undefined;
+    return cached?.data;
+  });
+  const [error, setError] = useState<Error | undefined>();
+  const [isLoading, setIsLoading] = useState(false);
+  const fetcherRef = useRef(fetcher);
+  fetcherRef.current = fetcher;
+
+  // Track the active key so in-flight fetches for stale keys are discarded
+  const activeKeyRef = useRef(key);
+  activeKeyRef.current = key;
+
+  // Track the active AbortController for cancellation (Issue #3102, Decision 3A)
+  const controllerRef = useRef<AbortController | null>(null);
+
+  // Reset data to cached value (or undefined) when key changes
+  useEffect(() => {
+    const cached = swrCache.get(key) as { data: T; fetchedAt: number } | undefined;
+    setData(cached?.data);
+  }, [key]);
+
+  const isStale = (() => {
+    const cached = swrCache.get(key);
+    if (!cached) return true;
+    return Date.now() - cached.fetchedAt > ttlMs;
+  })();
+
+  const doFetch = useCallback(async () => {
+    const fetchKey = key; // capture for closure
+
+    // Abort any previous in-flight fetch
+    controllerRef.current?.abort();
+    const controller = new AbortController();
+    controllerRef.current = controller;
+
+    setIsLoading(true);
+    setError(undefined);
+    try {
+      const result = await fetcherRef.current(controller.signal);
+      // Only update if this key is still the active one
+      if (activeKeyRef.current !== fetchKey) return;
+      swrCache.set(key, { data: result, fetchedAt: Date.now() });
+      setData(result);
+    } catch (err) {
+      // Suppress AbortError — it's expected when we cancel
+      if (err instanceof DOMException && err.name === "AbortError") return;
+      if (activeKeyRef.current !== fetchKey) return;
+      setError(err instanceof Error ? err : new Error(String(err)));
+    } finally {
+      if (activeKeyRef.current === fetchKey) {
+        setIsLoading(false);
+      }
+    }
+  }, [key]);
+
+  useEffect(() => {
+    if (!enabled) return;
+    if (isStale) {
+      doFetch();
+    }
+
+    // Abort in-flight request on unmount or key change
+    return () => {
+      controllerRef.current?.abort();
+    };
+  }, [key, enabled, isStale, doFetch]);
+
+  const mutate = useCallback(() => {
+    swrCache.delete(key);
+    doFetch();
+  }, [key, doFetch]);
+
+  return { data, error, isLoading, isStale, mutate };
+}

package/src/shared/hooks/use-tab-fallback.ts

@@ -0,0 +1,32 @@
+/**
+ * Hook to fall back to the first visible tab when the active tab
+ * becomes hidden (e.g. its brick was disabled).
+ *
+ * Replaces the inline useEffect that was duplicated across 6+ panels
+ * with inconsistent dependency arrays.
+ *
+ * @see Issue #3498
+ */
+
+import { useEffect } from "react";
+import { tabFallback } from "../components/sub-tab-bar-utils.js";
+
+/**
+ * If activeTab is not in visibleTabs, switch to the first visible tab.
+ *
+ * Uses visibleIds.join(",") as the dependency key to match the established
+ * codebase convention (see zones-panel, events-panel, etc.).
+ */
+export function useTabFallback<T extends string>(
+  visibleTabs: readonly { readonly id: T }[],
+  activeTab: T,
+  setActiveTab: (tab: T) => void,
+): void {
+  const visibleIds = visibleTabs.map((t) => t.id);
+
+  useEffect(() => {
+    const target = tabFallback(visibleIds, activeTab);
+    if (target !== null) setActiveTab(target);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [visibleIds.join(","), activeTab]);
+}

package/src/shared/hooks/use-text-input.ts

@@ -0,0 +1,113 @@
+/**
+ * Shared hook for text input mode in terminal panels.
+ *
+ * Encapsulates the repeated pattern of: activate input mode → capture
+ * keystrokes into a buffer → submit on Enter → cancel on Escape →
+ * delete on Backspace.
+ *
+ * Panels integrate this with useKeyboard by spreading inputBindings
+ * when the input is active, and passing onUnhandled as the second arg.
+ *
+ * @example
+ * ```tsx
+ * const textInput = useTextInput({
+ *   onSubmit: (val) => doSearch(val),
+ * });
+ *
+ * useKeyboard(
+ *   textInput.active
+ *     ? textInput.inputBindings
+ *     : { ...normalBindings },
+ *   textInput.active ? textInput.onUnhandled : undefined,
+ * );
+ *
+ * // Render: textInput.active ? `Search: ${textInput.buffer}█` : "..."
+ * // Activate: textInput.activate(existingQuery)
+ * ```
+ */
+
+import { useState, useCallback, useRef } from "react";
+
+export interface UseTextInputOptions {
+  /** Called when Enter is pressed. Receives the trimmed buffer value. */
+  readonly onSubmit: (value: string) => void;
+  /** Called when Escape is pressed. Defaults to no-op. */
+  readonly onCancel?: () => void;
+  /**
+   * Character filter — return true to accept, false to reject.
+   * Only called for single printable characters, not "space".
+   * Defaults to accepting all characters.
+   */
+  readonly filter?: (char: string) => boolean;
+}
+
+export interface UseTextInputReturn {
+  /** Whether input mode is currently active. */
+  readonly active: boolean;
+  /** Current buffer contents. */
+  readonly buffer: string;
+  /** Activate input mode with an optional initial value. */
+  readonly activate: (initialValue?: string) => void;
+  /** Deactivate input mode programmatically (clears buffer). */
+  readonly deactivate: () => void;
+  /**
+   * Keyboard bindings for input mode.
+   * Spread into useKeyboard when active.
+   * Includes: return, escape, backspace.
+   */
+  readonly inputBindings: Readonly<Record<string, () => void>>;
+  /**
+   * Unhandled key handler for capturing printable characters.
+   * Pass as the second arg to useKeyboard when active.
+   */
+  readonly onUnhandled: (keyName: string) => void;
+}
+
+export function useTextInput(options: UseTextInputOptions): UseTextInputReturn {
+  const [active, setActive] = useState(false);
+  const [buffer, setBuffer] = useState("");
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+
+  const activate = useCallback((initialValue?: string) => {
+    setBuffer(initialValue ?? "");
+    setActive(true);
+  }, []);
+
+  const deactivate = useCallback(() => {
+    setBuffer("");
+    setActive(false);
+  }, []);
+
+  const inputBindings: Record<string, () => void> = {
+    return: () => {
+      setActive(false);
+      optionsRef.current.onSubmit(buffer);
+    },
+    escape: () => {
+      setActive(false);
+      setBuffer("");
+      optionsRef.current.onCancel?.();
+    },
+    backspace: () => {
+      setBuffer((b) => b.slice(0, -1));
+    },
+  };
+
+  const onUnhandled = useCallback(
+    (keyName: string) => {
+      if (!active) return;
+      if (keyName === "space") {
+        setBuffer((b) => b + " ");
+      } else if (keyName.length === 1) {
+        const filter = optionsRef.current.filter;
+        if (!filter || filter(keyName)) {
+          setBuffer((b) => b + keyName);
+        }
+      }
+    },
+    [active],
+  );
+
+  return { active, buffer, activate, deactivate, inputBindings, onUnhandled };
+}

package/src/shared/hooks/use-visible-tabs.ts

@@ -0,0 +1,61 @@
+/**
+ * Shared hook for filtering panel sub-tabs based on enabled bricks.
+ *
+ * Provides the TabDef type and useVisibleTabs hook (Decision 2A: hybrid
+ * shared type, per-panel ownership).
+ */
+
+import { useMemo } from "react";
+import { useGlobalStore } from "../../stores/global-store.js";
+
+/**
+ * Definition of a sub-tab within a panel.
+ *
+ * Each panel defines its own ALL_TABS: TabDef[] array. The useVisibleTabs
+ * hook filters this array based on which bricks are currently enabled.
+ */
+export interface TabDef<T extends string = string> {
+  /** Tab identifier (matches the panel's tab union type). */
+  readonly id: T;
+  /** Display label shown in the sub-tab bar. */
+  readonly label: string;
+  /**
+   * Brick(s) required for this tab to be visible.
+   * - string: single brick must be enabled
+   * - string[]: any of the listed bricks must be enabled (OR semantics)
+   * - null: tab is always visible (no brick dependency)
+   */
+  readonly brick: string | readonly string[] | null;
+}
+
+export function filterTabs<T extends string>(
+  allTabs: readonly TabDef<T>[],
+  enabledBricks: readonly string[],
+  featuresLoaded: boolean,
+): readonly TabDef<T>[] {
+  if (!featuresLoaded) return allTabs;
+
+  return allTabs.filter((tab) => {
+    if (tab.brick === null) return true;
+    if (typeof tab.brick === "string") return enabledBricks.includes(tab.brick);
+    return tab.brick.some((b) => enabledBricks.includes(b));
+  });
+}
+
+/**
+ * Filter a panel's tab definitions to only those whose required bricks
+ * are currently enabled.
+ *
+ * Uses shallow comparison on enabledBricks to avoid unnecessary re-renders
+ * (Decision 15A).
+ */
+export function useVisibleTabs<T extends string>(
+  allTabs: readonly TabDef<T>[],
+): readonly TabDef<T>[] {
+  const enabledBricks = useGlobalStore((s) => s.enabledBricks);
+  const featuresLoaded = useGlobalStore((s) => s.featuresLoaded);
+
+  return useMemo(() => {
+    return filterTabs(allTabs, enabledBricks, featuresLoaded);
+  }, [allTabs, enabledBricks, featuresLoaded]);
+}

package/src/shared/lib/circular-buffer.ts

@@ -0,0 +1,82 @@
+/**
+ * Fixed-capacity circular buffer for bounded collections.
+ *
+ * Primary use: SSE event stream (prevents unbounded memory growth).
+ * When the buffer is full, the oldest item is silently evicted.
+ *
+ * @see Issue #3066, Phase D9 (SSE stream bounding)
+ */
+
+export class CircularBuffer<T> {
+  private readonly _items: Array<T | undefined>;
+  private _head = 0; // next write position
+  private _size = 0;
+  private _totalAdded = 0;
+
+  constructor(readonly capacity: number) {
+    if (capacity < 1) throw new Error("CircularBuffer capacity must be >= 1");
+    this._items = new Array<T | undefined>(capacity);
+  }
+
+  /** Number of items currently in the buffer. */
+  get size(): number {
+    return this._size;
+  }
+
+  /** Total items ever added (including evicted). */
+  get totalAdded(): number {
+    return this._totalAdded;
+  }
+
+  /** Number of items that have been evicted. */
+  get evictedCount(): number {
+    return this._totalAdded - this._size;
+  }
+
+  /** Whether the buffer has evicted any items. */
+  get hasOverflowed(): boolean {
+    return this._totalAdded > this.capacity;
+  }
+
+  /** Add an item. If full, the oldest item is evicted. */
+  push(item: T): void {
+    this._items[this._head] = item;
+    this._head = (this._head + 1) % this.capacity;
+    this._totalAdded++;
+    if (this._size < this.capacity) {
+      this._size++;
+    }
+  }
+
+  /** Get item by index (0 = oldest). Throws if out of range. */
+  get(index: number): T {
+    if (index < 0 || index >= this._size) {
+      throw new RangeError(`Index ${index} out of range [0, ${this._size})`);
+    }
+    const start = this._size < this.capacity
+      ? 0
+      : this._head; // head points to oldest when full
+    const actual = (start + index) % this.capacity;
+    return this._items[actual] as T;
+  }
+
+  /** Remove all items and reset counters. */
+  clear(): void {
+    this._items.fill(undefined);
+    this._head = 0;
+    this._size = 0;
+    this._totalAdded = 0;
+  }
+
+  /** Iterate from oldest to newest. */
+  *[Symbol.iterator](): Iterator<T> {
+    for (let i = 0; i < this._size; i++) {
+      yield this.get(i);
+    }
+  }
+
+  /** Return all items as an array (oldest first). */
+  toArray(): T[] {
+    return Array.from(this);
+  }
+}

package/src/shared/lib/clipboard.ts

@@ -0,0 +1,14 @@
+/**
+ * Clipboard support via OSC 52 terminal escape sequence.
+ * @see Issue #3066, Phase E3
+ */
+
+/**
+ * Copy text to the system clipboard using OSC 52.
+ * Works in terminals that support OSC 52 (most modern terminals).
+ * Silently no-ops if the terminal doesn't support it.
+ */
+export function copyToClipboard(text: string): void {
+  const encoded = Buffer.from(text).toString("base64");
+  process.stdout.write(`\x1b]52;c;${encoded}\x07`);
+}

package/src/shared/nav-items.ts

@@ -0,0 +1,73 @@
+/**
+ * Panel navigation items — single source of truth for SideNav rendering,
+ * keyboard shortcuts, and panel-to-store indicator mapping.
+ *
+ * Extracted from app.tsx to keep layout concerns separate from data.
+ *
+ * @see Issue #3497
+ */
+
+import type { PanelId } from "../stores/global-store.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface NavItem {
+  readonly id: PanelId;
+  /** Short label for collapsed / narrow terminals */
+  readonly label: string;
+  /** Full label for wide terminals */
+  readonly fullLabel: string;
+  /** Keyboard shortcut displayed in the nav */
+  readonly shortcut: string;
+  /** Single-char icon for collapsed mode */
+  readonly icon: string;
+}
+
+// =============================================================================
+// Nav items
+// =============================================================================
+
+export const NAV_ITEMS: readonly NavItem[] = [
+  { id: "files",          label: "Files", fullLabel: "Files",      shortcut: "1", icon: "□" },
+  { id: "versions",       label: "Ver",   fullLabel: "Versions",   shortcut: "2", icon: "◎" },
+  { id: "agents",         label: "Agent", fullLabel: "Agents",     shortcut: "3", icon: "◇" },
+  { id: "zones",          label: "Zone",  fullLabel: "Zones",      shortcut: "4", icon: "⬡" },
+  { id: "access",         label: "ACL",   fullLabel: "Access",     shortcut: "5", icon: "⊕" },
+  { id: "payments",       label: "Pay",   fullLabel: "Payments",   shortcut: "6", icon: "◈" },
+  { id: "search",         label: "Find",  fullLabel: "Search",     shortcut: "7", icon: "⊘" },
+  { id: "workflows",      label: "Flow",  fullLabel: "Workflows",  shortcut: "8", icon: "⟲" },
+  { id: "infrastructure", label: "Event", fullLabel: "Events",     shortcut: "9", icon: "◉" },
+  { id: "console",        label: "CLI",   fullLabel: "Console",    shortcut: "0", icon: "▶" },
+  { id: "connectors",     label: "Conn",  fullLabel: "Connectors", shortcut: "C", icon: "⊞" },
+  { id: "stack",          label: "Stack", fullLabel: "Stack",      shortcut: "S", icon: "▦" },
+];
+
+// =============================================================================
+// Per-panel indicator selectors (Decision 1A: thin adapter map)
+//
+// Only stores that expose loading/error state are wired up.
+// Panels without indicators simply return false.
+// =============================================================================
+
+/**
+ * Zustand-compatible selector: reads loading state from a store.
+ * Returns a boolean for use with Object.is equality (Decision 4A).
+ */
+export type IndicatorSelector<S> = (state: S) => boolean;
+
+/**
+ * Mapping from PanelId to the store hook + selector needed to read
+ * loading and error state. Stored as getState() thunks so they can
+ * be called outside React (in tests) or inside hooks.
+ *
+ * Lazy-imported in side-nav.tsx to avoid circular deps.
+ */
+export interface PanelIndicators {
+  readonly loading: boolean;
+  readonly error: boolean;
+}
+
+/** Default indicators for panels whose stores don't expose loading/error. */
+export const NO_INDICATORS: PanelIndicators = { loading: false, error: false };