feat(escrow): implement realtime escrow updates

[mijinummi]

Summary

Adds real-time WebSocket support to the escrow detail page, enabling live updates for escrow status changes, funding events, condition fulfillments, dispute activity, and timeline updates without requiring a manual page refresh.

Changes

WebSocket Integration

• Integrated the existing WebSocket client into the escrow detail experience

• Automatically joins the escrow:{id} room when an escrow page is opened

• Automatically leaves the room when navigating away from the page

• Subscribed to escrow lifecycle events including:

  • escrow:status_changed
  • escrow:funded
  • escrow:completed
  • escrow:condition_fulfilled
  • escrow:dispute_filed
  • escrow:dispute_resolved

React Query Cache Updates

• Added optimistic cache updates for incoming escrow events
• Updated escrow status, funding state, conditions, disputes, and timeline entries in real time
• Triggered background refetches after updates to ensure consistency with server state

User Notifications

• Added lightweight toast notifications for live escrow activity

• Examples:

  • "Status changed to Active"
  • "Escrow funded"
  • "Condition fulfilled"
  • "Dispute filed"
  • "Dispute resolved"

Live Timeline Updates

• Added support for appending new timeline events as WebSocket messages arrive
• Timeline now reflects escrow activity immediately without page refresh

Conditions Synchronization

• Updated condition fulfillment and confirmation states in real time
• Condition status changes are reflected instantly in the conditions section

Dispute Synchronization

• Added live updates for dispute creation and resolution events
• Dispute section now stays synchronized across participants viewing the escrow

Connection Status Indicator

• Added a visual "Live" indicator when the WebSocket connection is active
• Displays reconnecting/disconnected state when the real-time connection is unavailable

Fallback Behavior

• Added periodic React Query refetching when the WebSocket connection is disconnected
• Ensures escrow data remains current even during temporary connectivity issues

Testing

• Added coverage for room subscription lifecycle (join/leave)
• Added event handling and cache update tests
• Added timeline, condition, and dispute update tests
• Added disconnected-state fallback polling tests

Acceptance Criteria

• Join escrow:{id} room on page load
• Leave room when navigating away
• Listen for escrow lifecycle WebSocket events
• Update React Query cache optimistically
• Show toast notifications for live updates
• Refetch escrow data for consistency
• Update timeline in real time
• Update conditions without refresh
• Update disputes without refresh
• Display live connection indicator
• Fall back to periodic refetch when disconnected

Notes

This implementation keeps all escrow participants synchronized in near real time, improving visibility into escrow state changes while maintaining data consistency through React Query cache invalidation and fallback polling.

Closes #263

[drips-wave]

@mijinummi Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits