@nexus-ai-fs/tui 0.9.18

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

@@ -0,0 +1,50 @@
+/**
+ * Horizontal tab bar for switching between panels.
+ *
+ * Enhanced with semantic colors (Phase A1).
+ */
+
+import React from "react";
+import { palette } from "../theme.js";
+import { textStyle } from "../text-style.js";
+
+export interface Tab {
+  readonly id: string;
+  readonly label: string;
+  readonly shortcut: string;
+}
+
+interface TabBarProps {
+  readonly tabs: readonly Tab[];
+  readonly activeTab: string;
+  readonly onSelect: (id: string) => void;
+}
+
+export function TabBar({ tabs, activeTab }: TabBarProps): React.ReactNode {
+  return (
+    <box height={1} width="100%">
+      <text>
+        {tabs.map((tab, index) => {
+          const isActive = tab.id === activeTab;
+          const suffix = index < tabs.length - 1 ? " │ " : "";
+          if (isActive) {
+            return (
+              <span key={tab.id}>
+                <span style={textStyle({ fg: palette.accent, bold: true })}>{"▸ "}</span>
+                <span style={textStyle({ fg: palette.muted })}>{`${tab.shortcut}:`}</span>
+                <span style={textStyle({ fg: palette.accent, bold: true })}>{tab.label}</span>
+                <span style={textStyle({ fg: palette.faint })}>{suffix}</span>
+              </span>
+            );
+          }
+          return (
+            <span key={tab.id}>
+              <span style={textStyle({ fg: palette.muted })}>{`  ${tab.shortcut}:${tab.label}`}</span>
+              <span style={textStyle({ fg: palette.faint })}>{suffix}</span>
+            </span>
+          );
+        })}
+      </text>
+    </box>
+  );
+}

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

@@ -0,0 +1,73 @@
+/**
+ * Shared text input component for consistent input behavior.
+ *
+ * Handles: character input, backspace, enter (submit), escape (cancel).
+ * Can be used standalone or composed in forms.
+ *
+ * @see Issue #3066, Phase E7
+ */
+
+import React from "react";
+import { useKeyboard } from "../hooks/use-keyboard.js";
+import { statusColor } from "../theme.js";
+import { textStyle } from "../text-style.js";
+
+interface TextInputProps {
+  /** Current input value */
+  readonly value: string;
+  /** Called when value changes */
+  readonly onChange: (value: string) => void;
+  /** Called when Enter is pressed */
+  readonly onSubmit?: (value: string) => void;
+  /** Called when Escape is pressed */
+  readonly onCancel?: () => void;
+  /** Label shown before the input */
+  readonly label?: string;
+  /** Placeholder text when empty */
+  readonly placeholder?: string;
+  /** Whether input is active (receives key events) */
+  readonly active?: boolean;
+}
+
+export function TextInput({
+  value,
+  onChange,
+  onSubmit,
+  onCancel,
+  label,
+  placeholder,
+  active = true,
+}: TextInputProps): React.ReactNode {
+  useKeyboard(
+    active
+      ? {
+          return: () => onSubmit?.(value),
+          escape: () => onCancel?.(),
+          backspace: () => onChange(value.slice(0, -1)),
+        }
+      : {},
+    active
+      ? (key) => {
+          // Only append printable characters (single char)
+          if (key.length === 1) {
+            onChange(value + key);
+          }
+        }
+      : undefined,
+  );
+
+  const displayValue = value || (placeholder ? placeholder : "");
+  const isDimmed = !value && placeholder;
+
+  return (
+    <box flexDirection="row" height={1}>
+      {label && (
+        <text style={textStyle({ fg: statusColor.info })}>{`${label}: `}</text>
+      )}
+      <text style={textStyle({ dim: !!isDimmed })}>
+        {displayValue}
+        {active && <span style={textStyle({ fg: statusColor.info })}>{"█"}</span>}
+      </text>
+    </box>
+  );
+}

package/src/shared/components/tooltip.tsx

@@ -0,0 +1,53 @@
+/**
+ * Dismissible first-run tooltip.
+ *
+ * Shows a brief tip message at the top of a panel on first visit.
+ * Dismissed by any key press, tracked via the first-run store so
+ * it only shows once per session per key.
+ *
+ * NOTE: This tooltip is cosmetic-only. It dismisses on any key press but
+ * does NOT block parent keyboard handlers. This is intentional -- the
+ * tooltip is a hint overlay, not a modal dialog. Parent key bindings
+ * (j/k/tab/etc.) continue to work while the tooltip is visible.
+ */
+
+import React from "react";
+import { useFirstRunStore } from "../../stores/first-run-store.js";
+import { useKeyboard } from "../hooks/use-keyboard.js";
+import { statusColor } from "../theme.js";
+import { textStyle } from "../text-style.js";
+
+interface TooltipProps {
+  /** Unique key for this tooltip (e.g. "search-panel", "events-panel"). */
+  readonly tooltipKey: string;
+  /** The message to display. */
+  readonly message: string;
+}
+
+export function Tooltip({ tooltipKey, message }: TooltipProps): React.ReactNode {
+  const shouldShow = useFirstRunStore((s) => s.shouldShow);
+  const dismiss = useFirstRunStore((s) => s.dismiss);
+
+  const visible = shouldShow(tooltipKey);
+
+  // Dismiss on any keypress via onUnhandled only -- no explicit key bindings
+  // so we don't intercept j/k/tab/etc. from the parent panel.
+  useKeyboard(
+    {},
+    visible
+      ? (keyName: string) => {
+          if (keyName) dismiss(tooltipKey);
+        }
+      : undefined,
+  );
+
+  if (!visible) return null;
+
+  return (
+    <box height={1} width="100%">
+      <text style={textStyle({ fg: statusColor.info })}>
+        {`${message}  (press any key to dismiss)`}
+      </text>
+    </box>
+  );
+}

package/src/shared/components/virtual-list.tsx

@@ -0,0 +1,93 @@
+/**
+ * Windowed list rendering for terminal UIs.
+ *
+ * Only renders the visible rows plus an overscan buffer, instead of
+ * materializing all items. This keeps the terminal responsive even for
+ * 10k+ item lists.
+ *
+ * @see Issue #3102, Decision 1A
+ */
+
+import React, { useMemo } from "react";
+
+export interface VirtualListProps<T> {
+  /** Full (flat) list of items. */
+  readonly items: readonly T[];
+  /** Render callback for a single item row. */
+  readonly renderItem: (item: T, index: number) => React.ReactNode;
+  /** Height of each item in terminal rows. Default: 1 */
+  readonly itemHeight?: number;
+  /** Maximum number of visible rows in the viewport. */
+  readonly viewportHeight: number;
+  /** Currently selected/focused index (drives scroll position). */
+  readonly selectedIndex: number;
+  /** Extra rows rendered above and below the viewport. Default: 5 */
+  readonly overscan?: number;
+}
+
+/**
+ * Calculate the visible window for the given parameters.
+ *
+ * Exported for unit testing the pure math separately from React rendering.
+ */
+export function calculateWindow(
+  totalItems: number,
+  viewportHeight: number,
+  selectedIndex: number,
+  overscan: number,
+): { startIndex: number; endIndex: number; scrollOffset: number } {
+  if (totalItems === 0) {
+    return { startIndex: 0, endIndex: 0, scrollOffset: 0 };
+  }
+
+  // Determine the scroll offset so the selected item is visible.
+  // We keep a "follow" strategy: if selectedIndex would be outside the
+  // current viewport, we shift the scroll offset to bring it into view.
+  let scrollOffset = 0;
+
+  if (totalItems <= viewportHeight) {
+    // Everything fits — no scrolling needed
+    scrollOffset = 0;
+  } else {
+    // Center the selected item in the viewport, clamped to valid range
+    scrollOffset = Math.max(0, selectedIndex - Math.floor(viewportHeight / 2));
+    const maxOffset = totalItems - viewportHeight;
+    scrollOffset = Math.min(scrollOffset, maxOffset);
+  }
+
+  // Apply overscan to render a buffer above/below
+  const startIndex = Math.max(0, scrollOffset - overscan);
+  const endIndex = Math.min(totalItems, scrollOffset + viewportHeight + overscan);
+
+  return { startIndex, endIndex, scrollOffset };
+}
+
+export function VirtualList<T>({
+  items,
+  renderItem,
+  itemHeight = 1,
+  viewportHeight,
+  selectedIndex,
+  overscan = 5,
+}: VirtualListProps<T>): React.ReactNode {
+  const { startIndex, endIndex } = useMemo(
+    () => calculateWindow(items.length, viewportHeight, selectedIndex, overscan),
+    [items.length, viewportHeight, selectedIndex, overscan],
+  );
+
+  // Slice the items to only the visible window
+  const visibleItems = useMemo(
+    () => items.slice(startIndex, endIndex),
+    [items, startIndex, endIndex],
+  );
+
+  if (items.length === 0) {
+    return null;
+  }
+
+  return (
+    <box flexDirection="column" height={viewportHeight * itemHeight} width="100%">
+      {visibleItems.map((item, i) => renderItem(item, startIndex + i))}
+    </box>
+  );
+}

package/src/shared/components/welcome-screen.tsx

@@ -0,0 +1,111 @@
+/**
+ * Welcome screen shown on fresh servers.
+ * Offers to seed demo data or start with empty server.
+ */
+import React, { useState } from "react";
+import { useKeyboard } from "../hooks/use-keyboard.js";
+import { useGlobalStore } from "../../stores/global-store.js";
+import { statusColor } from "../theme.js";
+import { Spinner } from "./spinner.js";
+import { textStyle } from "../text-style.js";
+
+interface WelcomeScreenProps {
+  readonly onDismiss: () => void;
+}
+
+export function WelcomeScreen({ onDismiss }: WelcomeScreenProps): React.ReactNode {
+  const client = useGlobalStore((s) => s.client);
+  const config = useGlobalStore((s) => s.config);
+  const serverVersion = useGlobalStore((s) => s.serverVersion);
+  const [seeding, setSeeding] = useState(false);
+  const [seedError, setSeedError] = useState<string | null>(null);
+  const [showDetails, setShowDetails] = useState(false);
+
+  useKeyboard(seeding ? {} : {
+    "y": async () => {
+      if (!client) return;
+      setSeeding(true);
+      setSeedError(null);
+      try {
+        await client.post("/api/v2/admin/demo/seed", {});
+        onDismiss();
+      } catch {
+        setSeeding(false);
+        setSeedError("Seeding failed. Press Y to retry or N to skip.");
+      }
+    },
+    "n": onDismiss,
+    "?": () => setShowDetails((prev) => !prev),
+    "escape": onDismiss,
+  });
+
+  const baseUrl = config.baseUrl ?? "localhost:2026";
+
+  return (
+    <box height="100%" width="100%" justifyContent="center" alignItems="center">
+      <box
+        flexDirection="column"
+        borderStyle="double"
+        width={56}
+        padding={1}
+      >
+        <text style={textStyle({ fg: "#00d4ff", bold: true })}>
+          {"    _   _ _____ __  __ _   _ ____"}
+        </text>
+        <text style={textStyle({ fg: "#00b8ff", bold: true })}>
+          {"   | \\ | | ____|  \\/  | | | / ___|"}
+        </text>
+        <text style={textStyle({ fg: "#4d8eff", bold: true })}>
+          {"   |  \\| |  _|  >\\/< | | | \\___ \\"}
+        </text>
+        <text style={textStyle({ fg: "#8066ff", bold: true })}>
+          {"   | |\\  | |___/ /\\ \\| |_| |___) |"}
+        </text>
+        <text style={textStyle({ fg: "#b44dff", bold: true })}>
+          {"   |_| \\_|_____/_/  \\_\\\\___/|____/"}
+        </text>
+        <text>{""}</text>
+        <text style={textStyle({ dim: true })}>{`  Connected to ${baseUrl}${serverVersion ? ` (v${serverVersion})` : ""}`}</text>
+        <text>{""}</text>
+        <text>{"  This server has no data yet. Would you like"}</text>
+        <text>{"  to seed demo content?"}</text>
+        <text>{""}</text>
+        {seeding ? (
+          <Spinner label="  Seeding demo data..." />
+        ) : (
+          <>
+            <text>
+              <span style={textStyle({ fg: statusColor.info })}>{"  [Y]"}</span>
+              <span>{" Seed demo data (files, agents, permissions)"}</span>
+            </text>
+            <text>
+              <span style={textStyle({ fg: statusColor.dim })}>{"  [N]"}</span>
+              <span>{" Start with empty server"}</span>
+            </text>
+            <text>
+              <span style={textStyle({ fg: statusColor.dim })}>{"  [?]"}</span>
+              <span>{" What's in the demo data?"}</span>
+            </text>
+          </>
+        )}
+        {seedError && (
+          <>
+            <text>{""}</text>
+            <text style={textStyle({ fg: statusColor.error })}>{"  "}{seedError}</text>
+          </>
+        )}
+        {showDetails && (
+          <>
+            <text>{""}</text>
+            <text style={textStyle({ dim: true })}>{"  Demo data includes:"}</text>
+            <text style={textStyle({ dim: true })}>{"  \u2022 12 sample files (markdown, code, data)"}</text>
+            <text style={textStyle({ dim: true })}>{"  \u2022 2 user identities"}</text>
+            <text style={textStyle({ dim: true })}>{"  \u2022 1 agent with trajectories"}</text>
+            <text style={textStyle({ dim: true })}>{"  \u2022 HERB evaluation corpus"}</text>
+            <text style={textStyle({ dim: true })}>{"  \u2022 ReBAC permission policies"}</text>
+          </>
+        )}
+      </box>
+    </box>
+  );
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Hook to get the configured FetchClient from the global store.
+ */
+
+import { useGlobalStore } from "../../stores/global-store.js";
+import type { FetchClient } from "@nexus-ai-fs/api-client";
+
+export function useApi(): FetchClient | null {
+  return useGlobalStore((state) => state.client);
+}

package/src/shared/hooks/use-brick-available.ts

@@ -0,0 +1,42 @@
+/**
+ * Hook to check if a brick is available (enabled) in the current deployment.
+ *
+ * Returns { available, loading } to distinguish "not loaded yet" from
+ * "definitively disabled" (Decision 1A).
+ */
+
+import { useGlobalStore } from "../../stores/global-store.js";
+
+interface BrickAvailability {
+  readonly available: boolean;
+  readonly loading: boolean;
+}
+
+/**
+ * Check if a specific brick is enabled in the current deployment profile.
+ *
+ * During initial feature loading, returns { available: false, loading: true }
+ * to prevent flash of "not available" messages.
+ */
+export function useBrickAvailable(brickName: string): BrickAvailability {
+  const enabledBricks = useGlobalStore((s) => s.enabledBricks);
+  const featuresLoaded = useGlobalStore((s) => s.featuresLoaded);
+
+  return {
+    available: enabledBricks.includes(brickName),
+    loading: !featuresLoaded,
+  };
+}
+
+/**
+ * Check if any of the specified bricks are available (OR semantics).
+ */
+export function useAnyBrickAvailable(brickNames: readonly string[]): BrickAvailability {
+  const enabledBricks = useGlobalStore((s) => s.enabledBricks);
+  const featuresLoaded = useGlobalStore((s) => s.featuresLoaded);
+
+  return {
+    available: brickNames.some((name) => enabledBricks.includes(name)),
+    loading: !featuresLoaded,
+  };
+}

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

@@ -0,0 +1,66 @@
+/**
+ * Imperative confirmation dialog system.
+ *
+ * Usage in any component:
+ * ```ts
+ * const confirm = useConfirmStore((s) => s.confirm);
+ * const ok = await confirm("Delete file?", "This cannot be undone.");
+ * if (ok) { doDelete(); }
+ * ```
+ *
+ * A single <ConfirmDialog> instance at the App level reads from this store.
+ *
+ * @see Issue #3066 Architecture Decision 3A
+ */
+
+import { create } from "zustand";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface ConfirmState {
+  readonly visible: boolean;
+  readonly title: string;
+  readonly message: string;
+  readonly resolve: ((value: boolean) => void) | null;
+
+  /**
+   * Show a confirmation dialog and wait for the user's response.
+   * Returns true if confirmed, false if cancelled.
+   *
+   * If a previous confirmation is pending, it is auto-rejected (returns false).
+   */
+  readonly confirm: (title: string, message: string) => Promise<boolean>;
+}
+
+// =============================================================================
+// Store
+// =============================================================================
+
+export const useConfirmStore = create<ConfirmState>((set, get) => ({
+  visible: false,
+  title: "",
+  message: "",
+  resolve: null,
+
+  confirm: (title, message) => {
+    // Reject any pending confirmation
+    const prev = get().resolve;
+    if (prev) {
+      prev(false);
+    }
+
+    return new Promise<boolean>((resolve) => {
+      set({
+        visible: true,
+        title,
+        message,
+        resolve: (value: boolean) => {
+          resolve(value);
+          set({ visible: false, title: "", message: "", resolve: null });
+        },
+      });
+    });
+  },
+}));

package/src/shared/hooks/use-connection-state.ts

@@ -0,0 +1,67 @@
+/**
+ * Connection state detection for the PreConnectionScreen (Decision 12A).
+ *
+ * Pure function exported for testing — follows the detectFreshServer pattern.
+ */
+
+import type { ConnectionStatus } from "../../stores/global-store.js";
+import type { NexusClientOptions } from "@nexus-ai-fs/api-client";
+
+/**
+ * Describes why the TUI cannot connect, guiding the PreConnectionScreen UI.
+ *
+ *   "no-config"  — No API key configured (client is null)
+ *   "no-server"  — Server unreachable (connection error)
+ *   "auth-failed" — Server reachable but authentication failed
+ *   "connecting" — Still trying to connect
+ *   "ready"      — Connected and authenticated
+ */
+export type ConnectionState =
+  | "no-config"
+  | "no-server"
+  | "auth-failed"
+  | "connecting"
+  | "ready";
+
+/**
+ * Derive a high-level connection state from store values.
+ * Pure function — no side effects, fully testable.
+ */
+export function detectConnectionState(
+  connectionStatus: ConnectionStatus,
+  connectionError: string | null,
+  config: NexusClientOptions,
+): ConnectionState {
+  // No API key → client was never created
+  if (!config.apiKey) {
+    return "no-config";
+  }
+
+  switch (connectionStatus) {
+    case "connected":
+      return "ready";
+
+    case "connecting":
+    case "disconnected":
+      return "connecting";
+
+    case "error": {
+      if (!connectionError) return "no-server";
+
+      // Distinguish auth failures from network failures
+      const lower = connectionError.toLowerCase();
+      if (
+        lower.includes("unauthorized") ||
+        lower.includes("forbidden") ||
+        lower.includes("401") ||
+        lower.includes("403")
+      ) {
+        return "auth-failed";
+      }
+      return "no-server";
+    }
+
+    default:
+      return "connecting";
+  }
+}

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

@@ -0,0 +1,31 @@
+/**
+ * Hook for clipboard copy with visual feedback.
+ * Shows "Copied!" flash in the status area briefly.
+ */
+import { useState, useCallback, useRef, useEffect } from "react";
+import { copyToClipboard } from "../lib/clipboard.js";
+import { useAnnouncementStore } from "../../stores/announcement-store.js";
+import { formatSuccessAnnouncement } from "../accessibility-announcements.js";
+
+export function useCopy() {
+  const [copied, setCopied] = useState(false);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const announce = useAnnouncementStore((s) => s.announce);
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      if (timerRef.current) clearTimeout(timerRef.current);
+    };
+  }, []);
+
+  const copy = useCallback((text: string) => {
+    copyToClipboard(text);
+    announce(formatSuccessAnnouncement("Copied to clipboard"), "success");
+    setCopied(true);
+    if (timerRef.current) clearTimeout(timerRef.current);
+    timerRef.current = setTimeout(() => setCopied(false), 1500);
+  }, [announce]);
+
+  return { copy, copied };
+}

package/src/shared/hooks/use-fresh-server.ts

@@ -0,0 +1,62 @@
+/**
+ * Detects if the connected server is "fresh" (no user data yet).
+ * Used to trigger the welcome screen on first run.
+ */
+import { useState, useEffect } from "react";
+import { useGlobalStore } from "../../stores/global-store.js";
+
+interface FreshCheckClient {
+  get<T>(url: string): Promise<T>;
+}
+
+/**
+ * Pure detection logic — exported for testing without React hooks.
+ * Returns true if the server has no files and no agents.
+ */
+export async function detectFreshServer(client: FreshCheckClient): Promise<boolean> {
+  try {
+    const [files, agents] = await Promise.all([
+      client.get<{ entries: unknown[] }>("/api/v2/files?path=/&limit=5"),
+      client.get<{ agents: unknown[] }>("/api/v2/agents?limit=1&offset=0"),
+    ]);
+    const hasFiles = (files.entries?.length ?? 0) > 0;
+    const hasAgents = (agents.agents?.length ?? 0) > 0;
+    return !hasFiles && !hasAgents;
+  } catch {
+    return false; // Assume not fresh on error
+  }
+}
+
+export function useFreshServer(): { isFresh: boolean | null; loading: boolean } {
+  const client = useGlobalStore((s) => s.client);
+  const connectionStatus = useGlobalStore((s) => s.connectionStatus);
+  const [isFresh, setIsFresh] = useState<boolean | null>(null);
+  const [loading, setLoading] = useState(false);
+
+  useEffect(() => {
+    if (connectionStatus !== "connected" || !client) {
+      setIsFresh(null);
+      return;
+    }
+
+    let cancelled = false;
+    setLoading(true);
+
+    // Check if server has any user-created data
+    // A "fresh" server has no files beyond defaults and no agents
+    (async () => {
+      try {
+        const result = await detectFreshServer(client);
+        if (!cancelled) setIsFresh(result);
+      } catch {
+        if (!cancelled) setIsFresh(false);
+      } finally {
+        if (!cancelled) setLoading(false);
+      }
+    })();
+
+    return () => { cancelled = true; };
+  }, [client, connectionStatus]);
+
+  return { isFresh, loading };
+}