# Timeline UI Component

> **Module:** Eventing / Timeline
> **Status:** Implemented
> **Last Updated:** 2026-01-07

## Overview

The Timeline UI provides a visual representation of HLC-ordered events across StellaOps services. It enables operators to trace the causal flow of operations, identify bottlenecks, and investigate specific events with full evidence links.

## Features

### Causal Lanes Visualization

Events are displayed in swimlanes organized by service:

```
┌─────────────────────────────────────────────────────────────────────┐
│  HLC Timeline Axis                                                   │
│  |-------|-------|-------|-------|-------|-------|-------|-------> │
├─────────────────────────────────────────────────────────────────────┤
│ Scheduler  [E]─────────[X]───────────────[C]                        │
├─────────────────────────────────────────────────────────────────────┤
│ AirGap            [I]──────────[M]                                  │
├─────────────────────────────────────────────────────────────────────┤
│ Attestor                              [A]──────────[V]              │
├─────────────────────────────────────────────────────────────────────┤
│ Policy                                       [G]                    │
└─────────────────────────────────────────────────────────────────────┘
```

Legend:
- **[E]** Enqueue - Job queued for processing
- **[X]** Execute - Job execution started
- **[C]** Complete - Job completed
- **[I]** Import - Data imported (e.g., SBOM, advisory)
- **[M]** Merge - Data merged
- **[A]** Attest - Attestation created
- **[V]** Verify - Attestation verified
- **[G]** Gate - Policy gate evaluated

### Critical Path Analysis

The critical path view shows the longest sequence of dependent operations:

- Color-coded by severity (green/yellow/red)
- Bottleneck stage highlighted
- Percentage of total duration shown
- Clickable stages for drill-down

### Event Detail Panel

Selected events display:
- Event ID and metadata
- HLC timestamp and wall-clock time
- Service and event kind
- JSON payload viewer
- Engine version information
- Evidence links (SBOM, VEX, Policy, Attestation)

### Filtering

Events can be filtered by:
- **Services**: Scheduler, AirGap, Attestor, Policy, Scanner, etc.
- **Event Kinds**: ENQUEUE, EXECUTE, COMPLETE, IMPORT, ATTEST, etc.
- **HLC Range**: From/To timestamps

Filter state is persisted in URL query parameters.

### Export

Timeline data can be exported as:
- **NDJSON**: Newline-delimited JSON (streaming-friendly)
- **JSON**: Standard JSON array
- **DSSE-signed**: Cryptographically signed bundles for auditing

## Usage

### Accessing the Timeline

Navigate to `/timeline/{correlationId}` where `correlationId` is the unique identifier for a scan, job, or workflow.

Example:
```
/timeline/scan-abc123-def456
```

### Keyboard Navigation

| Key | Action |
|-----|--------|
| Tab | Navigate between events |
| Enter/Space | Select focused event |
| Escape | Clear selection |
| Arrow keys | Scroll within panel |

### URL Parameters

| Parameter | Description | Example |
|-----------|-------------|---------|
| `services` | Comma-separated service filter | `?services=Scheduler,AirGap` |
| `kinds` | Comma-separated kind filter | `?kinds=EXECUTE,COMPLETE` |
| `fromHlc` | Start of HLC range | `?fromHlc=1704067200000:0:node1` |
| `toHlc` | End of HLC range | `?toHlc=1704153600000:0:node1` |

## Component Architecture

```
timeline/
├── components/
│   ├── causal-lanes/          # Swimlane visualization
│   ├── critical-path/         # Bottleneck bar chart
│   ├── event-detail-panel/    # Selected event details
│   ├── evidence-links/        # Links to SBOM/VEX/Policy
│   ├── export-button/         # Export dropdown
│   └── timeline-filter/       # Service/kind filters
├── models/
│   └── timeline.models.ts     # TypeScript interfaces
├── pages/
│   └── timeline-page/         # Main page component
├── services/
│   └── timeline.service.ts    # API client
└── timeline.routes.ts         # Lazy-loaded routes
```

## API Integration

The Timeline UI integrates with the Timeline API:

| Endpoint | Description |
|----------|-------------|
| `GET /api/v1/timeline/{correlationId}` | Fetch events |
| `GET /api/v1/timeline/{correlationId}/critical-path` | Fetch critical path |
| `POST /api/v1/timeline/{correlationId}/export` | Initiate export |
| `GET /api/v1/timeline/export/{exportId}` | Check export status |
| `GET /api/v1/timeline/export/{exportId}/download` | Download bundle |

## Accessibility

The Timeline UI follows WCAG 2.1 AA guidelines:

- **Keyboard Navigation**: All interactive elements are focusable
- **Screen Readers**: ARIA labels on all regions and controls
- **Color Contrast**: 4.5:1 minimum contrast ratio
- **Focus Indicators**: Visible focus rings on all controls
- **Motion**: Respects `prefers-reduced-motion`

## Performance

- **Virtual Scrolling**: Handles 10K+ events efficiently
- **Lazy Loading**: Events loaded on-demand as user scrolls
- **Caching**: Recent queries cached to reduce API calls
- **Debouncing**: Filter changes debounced to avoid excessive requests

## Screenshots

### Timeline View
![Timeline View](./assets/timeline-view.png)

### Critical Path Analysis
![Critical Path](./assets/critical-path.png)

### Event Detail Panel
![Event Details](./assets/event-details.png)

## Related Documentation

- [Timeline API Reference](../../api/timeline-api.md)
- [HLC Clock Specification](../hlc/architecture.md)
- [Eventing SDK](../eventing/architecture.md)
- [Evidence Model](../../schemas/evidence.md)