@usearete/react 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import React, { ReactNode } from 'react';
-import { WalletAdapter, ConnectOptions, AuthConfig, Schema, ProgramSdkDefinition, StackDefinition, ConnectionState, ConnectedArete, StackWithAttachedPrograms, ProgramInterface, TypedInstruction, PreparedOperation, OperationReceiptFor, StorageAdapter, StorageAdapterConfig, UpdateCallback, RichUpdateCallback, Update, RichUpdate, ViewSortConfig, QueriesInterface, ChainClient, StackQueryDefinition, ViewGroup, ViewDef } from '@usearete/sdk';
-export { AccountCategory, AccountMeta, AccountResolutionOptions, AccountResolutionResult, Arete, AreteError, AreteOptions, AreteOptionsWithStorage, ArgSchema, ArgType, AuthConfig, BuildOptions, BuiltAccountMeta, BuiltInstruction, ConfirmationLevel, ConnectOptions, ConnectedArete, ConnectionManager, ConnectionState, DEFAULT_CONFIG, DEFAULT_MAX_ENTRIES_PER_VIEW, EntityFrame, ErrorMetadata, ExecuteOptions, ExecutionResult, Frame, FrameMode, FrameOp, FrameProcessor, FrameProcessorConfig, InstructionError, InstructionExecutor, InstructionHandler, InstructionHandlerConfig, MemoryAdapter, MergeProgramMaps, OperationExecutionOptions, OperationReceiptFor, PdaConfig, PdaSeed, PreparedFlow, PreparedInstruction, PreparedOperation, PreparedTransaction, PreparedTransactionInstruction, ProgramError, ReadRequestError, ResolvedAccount, ResolvedAccounts, RichUpdate, RichUpdateCallback, Schema, SendOptions, SendResult, SnapshotEntity, SnapshotFrame, StackDefinition, StackWithAttachedPrograms, StorageAdapter, StorageAdapterConfig, Subscription, SubscriptionRegistry, TransactionOptions, TypedInstruction, Update, UpdateCallback, ViewDef, ViewGroup, WalletAdapter, WalletConnectOptions, WalletState, buildInstruction, createInstructionExecutor, createInstructionHandler, createPublicKeySeed, createSeed, derivePda, executeInstruction, formatProgramError, isSnapshotFrame, isValidFrame, parseFrame, parseFrameFromBlob, parseInstructionError, resolveAccounts, serializeInstructionData, validateAccountResolution, withPrograms } from '@usearete/sdk';
+import { StackDefinition, WalletAdapter, ConnectOptions, AuthConfig, Schema, ProgramSdkDefinition, ConnectionState, ConnectedArete, StackWithAttachedPrograms, PreparedOperation, TransactionFailureOutcome, OperationExecutionEvent, OperationExecutionSuccessEvent, OperationTransactionReceipt, TransactionOutcome, ProgramInterface, TypedInstruction, OperationReceiptFor, StorageAdapter, StorageAdapterConfig, UpdateCallback, RichUpdateCallback, Update, RichUpdate, ViewSortConfig, QueriesInterface, ChainClient, StackConnectedExtensions, SocketIssue, StackQueryDefinition, ViewGroup, ViewDef, ContextSlotOptions, NativeBalanceInfo, TokenBalanceInput, TokenBalanceInfo, WaitForProcessedSlotOptions } from '@usearete/sdk';
+export { AccountCategory, AccountMeta, AccountResolutionOptions, AccountResolutionResult, Arete, AreteError, AreteOptions, AreteOptionsWithStorage, ArgSchema, ArgType, AuthConfig, BuildOptions, BuiltAccountMeta, BuiltInstruction, ConfirmationLevel, ConnectOptions, ConnectedArete, ConnectionManager, ConnectionState, ContextSlotOptions, DEFAULT_CONFIG, DEFAULT_MAX_ENTRIES_PER_VIEW, DefaultViewKey, EntityFrame, ErrorFrame, ErrorMetadata, ExecuteOptions, ExecutionResult, Frame, FrameMode, FrameOp, FrameProcessor, FrameProcessorConfig, FrameValidationDiagnostic, InstructionError, InstructionExecutor, InstructionHandler, InstructionHandlerConfig, MemoryAdapter, MergeProgramMaps, NativeBalanceInfo, OperationCallbackError, OperationExecutionError, OperationExecutionOptions, OperationReceiptFor, OperationTransactionReceipt, PdaConfig, PdaSeed, PreparedFlow, PreparedInstruction, PreparedOperation, PreparedTransaction, PreparedTransactionInstruction, ProcessedSlotTimeoutError, ProgramError, QueryLease, QuerySnapshot, QueryStore, ReadRequestError, ResolvedAccount, ResolvedAccounts, RichUpdate, RichUpdateCallback, Schema, SendOptions, SendResult, SnapshotEntity, SnapshotFrame, SocketIssue, StackDefinition, StackWithAttachedPrograms, StorageAdapter, StorageAdapterConfig, StringifiedBigints, SubscribedFrame, Subscription, SubscriptionQuery, SubscriptionRegistry, SubscriptionRequest, SubscriptionSnapshotOptions, TokenBalanceInfo, TokenBalanceInput, TransactionExecutionError, TransactionFailureOutcome, TransactionOptions, TransactionOutcome, TypedInstruction, UnsubscribedFrame, Update, UpdateCallback, ViewDef, ViewGroup, ViewKeyValue, WaitForProcessedSlotOptions, WalletAdapter, WalletConnectOptions, WalletState, buildInstruction, canonicalQueryKey, createInstructionExecutor, createInstructionHandler, createPublicKeySeed, createSeed, derivePda, executeInstruction, formatProgramError, formatRawToUi, getTransactionFailureOutcome, isErrorFrame, isHostedAreteEndpoint, isSnapshotFrame, isSubscribedFrame, isUnsubscribedFrame, isValidFrame, normalizeSubscriptionQuery, parseFrame, parseFrameFromBlob, parseInstructionError, resolveAccounts, safeToRawAmount, serializeInstructionData, serializeViewKey, stringifyBigints, toRawAmount, unwrapOperationExecutionError, validateAccountResolution, withPrograms } from '@usearete/sdk';
 import { UseBoundStore, StoreApi } from 'zustand';
 
 type ViewMode = 'state' | 'list';
@@ -14,16 +14,41 @@ interface TransactionDefinition<TParams = unknown> {
         key?: string | ((params: TParams) => string);
     }>;
 }
-type ProgramMap$2 = Record<string, ProgramSdkDefinition>;
+type ProgramMap$3 = Record<string, ProgramSdkDefinition>;
 /**
  * Global configuration for AreteProvider.
  *
- * Note: WebSocket URL is no longer configured here. The URL is:
- * 1. Embedded in the stack definition (`stack.endpoints.ws` / `stack.endpoints.http`)
- * 2. Optionally overridden per-hook via `useArete(stack, { url, httpUrl })`
+ * Note: WebSocket URL is usually embedded in the stack definition
+ * (`stack.endpoints.ws` / `stack.endpoints.http`). Override it for the whole
+ * app via `stackOptions`, or per-hook via `useArete(stack, { url, httpUrl })`.
  */
 interface AreteConfig {
+    /**
+     * Default stack for the app. When set, components can call `useArete()`
+     * with no arguments; passing a stack explicitly always wins. Register the
+     * stack's type once for full inference on argument-less calls:
+     *
+     * ```ts
+     * declare module '@usearete/react' {
+     *   interface AreteDefaultStackRegistry { defaultStack: OreStreamStack }
+     * }
+     * ```
+     */
+    stack?: StackDefinition;
+    /**
+     * Default lookup options for the provider stack. They also apply when that
+     * same stack is passed explicitly to `useArete(stack)` without options.
+     */
+    stackOptions?: ClientLookupOptions;
+    /**
+     * Connect immediately when the client is created (defaults to true).
+     * Provider connection settings are applied when a shared client is created;
+     * changing them does not mutate an existing client. Call retry() to replace
+     * that client with the latest settings. Wallet is the reactive exception.
+     */
     autoConnect?: boolean;
+    /** Reconnect automatically after an established connection is lost (defaults to true). */
+    autoReconnect?: boolean;
     wallet?: WalletAdapter;
     reconnectIntervals?: number[];
     maxReconnectAttempts?: number;
@@ -31,50 +56,122 @@ interface AreteConfig {
     flushIntervalMs?: number;
     fetch?: ConnectOptions['fetch'];
     validateFrames?: boolean;
+    /** Receives structured details when a generated schema rejects a frame. */
+    onFrameValidationError?: ConnectOptions['onFrameValidationError'];
     /** Authentication configuration */
     auth?: AuthConfig;
 }
 /**
  * Client lookup/connect options for React hooks.
  */
-interface ClientLookupOptions<TPrograms extends ProgramMap$2 | undefined = undefined> {
+interface ClientLookupOptions<TPrograms extends ProgramMap$3 | undefined = undefined> {
     /** Override the stack's embedded WebSocket URL (useful for local development) */
     url?: string;
     /** Override the stack's embedded HTTP read URL (useful for local development) */
     httpUrl?: string;
     /** Override the stack transport. HTTP mode disables streaming view subscriptions. */
     transport?: ConnectOptions<TPrograms>['transport'];
+    /** Override the transaction transport independently from the stack HTTP endpoint. */
+    transactions?: ConnectOptions<TPrograms>['transactions'];
     /** Attach additional program SDKs to the connected client. */
     programs?: TPrograms;
 }
-type UseAreteOptions<TPrograms extends ProgramMap$2 | undefined = undefined> = ClientLookupOptions<TPrograms>;
-interface ViewHookOptions<TSchema = unknown> {
+type UseAreteOptions<TPrograms extends ProgramMap$3 | undefined = undefined> = ClientLookupOptions<TPrograms>;
+interface ViewSchemaValidationDiagnostic {
+    readonly view: string;
+    readonly key?: string;
+    readonly entity: unknown;
+    readonly error: unknown;
+}
+type ViewSchemaValidationErrorCallback = (diagnostic: ViewSchemaValidationDiagnostic) => void;
+interface ViewHookSharedOptions<TSchema = unknown> {
     enabled?: boolean;
-    initialData?: unknown;
-    refreshOnReconnect?: boolean;
-    /** Schema to validate entities. Returns undefined if validation fails. */
+    /** Schema used to validate and project cached entities. Rejected entities are excluded. */
     schema?: Schema<TSchema>;
+    /** Observe entities rejected by the caller-supplied schema and suppress the development warning. */
+    onSchemaValidationError?: ViewSchemaValidationErrorCallback;
     /** Whether to include initial snapshot (defaults to true) */
     withSnapshot?: boolean;
     /** Cursor for resuming from a specific point (_seq value) */
     after?: string;
     /** Maximum number of entities to include in snapshot */
     snapshotLimit?: number;
+    partition?: string;
+    filters?: Record<string, unknown>;
+}
+interface StateViewHookOptions<TSchema = unknown> extends ViewHookSharedOptions<TSchema> {
+    initialData?: TSchema;
+}
+interface ListViewHookOptions<TSchema = unknown> extends ViewHookSharedOptions<TSchema> {
+    initialData?: readonly TSchema[];
+}
+interface ListOneViewHookOptions<TSchema = unknown> extends ViewHookSharedOptions<TSchema> {
+    initialData?: TSchema;
 }
-interface ViewHookResult<T> {
+/** @deprecated Use StateViewHookOptions, ListViewHookOptions, or ListOneViewHookOptions. */
+type ViewHookOptions<TSchema = unknown> = StateViewHookOptions<TSchema> | ListViewHookOptions<TSchema> | ListOneViewHookOptions<TSchema>;
+/**
+ * Lifecycle status of a view hook:
+ * - `'disabled'` — no key/params or `enabled: false`; nothing is subscribed.
+ * - `'connecting'` — enabled, but the Arete client has not connected yet.
+ * - `'subscribing'` — subscribed, waiting for the first snapshot.
+ * - `'ready'` — data is usable, from a live snapshot or trusted `initialData`.
+ * - `'error'` — the subscription failed; see `error`.
+ */
+type ViewStatus = 'disabled' | 'connecting' | 'subscribing' | 'ready' | 'error';
+interface ViewHookResultBase<T> {
     data: T | undefined;
-    isLoading: boolean;
-    error?: Error;
-    refresh: () => void;
+    isRefreshing: boolean;
+    refresh: () => Promise<void>;
 }
+type EmptyViewData<T> = T extends readonly unknown[] ? T : undefined;
+type ViewHookResult<T> = (ViewHookResultBase<T> & {
+    status: 'disabled';
+    isPending: false;
+    isReady: false;
+    isEmpty: false;
+    isLoading: false;
+    error: undefined;
+}) | (ViewHookResultBase<T> & {
+    status: 'connecting' | 'subscribing';
+    isPending: true;
+    isReady: false;
+    isEmpty: false;
+    isLoading: boolean;
+    error: undefined;
+}) | (ViewHookResultBase<T> & {
+    status: 'error';
+    isPending: false;
+    isReady: false;
+    isEmpty: false;
+    isLoading: false;
+    error: Error;
+}) | (Omit<ViewHookResultBase<T>, 'data'> & {
+    data: T;
+    status: 'ready';
+    isPending: false;
+    isReady: true;
+    isEmpty: false;
+    isLoading: false;
+    error: undefined;
+}) | (Omit<ViewHookResultBase<T>, 'data'> & {
+    data: EmptyViewData<T>;
+    status: 'ready';
+    isPending: false;
+    isReady: true;
+    isEmpty: true;
+    isLoading: false;
+    error: undefined;
+});
 interface ListParamsBase<TSchema = unknown> {
     key?: string;
-    where?: Record<string, unknown>;
-    limit?: number;
-    filters?: Record<string, string>;
+    partition?: string;
+    filters?: Record<string, unknown>;
     skip?: number;
     /** Schema to validate/filter entities. Only entities passing safeParse will be returned. */
     schema?: Schema<TSchema>;
+    /** Observe entities rejected by the caller-supplied schema and suppress the development warning. */
+    onSchemaValidationError?: ViewSchemaValidationErrorCallback;
     /** Whether to include initial snapshot (defaults to true) */
     withSnapshot?: boolean;
     /** Cursor for resuming from a specific point (_seq value) */
@@ -96,78 +193,164 @@ interface UseMutationReturn {
     signature?: string;
     reset: () => void;
 }
-interface StateViewHook<T> {
-    use: (key: {
-        [keyField: string]: string;
-    }, options?: ViewHookOptions) => ViewHookResult<T>;
+interface StateViewHook<T, TKey = string> {
+    use: (key: TKey | null | undefined, options?: StateViewHookOptions<T>) => ViewHookResult<T>;
+    /**
+     * Refresh active subscriptions for this view without holding a hook result.
+     * Pass a key to refresh one keyed subscription; omit it to refresh every
+     * active subscription of the view. No-op when nothing is subscribed, which
+     * makes it safe to use in `reconcile: { refresh: [...] }` targets.
+     */
+    refresh: (key?: TKey | null) => Promise<void>;
 }
 interface ListViewHook<T> {
-    use<TSchema = T>(params: ListParamsSingle<TSchema>, options?: ViewHookOptions): ViewHookResult<TSchema | undefined>;
-    use<TSchema = T>(params?: ListParamsMultiple<TSchema>, options?: ViewHookOptions): ViewHookResult<TSchema[]>;
-    useOne: <TSchema = T>(params?: Omit<ListParamsBase<TSchema>, 'take'>, options?: ViewHookOptions) => ViewHookResult<TSchema | undefined>;
+    use<TSchema = T>(params: ListParamsSingle<TSchema>, options?: ListOneViewHookOptions<TSchema>): ViewHookResult<TSchema>;
+    use<TSchema = T>(params?: ListParamsMultiple<TSchema>, options?: ListViewHookOptions<TSchema>): ViewHookResult<TSchema[]>;
+    useOne: <TSchema = T>(params?: Omit<ListParamsBase<TSchema>, 'take'>, options?: ListOneViewHookOptions<TSchema>) => ViewHookResult<TSchema>;
+    /** Refresh every active subscription of this list view. No-op when none. */
+    refresh: () => Promise<void>;
 }
 
-type ProgramMap$1 = Record<string, ProgramSdkDefinition>;
-type ResolvedStack$1<TStack extends StackDefinition, TPrograms extends ProgramMap$1 | undefined> = StackWithAttachedPrograms<TStack, TPrograms>;
+type ProgramMap$2 = Record<string, ProgramSdkDefinition>;
+type ResolvedStack$1<TStack extends StackDefinition, TPrograms extends ProgramMap$2 | undefined> = StackWithAttachedPrograms<TStack, TPrograms>;
+interface ClientChange {
+    cacheKey: string;
+    status: 'connecting' | 'connected' | 'error';
+    error?: Error;
+}
 interface AreteContextValue {
-    getOrCreateClient: <TStack extends StackDefinition, TPrograms extends ProgramMap$1 | undefined = undefined>(stack: TStack, options?: ClientLookupOptions<TPrograms>) => Promise<ConnectedArete<ResolvedStack$1<TStack, TPrograms>>>;
-    getClient: <TStack extends StackDefinition, TPrograms extends ProgramMap$1 | undefined = undefined>(stack: TStack | undefined, options?: ClientLookupOptions<TPrograms>) => ConnectedArete<ResolvedStack$1<TStack, TPrograms>> | null;
-    subscribeToClientChanges: (callback: () => void) => () => void;
+    getOrCreateClient: <TStack extends StackDefinition, TPrograms extends ProgramMap$2 | undefined = undefined>(stack: TStack, options?: ClientLookupOptions<TPrograms>) => Promise<ConnectedArete<ResolvedStack$1<TStack, TPrograms>>>;
+    getClient: <TStack extends StackDefinition, TPrograms extends ProgramMap$2 | undefined = undefined>(stack: TStack | undefined, options?: ClientLookupOptions<TPrograms>) => ConnectedArete<ResolvedStack$1<TStack, TPrograms>> | null;
+    retryClient: <TStack extends StackDefinition, TPrograms extends ProgramMap$2 | undefined = undefined>(stack: TStack, options?: ClientLookupOptions<TPrograms>) => Promise<ConnectedArete<ResolvedStack$1<TStack, TPrograms>>>;
+    subscribeToClientChanges: (callback: (change?: ClientChange) => void) => () => void;
     config: AreteConfig;
 }
-declare function AreteProvider({ children, fallback, ...config }: AreteConfig & {
+declare function AreteProvider({ children, ...config }: AreteConfig & {
     children: ReactNode;
-    fallback?: ReactNode;
 }): React.JSX.Element;
 declare function useAreteContext(): AreteContextValue;
 declare function useConnectionState(stack?: StackDefinition, options?: ClientLookupOptions): ConnectionState;
-declare function useView<T>(stack: StackDefinition, viewPath: string, options?: ClientLookupOptions): T[];
-declare function useEntity<T>(stack: StackDefinition, viewPath: string, key: string, options?: ClientLookupOptions): T | null;
 
 type MutationStatus = 'idle' | 'pending' | 'success' | 'error';
-type UseMutationOptions<TOptions extends object = Record<string, never>, TResult = unknown> = TOptions & {
-    onSuccess?: (result: TResult) => void;
-    onError?: (error: Error) => void;
+type MutationPhase = 'idle' | 'preparing' | 'awaiting-wallet' | 'submitted' | 'confirmed' | 'reconciling' | 'reconciled' | 'confirmed-unreconciled' | 'not-submitted' | 'submitted-unknown' | 'chain-failed';
+interface MutationLifecycleEvent<TResult = unknown, TPrepared extends PreparedOperation = PreparedOperation> {
+    readonly phase: MutationPhase;
+    readonly prepared: TPrepared | null;
+    readonly result?: TResult;
+    readonly failure?: TransactionFailureOutcome;
+    readonly error?: Error;
+    readonly transactionEvent?: OperationExecutionEvent<TPrepared> | OperationExecutionSuccessEvent<TPrepared>;
+}
+interface MutationReconciliationContext<TResult = unknown, TPrepared extends PreparedOperation = PreparedOperation> {
+    readonly result: TResult;
+    readonly prepared: TPrepared | null;
+    readonly signatures: readonly string[];
+    readonly completedReceipts: readonly OperationTransactionReceipt[];
+    readonly signal: AbortSignal;
+}
+interface MutationExecutionObserver<TPrepared extends PreparedOperation = PreparedOperation> {
+    onPrepared(prepared: TPrepared): void;
+    onAwaitingWallet(): void;
+    onTransactionStart(event: OperationExecutionEvent<TPrepared>): void;
+    onTransactionSuccess(event: OperationExecutionSuccessEvent<TPrepared>): void;
+    onCallbackError(error: unknown): void;
+}
+type MutationReconcileFn<TResult = unknown, TPrepared extends PreparedOperation = PreparedOperation> = (context: MutationReconciliationContext<TResult, TPrepared>) => unknown | Promise<unknown>;
+/**
+ * Anything that can be refreshed after a mutation reconciles: a plain
+ * callback, or any hook result carrying a `refresh` method (view hooks from
+ * `arete.views.*` and read hooks from `arete.read.*`), so callers can write
+ * `reconcile: { refresh: [board, round, quoteRead] }` without extracting
+ * `.refresh` functions by hand.
+ */
+type ReconciliationRefreshTarget = (() => unknown | Promise<unknown>) | {
+    readonly refresh: () => unknown | Promise<unknown>;
+};
+/**
+ * Shorthand overrides for the default reconciliation injected into generated
+ * program hooks. Only valid when the hook-level default is a marked default
+ * reconciliation (see `createProcessedSlotReconciliation`).
+ */
+interface MutationReconcileOverrides {
+    readonly refresh?: ReconciliationRefreshTarget | readonly ReconciliationRefreshTarget[];
+    readonly timeoutMs?: number;
+}
+type UseMutationOptions<TOptions extends object = Record<string, unknown>, TResult = unknown, TPrepared extends PreparedOperation = PreparedOperation> = TOptions & {
+    onConfirmed?: (result: TResult) => void | Promise<void>;
+    onSuccess?: (result: TResult) => void | Promise<void>;
+    onError?: (error: Error) => void | Promise<void>;
+    reconcile?: false | MutationReconcileFn<TResult, TPrepared> | MutationReconcileOverrides;
 };
 /**
  * Result of {@link useInstructionMutation}.
  *
- * `TParams` is the merged params object accepted by the instruction (IDL args
- * plus any user-provided account addresses), inferred from the generated
- * handler. `TError` is the handler's typed program-error union.
+ * `phase` is the primary, discriminated status: it walks
+ * 'preparing' → 'awaiting-wallet' → 'submitted' → 'confirmed' →
+ * 'reconciling' → 'reconciled' on the happy path, and lands on
+ * 'confirmed-unreconciled', 'not-submitted', 'submitted-unknown', or
+ * 'chain-failed' otherwise. UIs should branch on `phase` for busy labels and
+ * on {@link UseMutationResult.displayError} /
+ * {@link UseMutationResult.reconciliationError} for messages.
+ *
+ * `failure` and `outcome` describe chain execution only; callback and
+ * reconciliation failures never replace a confirmed outcome.
  */
-interface UseMutationResult<TParams = Record<string, unknown>, TResult = unknown, TOptions extends object = Record<string, never>> {
-    submit: (args: TParams, options?: Partial<UseMutationOptions<TOptions, TResult>>) => Promise<TResult>;
+interface UseMutationResult<TParams = Record<string, unknown>, TResult = unknown, TOptions extends object = Record<string, unknown>, TPrepared extends PreparedOperation = PreparedOperation> {
+    /** Event-handler form. Errors are recorded in mutation state and do not escape. */
+    mutate: (args: TParams, options?: Partial<UseMutationOptions<TOptions, TResult, TPrepared>>) => void;
+    /** Rejecting form for imperative composition. Equivalent to submit(). */
+    mutateAsync: (args: TParams, options?: Partial<UseMutationOptions<TOptions, TResult, TPrepared>>) => Promise<TResult>;
+    submit: (args: TParams, options?: Partial<UseMutationOptions<TOptions, TResult, TPrepared>>) => Promise<TResult>;
     status: MutationStatus;
+    phase: MutationPhase;
+    latestEvent: MutationLifecycleEvent<TResult, TPrepared> | null;
     error: string | null;
+    displayError: string | null;
+    failure: TransactionFailureOutcome | null;
+    outcome: TransactionOutcome | null;
+    prepared: TPrepared | null;
+    data: TResult | undefined;
+    result: TResult | undefined;
     signatures: string[];
     signature: string | null;
+    completedReceipts: OperationTransactionReceipt[];
+    callbackError: Error | null;
+    callbackErrors: Error[];
+    reconciliationError: Error | null;
     isLoading: boolean;
+    isConfirmed: boolean;
+    isSubmittedUnknown: boolean;
+    isPreparing: boolean;
+    isAwaitingWallet: boolean;
+    isReconciling: boolean;
+    canRetryReconciliation: boolean;
+    /** Retry only post-confirmation stream reconciliation; never resubmits. */
+    retryReconciliation: () => Promise<void>;
     reset: () => void;
 }
-type MutationExecutor<TParams = Record<string, unknown>, TResult = unknown, TOptions extends object = Record<string, never>> = {
-    (args: TParams, options?: TOptions): Promise<TResult>;
+type MutationExecutor<TParams = Record<string, unknown>, TResult = unknown, TOptions extends object = Record<string, unknown>, TPrepared extends PreparedOperation = PreparedOperation> = {
+    (args: TParams, options?: TOptions, observer?: MutationExecutionObserver<TPrepared>): Promise<TResult>;
 };
-declare function useInstructionMutation<TParams = Record<string, unknown>, TResult = unknown, TOptions extends object = Record<string, never>>(execute: MutationExecutor<TParams, TResult, TOptions>): UseMutationResult<TParams, TResult, TOptions>;
+declare function useInstructionMutation<TParams = Record<string, unknown>, TResult = unknown, TOptions extends object = Record<string, unknown>, TPrepared extends PreparedOperation = PreparedOperation>(execute: MutationExecutor<TParams, TResult, TOptions, TPrepared>, defaults?: Partial<UseMutationOptions<TOptions, TResult, TPrepared>>): UseMutationResult<TParams, TResult, TOptions, TPrepared>;
 
 type OperationOptionsArg<TClient> = TClient extends {
     execute(prepared: PreparedOperation, options?: infer TOptions): Promise<unknown>;
-} ? NonNullable<TOptions> : Record<string, never>;
+} ? NonNullable<TOptions> : Record<string, unknown>;
 type RawOptionsArg<TClient> = TClient extends {
     transaction(instructions: readonly unknown[], options?: infer TOptions): Promise<unknown>;
-} ? NonNullable<TOptions> : Record<string, never>;
+} ? NonNullable<TOptions> : Record<string, unknown>;
 type ConnectedOperationLike = {
     prepare(input: unknown): Promise<PreparedOperation>;
 };
 type RawInstructionHookFor<THandler, TClient> = THandler extends TypedInstruction<infer P, infer E> ? {
-    useMutation: () => UseMutationResult<P, E, RawOptionsArg<TClient>>;
+    useMutation: (options?: Partial<UseMutationOptions<RawOptionsArg<TClient>, E>>) => UseMutationResult<P, E, RawOptionsArg<TClient>>;
     execute: (input: P, options?: RawOptionsArg<TClient>) => Promise<E>;
     build: THandler['build'];
 } : never;
 type OperationHookFor<TOperation, TClient> = TOperation extends {
     prepare(input: infer P): Promise<infer TPrepared extends PreparedOperation>;
 } ? {
-    useMutation: () => UseMutationResult<P, OperationReceiptFor<TPrepared>, OperationOptionsArg<TClient>>;
+    useMutation: (options?: Partial<UseMutationOptions<OperationOptionsArg<TClient>, OperationReceiptFor<TPrepared>, TPrepared>>) => UseMutationResult<P, OperationReceiptFor<TPrepared>, OperationOptionsArg<TClient>, TPrepared>;
     execute: (input: P, options?: OperationOptionsArg<TClient>) => Promise<OperationReceiptFor<TPrepared>>;
     prepare: TOperation['prepare'];
 } : never;
@@ -186,6 +369,67 @@ type BuildProgramInterface<TPrograms extends Record<string, ProgramSdkDefinition
     [K in keyof TPrograms]: ProgramHookInterface<TPrograms[K], TClient>;
 } : Record<string, never>;
 
+type AsyncReadKey = string | number | bigint | boolean | null | undefined | readonly AsyncReadKey[] | {
+    readonly [key: string]: AsyncReadKey;
+};
+interface AsyncReadContext {
+    readonly signal: AbortSignal;
+    readonly key: AsyncReadKey;
+}
+interface UseAsyncReadOptions<T> {
+    enabled?: boolean;
+    initialData?: T;
+    debounceMs?: number;
+    /** Status to expose when the read is disabled by an unavailable dependency. */
+    disabledStatus?: Extract<AsyncReadStatus, 'disabled' | 'connecting'>;
+}
+type AsyncReadStatus = 'disabled' | 'connecting' | 'loading' | 'ready' | 'refreshing' | 'error';
+interface UseAsyncReadResult<T> {
+    data: T | undefined;
+    error: Error | null;
+    status: AsyncReadStatus;
+    /** True while the read is connecting or loading its first result. */
+    isPending: boolean;
+    /** True after the read has completed once, including during a refresh. */
+    isReady: boolean;
+    /** True when a ready read resolved to `null` or `undefined`. */
+    isEmpty: boolean;
+    isLoading: boolean;
+    isRefreshing: boolean;
+    refresh: () => Promise<T | undefined>;
+}
+/**
+ * Minimal keyed async state with no cache, retry, or request deduplication.
+ * A newer request aborts and supersedes the previous request for this hook.
+ *
+ * The returned state is tagged with the key that produced it: when the key
+ * changes, the hook immediately reports the fresh key's initial state instead
+ * of briefly exposing data fetched for the previous key. Callers never need
+ * to re-verify that `data` matches the arguments they passed.
+ */
+declare function useAsyncRead<T>(key: AsyncReadKey, read: (context: AsyncReadContext) => Promise<T>, options?: UseAsyncReadOptions<T>): UseAsyncReadResult<T>;
+
+type NullableArgs<TArgs extends readonly unknown[]> = {
+    [I in keyof TArgs]: TArgs[I] | undefined | null;
+};
+type RequiredNullableArgs<TArgs extends readonly unknown[]> = {
+    [I in keyof TArgs]-?: TArgs[I] | undefined | null;
+};
+type ReactReadInterface<TRead> = [TRead] extends [never] ? Record<string, never> : {
+    [K in keyof TRead]: TRead[K] extends (...args: infer TArgs) => infer TReturn ? TArgs extends readonly unknown[] ? TRead[K] & {
+        use: {
+            (...args: NullableArgs<TArgs>): UseAsyncReadResult<Awaited<TReturn>>;
+            (...args: [
+                ...RequiredNullableArgs<TArgs>,
+                ReadHookOptions<Awaited<TReturn>>
+            ]): UseAsyncReadResult<Awaited<TReturn>>;
+        };
+    } : never : never;
+};
+/** @deprecated Use {@link ReactReadInterface}; `read` now includes both forms. */
+type ReadHookInterface<TRead> = ReactReadInterface<TRead>;
+type ReadHookOptions<T> = Pick<UseAsyncReadOptions<T>, 'initialData' | 'debounceMs'>;
+
 interface ZustandState {
     entities: Map<string, Map<string, unknown>>;
     viewConfigs: Map<string, ViewSortConfig>;
@@ -226,47 +470,194 @@ declare class ZustandAdapter implements StorageAdapter {
     getViewConfig(viewPath: string): ViewSortConfig | undefined;
 }
 
-type ProgramMap = Record<string, ProgramSdkDefinition>;
-type ResolvedStack<TStack extends StackDefinition, TPrograms extends ProgramMap | undefined> = StackWithAttachedPrograms<TStack, TPrograms>;
+type ProgramMap$1 = Record<string, ProgramSdkDefinition>;
+type ResolvedStack<TStack extends StackDefinition, TPrograms extends ProgramMap$1 | undefined> = StackWithAttachedPrograms<TStack, TPrograms>;
 type StackQueries<TStack> = TStack extends {
     queries?: infer TQueries extends Record<string, StackQueryDefinition<unknown, unknown>> | undefined;
 } ? TQueries : undefined;
 type StackPrograms<TStack> = TStack extends {
     programs?: infer TPrograms extends Record<string, ProgramSdkDefinition> | undefined;
 } ? TPrograms : undefined;
-type ViewHookForDef<TDef> = TDef extends ViewDef<infer T, 'state'> ? {
-    use: <TSchema = T>(key?: Record<string, string>, options?: ViewHookOptions<TSchema>) => ViewHookResult<TSchema>;
+type ConnectedStack<TStack extends StackDefinition, TPrograms extends ProgramMap$1 | undefined> = ConnectedArete<ResolvedStack<TStack, TPrograms>>;
+type ConnectedField<TClient, TKey extends PropertyKey> = TKey extends keyof TClient ? TClient[TKey] : undefined;
+type ViewHookForDef<TDef> = TDef extends ViewDef<infer T, 'state', infer TKey> ? {
+    use: <TSchema = T>(key: TKey | null | undefined, options?: StateViewHookOptions<TSchema>) => ViewHookResult<TSchema>;
+    refresh: (key?: TKey | null) => Promise<void>;
 } : TDef extends ViewDef<infer T, 'list'> ? {
     use: {
-        <TSchema = T>(params: ListParamsSingle<TSchema>, options?: ViewHookOptions<TSchema>): ViewHookResult<TSchema | undefined>;
-        <TSchema = T>(params?: ListParamsMultiple<TSchema>, options?: ViewHookOptions<TSchema>): ViewHookResult<TSchema[]>;
+        <TSchema = T>(params: ListParamsSingle<TSchema>, options?: ListOneViewHookOptions<TSchema>): ViewHookResult<TSchema>;
+        <TSchema = T>(params?: ListParamsMultiple<TSchema>, options?: ListViewHookOptions<TSchema>): ViewHookResult<TSchema[]>;
     };
-    useOne: <TSchema = T>(params?: Omit<ListParamsBase<TSchema>, 'take'>, options?: ViewHookOptions<TSchema>) => ViewHookResult<TSchema | undefined>;
-} : TDef extends ViewDef<infer T, 'state' | 'list'> ? {
+    useOne: <TSchema = T>(params?: Omit<ListParamsBase<TSchema>, 'take'>, options?: ListOneViewHookOptions<TSchema>) => ViewHookResult<TSchema>;
+    refresh: () => Promise<void>;
+} : TDef extends ViewDef<infer T, 'state' | 'list', infer TKey> ? {
     use: {
-        <TSchema = T>(params: ListParamsSingle<TSchema>, options?: ViewHookOptions<TSchema>): ViewHookResult<TSchema | undefined>;
-        <TSchema = T>(params?: ListParamsMultiple<TSchema> | Record<string, string>, options?: ViewHookOptions<TSchema>): ViewHookResult<TSchema | TSchema[]>;
+        <TSchema = T>(params: ListParamsSingle<TSchema>, options?: ListOneViewHookOptions<TSchema>): ViewHookResult<TSchema>;
+        <TSchema = T>(params?: ListParamsMultiple<TSchema> | TKey, options?: ListViewHookOptions<TSchema> | StateViewHookOptions<TSchema>): ViewHookResult<TSchema | TSchema[]>;
     };
-    useOne: <TSchema = T>(params?: Omit<ListParamsBase<TSchema>, 'take'>, options?: ViewHookOptions<TSchema>) => ViewHookResult<TSchema | undefined>;
+    useOne: <TSchema = T>(params?: Omit<ListParamsBase<TSchema>, 'take'>, options?: ListOneViewHookOptions<TSchema>) => ViewHookResult<TSchema>;
+    refresh: (key?: TKey | null) => Promise<void>;
 } : never;
 type BuildViewInterface<TViews extends Record<string, ViewGroup>> = {
     [K in keyof TViews]: {
-        [SubK in keyof TViews[K] as TViews[K][SubK] extends ViewDef<unknown, ViewMode> ? SubK : never]: ViewHookForDef<TViews[K][SubK]>;
+        [SubK in keyof TViews[K] as TViews[K][SubK] extends ViewDef<any, ViewMode, any> ? SubK : never]: ViewHookForDef<TViews[K][SubK]>;
     };
 };
-type StackClient<TStack extends StackDefinition, TPrograms extends ProgramMap | undefined> = {
+type UseAreteResult<TStack extends StackDefinition, TPrograms extends ProgramMap$1 | undefined = undefined> = {
+    /**
+     * Typed subscription hooks, one per stack view. Keyed hooks only ever
+     * expose data for the key you passed — when the key changes, `data` is
+     * `undefined` (and `isLoading` true) until the new key's snapshot arrives,
+     * so callers never need to re-verify data against their inputs.
+     */
     views: BuildViewInterface<TStack['views']>;
     queries: QueriesInterface<StackQueries<ResolvedStack<TStack, TPrograms>>>;
-    programs: BuildProgramInterface<StackPrograms<ResolvedStack<TStack, TPrograms>>, ConnectedArete<ResolvedStack<TStack, TPrograms>>>;
-    chain: ChainClient;
-    zustandStore: UseBoundStore<StoreApi<AreteStore>>;
-    client: ConnectedArete<ResolvedStack<TStack, TPrograms>>;
+    programs: BuildProgramInterface<StackPrograms<ResolvedStack<TStack, TPrograms>>, ConnectedStack<TStack, TPrograms>>;
+    chain: ChainClient | null;
+    zustandStore: UseBoundStore<StoreApi<AreteStore>> | null;
+    client: ConnectedStack<TStack, TPrograms> | null;
+    read: ReactReadInterface<NonNullable<ConnectedField<StackConnectedExtensions<ResolvedStack<TStack, TPrograms>>, 'read'>>>;
+    /** @deprecated Hooks and imperative reads now share the `read` namespace. */
+    reads: ReactReadInterface<NonNullable<ConnectedField<StackConnectedExtensions<ResolvedStack<TStack, TPrograms>>, 'read'>>>;
+    addresses: ConnectedField<StackConnectedExtensions<ResolvedStack<TStack, TPrograms>>, 'addresses'>;
+    constants: ConnectedField<StackConnectedExtensions<ResolvedStack<TStack, TPrograms>>, 'constants'>;
+    defaults: ConnectedField<StackConnectedExtensions<ResolvedStack<TStack, TPrograms>>, 'defaults'>;
+    math: ConnectedField<StackConnectedExtensions<ResolvedStack<TStack, TPrograms>>, 'math'>;
+    /**
+     * Raw connection state reported by the client. Prefer {@link status},
+     * which also covers the initial client-creation window.
+     */
     connectionState: ConnectionState;
+    /**
+     * The single connection field UIs should read: 'connecting' while the
+     * client is being created or connecting, then the client's own state.
+     */
+    status: ConnectionState;
     isConnected: boolean;
     isLoading: boolean;
+    /** True when retry() can start a new shared connection attempt. */
+    canRetry: boolean;
     error: Error | null;
+    socketIssue: SocketIssue | null;
+    retry: () => Promise<void>;
+};
+/**
+ * Module-augmentation point for the default stack's type. When the provider
+ * declares a default stack (`<AreteProvider stack={...}>`), register its type
+ * once so argument-less `useArete()` calls are fully typed:
+ *
+ * ```ts
+ * declare module '@usearete/react' {
+ *   interface AreteDefaultStackRegistry { defaultStack: OreStreamStack }
+ * }
+ * ```
+ */
+interface AreteDefaultStackRegistry {
+}
+type RegisteredDefaultStack = AreteDefaultStackRegistry extends {
+    defaultStack: infer TStack extends StackDefinition;
+} ? TStack : StackDefinition;
+declare function useArete(stack?: undefined, options?: UseAreteOptions): UseAreteResult<RegisteredDefaultStack, undefined>;
+declare function useArete<TStack extends StackDefinition, TPrograms extends ProgramMap$1 | undefined = undefined>(stack: TStack, options?: UseAreteOptions<TPrograms>): UseAreteResult<TStack, TPrograms>;
+
+type ProgramMap = Record<string, ProgramSdkDefinition>;
+type BoundAreteProviderProps = Omit<AreteConfig, 'stack'> & {
+    children: ReactNode;
+};
+/**
+ * Bind the React SDK to one generated stack without ambient module
+ * augmentation. The returned hook remains explicit through an app-specific
+ * name such as `useOre`, while the generic provider and hook remain available
+ * for multi-stack applications.
+ */
+declare function createAreteReact<TStack extends StackDefinition>(stack: TStack): {
+    readonly Provider: ({ children, ...config }: BoundAreteProviderProps) => React.JSX.Element;
+    readonly useArete: <TPrograms extends ProgramMap | undefined = undefined>(options?: UseAreteOptions<TPrograms>) => UseAreteResult<TStack, TPrograms>;
+    readonly stack: TStack;
+};
+
+/**
+ * Minimal shape of a named status source: any view hook result, read hook
+ * result, or compatible object. Use `false`/`null`/`undefined` to exclude a
+ * source conditionally, e.g. `Miner: authority && miner`.
+ */
+type ViewStatusSource = {
+    isLoading: boolean;
+    isRefreshing?: boolean;
+    error?: Error | null;
+} | false | null | undefined;
+interface SummarizedViewStatus {
+    /** True while any included source is still loading. */
+    isLoading: boolean;
+    /** True when any included source has an error. */
+    hasError: boolean;
+    /** True while any included source is refreshing committed data. */
+    isRefreshing: boolean;
+    /** Names of sources still loading, in declaration order. */
+    loading: string[];
+    /** `"Name: message"` for each source error, in declaration order. */
+    errors: string[];
+    /** Names of sources refreshing committed data, in declaration order. */
+    refreshing: string[];
+}
+/**
+ * Aggregate the status of connection, view, and read hook results into loading,
+ * refreshing, and error lists. Pure function; call it during render.
+ *
+ * ```tsx
+ * const streams = summarizeStatuses({ Board: board, Round: round, Miner: authority && miner });
+ * {streams.loading.length > 0 && <p>Loading: {streams.loading.join(', ')}</p>}
+ * {streams.errors.length > 0 && <p role="alert">{streams.errors.join(' · ')}</p>}
+ * ```
+ */
+declare function summarizeStatuses(sources: Record<string, ViewStatusSource>): SummarizedViewStatus;
+/** @deprecated Use summarizeStatuses; it also accepts connection and read results. */
+declare const summarizeViews: typeof summarizeStatuses;
+type StatusSource = ViewStatusSource;
+type SummarizedStatus = SummarizedViewStatus;
+
+interface BalanceHookOptions<T> extends ContextSlotOptions, UseAsyncReadOptions<T> {
+}
+declare function useNativeBalance(chain: ChainClient | null | undefined, address: string | null | undefined, options?: BalanceHookOptions<NativeBalanceInfo>): UseAsyncReadResult<NativeBalanceInfo>;
+declare function useTokenBalance(chain: ChainClient | null | undefined, input: TokenBalanceInput | null | undefined, options?: BalanceHookOptions<TokenBalanceInfo>): UseAsyncReadResult<TokenBalanceInfo>;
+
+declare const DEFAULT_RECONCILIATION_TIMEOUT_MS = 30000;
+interface ProcessedSlotClient {
+    waitForProcessedSlot(slot: number | bigint, options?: WaitForProcessedSlotOptions): Promise<bigint>;
+}
+type ReconciliationRefresh = ReconciliationRefreshTarget;
+interface ProcessedSlotReconciliationOptions extends WaitForProcessedSlotOptions {
+    refresh?: ReconciliationRefresh | readonly ReconciliationRefresh[];
+}
+type ProcessedSlotReconciliationResult = {
+    readonly status: 'reconciled';
+    readonly confirmedSlot: bigint;
+    readonly processedSlot: bigint;
+} | {
+    readonly status: 'confirmed-unreconciled';
+    readonly confirmedSlot: bigint;
+    readonly error: Error;
 };
-declare function useArete<TStack extends StackDefinition, TPrograms extends ProgramMap | undefined = undefined>(stack: TStack, options?: UseAreteOptions<TPrograms>): StackClient<TStack, TPrograms>;
+declare function reconcileProcessedSlot(client: ProcessedSlotClient | null | undefined, slot: number | bigint, options?: ProcessedSlotReconciliationOptions): Promise<ProcessedSlotReconciliationResult>;
+declare function useReconcileProcessedSlot(client: ProcessedSlotClient | null | undefined): (slot: number | bigint, options?: ProcessedSlotReconciliationOptions) => Promise<ProcessedSlotReconciliationResult>;
+/**
+ * The default reconciliation injected into generated program mutation hooks.
+ * Marked so `useInstructionMutation` can resolve `reconcile: { ... }` override
+ * objects against it via {@link DefaultReconciliationFn.withOverrides}.
+ */
+interface DefaultReconciliationFn {
+    (context: MutationReconciliationContext<unknown, PreparedOperation>): Promise<ProcessedSlotReconciliationResult | undefined>;
+    readonly areteDefaultReconciliation: true;
+    readonly shouldReconcile: (context: MutationReconciliationContext<unknown, PreparedOperation>) => boolean;
+    readonly withOverrides: (overrides: MutationReconcileOverrides) => DefaultReconciliationFn;
+}
+/**
+ * Build the default reconciliation for generated program hooks: wait until the
+ * stream has processed the highest slot among completed transactions, then run
+ * any requested refreshes. Mutations without a reported slot (e.g. raw
+ * instruction sends) skip reconciliation silently.
+ */
+declare function createProcessedSlotReconciliation(client: ProcessedSlotClient | null | undefined, baseOverrides?: MutationReconcileOverrides): DefaultReconciliationFn;
 
-export { AreteProvider, ZustandAdapter, useArete, useAreteContext, useConnectionState, useEntity, useInstructionMutation, useView };
-export type { AreteConfig, AreteStore, ClientLookupOptions, ListParams, ListParamsBase, ListParamsMultiple, ListParamsSingle, ListViewHook, MutationStatus, StateViewHook, TransactionDefinition, UseAreteOptions, UseMutationOptions, UseMutationResult, UseMutationReturn, ViewHookOptions, ViewHookResult, ViewMode };
+export { AreteProvider, DEFAULT_RECONCILIATION_TIMEOUT_MS, ZustandAdapter, createAreteReact, createProcessedSlotReconciliation, reconcileProcessedSlot, summarizeStatuses, summarizeViews, useArete, useAreteContext, useAsyncRead, useConnectionState, useInstructionMutation, useNativeBalance, useReconcileProcessedSlot, useTokenBalance };
+export type { AreteConfig, AreteDefaultStackRegistry, AreteStore, AsyncReadContext, AsyncReadKey, AsyncReadStatus, BalanceHookOptions, BoundAreteProviderProps, ClientLookupOptions, DefaultReconciliationFn, ListOneViewHookOptions, ListParams, ListParamsBase, ListParamsMultiple, ListParamsSingle, ListViewHook, ListViewHookOptions, MutationExecutionObserver, MutationExecutor, MutationLifecycleEvent, MutationPhase, MutationReconcileFn, MutationReconcileOverrides, MutationReconciliationContext, MutationStatus, ProcessedSlotClient, ProcessedSlotReconciliationOptions, ProcessedSlotReconciliationResult, ReactReadInterface, ReadHookInterface, ReadHookOptions, ReconciliationRefresh, ReconciliationRefreshTarget, StateViewHook, StateViewHookOptions, StatusSource, SummarizedStatus, SummarizedViewStatus, TransactionDefinition, UseAreteOptions, UseAreteResult, UseAsyncReadOptions, UseAsyncReadResult, UseMutationOptions, UseMutationResult, UseMutationReturn, ViewHookOptions, ViewHookResult, ViewMode, ViewSchemaValidationDiagnostic, ViewSchemaValidationErrorCallback, ViewStatus, ViewStatusSource };