100: Add Perps collateral, leverage, value, uPnL and gross-exposure totals in EMC

openspec/specs/evelyn-perps-overview/spec.md

@@ -7,16 +7,15 @@ Let the owner inspect Evelyn perpetual positions grouped by wallet and venue in
 ## 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.
+The Perps tab SHALL display Position, Direction, Margin, Collateral, Leverage, Exposure, Value and uPnL in that order beneath the visible Perpetual Contracts root. Isolated hierarchy SHALL be wallet → venue → position; each Phoenix Cross account SHALL add a Cross group above its positions. Groups SHALL show applicable totals, leave direction/aggregate ratios blank, and be expanded by default.
 
 #### 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
+- **THEN** all eight columns, root totals and the account-aware hierarchy are visible
 
 #### 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
+- **WHEN** the owner collapses and expands a wallet, venue or Cross account
+- **THEN** descendants hide and return without changing totals
 
 ### 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.
@@ -43,11 +42,15 @@ The Perps table SHALL retain matching wallet, venue and position identities acro
 - **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.
+Positions SHALL show readable Long/Short direction and Isolated/Cross margin text. USD amounts SHALL use grouping and two decimals; leverage SHALL use a multiplication sign. Signed uPnL SHALL be green for positive, red for negative and neutral for rounded zero without negative zero. Existing faint direction backgrounds SHALL remain; groups SHALL have distinct weight and no direction color. Numeric columns SHALL be right-aligned with useful widths and tooltips.
+
+#### Scenario: Small or unavailable PnL
+- **WHEN** PnL rounds to zero or is unavailable
+- **THEN** zero has no negative sign/color and unavailable values show an em dash with an explanation
 
 #### Scenario: Inspect real positions
 - **WHEN** real Jupiter positions are displayed
-- **THEN** direction appears as readable text and background color, with formatted USD size
+- **THEN** direction appears as readable text and background color, with formatted gross USD exposure and applicable valuation metrics
 
 ### 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.
@@ -56,3 +59,33 @@ EMC SHALL obtain positions only from its environment's in-memory service snapsho
 - **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
+
+### Requirement: Definitions distinguish owned collateral and margin requirements
+Tooltips SHALL explain isolated collateral, exposure-based leverage, collateral-based ROI, estimated net Value and excluded slippage/swaps/rent. Cross position collateral SHALL be identified as initial margin required against shared collateral. Cross position Value SHALL be unavailable; unsupported Cross ROI/leverage SHALL be explained. Cross account leverage SHALL identify undiscounted equity before exit fees as its denominator.
+
+#### Scenario: Inspect a Cross position
+- **WHEN** the owner inspects a Cross row and its account group
+- **THEN** the position shows a USD margin requirement and the account shows shared capital once
+- **AND** no position-only metric is labeled account utilization
+
+### Requirement: Venue visibility follows available child rows
+EMC SHALL hide venue rows with neither positions nor Cross accounts and show them when children reappear. Funded empty Cross accounts SHALL keep their venue visible. Hidden venues SHALL remain in snapshots and totals, with read status available in wallet tooltips. Unknown scopes SHALL NOT become zero totals; failed reads SHALL preserve last-success totals. Wallet rows and the root SHALL remain visible.
+
+#### Scenario: Empty venue
+- **WHEN** Jupiter or Phoenix has no positions and no Cross accounts
+- **THEN** its heading is absent from that wallet's displayed children
+- **AND** a successful empty scope still contributes zero to totals
+
+#### Scenario: Funded Cross account without positions
+- **WHEN** Phoenix returns a Cross account with capital but no open positions
+- **THEN** Phoenix and its Cross account remain visible with that capital counted once
+
+#### Scenario: Positions disappear and return
+- **WHEN** a venue loses its last child and later returns a position
+- **THEN** its heading disappears and reappears with the correct child
+- **AND** unrelated retained rows keep their selection and expansion state
+
+#### Scenario: Hidden scope has not been read successfully
+- **WHEN** a childless venue has never been read successfully and its first read is pending or failed
+- **THEN** the heading is hidden and its read status is available on the wallet tooltip
+- **AND** required totals remain unavailable rather than reporting zero