@usearete/react 0.46.0 → 0.47.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import React, { ReactNode } from 'react';
-import { StackDefinition, WalletAdapter, ConnectOptions, AuthConfig, AreteError, 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, ProtocolTypeMap, ProtocolClient, ProtocolKeyClass, ProtocolInstanceDetail, ProtocolStepAvailabilityFor, ProtocolWalletActions, ProtocolParticipantDetail, ProtocolStreamEvent, 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 { StackDefinition, WalletAdapter, ConnectOptions, AuthConfig, AreteError, Schema, ProgramSdkDefinition, ConnectionState, ConnectedArete, StackWithAttachedPrograms, Session, SessionDefinition, CompositionSessionOptions, SessionOptions, PreparedOperation, TransactionFailureOutcome, OperationExecutionEvent, OperationExecutionSuccessEvent, OperationTransactionReceipt, TransactionOutcome, ProgramInterface, TypedInstruction, OperationReceiptFor, StorageAdapter, StorageAdapterConfig, UpdateCallback, RichUpdateCallback, Update, RichUpdate, ViewSortConfig, QueriesInterface, ChainClient, StackConnectedExtensions, SocketIssue, StackQueryDefinition, ViewGroup, ViewDef, OperationExecutionOptions, SendOptions, ProgramError, PlatformHttpClient, ContextSlotOptions, NativeBalanceInfo, TokenBalanceInput, TokenBalanceInfo, ProtocolTypeMap, ProtocolClient, ProtocolKeyClass, ProtocolInstanceDetail, ProtocolStepAvailabilityFor, ProtocolWalletActions, ProtocolParticipantDetail, ProtocolStreamEvent, WaitForProcessedSlotOptions } from '@usearete/sdk';
+export { AccountCategory, AccountMeta, AccountResolutionOptions, AccountResolutionResult, Arete, AreteError, AreteOptions, AreteOptionsWithStorage, ArgSchema, ArgType, AuthConfig, AuthTokenRequest, 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, PlatformHttpClient, PlatformHttpRequest, PlatformHttpResponse, PreparedFlow, PreparedInstruction, PreparedOperation, PreparedTransaction, PreparedTransactionInstruction, ProcessedSlotTimeoutError, ProgramError, QueryLease, QuerySnapshot, QueryStore, ReadRequestError, ResolvedAccount, ResolvedAccounts, RichUpdate, RichUpdateCallback, Schema, SendOptions, SendResult, Session, SessionDefinition, SessionOptions, 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, createPlatformHttpClient, 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';
@@ -62,7 +62,15 @@ interface AreteConfig {
      * holds no entity for (`reason: 'unknown-key'`).
      */
     onFrameValidationError?: ConnectOptions['onFrameValidationError'];
-    /** Authentication configuration */
+    /**
+     * Authentication configuration. An app whose users sign in to Arete (a
+     * dashboard) passes their login as an API credential:
+     * `{ tokenKind: 'api', tokenEndpoint: '/api/arete-token' }` or
+     * `{ tokenKind: 'api', getToken }`. Stack, gateway and program read
+     * connections then mint their sessions with it, and
+     * `usePlatformHttpClient()` calls the Arete API with it. A changed `auth`
+     * applies to clients created afterwards; call `retry()` to reconnect one.
+     */
     auth?: AuthConfig;
 }
 /**
@@ -244,6 +252,128 @@ declare function AreteProvider({ children, ...config }: AreteConfig & {
 declare function useAreteContext(): AreteContextValue;
 declare function useConnectionState(stack?: StackDefinition, options?: ClientLookupOptions): ConnectionState;
 
+/** Any session from `createSession`. */
+type AnySession = Session<any, any, any>;
+/**
+ * The session type for `T`: a session type as it is, or the session
+ * `createSession(definition)` opens for a definition type.
+ */
+type SessionOf<T> = T extends AnySession ? T : T extends SessionDefinition ? Session<T> : never;
+/**
+ * Options for the session the provider opens: `createSession`'s options
+ * without `wallet` (the provider's `wallet` prop sets it, without reopening).
+ */
+type AreteSessionOptions<TDef extends SessionDefinition = SessionDefinition> = Omit<TDef extends {
+    readonly mode: 'composition';
+} ? CompositionSessionOptions<TDef> : SessionOptions<TDef>, 'wallet'>;
+/**
+ * - `opening`: the session is being opened (or, for a provider given a
+ *   `session`, none has been given yet).
+ * - `open`: `session` is ready.
+ * - `error`: opening failed; `error` says why and `retry()` tries again.
+ */
+type AreteSessionStatus = 'opening' | 'open' | 'error';
+interface UseAreteSessionResult<TSession extends AnySession = AnySession> {
+    /** The open session; `null` while it opens, after a failure, and while it is reopened. */
+    readonly session: TSession | null;
+    readonly status: AreteSessionStatus;
+    /** Why the session could not be opened. */
+    readonly error: Error | null;
+    /**
+     * The session once it is open. Waits through a reopen (new auth or
+     * options) and resolves with the new session; rejects when opening fails,
+     * and with an {@link AreteSessionUnavailableError} when the provider is
+     * unmounted first.
+     * Stable, so it can be a `useOperationMutation` executor:
+     * `{ executor: ready }`.
+     */
+    ready(): Promise<TSession>;
+    /** Open the session again after a failure. Only for sessions the provider opens. */
+    retry(): void;
+}
+interface SessionProviderBaseProps {
+    children: ReactNode;
+    /**
+     * The wallet the session signs with (`session.wallet`). Changing it calls
+     * `session.setWallet`; the session is not reopened.
+     */
+    wallet?: WalletAdapter;
+}
+/** The provider opens (and closes) the session. */
+interface OwnedAreteSessionProviderProps<TDef extends SessionDefinition> extends SessionProviderBaseProps {
+    /** What to open, as for `createSession(definition, options)`. */
+    definition: TDef;
+    /**
+     * `createSession` options. `auth` and `fetch` default to the enclosing
+     * `AreteProvider`'s. A change reopens the session (see the README).
+     */
+    options?: AreteSessionOptions<TDef>;
+    session?: never;
+}
+/** The app opened the session; the provider shares it and never closes it. */
+interface ExternalAreteSessionProviderProps extends SessionProviderBaseProps {
+    /** The session to share; `null`/`undefined` while the app is still opening it. */
+    session: AnySession | null | undefined;
+    definition?: never;
+    options?: never;
+}
+type AreteSessionProviderProps<TDef extends SessionDefinition = SessionDefinition> = OwnedAreteSessionProviderProps<TDef> | ExternalAreteSessionProviderProps;
+/**
+ * `ready()` rejects with this when its `AreteSessionProvider` was removed
+ * before the session opened (or is called after the provider is gone): no
+ * session will come. `code` is `provider_unmounted`.
+ */
+declare class AreteSessionUnavailableError extends Error {
+    readonly code: "provider_unmounted";
+    constructor(message?: string);
+}
+/** Whether `error` is an {@link AreteSessionUnavailableError}. */
+declare function isAreteSessionUnavailableError(error: unknown): error is AreteSessionUnavailableError;
+/**
+ * One Arete session (`createSession`) for everything below it, read with
+ * {@link useAreteSession}.
+ *
+ * ```tsx
+ * const SQUADS = { programs: { squads: SQUADS_V4_PROGRAM } };
+ * const auth = { tokenKind: 'api', tokenEndpoint: '/api/arete-token' } as const;
+ *
+ * <AreteSessionProvider definition={SQUADS} options={{ auth }} wallet={wallet}>
+ *   <App />
+ * </AreteSessionProvider>;
+ *
+ * // below it
+ * const { session } = useAreteSession<typeof SQUADS>();
+ * session?.programs.squads; // typed
+ * ```
+ *
+ * Given `definition`, the provider opens the session when it mounts and
+ * closes it when it unmounts. `options.auth` and `options.fetch` default to
+ * the enclosing `AreteProvider`'s. When the definition or the options
+ * change, the old session is closed at once and a new one is opened:
+ * `session` is `null` until it is ready, so nothing runs against a session
+ * opened with credentials that no longer apply. Options are compared by
+ * shape two levels deep (an inline `auth` object with the same fields is the
+ * same auth); functions such as `getToken` or `fetch` compare by identity,
+ * so keep them stable. The wallet never reopens the session: changing
+ * `wallet` calls `session.setWallet`.
+ *
+ * Given `session`, the provider only shares it: the app opened it and closes
+ * it. `wallet`, when passed, is set on it the same way.
+ */
+declare function AreteSessionProvider<TDef extends SessionDefinition>(props: AreteSessionProviderProps<TDef>): React.ReactElement;
+/**
+ * The nearest {@link AreteSessionProvider}'s session. Pass the definition
+ * (or the session type) for typed members:
+ *
+ * ```tsx
+ * const { session, status, ready } = useAreteSession<typeof SQUADS>();
+ * const squads = session?.programs.squads;
+ * ```
+ *
+ * Throws outside an `AreteSessionProvider`.
+ */
+declare function useAreteSession<T extends SessionDefinition | AnySession = AnySession>(): UseAreteSessionResult<SessionOf<T>>;
+
 type MutationStatus = 'idle' | 'pending' | 'success' | 'error';
 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> {
@@ -483,6 +613,7 @@ declare class ZustandAdapter implements StorageAdapter {
     getViewConfig(viewPath: string): ViewSortConfig | undefined;
 }
 
+type AnyClient = ConnectedArete<StackDefinition>;
 type ProgramMap$1 = Record<string, ProgramSdkDefinition>;
 type ResolvedStack<TStack extends StackDefinition, TPrograms extends ProgramMap$1 | undefined> = StackWithAttachedPrograms<TStack, TPrograms>;
 type StackQueries<TStack> = TStack extends {
@@ -554,6 +685,55 @@ type UseAreteResult<TStack extends StackDefinition, TPrograms extends ProgramMap
     socketIssue: SocketIssue | null;
     retry: () => Promise<void>;
 };
+/**
+ * A connected stack client: a session member (`session.stacks.<key>` from
+ * `createSession`) or a client from `Arete.connect`.
+ */
+type AnyStackClient = Pick<AnyClient, 'getSubscriptionRegistry' | 'onConnectionStateChange' | 'onSocketIssue' | 'connectionState'>;
+/** The stack a connected client was connected for (with its attached programs). */
+type StackOfClient<TClient> = NonNullable<TClient> extends ConnectedArete<infer TStack extends StackDefinition, infer _TExtensions> ? TStack : never;
+/**
+ * The definition of a member's stack, for `useArete(member, { stack })`: any
+ * stack definition with the member's views (the generated stack, before or
+ * after `programs` are attached).
+ */
+type MemberStackDefinition<TStack extends StackDefinition> = StackDefinition & Pick<TStack, 'views'>;
+/** Options for `useArete(member)`, where `member` is a client someone else connected. */
+interface UseAreteMemberOptions<TStack extends StackDefinition = StackDefinition> {
+    /**
+     * The member's stack definition. Required while the member can be `null` or
+     * `undefined` (the session is still opening), so views, programs,
+     * addresses and constants exist before it opens; once it has opened, the
+     * member's own `stack` is used.
+     */
+    stack?: MemberStackDefinition<TStack>;
+    /**
+     * Programs the session attached to this member (its member options'
+     * `programs`), for the placeholders while the session opens: their
+     * addresses, PDAs and constants work before it opens, as with
+     * `useArete(stack, { programs })`. Once it has opened, the member's own
+     * programs are used. TypeScript asks for every attached program `stack`
+     * does not already have.
+     */
+    programs?: ProgramMap$1;
+}
+type ProgramKeysOf<TStack> = TStack extends {
+    programs?: infer TPrograms;
+} ? TPrograms extends object ? keyof TPrograms & string : never : never;
+/**
+ * Options for `useArete(member, options)` while the member may be missing:
+ * the placeholder `stack`, plus `programs` for each program the member has
+ * (one attached through the session's member options) that `stack` lacks.
+ */
+type UseAreteMemberPlaceholderOptions<TStack extends StackDefinition, TPlaceholder extends MemberStackDefinition<TStack>> = {
+    stack: TPlaceholder;
+} & ([
+    Exclude<ProgramKeysOf<TStack>, ProgramKeysOf<TPlaceholder>>
+] extends [never] ? {
+    programs?: ProgramMap$1;
+} : {
+    programs: ProgramMap$1 & Record<Exclude<ProgramKeysOf<TStack>, ProgramKeysOf<TPlaceholder>>, ProgramSdkDefinition>;
+});
 /**
  * Module-augmentation point for the default stack's type. When the provider
  * declares a default stack (`<AreteProvider stack={...}>`), register its type
@@ -572,6 +752,30 @@ type RegisteredDefaultStack = AreteDefaultStackRegistry extends {
 } ? 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>;
+/**
+ * The hooks for a stack client that is already connected, typically a
+ * session member: `useArete(session.stacks.ore)`. The hooks read the
+ * member's own connection and store, so nothing connects again, and the
+ * member's owner (the session) disconnects it; unmounting never does.
+ * Mutations sign with the member's wallet, which `session.setWallet` (or
+ * `AreteSessionProvider`'s `wallet`) sets.
+ *
+ * While the session opens, pass the member as it may be (`null` or
+ * `undefined`) together with its stack definition, and the result is the
+ * connecting state `useArete(stack)` reports before its client exists:
+ *
+ * ```tsx
+ * const { session } = useAreteSession<typeof APP>();
+ * const ore = useArete(session?.stacks.ore, { stack: APP.stacks.ore });
+ * ```
+ *
+ * A member the session attached programs to (`createSession(APP, { stacks:
+ * { ore: { programs: { memo } } } })`) also takes them, so their helpers work
+ * while it opens: `useArete(session?.stacks.ore, { stack: APP.stacks.ore,
+ * programs: { memo } })`. TypeScript asks for any it is missing.
+ */
+declare function useArete<TClient extends AnyStackClient>(member: TClient, options?: UseAreteMemberOptions<StackOfClient<TClient>>): UseAreteResult<StackOfClient<TClient>>;
+declare function useArete<TClient extends AnyStackClient, TPlaceholder extends MemberStackDefinition<StackOfClient<TClient>>>(member: TClient | null | undefined, options: UseAreteMemberPlaceholderOptions<StackOfClient<TClient>, TPlaceholder>): UseAreteResult<StackOfClient<TClient>>;
 
 type ProgramMap = Record<string, ProgramSdkDefinition>;
 type BoundAreteProviderProps = Omit<AreteConfig, 'stack'> & {
@@ -629,6 +833,220 @@ declare const summarizeViews: typeof summarizeStatuses;
 type StatusSource = ViewStatusSource;
 type SummarizedStatus = SummarizedViewStatus;
 
+/**
+ * Where an operation run is:
+ *
+ * - `idle`: nothing has run (or `reset()` was called).
+ * - `preparing`: `prepare` is building the operation.
+ * - `signing`: a transaction is waiting for its signatures, which for a
+ *   browser wallet means its approval prompt is open ("check your wallet").
+ * - `sending`: signed; the transaction is being submitted.
+ * - `confirming`: submitted; waiting for the commitment.
+ * - `done`: every transaction of the operation confirmed; `result` is set.
+ * - `error`: the run failed; `error` says how.
+ *
+ * `sending` and `confirming` are reported by wallets that publish their
+ * activity (the `@usearete/adapter-kit` adapters do, through `onActivity`).
+ * With any other wallet a transaction stays `signing` until it confirms.
+ * A flow walks `signing` → `sending` → `confirming` once per transaction.
+ */
+type OperationMutationStatus = 'idle' | 'preparing' | 'signing' | 'sending' | 'confirming' | 'done' | 'error';
+/** Something that executes a prepared operation: a connected client or a session. */
+interface OperationExecutor {
+    execute<TPrepared extends PreparedOperation, TSigner = unknown>(prepared: TPrepared, options?: OperationExecutionOptions<TSigner, TPrepared>): Promise<OperationReceiptFor<TPrepared>>;
+}
+/**
+ * The executor, or a function that resolves it when a run starts (for
+ * example a session opened on first use). `null` while it is not available
+ * yet: a run then fails with `not-ready`. Omitted (or `undefined`), the hook
+ * uses the nearest `AreteSessionProvider`'s session, waiting for it to open.
+ */
+type OperationExecutorSource = OperationExecutor | (() => OperationExecutor | Promise<OperationExecutor>) | null | undefined;
+/** A prepared operation with signers made while preparing it (a create key). */
+interface PreparedOperationWithSigners<TPrepared extends PreparedOperation> {
+    readonly operation: TPrepared;
+    readonly signers?: readonly unknown[];
+}
+/** Builds the operation for one run, e.g. `(input) => program.flows.x.y.prepare(input)`. */
+type OperationPrepareFn<TInput, TPrepared extends PreparedOperation> = (input: TInput) => TPrepared | PreparedOperationWithSigners<TPrepared> | Promise<TPrepared | PreparedOperationWithSigners<TPrepared>>;
+/** Per-run settings; each also has a hook-level default. */
+interface OperationRunOptions {
+    /**
+     * The wallet that signs. Without one the run fails with `not-ready` and
+     * nothing is prepared or signed, unless the hook sets
+     * `allowExecutorWallet`.
+     */
+    readonly wallet?: WalletAdapter;
+    /** Extra local signers for this run, added to the hook's and `prepare`'s. */
+    readonly signers?: readonly unknown[];
+    /** Send options forwarded to the wallet (transaction version, resources). */
+    readonly send?: SendOptions;
+}
+interface UseOperationMutationOptions<TPrepared extends PreparedOperation> extends OperationRunOptions {
+    /** What runs the operation; defaults to the nearest `AreteSessionProvider`'s session. */
+    readonly executor?: OperationExecutorSource;
+    /**
+     * Sign with the executor's own wallet (`session.wallet`, the client's
+     * wallet) when neither the run nor the hook names one. Off by default, so
+     * a run never signs with a wallet the component did not pass.
+     */
+    readonly allowExecutorWallet?: boolean;
+    readonly onSuccess?: (result: OperationReceiptFor<TPrepared>, prepared: TPrepared) => void | Promise<void>;
+    readonly onError?: (error: OperationMutationError<TPrepared>) => void | Promise<void>;
+    /**
+     * Called on every status change of a run, as it happens (React may batch
+     * the re-renders of quick changes, this callback never skips one).
+     * `transactionIndex` is the transaction of the operation it is about.
+     */
+    readonly onStatusChange?: (status: OperationMutationStatus, context: {
+        readonly transactionIndex: number | null;
+    }) => void;
+}
+/**
+ * How a run failed:
+ *
+ * - `busy`: a run of this hook is already in progress; nothing was started.
+ * - `not-ready`: no executor, or no wallet, to run with; nothing was
+ *   prepared or signed.
+ * - `prepare-failed`: `prepare` threw; nothing was signed.
+ * - `wallet-rejected`: the user declined (or closed) the wallet prompt.
+ * - `wallet-feature-unsupported`: the wallet cannot sign without sending
+ *   (it lacks `solana:signTransaction`), so Arete cannot relay for it.
+ * - `wallet-chain-unsupported`: the wallet (or the account) does not sign
+ *   for the chain it was asked to.
+ * - `wallet-version-unsupported`: the wallet signs, but not this
+ *   transaction version (a v0-only wallet and a V1 transaction).
+ * - `wallet-modified`: the wallet changed the transaction it was asked to
+ *   sign (for example to add a priority fee), so it was not sent.
+ * - `not-submitted`: failed before anything reached the chain.
+ * - `submitted-unknown`: sent, but its confirmation did not arrive; check
+ *   the chain before trying again.
+ * - `chain-failed`: the transaction failed on chain; see `programError`.
+ */
+type OperationMutationErrorKind = 'busy' | 'not-ready' | 'prepare-failed' | 'wallet-rejected' | 'wallet-feature-unsupported' | 'wallet-chain-unsupported' | 'wallet-version-unsupported' | 'wallet-modified' | 'not-submitted' | 'submitted-unknown' | 'chain-failed';
+/** The typed failure of a {@link useOperationMutation} run. */
+declare class OperationMutationError<TPrepared extends PreparedOperation = PreparedOperation> extends Error {
+    readonly kind: OperationMutationErrorKind;
+    /** The transaction outcome, when the failure happened at or after signing. */
+    readonly failure: TransactionFailureOutcome | null;
+    /** The operation that was running, once prepared. */
+    readonly prepared: TPrepared | null;
+    /** Signatures of the transactions that confirmed before the failure. */
+    readonly completedSignatures: readonly string[];
+    /** The failing transaction's signature, when it was signed. */
+    readonly signature?: string;
+    readonly programError?: ProgramError;
+    readonly cause: unknown;
+    constructor(input: {
+        kind: OperationMutationErrorKind;
+        message: string;
+        cause: unknown;
+        failure?: TransactionFailureOutcome | null;
+        prepared?: TPrepared | null;
+        completedSignatures?: readonly string[];
+    });
+}
+/**
+ * Whether `error` (or anything in its `cause` chain) is a wallet prompt the
+ * user declined or closed. Wallets report this in a few ways: EIP-1193 code
+ * 4001 (Phantom, Solflare), a `...RejectedError`, or the message.
+ */
+declare function isWalletRejection(error: unknown): boolean;
+/**
+ * Classify an execution failure. Exported so code outside the hook (an
+ * imperative `session.execute`) can show the same messages.
+ */
+declare function toOperationMutationError<TPrepared extends PreparedOperation = PreparedOperation>(error: unknown, prepared?: TPrepared | null, completedSignatures?: readonly string[]): OperationMutationError<TPrepared>;
+interface UseOperationMutationResult<TInput, TPrepared extends PreparedOperation> {
+    /** Run the operation; rejects with an {@link OperationMutationError}. */
+    run(input: TInput, options?: OperationRunOptions): Promise<OperationReceiptFor<TPrepared>>;
+    /** Event-handler form of `run`: the failure is kept in `error`, never thrown. */
+    mutate(input: TInput, options?: OperationRunOptions): void;
+    readonly status: OperationMutationStatus;
+    /**
+     * `preparing`, `signing`, `sending` or `confirming`. Exactly when it is
+     * true, `run()` is refused with `busy`: once `status` is `done` or `error`
+     * the hook takes a new run, even while `onSuccess`/`onError` are pending.
+     */
+    readonly isBusy: boolean;
+    /** The wallet is waiting for the user: show "check your wallet". */
+    readonly isAwaitingWallet: boolean;
+    /** The operation of the latest run, once prepared. */
+    readonly prepared: TPrepared | null;
+    /** The prepared operation's artifacts (derived addresses and the like). */
+    readonly artifacts: TPrepared['artifacts'] | undefined;
+    /** The receipt of the latest successful run. */
+    readonly result: OperationReceiptFor<TPrepared> | undefined;
+    readonly error: OperationMutationError<TPrepared> | null;
+    /** Signatures of the transactions confirmed so far in the latest run. */
+    readonly signatures: readonly string[];
+    /** Which of `transactionCount` transactions is in progress (0-based). */
+    readonly transactionIndex: number | null;
+    readonly transactionCount: number | null;
+    reset(): void;
+}
+/**
+ * Run a prepared instruction, transaction or flow with a wallet and report
+ * where it is: idle → preparing → signing → sending → confirming → done (or
+ * error). Works with anything that has `execute(prepared, options)`, a
+ * connected client or a session, so it needs no stack:
+ *
+ * ```tsx
+ * const createMultisig = useOperationMutation(
+ *   async (input: CreateInput) => {
+ *     const createKey = await generateKeyPairSigner();
+ *     return {
+ *       operation: await squads.flows.arete.createMultisig.prepare({ ...input, createKey: createKey.address }),
+ *       signers: [createKey],
+ *     };
+ *   },
+ *   { executor: session, wallet },
+ * );
+ * // Inside an AreteSessionProvider, `executor` can be left out.
+ * // createMultisig.mutate(input); createMultisig.isAwaitingWallet → "Approve in your wallet"
+ * ```
+ *
+ * Signers returned by `prepare`, given to the hook and given to the run are
+ * all passed to `execute`. A run without a wallet fails with `not-ready`
+ * before `prepare` is called; set `allowExecutorWallet` to sign with the
+ * executor's own wallet instead. A second run while one is in progress rejects
+ * with `busy` and leaves the first alone, so a double click never opens two
+ * wallet prompts. "In progress" is exactly `isBusy`: a run ends when its
+ * `done` or `error` status is published, before `onSuccess`/`onError` are
+ * awaited, so a button disabled by `isBusy` is never enabled while `run()`
+ * would refuse it. A run started during those callbacks is a new run; the
+ * earlier run's `run()` promise still settles after its callback.
+ */
+declare function useOperationMutation<TInput, TPrepared extends PreparedOperation>(prepare: OperationPrepareFn<TInput, TPrepared>, options: UseOperationMutationOptions<TPrepared>): UseOperationMutationResult<TInput, TPrepared>;
+
+interface UsePlatformHttpClientOptions {
+    /** API origin, with or without `/api`. Defaults to `https://api.arete.run`. */
+    readonly apiUrl?: string;
+    /** Defaults to the provider's `auth`. */
+    readonly auth?: AuthConfig;
+}
+/**
+ * A client for the Arete API's account routes, authenticated with the
+ * provider's `auth` (and `fetch`). With `auth.tokenKind: 'api'`, the same
+ * credential the provider mints its stack and gateway sessions with, so one
+ * login drives both:
+ *
+ * ```tsx
+ * <AreteProvider auth={{ tokenKind: 'api', tokenEndpoint: '/api/arete-token' }}>
+ *   …
+ * </AreteProvider>
+ * // in a component
+ * const http = usePlatformHttpClient({ apiUrl });
+ * const squads = useMemo(() => createSquadsClient({ http }), [http]);
+ * ```
+ *
+ * The client is stable while `apiUrl`, `auth` and `fetch` keep their
+ * identity, so pass a memoized (or module-level) `auth` object. Throws
+ * during render when the auth carries no API credential, like
+ * `createPlatformHttpClient`.
+ */
+declare function usePlatformHttpClient(options?: UsePlatformHttpClientOptions): PlatformHttpClient;
+
 interface BalanceHookOptions<T> extends ContextSlotOptions, UseAsyncReadOptions<T> {
 }
 declare function useNativeBalance(chain: ChainClient | null | undefined, address: string | null | undefined, options?: BalanceHookOptions<NativeBalanceInfo>): UseAsyncReadResult<NativeBalanceInfo>;
@@ -744,5 +1162,5 @@ interface DefaultReconciliationFn {
  */
 declare function createProcessedSlotReconciliation(client: ProcessedSlotClient | null | undefined, baseOverrides?: MutationReconcileOverrides): DefaultReconciliationFn;
 
-export { AreteProvider, DEFAULT_RECONCILIATION_TIMEOUT_MS, ZustandAdapter, createAreteReact, createProcessedSlotReconciliation, reconcileProcessedSlot, summarizeStatuses, summarizeViews, useAllowedSteps, useArete, useAreteContext, useAsyncRead, useConnectionState, useInstructionMutation, useNativeBalance, useProtocolEvents, useProtocolInstance, useProtocolParticipant, useReconcileProcessedSlot, useTokenBalance, useWalletActions };
-export type { AnyProtocolClient, 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, UseProtocolEventsOptions, UseProtocolInstanceOptions, UseProtocolInstanceResult, UseProtocolStepsOptions, UseWalletActionsInput, ViewHookOptions, ViewHookResult, ViewMode, ViewSchemaValidationDiagnostic, ViewSchemaValidationErrorCallback, ViewStatus, ViewStatusSource };
+export { AreteProvider, AreteSessionProvider, AreteSessionUnavailableError, DEFAULT_RECONCILIATION_TIMEOUT_MS, OperationMutationError, ZustandAdapter, createAreteReact, createProcessedSlotReconciliation, isAreteSessionUnavailableError, isWalletRejection, reconcileProcessedSlot, summarizeStatuses, summarizeViews, toOperationMutationError, useAllowedSteps, useArete, useAreteContext, useAreteSession, useAsyncRead, useConnectionState, useInstructionMutation, useNativeBalance, useOperationMutation, usePlatformHttpClient, useProtocolEvents, useProtocolInstance, useProtocolParticipant, useReconcileProcessedSlot, useTokenBalance, useWalletActions };
+export type { AnyProtocolClient, AnySession, AnyStackClient, AreteConfig, AreteDefaultStackRegistry, AreteSessionOptions, AreteSessionProviderProps, AreteSessionStatus, AreteStore, AsyncReadContext, AsyncReadKey, AsyncReadStatus, BalanceHookOptions, BoundAreteProviderProps, ClientLookupOptions, DefaultReconciliationFn, ExternalAreteSessionProviderProps, ListOneViewHookOptions, ListParams, ListParamsBase, ListParamsMultiple, ListParamsSingle, ListViewHook, ListViewHookOptions, MemberStackDefinition, MutationExecutionObserver, MutationExecutor, MutationLifecycleEvent, MutationPhase, MutationReconcileFn, MutationReconcileOverrides, MutationReconciliationContext, MutationStatus, OperationExecutor, OperationExecutorSource, OperationMutationErrorKind, OperationMutationStatus, OperationPrepareFn, OperationRunOptions, OwnedAreteSessionProviderProps, PreparedOperationWithSigners, ProcessedSlotClient, ProcessedSlotReconciliationOptions, ProcessedSlotReconciliationResult, ReactReadInterface, ReadHookInterface, ReadHookOptions, ReconciliationRefresh, ReconciliationRefreshTarget, SessionOf, StackOfClient, StateViewHook, StateViewHookOptions, StatusSource, SummarizedStatus, SummarizedViewStatus, TransactionDefinition, UseAreteMemberOptions, UseAreteMemberPlaceholderOptions, UseAreteOptions, UseAreteResult, UseAreteSessionResult, UseAsyncReadOptions, UseAsyncReadResult, UseMutationOptions, UseMutationResult, UseMutationReturn, UseOperationMutationOptions, UseOperationMutationResult, UsePlatformHttpClientOptions, UseProtocolEventsOptions, UseProtocolInstanceOptions, UseProtocolInstanceResult, UseProtocolStepsOptions, UseWalletActionsInput, ViewHookOptions, ViewHookResult, ViewMode, ViewSchemaValidationDiagnostic, ViewSchemaValidationErrorCallback, ViewStatus, ViewStatusSource };