Add Freighter wallet connection state machine #7

Description

Difficulty: Expert

Type: Feature

Summary

Implement a robust Freighter wallet connection state machine for disconnected, connecting, connected, wrong network, locked, rejected, unavailable, and error states.

Current Behaviour

Wallet connection logic may be spread across components and not handle all failure states clearly.

Expected Behaviour

The dashboard should provide consistent wallet state handling across admin and investor flows.

Suggested Implementation

Create wallet state model, provider hooks, reusable connection components, error mapping, network warning UI, tests or fixtures, and docs.

Files or Areas Likely Affected

• src/features/wallet/
• src/hooks/
• src/components/
• src/lib/
• app/
• docs/

Acceptance Criteria

• Wallet connection state model is implemented.
• Unavailable, rejected, wrong-network, and connected states are distinct.
• Reusable wallet connection component is added.
• Admin and investor flows consume shared wallet state.
• User-facing errors are clear.
• Documentation explains Freighter assumptions.

Additional Notes

This is foundational for signed dashboard flows.