105: EMC Perps: add instant text filter for positions and wallet groups

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

@@ -70,7 +70,7 @@ Tooltips SHALL explain isolated collateral, exposure-based leverage, collateral-
 - **AND** no position-only metric is labeled account utilization
 
 ### Requirement: Venue visibility follows available child rows
-EMC SHALL hide venue rows with neither positions, Cross accounts nor TWAP warnings and show them when children reappear. Funded empty Cross accounts and accounts with eligible TWAP warnings SHALL keep their venue visible. Unmatched isolated warnings SHALL remain on the venue with true subaccount identity, never on an invented Cross parent. 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.
+EMC SHALL hide venue rows with neither positions, Cross accounts nor TWAP warnings and show them when children reappear. Funded empty Cross accounts and accounts with eligible TWAP warnings SHALL keep their venue visible. Unmatched isolated warnings SHALL remain on the venue with true subaccount identity, never on an invented Cross parent. 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. Without a text filter, wallet rows and the root SHALL remain visible. With a text filter, only matching branches SHALL remain, with the root always retained as context.
 
 #### Scenario: Empty venue
 - **WHEN** Jupiter or Phoenix has no positions, Cross accounts or TWAP warnings
@@ -165,3 +165,51 @@ Available estimated Value SHALL show one `≈` before USD formatting with two de
 - **WHEN** Phoenix estimates contribute to a mixed portfolio
 - **THEN** available affected totals also explain Phoenix's estimated closing Value
 - **AND** a missing required contribution leaves the affected total `—` without `≈`
+
+### Requirement: Perps text filtering responds immediately
+Each environment's Perps tab SHALL provide a Filter text field and adjacent X clear button above the table. Every text change SHALL immediately apply case-insensitive literal substring matching only to Position and Risk text, including full wallet addresses, without Return, focus loss, polling or service calls. Empty text SHALL restore the normal overview.
+
+#### Scenario: Edit and clear
+- **WHEN** the owner types B, BT, BTC, changes it to btc, deletes text or pastes a query
+- **THEN** every edit immediately updates the results and BTC and btc give identical matches
+- **AND** X clears the field and immediately restores the normal overview
+
+#### Scenario: Search scope is limited to Position and Risk
+- **WHEN** a query occurs only in Direction, Margin, Collateral, Leverage, Exposure, Value, uPnL, TWAP or tooltip text
+- **THEN** that content does not produce a match
+- **WHEN** a query occurs in Position or Risk text, or the full wallet address behind a shortened Position label
+- **THEN** the corresponding row matches
+
+### Requirement: Text filtering preserves hierarchical context
+Matching positions SHALL retain their ancestors; matching groups SHALL include all descendants. Unrelated branches SHALL be hidden. The root SHALL always remain as context. Changing the query SHALL expand result ancestors so matches are readily visible.
+
+#### Scenario: Symbol and wallet matches
+- **WHEN** BTC matches positions only
+- **THEN** those positions and their ancestors remain, without unrelated positions
+- **WHEN** a substring matches a full wallet address, venue name or Cross group name
+- **THEN** its whole branch remains, including descendants with other symbols
+
+#### Scenario: No matches
+- **WHEN** no row matches the query
+- **THEN** only the contextual root remains
+
+### Requirement: Filtering preserves complete account context
+Filtering SHALL preserve original snapshot totals, risk summaries, TWAP warnings and freshness/retention qualifications. While text is nonempty, an explanation near the filter SHALL state that totals include hidden positions; the explanation SHALL disappear when cleared. Shared Cross capital SHALL never be apportioned to visible positions.
+
+#### Scenario: Partial portfolio shown
+- **WHEN** the filter hides some positions
+- **THEN** root and group values and summaries remain those of their complete scopes
+- **AND** the active-filter explanation remains visible
+
+### Requirement: Filter state survives observation updates
+Each Perps tab SHALL keep its own query through polling and read failures. Updates SHALL re-evaluate current rows. Unchanged observations SHALL retain visible row identities, selection and expansion. Clearing SHALL restore normal group expansion state from before filtering, with new groups expanded by default.
+
+#### Scenario: Updates and recovery
+- **WHEN** positions change or a read fails and recovers while filtering
+- **THEN** the query persists and matching additions/removals appear immediately on update
+- **AND** retained values keep their original freshness semantics
+
+#### Scenario: Independent views and restoration
+- **WHEN** one environment is filtered and groups in the normal overview were previously collapsed
+- **THEN** the other environment's filter is unaffected
+- **AND** clearing restores those collapsed groups