\n );\n}\n\nexport default function App() {\n return (\n \n \n \n );\n}\n```\n\nThe hosted ORE stack requires this publishable key for authentication and rate limiting. Read-only browser viewing does not require a wallet, but it is not unauthenticated.\n\nSingle-stack applications can remove the repeated constant without ambient types by binding the React API once:\n\n```tsx\nimport { createAreteReact } from '@usearete/react';\nimport { ORE_STREAM_STACK } from './generated/ore-stack';\n\nexport const {\n Provider: OreProvider,\n useArete: useOre,\n} = createAreteReact(ORE_STREAM_STACK);\n```\n\n`useOre()` remains explicit about the application dependency. Multi-stack apps can keep using `AreteProvider` and `useArete(stack)` directly.\n\nProvider-default `useArete()` calls remain available. For full type inference, register the stack type once (e.g. in `src/arete.d.ts`):\n\n```ts\nimport type { OreStreamStack } from './generated/ore-stack';\n\ndeclare module '@usearete/react' {\n interface AreteDefaultStackRegistry {\n defaultStack: OreStreamStack;\n }\n}\n```\n\nMulti-stack apps can keep passing the stack explicitly: `useArete(stack, options)` always wins over the provider default.\n\n## Provider\n\n`AreteProvider` manages connected clients for descendant hooks.\n\nSupported props:\n\n- `stack` — default stack for argument-less `useArete()` calls\n- `stackOptions` — default client lookup options (`url`, `httpUrl`, `transport`, `transactions`, `programs`) for the provider stack, including explicit `useArete(providerStack)` calls\n- `autoConnect` — defaults to `true`; controls only whether the provider starts the initial connection\n- `autoReconnect` — defaults to `true`; controls only recovery after an established connection is lost\n- `wallet`\n- `auth`\n- `fetch`\n- `validateFrames` — set `false` to suppress rejected-frame warnings; generated schemas still normalize and validate entities\n- `onFrameValidationError` — structured callback for generated-schema rejections\n- `reconnectIntervals`\n- `maxReconnectAttempts`\n- `maxEntriesPerView`\n- `flushIntervalMs`\n\nThese are provider-wide defaults. Per-call overrides stay on the hook call and always win. Connection settings are captured when a shared client is created; changing provider props does not mutate that client. `wallet` updates are synchronized in place. For other changed settings, call `retry()` to replace the shared client using the latest provider configuration.\n\nThe lifecycle flags are intentionally independent. `autoConnect={false}` leaves initial connection ownership to the application. It does not disable automatic recovery for a connection the application establishes, but `canRetry` remains false because provider-owned replacement attempts would also stay disconnected; use the client lifecycle directly. `autoReconnect={false}` does not suppress the initial connection; it disables only automatic recovery after that connection is lost.\n\n## `useArete(stack?, options?)`\n\n`useArete` returns the connected React surface for a stack. With no arguments it resolves the provider's `stack`/`stackOptions`. Passing the same stack explicitly keeps the provider's `stackOptions`; per-call options override them, while another explicit stack is isolated from the provider stack's options. It throws a descriptive error when no stack is passed and no default is configured.\n\n- `views`\n- `programs`\n- `queries`\n- `read` — callable stack reads with `.use(...args, options?)` React hooks\n- `chain`\n- `client`\n- `reads` — deprecated alias of `read`\n- `status` — preferred connection state for UI; includes the initial client-creation window\n- `connectionState` — raw state from the connected client\n- `isConnected`\n- `isLoading`\n- `canRetry` — true when `retry()` can start a new shared connection attempt\n- `error`\n- `socketIssue` — the latest structured server WebSocket issue, if any\n- `retry()` — replaces the failed shared client; every matching `useArete` consumer observes the connecting window and adopts the same replacement\n\nSupported hook options:\n\n- `url`\n- `httpUrl`\n- `transport`\n- `transactions` — explicit transaction transport when execution uses a different service from `httpUrl`\n- `programs`\n\nAll options are optional. By default the client connects to the endpoints embedded in the generated stack definition (`stack.endpoints`), so `useArete(STACK)` with no options is the common case.\n\nNotes:\n\n- `transport: 'http'` disables streaming view subscriptions, but HTTP-backed surfaces like `queries`, `chain`, and program reads still work.\n- Attached `programs` are keyed by value (program name and id): passing a fresh object literal each render still resolves to the same client.\n- Repeated `useArete` calls with the same stack object and options share one provider-managed client and store. It is safe for sibling components to call the hook independently.\n\n## Views\n\nView hooks return a discriminated `ViewHookResult`. `status` and `isEmpty`\nnarrow the associated data and error fields:\n\n```ts\nif (round.status === 'error') {\n console.error(round.error); // Error\n} else if (round.status === 'ready' && !round.isEmpty) {\n console.log(round.data.id.roundId); // entity, not undefined\n}\n```\n\n`status` distinguishes \"no client yet\" (`connecting`) from \"subscribed, waiting for the first frame\" (`subscribing`). `isPending` covers both states, `isReady` marks a usable ready result, and `isEmpty` distinguishes a ready hook with no entity or list entries from loading. Errors may retain previously committed data, but `isReady` becomes false. `isLoading` remains for compatibility.\n\nUse the connection `status` together with `socketIssue` and `retry()` for recovery UI:\n\n```tsx\nconst arete = useArete(ORE_STREAM_STACK);\n\nif (arete.canRetry) {\n return ;\n}\n\nreturn ;\n```\n\nThe view hook objects themselves are refresh targets — they refresh that view's *active* subscriptions without you holding a hook result, and are a no-op when nothing is subscribed:\n\n```ts\nawait arete.views.OreRound.state.refresh({ roundId }); // one keyed subscription\nawait arete.views.OreRound.state.refresh(); // every active subscription of the view\nawait arete.views.OreRound.latest.refresh(); // list views\n\n// Handy in mutation reconciliation — the component doesn't need its own\n// subscriptions just to refresh them:\nclaim.submit(args, {\n reconcile: { refresh: [arete.views.OreBoard.state, arete.views.OreMiner.state, preview] },\n});\n```\n\nWhen several resources feed one status line, aggregate them with `summarizeStatuses` instead of hand-rolling loading/error lists:\n\n```tsx\nconst streams = summarizeStatuses({ Board: board, Round: round, Miner: authority && miner });\n// streams.loading → names still loading, e.g. ['Board']\n// streams.refreshing → names resynchronizing committed data\n// streams.errors → 'Name: message' strings\n// streams.isLoading / streams.isRefreshing / streams.hasError\n```\n\nFalsy entries (`authority && miner`) are skipped.\n\nList views support:\n\n- `.use()`\n- `.use({ take: 1 })`\n- `.useOne()`\n\nPut list query configuration (`take`, `skip`, `key`, `partition`, `filters`, `after`, `withSnapshot`, `snapshotLimit`, `schema`, and `onSchemaValidationError`) in the first params object. For compatibility, fields also accepted by view options are honored from the second argument when absent from params; params win when both are supplied. Keep `enabled` and `initialData` in the second argument. State hooks accept one entity as `initialData`, list hooks accept an entity array, and `useOne` accepts one entity.\n\n`onSchemaValidationError(diagnostic)` observes entities rejected by a caller-supplied schema. The diagnostic is `{ view, key?, entity, error }`. Accepted entities and existing filtering behavior are unchanged.\n\nProtocol v2 gives each parameter set independent ordered membership. Different windows and filters on one view can coexist, while equivalent normalized queries share one reference-counted wire subscription:\n\n```tsx\nconst firstPage = views.OreRound.latest.use({ take: 10 });\nconst secondPage = views.OreRound.latest.use({ take: 10, skip: 10 });\n\nif (firstPage.isLoading) return
Loading...
;\n\nreturn (\n <>\n {firstPage.isRefreshing &&
Refreshing...
}\n \n \n \n);\n```\n\nDuring reconnect, hooks preserve their committed data and set `isRefreshing`. A completed authoritative snapshot then atomically replaces membership for that exact query, including an empty result.\n\n`await result.refresh()` resolves after the refreshed subscription's next complete snapshot is committed. Registration, send, and subscription failures reject, clear `isRefreshing`, and appear in `result.error`. A view refresh with no active matching subscription remains a no-op.\n\nOn a replayable append view, `result.cursor` is the `{epoch}:{offset}` position of the last event delivered to that hook. Persist it with whatever you derive from the data and pass it back as `after` to resume; `after` is exclusive and is never a `_seq` value. State and list views project membership rather than a tape, so their hooks have no cursor. A server refusal of a cursor (`cursor-expired`, `cursor-epoch-changed`, `cursor-unknown`, `invalid-cursor`, `replay-gap`, `replay-lagged`) arrives in `result.error` under its wire `code`, each with a different recovery.\n\nState views support:\n\n- `.use(key)` — subscribe to one keyed entity using the generated key type (for example `{ roundId: bigint }`)\n- `.use(undefined)` — disabled: no subscription, `{ data: undefined, isLoading: false }`. Useful while a wallet is not connected: `views.OreMiner.state.use(authority ? { authority } : undefined)`.\n\nKeyed hooks only expose data for the key you passed: when the key changes, `data` becomes `undefined` (and `isLoading` true) until the new key's snapshot arrives. Components never need to re-verify returned data against their inputs.\n\n`initialData` is trusted as immediately usable ready data. The first live store update or completed empty snapshot replaces it; an empty list settles as `[]` and an absent state entity settles as `undefined`. Do not seed transaction-authorizing data unless the application is willing to trust that seed.\n\n> **BigInt props in development:** entities contain bigints, and React ≤19.2's dev-mode performance track calls `JSON.stringify` on changed props — it crashes on bigint *arrays and objects* (scalar bigints are fine), wedging the app after the first live update. Prefer stack-provided UI fields when they exist (e.g. `deployedPerSquareUi` next to `deployedPerSquare`), use `stringifyBigints(value)` for a typed structural bigint→string conversion of the rest (raw account snapshots are the common case), or upgrade to React 19.3+ where this is fixed.\n\n## Reads\n\nStacks can expose one-shot read functions (e.g. RPC-backed previews). Each one gets a React hook:\n\n```tsx\nconst preview = arete.read.solClaimPreview.use(authority);\nconst quote = arete.read.quoteManualDeployment.use(\n input,\n { debounceMs: 300 },\n);\n```\n\n- Arguments form the cache key — the read re-runs when they change, and the previous arguments' data is never exposed while the fresh result is loading.\n- The hook is disabled while any required argument is `null`/`undefined`, so no `enabled` flag or non-null assertions are needed.\n- `.use(...args, { debounceMs, initialData })` adds React-only behavior with options last. Debounce applies to automatic argument changes; `refresh()` always runs immediately. When options follow an omitted optional read argument, pass `undefined` in that argument's position.\n- `status` is `'disabled' | 'connecting' | 'loading' | 'ready' | 'refreshing' | 'error'`. The existing loading and refreshing booleans remain available.\n- `isPending`, `isReady`, and `isEmpty` cover the common UI branches without comparing status strings.\n- `preview.refresh()` re-runs the read on demand, typically after a mutation (see below).\n\nThe same functions remain callable for imperative access: `await arete.read.solClaimPreview(authority)`. The old `arete.reads` namespace remains as a deprecated alias.\n\n## Programs, Queries, and Chain\n\n`useArete` mirrors the connected core client surface:\n\n- `programs..raw.` for raw typed instructions\n- `programs..instructions`, `.transactions`, and `.flows` for semantic operations\n- `programs..accounts` and `programs..queries` for HTTP reads\n- `queries` for stack-level HTTP queries\n- `chain` for chain helpers\n\nRaw instruction hooks preserve `.execute`, `.build`, and `.useMutation()`.\n\nSemantic operation hooks preserve:\n\n- `.execute`\n- `.prepare`\n- `.useMutation()`\n\nMutation hooks expose `mutate(args, options)` for event handlers. It records\nerrors in hook state and does not return a promise. Use the equivalent rejecting\n`mutateAsync(args, options)` or `submit(args, options)` when the caller must\nawait or compose the result.\n\nProgram and read hooks are safe to call while the client is still connecting: mutations throw \"Arete client is not connected\" if submitted early, and reads stay disabled.\n\n## Safe amount parsing\n\n`safeToRawAmount(input, decimals)` is re-exported by `@usearete/react` for form validation. Unlike `toRawAmount`, it reports invalid input without throwing:\n\n```tsx\nimport { safeToRawAmount } from '@usearete/react';\n\nconst parsed = safeToRawAmount({ ui: amountText }, 9);\nif (!parsed.success) {\n setAmountError(String(parsed.error));\n return;\n}\n\nconst rawAmount = parsed.data;\n```\n\nThe return type is `{ success: true, data } | { success: false, error }`.\n\n## Default reconciliation\n\nMutations from generated program hooks **reconcile against the stream by default**: after the transaction confirms on-chain, the hook waits until the stack has processed the highest confirmed receipt slot before settling (30s timeout). HTTP-only mutations and results without a receipt slot skip this step. The processed-slot watermark does not promise that a particular entity changed; use `refresh` for the views or one-shot reads that must be re-read.\n\nPer-submit options:\n\n```tsx\n// Opt out entirely:\ndeploy.submit(args, { reconcile: false });\n\n// Keep the default, but also refresh views and one-shot reads afterwards.\n// `refresh` accepts view hook objects, view/read hook results, or plain\n// callbacks:\nclaim.submit(args, {\n reconcile: { refresh: [arete.views.OreBoard.state, miner, preview] },\n});\n\n// Custom timeout:\ndeploy.submit(args, { reconcile: { timeoutMs: 10_000 } });\n\n// Full control — a function replaces the default:\ndeploy.submit(args, { reconcile: async (context) => { /* ... */ } });\n```\n\nThe mutation `phase` field is the discriminated status to branch on for busy labels (`'preparing'`, `'awaiting-wallet'`, `'submitted'`, `'confirmed'`, `'reconciling'`, `'reconciled'`, plus the failure outcomes); `status` remains `'pending'` until the mutation settles. Generated operation hooks publish each completed receipt and signature during `submitted`, before the final operation receipt resolves. `onConfirmed` runs immediately after chain confirmation; `onSuccess` runs only after successful reconciliation (or immediately when reconciliation is disabled/skipped). Reconciliation failure, including a refreshed snapshot timeout, is exposed through `reconciliationError`, does not call `onSuccess`, and does not reject the confirmed `submit()` result. The confirmed transaction remains landed. `retryReconciliation()` repeats only post-confirmation watermark/refresh work using the saved receipts and targets; it never rebuilds, signs, or submits. Convenience booleans (`isPreparing`, `isAwaitingWallet`, `isReconciling`, `canRetryReconciliation`) remain available.\n\n## Migration notes (0.3 → next)\n\n- `AreteProvider` accepts a default `stack` and `stackOptions`; `useArete()` may then be called with no arguments. Register the stack type via `AreteDefaultStackRegistry` for full inference.\n- View hook results expose a `status` field (`'disabled' | 'connecting' | 'subscribing' | 'ready' | 'error'`).\n- View hook objects (`arete.views.X.state` / `.list`) expose `refresh(key?)` and can be passed directly in `reconcile: { refresh: [...] }`.\n- New `summarizeStatuses(namedResults)` status aggregator; `summarizeViews` remains as a deprecated alias.\n- New `stringifyBigints(value)` display helper (also re-exported from `@usearete/sdk`).\n- `UseAreteResult`'s second type parameter defaults to `undefined`.\n- The duplicate low-level `useView` and `useEntity` hooks were removed. Use generated `arete.views...use(...)` hooks.\n\n## Migration notes (0.2 → 0.3)\n\n- **Generated-hook mutations reconcile by default.** `submit()` now resolves after stream reconciliation instead of right after confirmation. Timeouts settle as `confirmed-unreconciled` rather than failing. Pass `reconcile: false` to restore the old behavior.\n- **State view keys are required and generated.** Pass the generated key object, or explicitly pass `undefined`/`null` to disable the hook. Zero-argument state subscriptions are no longer supported, and malformed keys throw the shared core serializer error.\n- **Disabled view hooks report `isLoading: false`.** Previously `enabled: false` still started in a loading state.\n- New additive `UseMutationResult` fields: `isPreparing`, `isAwaitingWallet`, `isReconciling`.\n- New mutation callback: `onConfirmed`, for work that must run after chain confirmation even if stream reconciliation later fails.\n- `useArete` now exposes `socketIssue` and deduplicated `retry()`.\n- Stack reads expose imperative calls and hooks together under `arete.read.`; `arete.reads` remains a deprecated alias.\n- Repeated `useArete` calls now share a provider-managed client when stack and option identities match; remove component-local connection ownership workarounds.\n\n## Low-Level Hooks\n\nThe React SDK also exports:\n\n- `useConnectionState`\n- `useAreteContext`\n\nThese accept the same client lookup overrides when you need to target a non-default client.\n\n## Relationship with `@usearete/sdk`\n\n`@usearete/react` re-exports selected core APIs and types for convenience, but it is not a complete mirror of the core package.\n\nIf you need the full low-level surface, import directly from `@usearete/sdk`.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}