Why React is a projection
Keep UI reactivity separate from domain and transport ownership.
The Core SDK's CapxulClient owns domain methods, typed results, bootstrap
configuration, and the bridge to backend/provider adapters. The React package
adds lifecycle and reactivity around that boundary; it does not implement a
second financial or identity model.
This distinction answers a practical integration question: use the Core SDK reference to understand what an operation does, and use the React reference to understand how that operation appears in component state.
component
-> useCapxul* hook
-> TanStack query or mutation
-> CapxulClient method bundle
-> Promise<CapxulResult<T>>
-> data or CapxulError stateThis direction keeps non-React consumers first-class and prevents hooks from becoming hidden transport APIs. It also makes proof boundaries visible: a hook contract can be hermetically proven while its underlying provider capability still needs integration or live evidence.
What each layer owns
| Concern | Core SDK | React SDK |
|---|---|---|
| Bootstrap and runtime configuration | Owns | Starts or receives the Core client |
Domain methods and CapxulResult<T> | Owns | Projects into query and mutation state |
| Component loading and error UI | Does not own | Owns |
| Query keys, caching, and invalidation | Does not own | Owns |
| Payment, identity, and Account availability | Owns the contract | Cannot expand it |
If a Core method returns NOT_IMPLEMENTED, wrapping it in a hook does not make
the operation available. Conversely, a component rendering bug does not change
the Core method's domain contract.
Why there is only one client
CapxulProvider creates or receives one CapxulClient and shares it with every
hook below that provider. Hooks do not bootstrap their own clients. This keeps
session state, Account readiness, observation, and runtime configuration on one
application boundary instead of allowing components to disagree.
When a domain method changes, update the SDK owner first, then this projection and its hook reference. When only loading UI changes, the Core SDK docs do not need to move.