feat: Implement Optimistic UI with Rollback for Escrow State Transitions (#62)

[dahgold001]

Description

This PR implements the optimistic UI layer for Escrow State Transitions as detailed in #62.

The core objective is to introduce an optimistic update layer that reflects escrow state changes (Funded → InProgress → Released/Disputed) instantly in the UI and cleanly rolls back on transaction rejection or ledger failure.

Related Issue

Closes #62

Type of Change

• New feature (non-breaking change which adds functionality)

Changes Made

• Optimistic State Store: Created shared/optimistic/escrow-state.ts utilizing useSyncExternalStore for framework-agnostic, instant optimistic state management.
• Hook Abstraction: Added hooks/useOptimisticEscrow.ts to wrap useEscrowContract calls with applyOptimisticUpdate, confirmUpdate, and rollbackUpdate.
• UI Components:
  • Built EscrowStateBadge atom to visually represent statuses with pulsing animations for pending states and shake animations for rollbacks.
  • Built EscrowMilestoneTracker molecule to display a timeline of milestones and manage actions (Fund, Release, Dispute, Refund).
• Dashboard Integration: Added the new milestone tracker to pages/dashboard.tsx with a demo gig to test optimistic actions and simulated rollbacks.
• CI Enhancements: Added explicit actions/cache for npm dependencies in .github/workflows/ci.yml.
• Testing Infrastructure: Added robust test coverage for the store (escrow-state.test.ts) and hook (useOptimisticEscrow.test.ts).

Checklist

• My code follows the project's code style
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• My changes generate no new warnings or errors
• I have run npm run lint and fixed all issues
• I have run npm run typecheck with no errors
• I have run npm run build successfully
• I have tested my changes locally

[vercel]

@dahgold001 is attempting to deploy a commit to the Meshack Yaro's projects Team on Vercel.

A member of the Team first needs to authorize it.

[meshackyaro]

Really solid piece of work. Using useSyncExternalStore for the optimistic layer is the right call — it keeps the store framework-agnostic and avoids the read tearing you'd risk with a context-based approach when multiple components watch escrow state mid-transition. The hook abstraction around applyOptimisticUpdate/confirmUpdate/rollbackUpdate is clean and makes the optimistic/pessimistic boundary explicit rather than smeared across call sites.

The UI touches are thoughtful too — pulsing states for pending and a shake on rollback give users real feedback about what's happening to their transaction, which matters a lot for something as high-stakes as escrow. Good instinct building the milestone tracker as a proper component with the full action surface (Fund/Release/Dispute/Refund) rather than bolting actions onto existing UI.

Appreciate the test coverage on both the store and the hook — that's exactly where optimistic-update bugs like to hide. Nice work all around.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
trustflow-frontend	Ready	Preview	Aug 27, 2026 3:20pm