com_r35157_nenjim-hubd-impl_ref/openspec/changes/archive/2026-10-19-95-display-perps-sample-positions/design.md

Design

Context

See proposal.md for motivation. EMC currently constructs matching placeholder tabs under Production and Test in EvelynMissionControlImpl. JavaFX and its shared runtime are already available.

Goals / Non-Goals

Goals: Isolate the prototype's construction and sample data inside the EMC implementation package; keep the existing environment tab colors.

Non-Goals: Public position APIs, domain/service models, runtime changes, refresh scheduling, or configuration.

Decisions

• Add a package-private Perps tab builder instead of growing the chart-oriented main implementation or introducing service abstractions. Each environment gets a fresh tree, so collapsing one view does not affect the other.
• Use JavaFX's native tree table and an invisible expanded root. A private display record holds a label, optional direction, and optional USD size using the existing ΩAmountΩ ValueTag (BigDecimal). This is a monetary amount expressed in USD by the display contract, not a USDC token amount or Jupiter-specific raw integer. No Detag configuration changes are needed.
• Format the numeric size as US currency in the display layer, align it right, and leave group values blank. Disable column sorting to preserve the sample grouping and position order.
• Apply faint background colors through the row factory and reset the style when a virtualized row becomes empty or represents a group. Keep native selection styling and readable text by setting the control's inner background colors rather than overriding selected-row backgrounds.
• Put a wrapping sample-data notice above the table, including the illustrative status of Phoenix. Use a growing layout so the table follows the available window size.

Risks / Trade-offs

• [Reused rows could retain a position color after collapse or scrolling] → Clear inline styling for groups and empty rows and check it in UI validation.
• [Samples could be mistaken for real positions in Production] → Show the explicit sample notice in both environments.
• [No graphical display may be available in the execution environment] → Attempt isolated UI verification without starting the operational Hub; record any remaining visual checks honestly.