@nexus-ai-fs/tui 0.9.18

package/src/shared/components/side-nav.tsx

@@ -0,0 +1,287 @@
+/**
+ * Vertical sidebar navigation replacing the horizontal TabBar.
+ *
+ * Features:
+ * - 12 panels with keyboard shortcuts
+ * - 6-state indicators: active (bold + ◂), loading (spinner), error (red ●),
+ *   unseen (blue ●), stale (dimmed text), healthy (no indicator)
+ * - 3 responsive breakpoints: full (>=120), collapsed (80-119), hidden (<80)
+ * - Ctrl+B toggles visibility; hidden during zoom
+ *
+ * @see Issue #3497, #3503
+ */
+
+import React, { useState, useEffect } from "react";
+import { useTerminalDimensions } from "@opentui/react";
+import { palette } from "../theme.js";
+import { NAV_ITEMS, type NavItem } from "../nav-items.js";
+import { getSideNavMode, STALE_THRESHOLD_MS, type SideNavMode } from "./side-nav-utils.js";
+import type { PanelId } from "../../stores/global-store.js";
+import { useUiStore } from "../../stores/ui-store.js";
+
+// Per-panel store imports for indicator selectors (Decision 1A)
+import { useFilesStore } from "../../stores/files-store.js";
+import { useVersionsStore } from "../../stores/versions-store.js";
+import { useAgentsStore } from "../../stores/agents-store.js";
+import { useZonesStore } from "../../stores/zones-store.js";
+import { useAccessStore } from "../../stores/access-store.js";
+import { usePaymentsStore } from "../../stores/payments-store.js";
+import { useSearchStore } from "../../stores/search-store.js";
+import { useWorkflowsStore } from "../../stores/workflows-store.js";
+import { useInfraStore } from "../../stores/infra-store.js";
+import { useApiConsoleStore } from "../../stores/api-console-store.js";
+import { useConnectorsStore } from "../../stores/connectors-store.js";
+import { useStackStore } from "../../stores/stack-store.js";
+
+// =============================================================================
+// Spinner frames (same as shared Spinner component)
+// =============================================================================
+
+const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const SPINNER_INTERVAL_MS = 80;
+
+// =============================================================================
+// Per-panel indicator hook (Decision 4A: individual primitive selectors)
+// =============================================================================
+
+interface PanelIndicatorMap {
+  loading: Readonly<Record<PanelId, boolean>>;
+  error: Readonly<Record<PanelId, boolean>>;
+  unseen: Readonly<Record<PanelId, boolean>>;
+  stale: Readonly<Record<PanelId, boolean>>;
+}
+
+/**
+ * Subscribes to per-panel loading and error state using individual primitive
+ * selectors. Each selector returns a boolean, so Zustand's Object.is check
+ * ensures re-renders only fire when the value actually changes.
+ *
+ * Also derives unseen (new data since last visit) and stale (data not
+ * refreshed within STALE_THRESHOLD_MS) from centralized ui-store timestamps.
+ */
+function usePanelIndicators(now: number): PanelIndicatorMap {
+  // Loading: only 3 stores expose top-level isLoading
+  const versionsLoading = useVersionsStore((s) => s.isLoading);
+  const zonesLoading = useZonesStore((s) => s.isLoading);
+  const consoleLoading = useApiConsoleStore((s) => s.isLoading);
+
+  // Error: most stores expose top-level error: string | null
+  const filesError = useFilesStore((s) => !!s.error);
+  const versionsError = useVersionsStore((s) => !!s.error);
+  const agentsError = useAgentsStore((s) => !!s.error);
+  const zonesError = useZonesStore((s) => !!s.error);
+  const accessError = useAccessStore((s) => !!s.error);
+  const paymentsError = usePaymentsStore((s) => !!s.error);
+  const searchError = useSearchStore((s) => !!s.error);
+  const workflowsError = useWorkflowsStore((s) => !!s.error);
+  const infraError = useInfraStore((s) => !!s.error);
+  const connectorsError = useConnectorsStore((s) => !!s.error);
+  const stackError = useStackStore((s) => !!s.error);
+
+  // Timestamps for unseen/stale derivation
+  const dataTs = useUiStore((s) => s.panelDataTimestamps);
+  const visitTs = useUiStore((s) => s.panelVisitTimestamps);
+
+  // Derive unseen and stale per panel
+  const unseen = {} as Record<PanelId, boolean>;
+  const stale = {} as Record<PanelId, boolean>;
+  for (const item of NAV_ITEMS) {
+    const lastData = dataTs[item.id] ?? 0;
+    const lastVisit = visitTs[item.id] ?? 0;
+    unseen[item.id] = lastData > 0 && lastVisit < lastData;
+    stale[item.id] = lastData > 0 && now - lastData > STALE_THRESHOLD_MS;
+  }
+
+  return {
+    loading: {
+      files: false,
+      versions: versionsLoading,
+      agents: false,
+      zones: zonesLoading,
+      access: false,
+      payments: false,
+      search: false,
+      workflows: false,
+      infrastructure: false,
+      console: consoleLoading,
+      connectors: false,
+      stack: false,
+    },
+    error: {
+      files: filesError,
+      versions: versionsError,
+      agents: agentsError,
+      zones: zonesError,
+      access: accessError,
+      payments: paymentsError,
+      search: searchError,
+      workflows: workflowsError,
+      infrastructure: infraError,
+      console: false, // error is inside ResponseState, not panel-level
+      connectors: connectorsError,
+      stack: stackError,
+    },
+    unseen,
+    stale,
+  };
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+interface SideNavProps {
+  readonly activePanel: PanelId;
+  readonly visible: boolean;
+}
+
+/** Interval (ms) for re-evaluating stale state. */
+const STALE_CHECK_INTERVAL_MS = 10_000;
+
+export function SideNav({ activePanel, visible }: SideNavProps): React.ReactNode {
+  const { width: columns } = useTerminalDimensions();
+  const mode = getSideNavMode(columns);
+
+  // Periodic tick so stale derivation re-evaluates over time
+  const [now, setNow] = useState(Date.now);
+  useEffect(() => {
+    const timer = setInterval(() => setNow(Date.now()), STALE_CHECK_INTERVAL_MS);
+    return () => clearInterval(timer);
+  }, []);
+
+  const indicators = usePanelIndicators(now);
+
+  // Spinner animation for loading indicators
+  const [spinnerFrame, setSpinnerFrame] = useState(0);
+  const hasAnyLoading = Object.values(indicators.loading).some(Boolean);
+
+  useEffect(() => {
+    if (!hasAnyLoading) return;
+    const timer = setInterval(() => {
+      setSpinnerFrame((prev) => (prev + 1) % SPINNER_FRAMES.length);
+    }, SPINNER_INTERVAL_MS);
+    return () => clearInterval(timer);
+  }, [hasAnyLoading]);
+
+  if (!visible || mode === "hidden") return null;
+
+  return (
+    <box
+      flexDirection="column"
+      width={mode === "full" ? 18 : 6}
+      height="100%"
+      borderRight
+      borderColor={palette.faint}
+    >
+      {NAV_ITEMS.map((item) => (
+        <SideNavItem
+          key={item.id}
+          item={item}
+          isActive={item.id === activePanel}
+          isLoading={indicators.loading[item.id]}
+          hasError={indicators.error[item.id]}
+          isUnseen={indicators.unseen[item.id]}
+          isStale={indicators.stale[item.id]}
+          mode={mode}
+          spinnerFrame={SPINNER_FRAMES[spinnerFrame]!}
+        />
+      ))}
+    </box>
+  );
+}
+
+// =============================================================================
+// Individual nav item (not memo'd per Decision 4A — 12 text lines is trivial)
+// =============================================================================
+
+/** Blue accent for unseen indicators. */
+const UNSEEN_COLOR = "#60A5FA";
+
+interface SideNavItemProps {
+  readonly item: NavItem;
+  readonly isActive: boolean;
+  readonly isLoading: boolean;
+  readonly hasError: boolean;
+  readonly isUnseen: boolean;
+  readonly isStale: boolean;
+  readonly mode: SideNavMode;
+  readonly spinnerFrame: string;
+}
+
+function SideNavItem({
+  item,
+  isActive,
+  isLoading,
+  hasError,
+  isUnseen,
+  isStale,
+  mode,
+  spinnerFrame,
+}: SideNavItemProps): React.ReactNode {
+  // Determine the status indicator character
+  // Priority: loading > error > unseen (when not active) > active > healthy
+  const indicator = isLoading
+    ? spinnerFrame
+    : hasError
+      ? "●"
+      : isUnseen && !isActive
+        ? "●"
+        : isActive
+          ? "◂"
+          : " ";
+
+  const indicatorColor = isLoading
+    ? palette.accent
+    : hasError
+      ? palette.error
+      : isUnseen && !isActive
+        ? UNSEEN_COLOR
+        : isActive
+          ? palette.accent
+          : undefined;
+
+  // Text color: active > stale (dimmed) > normal muted
+  const textColor = isActive
+    ? palette.accent
+    : isStale && !isUnseen
+      ? palette.faint
+      : palette.muted;
+
+  if (mode === "collapsed") {
+    // Collapsed: " ◎2◂" — icon + shortcut + indicator
+    return (
+      <box height={1}>
+        <text>
+          <span foregroundColor={isActive ? palette.accent : textColor}>
+            {` ${item.icon}${item.shortcut}`}
+          </span>
+          <span foregroundColor={indicatorColor}>{indicator}</span>
+        </text>
+      </box>
+    );
+  }
+
+  // Full: " 2:Versions  ◂" — shortcut:label + indicator
+  const label = item.fullLabel;
+  // Pad label to fill the available width: 18 total - 2 (left " ") - 2 (shortcut + ":") - 1 (indicator) - 1 (right pad) = 12 chars for label
+  const paddedLabel = label.padEnd(12);
+
+  return (
+    <box height={1}>
+      <text>
+        {isActive ? (
+          <>
+            <span foregroundColor={palette.accent} bold>{` ${item.shortcut}:`}</span>
+            <span foregroundColor={palette.accent} bold>{paddedLabel}</span>
+          </>
+        ) : (
+          <>
+            <span foregroundColor={textColor}>{` ${item.shortcut}:`}</span>
+            <span foregroundColor={textColor}>{paddedLabel}</span>
+          </>
+        )}
+        <span foregroundColor={indicatorColor}>{indicator}</span>
+      </text>
+    </box>
+  );
+}

package/src/shared/components/spinner.tsx

@@ -0,0 +1,26 @@
+/**
+ * Animated loading spinner using braille characters.
+ */
+
+import React, { useState, useEffect } from "react";
+
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const INTERVAL_MS = 80;
+
+interface SpinnerProps {
+  readonly label?: string;
+}
+
+export function Spinner({ label }: SpinnerProps): React.ReactNode {
+  const [frame, setFrame] = useState(0);
+
+  useEffect(() => {
+    const timer = setInterval(() => {
+      setFrame((prev) => (prev + 1) % FRAMES.length);
+    }, INTERVAL_MS);
+    return () => clearInterval(timer);
+  }, []);
+
+  const text = label ? `${FRAMES[frame]} ${label}` : FRAMES[frame]!;
+  return <text>{text}</text>;
+}

package/src/shared/components/status-bar.tsx

@@ -0,0 +1,117 @@
+/**
+ * Bottom status bar showing connection state, active identity, and path.
+ *
+ * Enhanced with semantic colors from theme.ts (Phase A1).
+ *
+ * Note: OpenTUI does not support nested <text> elements. Use <span> for
+ * inline styled segments inside a <text>.
+ */
+
+import React, { useState, useEffect } from "react";
+import { useGlobalStore } from "../../stores/global-store.js";
+import { useEventsStore } from "../../stores/events-store.js";
+import { connectionColor, palette, statusColor } from "../theme.js";
+import { textStyle } from "../text-style.js";
+
+const MIN_COLS = 80;
+const MIN_ROWS = 24;
+
+const STATUS_ICONS: Record<string, string> = {
+  connected: "●",
+  connecting: "◐",
+  disconnected: "○",
+  error: "✗",
+};
+
+export function StatusBar(): React.ReactNode {
+  const status = useGlobalStore((s) => s.connectionStatus);
+  const config = useGlobalStore((s) => s.config);
+  const serverVersion = useGlobalStore((s) => s.serverVersion);
+  const zoneId = useGlobalStore((s) => s.zoneId);
+  const activePanel = useGlobalStore((s) => s.activePanel);
+  const userInfo = useGlobalStore((s) => s.userInfo);
+  const enabledBricks = useGlobalStore((s) => s.enabledBricks);
+  const profile = useGlobalStore((s) => s.profile);
+  const mode = useGlobalStore((s) => s.mode);
+
+  // Check if events panel has active filters
+  const eventFilters = useEventsStore((s) => s.filters);
+  const hasActiveFilter = eventFilters.eventType !== null || eventFilters.search !== null;
+
+  // Terminal size guard (#3245)
+  const [terminalTooSmall, setTerminalTooSmall] = useState(false);
+  useEffect(() => {
+    const check = () => {
+      const cols = process.stdout.columns ?? 80;
+      const rows = process.stdout.rows ?? 24;
+      setTerminalTooSmall(cols < MIN_COLS || rows < MIN_ROWS);
+    };
+    check();
+    process.stdout.on("resize", check);
+    return () => { process.stdout.off("resize", check); };
+  }, []);
+
+  const icon = STATUS_ICONS[status] ?? "?";
+  const baseUrl = config.baseUrl ?? "localhost:2026";
+
+  // Build identity segment
+  const identityParts: string[] = [];
+  if (userInfo?.display_name ?? userInfo?.username) {
+    identityParts.push(userInfo!.display_name ?? userInfo!.username!);
+  } else if (config.agentId) {
+    identityParts.push(`agent:${config.agentId}`);
+  }
+  if (config.subject && config.subject !== config.agentId) {
+    identityParts.push(`sub:${config.subject}`);
+  }
+
+  // Build zone segment
+  const zone = config.zoneId ?? zoneId;
+
+  return (
+    <box
+      height={1}
+      width="100%"
+      flexDirection="row"
+    >
+      <text>
+        {terminalTooSmall ? (
+          <span style={textStyle({ fg: statusColor.warning })}>{`⚠ Terminal too small (need ${MIN_COLS}×${MIN_ROWS}) `}</span>
+        ) : ""}
+        <span style={textStyle({ fg: connectionColor[status] })}>{icon}</span>
+        <span style={textStyle({ dim: true })}>{` ${status} │ `}</span>
+        <span>{baseUrl}</span>
+        {identityParts.length > 0 ? (
+          <>
+            <span style={textStyle({ dim: true })}>{" │ "}</span>
+            <span style={textStyle({ fg: statusColor.identity })}>{identityParts.join(", ")}</span>
+          </>
+        ) : ""}
+        {serverVersion ? (
+          <>
+            <span style={textStyle({ dim: true })}>{" │ "}</span>
+            <span style={textStyle({ dim: true })}>{`v${serverVersion}${profile ? `/${profile}` : ""}${mode ? `/${mode}` : ""}`}</span>
+          </>
+        ) : ""}
+        {zone ? (
+          <>
+            <span style={textStyle({ dim: true })}>{" │ "}</span>
+            <span style={textStyle({ fg: statusColor.reference })}>{`zone:${zone}`}</span>
+          </>
+        ) : ""}
+        {enabledBricks.length > 0 ? (
+          <>
+            <span style={textStyle({ dim: true })}>{" │ "}</span>
+            <span style={textStyle({ fg: statusColor.info })}>{`${enabledBricks.length} bricks`}</span>
+          </>
+        ) : ""}
+        <span style={textStyle({ dim: true })}>{" │ "}</span>
+        <span style={textStyle({ fg: statusColor.info })}>{`[${activePanel}]`}</span>
+        {hasActiveFilter ? (
+          <span style={textStyle({ fg: "yellow" })}>{" [filtered]"}</span>
+        ) : ""}
+        <span style={textStyle({ fg: palette.faint })}>{" │ Ctrl+D:setup  ?:help"}</span>
+      </text>
+    </box>
+  );
+}

package/src/shared/components/styled-text.tsx

@@ -0,0 +1,72 @@
+/**
+ * Render ANSI-styled text in OpenTUI.
+ *
+ * Takes raw text containing ANSI escape codes and renders it as
+ * a series of styled <text> elements using the `anser` library
+ * (6M+ weekly downloads, used by Jest/Jupyter).
+ *
+ * @see Issue #3066 Architecture Decision 1C
+ */
+
+import React from "react";
+import Anser from "anser";
+import { textStyle } from "../text-style.js";
+
+/** Convert anser's "R, G, B" format to "#RRGGBB" hex for terminal compatibility. */
+function rgbToHex(rgb: string): string {
+  const parts = rgb.split(",").map((s) => parseInt(s.trim(), 10));
+  if (parts.length !== 3 || parts.some(Number.isNaN)) return rgb;
+  return `#${parts.map((n) => Math.max(0, Math.min(255, n!)).toString(16).padStart(2, "0")).join("")}`;
+}
+
+interface StyledTextProps {
+  /** Raw text potentially containing ANSI escape codes. */
+  readonly children: string;
+}
+
+export function StyledText({ children }: StyledTextProps): React.ReactNode {
+  if (!children) return null;
+
+  const spans = Anser.ansiToJson(children, {
+    json: true,
+    remove_empty: true,
+  });
+
+  if (spans.length === 0) return null;
+
+  // Single unstyled span — render directly
+  if (spans.length === 1 && !spans[0]!.was_processed) {
+    return <text>{spans[0]!.content}</text>;
+  }
+
+  return (
+    <text>
+      {spans.map((span, i) => {
+        const decoration = span.decoration ?? "";
+        return (
+          <span
+            key={i}
+            style={textStyle({
+              bold: decoration.includes("bold") || undefined,
+              dim: decoration.includes("dim") || undefined,
+              underline: decoration.includes("underline") || undefined,
+              inverse: decoration.includes("reverse") || undefined,
+              fg: span.fg ? rgbToHex(span.fg) : undefined,
+              bg: span.bg ? rgbToHex(span.bg) : undefined,
+            })}
+          >
+            {span.content}
+          </span>
+        );
+      })}
+    </text>
+  );
+}
+
+/**
+ * Strip all ANSI escape sequences from a string, returning plain text.
+ * Re-exported from anser for convenience.
+ */
+export function stripAnsi(input: string): string {
+  return Anser.ansiToText(input);
+}

package/src/shared/components/sub-tab-bar-utils.ts

@@ -0,0 +1,100 @@
+/**
+ * Pure utility functions for sub-tab bar keyboard cycling.
+ *
+ * Separated from sub-tab-bar.tsx so tests can import without triggering
+ * JSX compilation (matching tab-bar-utils.ts pattern).
+ *
+ * @see Issue #3498
+ */
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/** Minimal tab shape consumed by cycling helpers. */
+export interface SubTab {
+  readonly id: string;
+  readonly label: string;
+}
+
+// =============================================================================
+// Cycling helpers
+// =============================================================================
+
+/**
+ * Cycle forward to the next tab (wraps around).
+ *
+ * If activeTab is not found in tabs (e.g. brick just disabled it),
+ * defaults to the first tab to avoid undefined behavior.
+ */
+export function subTabForward<T extends string>(
+  tabs: readonly { readonly id: T }[],
+  activeTab: T,
+  setActiveTab: (tab: T) => void,
+): void {
+  if (tabs.length === 0) return;
+  const idx = tabs.findIndex((t) => t.id === activeTab);
+  // Guard: if activeTab not in list, jump to first tab
+  const nextIdx = idx === -1 ? 0 : (idx + 1) % tabs.length;
+  const next = tabs[nextIdx];
+  if (next) setActiveTab(next.id);
+}
+
+/**
+ * Cycle backward to the previous tab (wraps around).
+ *
+ * Same guard as subTabForward for missing activeTab.
+ */
+export function subTabBackward<T extends string>(
+  tabs: readonly { readonly id: T }[],
+  activeTab: T,
+  setActiveTab: (tab: T) => void,
+): void {
+  if (tabs.length === 0) return;
+  const idx = tabs.findIndex((t) => t.id === activeTab);
+  // Guard: if activeTab not in list, jump to first tab
+  const prevIdx = idx === -1 ? 0 : (idx - 1 + tabs.length) % tabs.length;
+  const prev = tabs[prevIdx];
+  if (prev) setActiveTab(prev.id);
+}
+
+// =============================================================================
+// Keyboard binding helper
+// =============================================================================
+
+/**
+ * Returns a keybinding object with `tab` (forward) and `shift+tab` (backward)
+ * entries that panels can spread into useKeyboard.
+ *
+ * Split-pane panels that need Shift+Tab for focus-toggle can override after
+ * spreading: `{ ...subTabCycleBindings(...), "shift+tab": () => toggleFocus("zones") }`
+ */
+export function subTabCycleBindings<T extends string>(
+  tabs: readonly { readonly id: T }[],
+  activeTab: T,
+  setActiveTab: (tab: T) => void,
+): Record<string, () => void> {
+  return {
+    tab: () => subTabForward(tabs, activeTab, setActiveTab),
+    "shift+tab": () => subTabBackward(tabs, activeTab, setActiveTab),
+  };
+}
+
+// =============================================================================
+// Tab fallback logic
+// =============================================================================
+
+/**
+ * Determine if the active tab needs to fall back to the first visible tab.
+ *
+ * Returns the tab ID to switch to, or null if no switch is needed.
+ * Pure function — the hook (useTabFallback) wraps this in a useEffect.
+ */
+export function tabFallback<T extends string>(
+  visibleIds: readonly T[],
+  activeTab: T,
+): T | null {
+  if (visibleIds.length === 0) return null;
+  if (visibleIds.includes(activeTab)) return null;
+  return visibleIds[0]!;
+}

package/src/shared/components/sub-tab-bar.tsx

@@ -0,0 +1,40 @@
+/**
+ * Shared sub-tab bar component for panel sub-navigation.
+ *
+ * Render-only — does NOT own keyboard bindings. Panels compose
+ * subTabForward/subTabBackward from sub-tab-bar-utils.ts into their
+ * own useKeyboard calls.
+ *
+ * @see Issue #3498
+ */
+
+import React from "react";
+import type { SubTab } from "./sub-tab-bar-utils.js";
+
+export interface SubTabBarProps {
+  /** Visible tabs to render (output of useVisibleTabs). */
+  readonly tabs: readonly SubTab[];
+  /** Currently active tab ID. */
+  readonly activeTab: string;
+}
+
+/**
+ * Renders a horizontal sub-tab bar with bracket notation for the active tab.
+ *
+ * Example output: `[Zones]  Bricks   Drift   Reindex`
+ */
+export function SubTabBar({ tabs, activeTab }: SubTabBarProps): React.ReactNode {
+  if (tabs.length === 0) return null;
+
+  return (
+    <box height={1} width="100%">
+      <text>
+        {tabs
+          .map((tab) =>
+            tab.id === activeTab ? `[${tab.label}]` : ` ${tab.label} `,
+          )
+          .join(" ")}
+      </text>
+    </box>
+  );
+}

package/src/shared/components/tab-bar-utils.ts

@@ -0,0 +1,36 @@
+/**
+ * Tab type and pure utility functions for the tab bar (#3243).
+ *
+ * Separated from tab-bar.tsx so tests can import without triggering
+ * JSX compilation (matching the codebase pattern where pure logic
+ * is testable without React context).
+ */
+
+export interface Tab {
+  readonly id: string;
+  readonly label: string;
+  readonly fullLabel?: string;
+  readonly shortcut: string;
+}
+
+/**
+ * Compute the rendered character width of the tab bar for a given label mode.
+ *
+ * Layout per tab: prefix (2) + shortcut (1) + ":" (1) + label length.
+ * Separator between tabs: " │ " (3 chars).
+ */
+export function computeTabBarWidth(tabs: readonly Tab[], useFullLabels: boolean): number {
+  let width = 0;
+  for (let i = 0; i < tabs.length; i++) {
+    const tab = tabs[i]!;
+    const label = useFullLabels ? (tab.fullLabel ?? tab.label) : tab.label;
+    width += 4 + label.length;
+    if (i < tabs.length - 1) width += 3;
+  }
+  return width;
+}
+
+/** Returns true when full labels fit within the given column count. */
+export function shouldUseFullLabels(tabs: readonly Tab[], columns: number): boolean {
+  return computeTabBarWidth(tabs, true) <= columns;
+}