robust async state machine for the swap interface (loading/empty/error/success)

[mikewheeleer]

Summary

The swap interface conflates loading, empty, error, and success, so users sometimes see a blank screen or an error behind data. Model the fetch as an explicit state machine with mutually-exclusive states and a retry.

Why this matters

Ambiguous async states are a top source of confusing UIs and bugs. An explicit machine makes every state intentional and testable.

Requirements

• Model the swap interface fetch as loading | empty | error | success, mutually exclusive by construction.
• Render the correct UI for each, with a retry affordance on error.
• Transitions are deterministic; no state can render behind another.
• Announce state changes to assistive tech.

Technical guidance

• Represent state as one discriminated union, not separate booleans.
• Reset to loading on an explicit refetch.

Edge cases — each must have a test

• loading -> shows loader only
• empty result -> empty state only
• error -> error + retry only
• success -> content only
• retry -> returns to loading then resolves

Acceptance criteria

• All requirements and every edge case above implemented and covered by tests
• New unit and integration tests; existing tests still pass and no regressions
• Structured, typed errors (no leaked internals; stable codes)
• npm run lint, npm test, and npm run build all pass locally
• Code follows the repo's existing conventions; no duplication or dead code
• Short docs/comments explaining the design and any non-obvious decisions
• PR description explains the approach and includes Closes #<issue>

Out of scope

• Global fetch cache
• Suspense migration

Rewards

Part of the GrantFox OSS / Official Campaign (FWC26) — this task may be rewarded. PR quality is assessed by AI: depth, correctness under edge cases, meaningful tests, and clean design are what earn the reward. Shallow changes (typos, formatting, trivial docs) do not qualify.