> ## Documentation Index
> Fetch the complete documentation index at: https://ouroborai.xyz/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Web Components & Hooks

> UI component tree and custom hooks reference

The ouroborai web terminal is a Next.js 15 app with a chat-based terminal
interface. Components live in `apps/web/src/app/app/components/` and hooks
in `apps/web/src/app/app/hooks/`.

## Component Architecture

```
AppLayout
  |-- Header
  |-- LeftSidebar
  |     |-- SessionTabs
  |     |-- ActivityPanel
  |     |-- AutomationsPanel
  |-- ChatPanel (center)
  |-- RightSidebar
        |-- WalletPanel
        |-- PositionsPanel
        |-- MarketPanel
        |-- NftsPanel
        |-- PredictionsPanel
        |-- StakingPanel
        |-- LaunchpadPanel
```

## Layout Components

| Component            | File                      | Description                             |
| -------------------- | ------------------------- | --------------------------------------- |
| `LeftSidebar`        | `left-sidebar.tsx`        | Session management and activity feed    |
| `RightSidebar`       | `right-sidebar.tsx`       | Wallet, positions, and market data      |
| `MobileNav`          | `mobile-nav.tsx`          | Responsive navigation for small screens |
| `CollapsibleSection` | `collapsible-section.tsx` | Expandable/collapsible container        |

## Core Components

| Component       | File                 | Description                                        |
| --------------- | -------------------- | -------------------------------------------------- |
| `ChatPanel`     | `chat-panel.tsx`     | Main chat interface with message history and input |
| `SessionTabs`   | `session-tabs.tsx`   | Tab manager for multiple conversation sessions     |
| `ActivityPanel` | `activity-panel.tsx` | Recent agent job feed with status indicators       |

## Sidebar Panels

| Component          | File                    | Description                           |
| ------------------ | ----------------------- | ------------------------------------- |
| `WalletPanel`      | `wallet-panel.tsx`      | ETH and ERC-20 token balances         |
| `PositionsPanel`   | `positions-panel.tsx`   | Aave V3 and GMX V2 position summaries |
| `MarketPanel`      | `market-panel.tsx`      | Token prices and trending pools       |
| `NftsPanel`        | `nfts-panel.tsx`        | NFT gallery for connected wallet      |
| `PredictionsPanel` | `predictions-panel.tsx` | Polymarket prediction markets         |
| `StakingPanel`     | `staking-panel.tsx`     | Staking positions overview            |
| `LaunchpadPanel`   | `launchpad-panel.tsx`   | Token launch tracking                 |
| `AutomationsPanel` | `automations-panel.tsx` | Scheduled automation management       |
| `SwapPanel`        | `swap-panel.tsx`        | Quick swap interface                  |

## Modal Components

| Component           | File                      | Description                 |
| ------------------- | ------------------------- | --------------------------- |
| `SendModal`         | `send-modal.tsx`          | Token transfer dialog       |
| `DepositModal`      | `deposit-modal.tsx`       | Deposit flow dialog         |
| `BridgeModal`       | `bridge-modal.tsx`        | Cross-chain bridge dialog   |
| `CreateTokenModal`  | `create-token-modal.tsx`  | Token launch wizard         |
| `NftDetailModal`    | `nft-detail-modal.tsx`    | NFT detail view             |
| `NftTransferModal`  | `nft-transfer-modal.tsx`  | NFT transfer dialog         |
| `WrongNetworkModal` | `wrong-network-modal.tsx` | Chain switching prompt      |
| `FeatureInfoModal`  | `feature-info-modal.tsx`  | Feature description overlay |

***

## Custom Hooks

### useChat

**File**: `hooks/use-chat.ts`

Manages the chat interface state including message history, job polling, and
thread persistence via `sessionStorage`.

```typescript theme={"theme":{"light":"dracula","dark":"dracula"}}
function useChat(apiKey: string | null): {
  messages: Message[];
  isLoading: boolean;
  sendMessage: (content: string) => Promise<void>;
  clearMessages: () => void;
  sessionId: string;
}
```

| Return Value    | Type                                 | Description                         |
| --------------- | ------------------------------------ | ----------------------------------- |
| `messages`      | `Message[]`                          | Chat message history (user + agent) |
| `isLoading`     | `boolean`                            | Whether a job is pending or running |
| `sendMessage`   | `(content: string) => Promise<void>` | Submit a prompt to the agent        |
| `clearMessages` | `() => void`                         | Clear message history               |
| `sessionId`     | `string`                             | Current session identifier          |

The hook polls `/agent/job/:id` every 2 seconds while a job is running.
Thread IDs are persisted to `sessionStorage` under `thread:{sessionId}` for
cross-refresh recovery.

### useWalletBalances

**File**: `hooks/use-wallet-balances.ts`

Fetches ERC-20 token balances for the connected wallet using wagmi's
`useReadContracts`.

```typescript theme={"theme":{"light":"dracula","dark":"dracula"}}
function useWalletBalances(): {
  balances: TokenBalance[];
  isLoading: boolean;
  refetch: () => void;
}
```

| Return Value | Type             | Description                                    |
| ------------ | ---------------- | ---------------------------------------------- |
| `balances`   | `TokenBalance[]` | Array of token balances with formatted amounts |
| `isLoading`  | `boolean`        | Loading state                                  |
| `refetch`    | `() => void`     | Manually trigger a refresh                     |

Each `TokenBalance` includes: `symbol`, `address`, `balance` (bigint),
`decimals`, and `formatted` (human-readable string).

### useTokenPrices

**File**: `hooks/use-token-prices.ts`

Fetches current token prices from the `/market/prices` API endpoint.

```typescript theme={"theme":{"light":"dracula","dark":"dracula"}}
function useTokenPrices(apiKey: string | null): {
  prices: Record<string, { price: number; change24h: number }>;
  isLoading: boolean;
}
```

### useActivity

**File**: `hooks/use-activity.ts`

Fetches recent agent jobs from `/portfolio/jobs` and transforms them into
activity feed items.

```typescript theme={"theme":{"light":"dracula","dark":"dracula"}}
function useActivity(apiKey: string | null): {
  activities: Activity[];
  isLoading: boolean;
  refetch: () => void;
}
```

Each `Activity` includes: `id`, `type` (inferred from tool calls), `description`,
`status`, `timestamp`, and optional `toolCalls`.

### usePositions

**File**: `hooks/use-positions.ts`

Fetches aggregated DeFi positions from `/portfolio/positions`.

```typescript theme={"theme":{"light":"dracula","dark":"dracula"}}
function usePositions(apiKey: string | null): {
  positions: PositionsData | null;
  isLoading: boolean;
  refetch: () => void;
}
```

`PositionsData` contains `aave` (Aave V3 account data with health factor,
collateral, and debt) and `gmx` (array of perpetual positions with PnL
and liquidation prices).

### useMarketData

**File**: `hooks/use-market-data.ts`

Fetches trending pools from `/market/trending`.

```typescript theme={"theme":{"light":"dracula","dark":"dracula"}}
function useMarketData(apiKey: string | null): {
  trending: TrendingPool[];
  isLoading: boolean;
}
```

### useNfts

**File**: `hooks/use-nfts.ts`

Fetches NFTs for the connected wallet from `/nfts/:address`.

```typescript theme={"theme":{"light":"dracula","dark":"dracula"}}
function useNfts(address: string | undefined, apiKey: string | null): {
  nfts: NftItem[];
  isLoading: boolean;
  refetch: () => void;
}
```

### useAutomations

**File**: `hooks/use-automations.ts`

Manages automation CRUD operations against `/automations`.

```typescript theme={"theme":{"light":"dracula","dark":"dracula"}}
function useAutomations(
  walletAddress: string | undefined,
  apiKey: string | null
): {
  automations: Automation[];
  isLoading: boolean;
  create: (params: CreateAutomationParams) => Promise<void>;
  updateStatus: (id: string, status: string) => Promise<void>;
  remove: (id: string) => Promise<void>;
  refetch: () => void;
}
```

***

## Styling

The web terminal uses a vibrant dark theme with Arbitrum brand colors:

| Token        | Value         | Usage                       |
| ------------ | ------------- | --------------------------- |
| Primary      | `#12AAFF`     | Interactive elements, links |
| Light accent | `#00D4FF`     | Hover states, highlights    |
| Dark accent  | `#0088CC`     | Borders, secondary elements |
| Background   | Dark gradient | Page background             |