# evelyn-perps-overview Specification

## Purpose

Let the owner inspect Evelyn perpetual positions grouped by wallet and venue in Mission Control, with stable row identities across service snapshot updates.

## Requirements

### Requirement: Perps overview displays a collapsible position hierarchy
The Perps tab SHALL display a tree table with columns `Position`, `Direction`, and `Position size, USD`. The hierarchy SHALL be wallet → venue → position, expanded by default, with collapsible wallet and venue groups. Wallet and venue rows SHALL leave direction and size empty.

#### Scenario: Open either environment's Perps tab
- **WHEN** the owner opens Perps in Production or Test
- **THEN** the three named columns and the fully expanded hierarchy are visible
- **AND** direction and size appear only on position rows

#### Scenario: Collapse and expand groups
- **WHEN** the owner collapses and then expands a wallet or venue
- **THEN** its descendants are hidden and then shown again

### Requirement: Asynchronous polling follows window visibility
EMC SHALL request the current Perps snapshot from each environment's own service immediately on opening and every three seconds while visible, without blocking the UI thread. UI updates SHALL occur only on the JavaFX thread. Hiding the window SHALL stop polling; reopening SHALL create only one active polling loop and ignore results belonging to an earlier window session. Poll failures SHALL preserve the current view and allow subsequent attempts.

#### Scenario: Read takes time or fails
- **WHEN** a snapshot read is delayed or fails
- **THEN** the UI remains responsive and the existing view is retained
- **AND** later polling remains possible without overlapping scheduled reads

#### Scenario: Hide and reopen
- **WHEN** the owner hides and reopens EMC repeatedly
- **THEN** each visible session has only one polling loop and obsolete results cannot update its views

#### Scenario: Environment data stays separate
- **WHEN** TEST and PROD return different snapshots
- **THEN** each tab displays only its own service's data
- **AND** a failure reading one service does not prevent attempting the other service

### Requirement: Polling preserves Perps view state
The Perps table SHALL retain matching wallet, venue and position identities across snapshots. Repeated unchanged snapshots SHALL leave existing rows, expansion, selection and formatting untouched without flicker. New groups SHALL be expanded by default, and future added or removed positions SHALL be reconciled by identity without resetting retained groups.

#### Scenario: Poll unchanged positions
- **WHEN** a user collapses a group or selects a position and repeated snapshots are unchanged
- **THEN** the same rows remain, with the same expansion and selection and no rebuild or refresh

### Requirement: Jupiter positions communicate direction and USD size
Position rows SHALL show Long or Short and USD sizes with grouping separators and two decimal places. Long rows SHALL have faint green backgrounds and Short rows faint red backgrounds; wallet and venue rows SHALL have no direction-based color. Existing columns and hierarchy SHALL be preserved.

#### Scenario: Inspect real positions
- **WHEN** real Jupiter positions are displayed
- **THEN** direction appears as readable text and background color, with formatted USD size

### Requirement: EMC presents service data without sample notices
EMC SHALL obtain positions only from its environment's in-memory service snapshot and SHALL contain no sample positions, sample notices, illustrative-Phoenix notices, or Refresh button. EMC SHALL own UI components, colors and formatting; integration reads SHALL belong to the service.

#### Scenario: Snapshot changes
- **WHEN** positions are added or removed after refresh
- **THEN** EMC reconciles rows by identity while preserving retained selections and expansion state
- **AND** no sample labels or Phoenix examples appear