- Extract inline CSS from layout.html into static/hermes-trace.css
(-42%, dead selectors from legacy side-panel/three-pane/waterfall removed)
- Fix fragile query-string building in openTurn (URLSearchParams)
- Fix payload race: beforeSwap guard drops stale JSON payloads when
switching turns mid-flight
- Show Loading placeholder and surface HTMX failures instead of
failing silently
- Extract inline x-data into Alpine.data("turnDetail") component
- a11y: keyboard-operable rows (tabindex + Enter/Space), Esc closes
overlay, aria-label on close button, focusable token tooltip,
higher-contrast latency-medium
- Table consistency: LLM latency renders with 's' unit, truncated
cells get title attributes
- Show all turns in session view (drop default limit of 100) and
remove now-dead _order offset logic
- Add X-Content-Type-Options: nosniff header and data: favicon
- Sync docs (frontend.md, database.md, AGENTS.md) with the above
172 lines
7.1 KiB
Markdown
172 lines
7.1 KiB
Markdown
# hermes-trace Frontend
|
|
|
|
## Stack
|
|
|
|
- **HTMX 2.0.10** — server round-trips for turn detail loading, lazy JSON loading
|
|
- **Alpine.js 3.15.12** — client-side state management (overlay panel, JSON toggles, tooltips)
|
|
- **Jinja2** — server-side HTML rendering
|
|
- **CSS** — all styles in `static/hermes-trace.css` (linked from `layout.html`; no inline `<style>` block)
|
|
- **JS** — shared listeners/components in `static/hermes-trace.js` (Alpine component registration, HTMX event guards, copy/resize handlers)
|
|
|
|
## Session View (`/session/{id}`)
|
|
|
|
The session view uses a **flat table + right-side overlay panel** pattern (not a CSS grid).
|
|
|
|
| Component | Role |
|
|
|-----------|------|
|
|
| **Table** | Turn timeline: LLM calls + nested tool calls in a unified table |
|
|
| **Overlay panel** | Right-side fixed panel for turn detail, opened by clicking a row |
|
|
|
|
### Table Structure
|
|
|
|
Columns:
|
|
|
|
| Col | Content |
|
|
|-----|---------|
|
|
| **Start** | Timestamp (UTC+8) of LLM call |
|
|
| **Call** | Badge: LLM #N (numbered by `t._order`; newest turn = largest N, e.g. 3 turns → newest is #3) |
|
|
| **Input** | Truncated request preview (first 80 chars) |
|
|
| **Response** | Truncated response preview (first 80 chars) |
|
|
| **Latency** | Duration in seconds (LLM) or ms (tool), colour-coded |
|
|
| **Model** | Model name badge |
|
|
|
|
**Two row types:**
|
|
|
|
- **`tr-llmcall`** — LLM API call row. Clicking it loads turn detail into the overlay via HTMX: `htmx.ajax('GET', '/turn/{id}?order=N', {target:'#detail-body'})`.
|
|
- **`tr-toolcall`** — Tool call row, indented under its parent LLM call with a ↳ arrow. Clicking a tool call loads turn detail with `?focus_tc=N` to auto-scroll to that tool call in the detail panel.
|
|
|
|
Both row types are keyboard-accessible: `tabindex="0"` + Enter/Space handlers (query string built with `URLSearchParams`), with `:focus-visible` outlines.
|
|
|
|
### Detail Overlay Panel
|
|
|
|
```css
|
|
.detail-overlay {
|
|
position: fixed;
|
|
top: 0;
|
|
right: 0;
|
|
width: 50%;
|
|
height: 100vh;
|
|
background: var(--bg-card);
|
|
transform: translateX(100%);
|
|
transition: transform 0.25s ease;
|
|
z-index: 1000;
|
|
display: flex;
|
|
flex-direction: column;
|
|
box-shadow: -4px 0 16px rgba(0,0,0,0.35);
|
|
}
|
|
```
|
|
|
|
- Opens via Alpine `showDetail` state when a table row is clicked; Esc closes it (`@keydown.escape.window`)
|
|
- Has a resizable handle on the left edge (drag to resize, min 350px, max 92% width)
|
|
- Contains a header (title + close button) and the scrollable `#detail-body`
|
|
- Turn detail content is loaded into `#detail-body` via HTMX
|
|
|
|
### Loading & Error States
|
|
|
|
- `openTurn()` sets `#detail-body` to a `.detail-loading` "Loading…" placeholder before firing `htmx.ajax`.
|
|
- HTMX failures are caught by an `htmx:responseError` listener (`static/hermes-trace.js`) that renders an error fragment into `#detail-body` / `#json-request` / `#json-response`.
|
|
|
|
### Navigation Between Sessions
|
|
|
|
- Back button at top: `← Back to sessions` links back to `/`
|
|
- Summary line: total turns, total tool calls, avg latency, tokens/sec
|
|
|
|
## Turn Detail (`GET /turn/{id}`)
|
|
|
|
An HTMX fragment rendered inside the overlay panel. Two tabs:
|
|
|
|
### Preview Tab (default)
|
|
|
|
| Section | Content |
|
|
|---------|---------|
|
|
| **Metadata chips** | Latency, token usage (with hover breakdown tooltip), finish reason, turn type |
|
|
| **User Input** | `<pre>` block with copy button |
|
|
| **Response** | `<pre>` block with copy button |
|
|
| **Reasoning** (if present) | `<pre>` block with token count badge |
|
|
| **Tool calls** | Each tool: Arguments + Result, each with JSON pretty/raw toggle and copy button |
|
|
|
|
### JSON Tab
|
|
|
|
Lazy-loaded via HTMX when tab is clicked:
|
|
|
|
- **Full Request** — `<textarea readonly>` for crash-safe rendering of one server-formatted, valid JSON representation
|
|
- **Full Response** — same pattern
|
|
- Both sections loaded via `htmx.ajax('GET', '/turn/{id}/payload?type=request|response', ...)`
|
|
|
|
## JSON Display
|
|
|
|
### Large JSON Safety
|
|
|
|
- **Full Request/Response**: Use `<textarea readonly>` not `<pre>`
|
|
- Browser virtualizes textarea rendering — only visible lines are laid out
|
|
- Formatted view: `white-space: pre; overflow: auto` (horizontal scroll)
|
|
|
|
### Full Payload JSON
|
|
|
|
For large payloads (Full Request/Response), the server formats the JSON once without expanding escaped `\\n` sequences. The response contains one copy only:
|
|
|
|
```html
|
|
<div class="td-payload">
|
|
<textarea readonly class="td-textarea"
|
|
style="white-space:pre;overflow:auto;">{{ formatted_json }}</textarea>
|
|
</div>
|
|
```
|
|
|
|
Small tool-call JSON (Arguments/Result) retains its client-side pretty/raw toggle because those payloads are typically only a few KB.
|
|
|
|
### Lazy Loading
|
|
|
|
Full Request/Response are lazy-loaded only when the JSON tab is first activated:
|
|
|
|
1. Clicking the JSON tab calls the Alpine `loadJson()` method on the `turnDetail` component — it runs once per fragment, guarded by a `jsonLoaded` flag.
|
|
2. `loadJson()` fires two `htmx.ajax` GETs to `/turn/{id}/payload?type=request|response`, swapped into `#json-request` / `#json-response` (which show a `.json-empty` "Loading..." placeholder until then).
|
|
3. An `htmx:beforeSwap` race guard (`static/hermes-trace.js`) discards a payload response whose turn id (parsed from `/turn/{id}/payload` in `requestConfig.path`) doesn't match the current fragment's `data-turn-id` — prevents stale JSON when the user switches turns mid-flight.
|
|
4. Network failures surface via the `htmx:responseError` handler, which renders an error div into the target.
|
|
|
|
## Token Usage Tooltip
|
|
|
|
Langfuse-inspired breakdown on hover or keyboard focus (the chip has `tabindex="0"` with `@focus`/`@blur` handlers):
|
|
|
|
**Pill:** `1,618 prompt → 31 completion` (the Σ total is a separate chip)
|
|
|
|
**Hover tooltip:**
|
|
```
|
|
Usage breakdown
|
|
━━━━━━━━━━━━━━━━━━━━━━━
|
|
Input usage 193,362
|
|
cache_read_input_tokens 191,744
|
|
input 1,618
|
|
|
|
Output usage 31
|
|
output 31
|
|
|
|
Total usage 193,393
|
|
```
|
|
|
|
## Metadata Pills
|
|
|
|
Detail pane top bar uses pill-shaped badges:
|
|
|
|
```
|
|
[Latency 5.4s] [Tokens 1,618 prompt → 31 completion] [Σ 193,393] [Finish tool_calls] [Type main]
|
|
```
|
|
|
|
- `Latency`: Duration in seconds or milliseconds
|
|
- `Tokens`: prompt → completion counts; hover or focus for breakdown
|
|
- `Σ`: Total tokens (separate chip, shown when present)
|
|
- `Finish`: stop / tool_calls / length / error (color-coded)
|
|
- `Type`: main / background_review / subagent
|
|
|
|
## Alpine Patterns
|
|
|
|
| Pattern | Usage |
|
|
|---------|-------|
|
|
| `x-data` | Inline component state (showDetail, selectedTurn, raw, showTokens) |
|
|
| `Alpine.data("turnDetail")` | Turn detail fragment state (tab, jsonLoaded, focusTc) — registered in `static/hermes-trace.js` via `alpine:init`; root div carries `data-turn-id` |
|
|
| `x-show` | Conditional visibility (toggle sections, overlay) |
|
|
| `$nextTick` | Wait for DOM before dispatching HTMX requests |
|
|
| `x-cloak` | Prevent flash of unstyled content |
|
|
| `@click` | Event handlers for row selection, tab switching |
|
|
| `@keydown` | Keyboard support: Enter/Space on rows opens a turn, Esc closes the overlay |
|
|
| `@focus` / `@blur` | Token tooltip for keyboard users (chip has `tabindex="0"`) |
|
|
| `:class` | Dynamic CSS classes for selected/highlight states |
|