docs/FRONTEND_GUIDE.md

# Frontend Guide

## File and runtime

The entire Futures dashboard UI is packaged in:

```text
hermes_overlay/tools/templates/hermes_futures_desk_luxury.html
```

The router reads this file at request time from its installed `tools/templates` directory and serves it at `/futures`. Do not add a second frontend server, bundler process, or port.

## Design system

The UI uses an Obsidian & Gold workstation theme with a light-theme option. Operational values use readable sans-serif/monospace styling. Decorative serif/italic styling is limited to headings and visual accents.

Responsive modes cover desktop, tablet, and mobile. `prefers-reduced-motion` is respected.

## Main UI regions

- fixed/collapsible navigation and local market lists;
- command deck with symbol, risk, **Optional AI context** switch, Analyze, and Paper Execute controls;
- selected-market header and chart;
- market diagnostics and field provenance;
- decision, score, risk approval, and execution mode;
- trade-plan geometry and execution checklist;
- signal reasons and components;
- Paper account and positions;
- datasource health and technical diagnostics;
- Telegram operational status;
- local activity/history and export actions.

## API usage

The helper uses:

```javascript
fetch(url, {
  credentials: 'same-origin',
  cache: 'no-store'
})
```

Primary calls:

```text
GET  /api/futures/status
GET  /api/futures/symbols
GET  /api/futures/positions
GET  /api/futures/market
GET  /api/futures/trade-plan
GET  /api/futures/signals
GET  /api/futures/advisory
GET  /api/futures/activity
POST /api/futures/analyze
POST /api/futures/paper/execute
GET  /api/telegram/status
```

The V6 page router also lazy-loads dedicated read routes for trade plan, signals, optional AI context (advisory), and server activity. These requests are authenticated, use `cache: 'no-store'`, and never fabricate fallback trading values when a route is empty or unavailable. The trade-plan page renders an **authority contrast** panel (emerald deterministic lane vs violet advisory lane) when data is present.

CSRF bootstrap uses `GET /api/futures/csrf-token` before POST mutations.

## Refresh behavior

Default intervals:

- clock and age labels: 1 second;
- status and positions: 5 seconds while auto-refresh is enabled and page is visible;
- market data: 15 seconds;
- Telegram status: 60 seconds.

When the page becomes visible again, status and market data refresh if automatic refresh is enabled.

## Chart behavior

Supported intervals:

```text
1m 5m 15m 1h
```

Supported candle limits:

```text
60 120 240
```

Modes:

- Candles;
- Line;
- optional volume bars.

The chart is an inline SVG and uses only `candles` returned by the market endpoint. Crosshair, OHLCV legend, tooltip, current-price reference, price labels, visible high/low, range position, and last-candle age are derived from the returned series.

No visual interpolation or fallback is permitted to create production candles.

## Display-only diagnostics

The UI calculates visible trend, average candle range, relative last-candle volume, realized variation, last-candle direction, and range position from the real returned candles. These values are explicitly informational and must never change:

```text
LONG / SHORT / NO_TRADE
risk approval
noTradeGuard
Entry / SL / TP
leverage
quantity
execution eligibility
```

## Local browser state

The UI stores only convenience preferences/history in `localStorage`.

Known keys:

```text
hermes_watchlist
hermes_recent_markets
hermes_auto_refresh
hermes_compact
hermes_motion
hermes_glow
hermes_ui_scale
hermes_sidebar_collapsed
```

Watchlist, recent markets, local analysis history, and workspace activity use Hermes-prefixed local keys defined in the template. They are not synchronized to the server and are not trusted for execution.

## Keyboard shortcuts

| Key | Action |
|---|---|
| `/` | Focus and select symbol search. |
| `A` | Run analysis when not already analyzing. |
| `R` | Manual refresh. |
| `D` | Toggle display density. |
| `T` | Toggle theme. |
| `?` | Open shortcut help. |
| `Escape` | Close overlays/help. |

There is deliberately no keyboard shortcut for Paper Execute.

## Analysis state rendering

Use the server result to set one of:

```text
NOT_ANALYZED
ANALYZING
LONG
SHORT
NO_TRADE
ANALYSIS_FAILED
STALE
API_UNAVAILABLE
```

Important rules:

- initial state is “Waiting for analysis,” not `NO_TRADE`;
- HTTP/network failure is `ANALYSIS_FAILED` or `API_UNAVAILABLE`;
- score is “Unavailable” when components do not exist, not numeric zero;
- expiry is prominent only for a valid directional plan;
- rejected/incomplete analysis is not presented as executable;
- changing symbol or risk invalidates the current browser plan;
- server state remains authoritative.

## Execute availability

The button is disabled unless the latest browser plan mirrors all required server fields. The UI displays a concrete disabled reason such as:

```text
Run analysis first
No directional plan
Risk approval failed
noTradeGuard active
Market-only symbol
Plan expired
Symbol changed
Risk profile changed
Plan already executed
Required Futures fields unavailable
```

These checks improve UX but do not replace backend revalidation.

## Adding a UI feature safely

1. Reuse existing API fields or add an additive backend field.
2. Render missing values as `Unavailable`, never zero or fabricated content.
3. Keep browser calculations labeled display-only.
4. Do not add another Execute path or shortcut.
5. Invalidate plan display when relevant controls change.
6. Keep DOM IDs unique and update static ID checks.
7. Preserve responsive and reduced-motion behavior.
8. Do not display raw provider errors or secrets.
9. Verify Console and Network in an authenticated deployed session.