@tangle-network/ui 1.0.0

package/src/hooks/use-auth.ts

@@ -0,0 +1,153 @@
+"use client";
+
+import * as React from "react";
+
+export interface AuthUser {
+  customer_id: string;
+  email: string;
+  name?: string;
+  tier: string;
+  github?: {
+    login: string;
+    connected: boolean;
+  } | null;
+  session_expires_at?: string;
+}
+
+export interface UseAuthOptions {
+  apiBaseUrl: string;
+  revalidateOnFocus?: boolean;
+  shouldRetryOnError?: boolean;
+}
+
+export interface UseAuthResult {
+  user: AuthUser | null;
+  isLoading: boolean;
+  isError: boolean;
+  error: Error | null;
+  mutate: () => Promise<void>;
+}
+
+/**
+ * Hook for managing authentication state.
+ * Fetches user session from the API and provides loading/error states.
+ */
+export function useAuth({
+  apiBaseUrl,
+  revalidateOnFocus = false,
+  shouldRetryOnError = false,
+}: UseAuthOptions): UseAuthResult {
+  const [user, setUser] = React.useState<AuthUser | null>(null);
+  const [isLoading, setIsLoading] = React.useState(true);
+  const [error, setError] = React.useState<Error | null>(null);
+  const retryTimerRef = React.useRef<ReturnType<typeof setTimeout> | null>(null);
+  const abortRef = React.useRef<AbortController | null>(null);
+
+  const fetchSession = React.useCallback(async () => {
+    abortRef.current?.abort();
+    const controller = new AbortController();
+    abortRef.current = controller;
+
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      const res = await fetch(`${apiBaseUrl}/auth/session`, {
+        credentials: "include",
+        signal: controller.signal,
+      });
+
+      if (!res.ok) {
+        throw new Error("Not authenticated");
+      }
+
+      const data = await res.json();
+      if (data.success && data.data) {
+        setUser(data.data);
+      } else {
+        setUser(null);
+      }
+    } catch (err) {
+      if ((err as Error).name === "AbortError") return;
+      setError(err instanceof Error ? err : new Error("Unknown error"));
+      setUser(null);
+
+      if (shouldRetryOnError) {
+        if (retryTimerRef.current) clearTimeout(retryTimerRef.current);
+        retryTimerRef.current = setTimeout(fetchSession, 5000);
+      }
+    } finally {
+      if (!controller.signal.aborted) {
+        setIsLoading(false);
+      }
+    }
+  }, [apiBaseUrl, shouldRetryOnError]);
+
+  React.useEffect(() => {
+    fetchSession();
+    return () => {
+      abortRef.current?.abort();
+      if (retryTimerRef.current) clearTimeout(retryTimerRef.current);
+    };
+  }, [fetchSession]);
+
+  React.useEffect(() => {
+    if (!revalidateOnFocus) return;
+
+    const handleFocus = () => {
+      fetchSession();
+    };
+
+    window.addEventListener("focus", handleFocus);
+    return () => window.removeEventListener("focus", handleFocus);
+  }, [revalidateOnFocus, fetchSession]);
+
+  return {
+    user,
+    isLoading,
+    isError: !!error,
+    error,
+    mutate: fetchSession,
+  };
+}
+
+/**
+ * Creates a fetcher function that includes auth credentials.
+ * Uses both cookie-based session and localStorage API key for backwards compatibility.
+ */
+export function createAuthFetcher(_apiBaseUrl: string) {
+  return async function authFetcher<T = unknown>(
+    url: string,
+    options?: RequestInit,
+  ): Promise<T> {
+    const res = await fetch(url, {
+      ...options,
+      credentials: "include",
+      headers: {
+        ...options?.headers,
+      },
+    });
+
+    if (!res.ok) {
+      throw new Error(`Request failed with status ${res.status}`);
+    }
+
+    return res.json();
+  };
+}
+
+/**
+ * Hook to get the API key from localStorage.
+ * For backwards compatibility with API key-based auth.
+ */
+export function useApiKey(): string | null {
+  const [apiKey, setApiKey] = React.useState<string | null>(null);
+
+  React.useEffect(() => {
+    if (typeof window !== "undefined") {
+      setApiKey(localStorage.getItem("apiKey"));
+    }
+  }, []);
+
+  return apiKey;
+}

package/src/hooks/use-auto-scroll.ts

@@ -0,0 +1,59 @@
+import {
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  type RefObject,
+} from "react";
+
+const BOTTOM_THRESHOLD = 40;
+
+/**
+ * Scroll-to-bottom behaviour: sticks to the bottom while streaming,
+ * pauses when user scrolls up, resumes when user scrolls back down.
+ */
+export function useAutoScroll(
+  containerRef: RefObject<HTMLElement | null>,
+  deps: unknown[] = [],
+) {
+  const [isAtBottom, setIsAtBottom] = useState(true);
+  const userScrolledUp = useRef(false);
+
+  const checkBottom = useCallback(() => {
+    const el = containerRef.current;
+    if (!el) return true;
+    return el.scrollHeight - el.scrollTop - el.clientHeight < BOTTOM_THRESHOLD;
+  }, [containerRef]);
+
+  useEffect(() => {
+    const el = containerRef.current;
+    if (!el) return;
+
+    const onScroll = () => {
+      const atBottom = checkBottom();
+      setIsAtBottom(atBottom);
+      userScrolledUp.current = !atBottom;
+    };
+
+    el.addEventListener("scroll", onScroll, { passive: true });
+    return () => el.removeEventListener("scroll", onScroll);
+  }, [containerRef, checkBottom]);
+
+  useEffect(() => {
+    if (userScrolledUp.current) return;
+    const el = containerRef.current;
+    if (!el) return;
+    el.scrollTop = el.scrollHeight;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, deps);
+
+  const scrollToBottom = useCallback(() => {
+    const el = containerRef.current;
+    if (!el) return;
+    userScrolledUp.current = false;
+    el.scrollTo({ top: el.scrollHeight, behavior: "smooth" });
+    setIsAtBottom(true);
+  }, [containerRef]);
+
+  return { isAtBottom, scrollToBottom };
+}

package/src/hooks/use-dropdown-menu.ts

@@ -0,0 +1,40 @@
+import { useEffect, useRef, useState } from 'react';
+
+interface UseDropdownMenuOptions {
+  closeOnEsc?: boolean;
+}
+
+export function useDropdownMenu(options?: UseDropdownMenuOptions) {
+  const closeOnEsc = options?.closeOnEsc ?? true;
+  const [open, setOpen] = useState(false);
+  const ref = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    function handleClick(e: MouseEvent) {
+      if (ref.current && !ref.current.contains(e.target as Node)) {
+        setOpen(false);
+      }
+    }
+    if (open) {
+      document.addEventListener('mousedown', handleClick);
+    }
+    return () => document.removeEventListener('mousedown', handleClick);
+  }, [open]);
+
+  useEffect(() => {
+    if (!open || !closeOnEsc) return;
+    function handleKey(e: KeyboardEvent) {
+      if (e.key === 'Escape') setOpen(false);
+    }
+    document.addEventListener('keydown', handleKey);
+    return () => document.removeEventListener('keydown', handleKey);
+  }, [open, closeOnEsc]);
+
+  return {
+    open,
+    setOpen,
+    ref,
+    toggle: () => setOpen((prev) => !prev),
+    close: () => setOpen(false),
+  };
+}

package/src/hooks/use-live-time.test.tsx

@@ -0,0 +1,40 @@
+import { describe, it, expect, vi, afterEach, beforeEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import { useLiveTime } from "./use-live-time";
+
+describe("useLiveTime", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("advances Date.now() snapshot on the given cadence", () => {
+    vi.setSystemTime(new Date("2025-01-01T00:00:00Z"));
+    const { result } = renderHook(() => useLiveTime(1000));
+    const initial = result.current;
+
+    act(() => {
+      vi.advanceTimersByTime(1000);
+    });
+    expect(result.current).toBeGreaterThan(initial);
+
+    act(() => {
+      vi.advanceTimersByTime(2000);
+    });
+    expect(result.current).toBeGreaterThanOrEqual(initial + 3000);
+  });
+
+  it("falls back to a safe cadence when intervalMs is NaN", () => {
+    vi.setSystemTime(new Date("2025-01-01T00:00:00Z"));
+    const setIntervalSpy = vi.spyOn(window, "setInterval");
+    renderHook(() => useLiveTime(Number.NaN));
+    // Must not pass NaN (browsers coerce to 0 and spin a render loop)
+    // nor drop below the 100ms floor.
+    const [, delay] = setIntervalSpy.mock.calls[0]!;
+    expect(Number.isFinite(delay)).toBe(true);
+    expect(delay).toBeGreaterThanOrEqual(100);
+  });
+});

package/src/hooks/use-live-time.ts

@@ -0,0 +1,27 @@
+"use client";
+
+import * as React from "react";
+
+/**
+ * Returns `Date.now()` and re-renders every `intervalMs` so derived
+ * values like "uptime" tick forward without polling upstream data.
+ */
+export function useLiveTime(intervalMs: number = 1000): number {
+  const [now, setNow] = React.useState<number>(() => Date.now());
+
+  React.useEffect(() => {
+    // Guard against NaN/negative: `setInterval(cb, NaN)` coerces to 0
+    // in browsers, which would spin a tight render loop.
+    const requested =
+      Number.isFinite(intervalMs) && intervalMs > 0 ? intervalMs : 1000;
+    const delay = Math.max(requested, 100);
+    const id = window.setInterval(() => {
+      setNow(Date.now());
+    }, delay);
+    return () => {
+      window.clearInterval(id);
+    };
+  }, [intervalMs]);
+
+  return now;
+}

package/src/hooks/use-realtime-session.ts

@@ -0,0 +1,319 @@
+import { createElement, useEffect, useMemo, useRef, useState } from "react";
+import type { SdkSessionEvent } from "./use-sdk-session";
+import {
+  bumpActiveSessionActivity,
+  registerActiveSession,
+  setActiveSessionAttention,
+  setActiveSessionConnection,
+  setActiveSessionError,
+  setActiveSessionRunning,
+  setForegroundActiveSession,
+  unregisterActiveSession,
+  updateActiveSessionMeta,
+  type ActiveSessionConnectionState,
+  type ActiveSessionTransportMode,
+  type RegisterActiveSessionOptions,
+} from "../stores/active-sessions-store";
+
+export interface RealtimeSessionOptions extends RegisterActiveSessionOptions {
+  connectUrl?: string | null;
+  enabled?: boolean;
+  foreground?: boolean;
+  keepRegistered?: boolean;
+  reconnect?: boolean;
+  reconnectIntervalMs?: number;
+  maxReconnectAttempts?: number;
+  transportMode?: ActiveSessionTransportMode;
+  onEvent?: (event: SdkSessionEvent) => void;
+  onOpen?: () => void;
+  onClose?: () => void;
+  onError?: (error: Error) => void;
+}
+
+export interface RealtimeSessionState {
+  connectionState: ActiveSessionConnectionState;
+  lastError: string | null;
+  reconnectAttempts: number;
+  isConnected: boolean;
+}
+
+export interface RealtimeSessionTarget extends RealtimeSessionOptions {
+  key?: string;
+}
+
+export interface RealtimeSessionRegistryProps {
+  sessions: RealtimeSessionTarget[];
+}
+
+function parseEvent(message: string): SdkSessionEvent | null {
+  try {
+    const parsed = JSON.parse(message) as SdkSessionEvent;
+    return typeof parsed?.type === "string" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function eventTimestamp(event: SdkSessionEvent): number | null {
+  const rootTimestamp = (event as { timestamp?: unknown }).timestamp;
+  if (typeof rootTimestamp === "number" && Number.isFinite(rootTimestamp)) {
+    return rootTimestamp;
+  }
+
+  const raw = event.data?.timestamp ?? event.data?.ts ?? event.data?.time ?? event.data?.eventAt;
+  if (typeof raw === "number" && Number.isFinite(raw)) return raw;
+  return null;
+}
+
+function resolveErrorMessage(event: SdkSessionEvent): string | null {
+  const message = event.data?.message;
+  return typeof message === "string" && message.length > 0 ? message : null;
+}
+
+function updateStoreFromEvent(sessionId: string, event: SdkSessionEvent): void {
+  const lastEventAt = eventTimestamp(event) ?? Date.now();
+  bumpActiveSessionActivity(sessionId, { lastEventAt });
+
+  if (event.type === "session.run.started") {
+    setActiveSessionRunning(sessionId, true, { lastEventAt });
+    return;
+  }
+
+  if (event.type === "session.run.completed" || event.type === "done" || event.type === "result") {
+    setActiveSessionRunning(sessionId, false, { lastEventAt });
+    return;
+  }
+
+  if (event.type === "session.attention") {
+    setActiveSessionAttention(sessionId, true, { lastEventAt });
+    return;
+  }
+
+  if (event.type === "error" || event.type === "session.run.failed") {
+    setActiveSessionError(sessionId, resolveErrorMessage(event) ?? "Session error");
+    return;
+  }
+}
+
+export function useRealtimeSession({
+  sessionId,
+  projectId = null,
+  projectLabel,
+  title,
+  href,
+  metadata,
+  connectUrl,
+  enabled = true,
+  foreground = true,
+  keepRegistered = true,
+  reconnect = true,
+  reconnectIntervalMs = 1500,
+  maxReconnectAttempts = Infinity,
+  transportMode = "websocket",
+  onEvent,
+  onOpen,
+  onClose,
+  onError,
+}: RealtimeSessionOptions): RealtimeSessionState {
+  const [connectionState, setConnectionState] = useState<ActiveSessionConnectionState>("disconnected");
+  const [lastError, setLastError] = useState<string | null>(null);
+  const [reconnectAttempts, setReconnectAttempts] = useState(0);
+  const socketRef = useRef<WebSocket | null>(null);
+  const timerRef = useRef<number | null>(null);
+  const reconnectAttemptsRef = useRef(0);
+  const shouldReconnectRef = useRef(true);
+
+  const registration = useMemo<RegisterActiveSessionOptions>(
+    () => ({
+      sessionId,
+      projectId,
+      projectLabel,
+      title,
+      href,
+      metadata,
+    }),
+    [href, metadata, projectId, projectLabel, sessionId, title],
+  );
+
+  useEffect(() => {
+    if (!sessionId || !keepRegistered) return undefined;
+    registerActiveSession(registration);
+    return () => {
+      unregisterActiveSession(sessionId);
+    };
+  }, [keepRegistered, registration, sessionId]);
+
+  useEffect(() => {
+    if (!sessionId || !keepRegistered) return;
+    updateActiveSessionMeta(sessionId, {
+      projectId,
+      projectLabel,
+      title,
+      href,
+      metadata,
+    });
+  }, [href, keepRegistered, metadata, projectId, projectLabel, sessionId, title]);
+
+  useEffect(() => {
+    if (!sessionId || !foreground) return undefined;
+    setForegroundActiveSession(sessionId);
+    return () => {
+      setForegroundActiveSession(null);
+    };
+  }, [foreground, sessionId]);
+
+  useEffect(() => {
+    if (!enabled || !sessionId || !connectUrl || typeof window === "undefined") {
+      setConnectionState("disconnected");
+      if (sessionId) {
+        setActiveSessionConnection(sessionId, {
+          connectionState: "disconnected",
+          reconnectState: "idle",
+          transportMode,
+        });
+      }
+      return undefined;
+    }
+
+    shouldReconnectRef.current = true;
+
+    const clearReconnectTimer = () => {
+      if (timerRef.current != null) {
+        window.clearTimeout(timerRef.current);
+        timerRef.current = null;
+      }
+    };
+
+    const connect = () => {
+      clearReconnectTimer();
+      setConnectionState(reconnectAttemptsRef.current > 0 ? "reconnecting" : "connecting");
+      setActiveSessionConnection(sessionId, {
+        connectionState: reconnectAttemptsRef.current > 0 ? "reconnecting" : "connecting",
+        reconnectState: reconnectAttemptsRef.current > 0 ? "reconnecting" : "idle",
+        transportMode,
+        lastError: null,
+      });
+
+      const socket = new window.WebSocket(connectUrl);
+      socketRef.current = socket;
+
+      socket.onopen = () => {
+        reconnectAttemptsRef.current = 0;
+        setReconnectAttempts(0);
+        setLastError(null);
+        setConnectionState("connected");
+        registerActiveSession(registration);
+        setActiveSessionConnection(sessionId, {
+          connectionState: "connected",
+          reconnectState: "idle",
+          transportMode,
+          lastError: null,
+          lastEventAt: Date.now(),
+        });
+        onOpen?.();
+      };
+
+      socket.onmessage = (message) => {
+        const event = parseEvent(message.data);
+        if (!event) return;
+        registerActiveSession(registration);
+        updateStoreFromEvent(sessionId, event);
+        onEvent?.(event);
+      };
+
+      socket.onerror = () => {
+        const nextError = "Realtime session connection error";
+        setLastError(nextError);
+        setConnectionState("error");
+        setActiveSessionConnection(sessionId, {
+          connectionState: "error",
+          reconnectState: reconnect ? "reconnecting" : "failed",
+          transportMode,
+          lastError: nextError,
+        });
+        onError?.(new Error(nextError));
+      };
+
+      socket.onclose = () => {
+        socketRef.current = null;
+        onClose?.();
+
+        if (!shouldReconnectRef.current || !reconnect) {
+          setConnectionState("disconnected");
+          setActiveSessionConnection(sessionId, {
+            connectionState: "disconnected",
+            reconnectState: "idle",
+            transportMode,
+          });
+          return;
+        }
+
+        reconnectAttemptsRef.current += 1;
+        setReconnectAttempts(reconnectAttemptsRef.current);
+
+        if (reconnectAttemptsRef.current > maxReconnectAttempts) {
+          setConnectionState("error");
+          setActiveSessionConnection(sessionId, {
+            connectionState: "error",
+            reconnectState: "failed",
+            transportMode,
+            lastError: "Unable to reconnect to realtime session",
+          });
+          return;
+        }
+
+        setConnectionState("reconnecting");
+        timerRef.current = window.setTimeout(connect, reconnectIntervalMs);
+      };
+    };
+
+    connect();
+
+    return () => {
+      shouldReconnectRef.current = false;
+      clearReconnectTimer();
+      const socket = socketRef.current;
+      socketRef.current = null;
+      if (socket && socket.readyState < WebSocket.CLOSING) {
+        socket.close();
+      }
+    };
+  }, [
+    connectUrl,
+    enabled,
+    maxReconnectAttempts,
+    onClose,
+    onError,
+    onEvent,
+    onOpen,
+    reconnect,
+    reconnectIntervalMs,
+    registration,
+    sessionId,
+    transportMode,
+  ]);
+
+  return {
+    connectionState,
+    lastError,
+    reconnectAttempts,
+    isConnected: connectionState === "connected",
+  };
+}
+
+function RealtimeSessionRegistryItem(props: RealtimeSessionTarget) {
+  useRealtimeSession({
+    ...props,
+    foreground: props.foreground ?? false,
+  });
+  return null;
+}
+
+export function RealtimeSessionRegistry({ sessions }: RealtimeSessionRegistryProps) {
+  return sessions.map((session) =>
+    createElement(RealtimeSessionRegistryItem, {
+      key: session.key ?? session.sessionId,
+      ...session,
+    }),
+  );
+}

package/src/hooks/use-run-collapse-state.ts

@@ -0,0 +1,25 @@
+import { useCallback, useState } from "react";
+import type { Run } from "../types/run";
+
+/**
+ * Manages per-run collapse state with auto-collapse after run completion.
+ *
+ * - Runs stay expanded by default
+ * - Collapse is manual only
+ */
+export function useRunCollapseState(runs: Run[]) {
+  const [collapsedMap, setCollapsedMap] = useState<Record<string, boolean>>({});
+
+  const isCollapsed = useCallback(
+    (runId: string): boolean => {
+      return collapsedMap[runId] ?? false;
+    },
+    [collapsedMap],
+  );
+
+  const toggleCollapse = useCallback((runId: string) => {
+    setCollapsedMap((prev) => ({ ...prev, [runId]: !prev[runId] }));
+  }, []);
+
+  return { isCollapsed, toggleCollapse };
+}