@usearete/react 0.46.0 → 0.47.0

package/dist/index.esm.js

@@ -1,6 +1,6 @@
-import React, { createContext, useRef, useCallback, useEffect, useContext, useState, useSyncExternalStore, useMemo } from 'react';
-import { Arete, getTransactionFailureOutcome, OperationExecutionError, unwrapOperationExecutionError, InstructionError, compareProgramIdentity, serializeViewKey, canonicalQueryKey, AreteError, getStackRuntimeExtensions } from '@usearete/sdk';
-export { Arete, AreteError, ConnectionManager, DEFAULT_CONFIG, DEFAULT_MAX_ENTRIES_PER_VIEW, FrameProcessor, InstructionError, MemoryAdapter, OperationCallbackError, OperationExecutionError, ProcessedSlotTimeoutError, QueryStore, ReadRequestError, SubscriptionRegistry, TransactionExecutionError, 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 React, { createContext, useRef, useCallback, useEffect, useContext, useState, useMemo, useSyncExternalStore } from 'react';
+import { Arete, createSession, getTransactionFailureOutcome, OperationExecutionError, unwrapOperationExecutionError, InstructionError, compareProgramIdentity, serializeViewKey, canonicalQueryKey, AreteError, getStackRuntimeExtensions, createPlatformHttpClient } from '@usearete/sdk';
+export { Arete, AreteError, ConnectionManager, DEFAULT_CONFIG, DEFAULT_MAX_ENTRIES_PER_VIEW, FrameProcessor, InstructionError, MemoryAdapter, OperationCallbackError, OperationExecutionError, ProcessedSlotTimeoutError, QueryStore, ReadRequestError, SubscriptionRegistry, TransactionExecutionError, 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 { create } from 'zustand';
 
 const DEFAULT_FLUSH_INTERVAL_MS = 16;
@@ -379,6 +379,10 @@ function AreteProvider({ children, ...config }) {
     };
     return (React.createElement(AreteContext.Provider, { value: value }, children));
 }
+/** The enclosing `AreteProvider`'s context, or `null` outside one. */
+function useOptionalAreteContext() {
+    return useContext(AreteContext);
+}
 function useAreteContext() {
     const context = useContext(AreteContext);
     if (!context) {
@@ -421,6 +425,276 @@ function useConnectionState(stack, options) {
     return state;
 }
 
+const AreteSessionContext = createContext(null);
+/**
+ * `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`.
+ */
+class AreteSessionUnavailableError extends Error {
+    constructor(message = 'The AreteSessionProvider was unmounted before its session opened') {
+        super(message);
+        this.code = 'provider_unmounted';
+        this.name = 'AreteSessionUnavailableError';
+    }
+}
+/** Whether `error` is an {@link AreteSessionUnavailableError}. */
+function isAreteSessionUnavailableError(error) {
+    return error instanceof AreteSessionUnavailableError;
+}
+function createDeferred() {
+    let resolvePromise;
+    let rejectPromise;
+    const promise = new Promise((resolve, reject) => {
+        resolvePromise = resolve;
+        rejectPromise = reject;
+    });
+    // A failure nobody awaited is reported through `status`, not as an
+    // unhandled rejection.
+    promise.catch(() => undefined);
+    const deferred = {
+        promise,
+        settled: false,
+        resolve(value) {
+            if (deferred.settled)
+                return;
+            deferred.settled = true;
+            resolvePromise(value);
+        },
+        reject(error) {
+            if (deferred.settled)
+                return;
+            deferred.settled = true;
+            rejectPromise(error);
+        },
+    };
+    return deferred;
+}
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+/**
+ * Equal by identity, or plain objects with the same keys whose values are
+ * equal to `depth` levels. Arrays, functions and class instances compare by
+ * identity.
+ */
+function sameShape(left, right, depth) {
+    if (Object.is(left, right))
+        return true;
+    if (depth === 0 || !isPlainObject(left) || !isPlainObject(right))
+        return false;
+    const leftKeys = Object.keys(left).filter((key) => left[key] !== undefined);
+    const rightKeys = Object.keys(right).filter((key) => right[key] !== undefined);
+    return leftKeys.length === rightKeys.length
+        && leftKeys.every((key) => Object.prototype.hasOwnProperty.call(right, key) && sameShape(left[key], right[key], depth - 1));
+}
+/**
+ * `value`, or the previous one while it has the same shape: two levels of
+ * plain objects, so `options={{ apiUrl, auth: { tokenKind: 'api', … } }}`
+ * written inline does not reopen the session on every render.
+ */
+function useSameShape(value) {
+    const ref = useRef(value);
+    if (!sameShape(ref.current, value, 2))
+        ref.current = value;
+    return ref.current;
+}
+function toError(value) {
+    return value instanceof Error ? value : new Error(String(value));
+}
+const openSession = createSession;
+/**
+ * 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.
+ */
+function AreteSessionProvider(props) {
+    const arete = useOptionalAreteContext();
+    const isExternal = props.definition === undefined;
+    const externalSession = isExternal ? props.session ?? null : null;
+    const definition = useSameShape(props.definition);
+    const given = (props.options ?? {});
+    const inheritedAuth = arete?.config.auth;
+    const inheritedFetch = arete?.config.fetch;
+    const options = useSameShape({
+        ...given,
+        ...(given.auth === undefined && inheritedAuth ? { auth: inheritedAuth } : {}),
+        ...(given.fetch === undefined && inheritedFetch ? { fetch: inheritedFetch } : {}),
+    });
+    const [attempt, setAttempt] = useState(0);
+    const key = useMemo(() => ({ definition, options, external: externalSession, attempt }), [definition, options, externalSession, attempt]);
+    const keyRef = useRef(key);
+    keyRef.current = key;
+    const walletRef = useRef(props.wallet);
+    walletRef.current = props.wallet;
+    const syncsWallet = !isExternal || 'wallet' in props;
+    const deferredsRef = useRef(new WeakMap());
+    // Every waiter that may still be pending, so unmounting can settle them.
+    const pendingRef = useRef(new Set());
+    const unmountedRef = useRef(false);
+    const deferredFor = useCallback((forKey) => {
+        let deferred = deferredsRef.current.get(forKey);
+        if (!deferred) {
+            deferred = createDeferred();
+            if (unmountedRef.current)
+                deferred.reject(new AreteSessionUnavailableError());
+            deferredsRef.current.set(forKey, deferred);
+            for (const pending of pendingRef.current) {
+                if (pending.settled)
+                    pendingRef.current.delete(pending);
+            }
+            if (!deferred.settled)
+                pendingRef.current.add(deferred);
+        }
+        return deferred;
+    }, []);
+    // Removed for good, nothing will open: the waiters fail instead of
+    // hanging. The check waits a microtask because StrictMode (and a tree
+    // that is hidden and shown again) runs this cleanup and then mounts the
+    // same provider again, which keeps the waiters for the session it opens.
+    const mountedRef = useRef(false);
+    useEffect(() => {
+        mountedRef.current = true;
+        unmountedRef.current = false;
+        const waiters = pendingRef.current;
+        return () => {
+            mountedRef.current = false;
+            void Promise.resolve().then(() => {
+                if (mountedRef.current)
+                    return;
+                unmountedRef.current = true;
+                const pending = [...waiters];
+                waiters.clear();
+                // Mounted again later (a hidden tree shown again), `ready()` waits
+                // for the session opened then rather than repeating this failure.
+                deferredsRef.current = new WeakMap();
+                for (const deferred of pending)
+                    deferred.reject(new AreteSessionUnavailableError());
+            });
+        };
+    }, []);
+    const [opened, setOpened] = useState(null);
+    // A caller waiting on the previous key's session gets the next one.
+    const previousKeyRef = useRef(null);
+    useEffect(() => {
+        const previous = previousKeyRef.current;
+        previousKeyRef.current = key;
+        if (previous && previous !== key) {
+            const waiting = deferredsRef.current.get(previous);
+            if (waiting && !waiting.settled)
+                waiting.resolve(deferredFor(key).promise);
+        }
+    }, [key, deferredFor]);
+    useEffect(() => {
+        if (key.external)
+            deferredFor(key).resolve(key.external);
+    }, [key, deferredFor]);
+    useEffect(() => {
+        if (!key.definition)
+            return undefined;
+        let active = true;
+        let session = null;
+        const deferred = deferredFor(key);
+        const wallet = walletRef.current;
+        openSession(key.definition, { ...key.options, ...(wallet ? { wallet } : {}) }).then((openedSession) => {
+            if (!active) {
+                openedSession.close();
+                return;
+            }
+            session = openedSession;
+            // The wallet may have changed while the session was opening.
+            if (openedSession.wallet !== walletRef.current)
+                openedSession.setWallet(walletRef.current);
+            deferred.resolve(openedSession);
+            setOpened({ key, session: openedSession, error: null });
+        }, (cause) => {
+            if (!active)
+                return;
+            const error = toError(cause);
+            deferred.reject(error);
+            setOpened({ key, session: null, error });
+        });
+        return () => {
+            active = false;
+            session?.close();
+        };
+    }, [key, deferredFor]);
+    let session = null;
+    let error = null;
+    let status = 'opening';
+    if (isExternal) {
+        session = externalSession;
+        status = session ? 'open' : 'opening';
+    }
+    else if (opened?.key === key) {
+        session = opened.session;
+        error = opened.error;
+        status = error ? 'error' : 'open';
+    }
+    const { wallet } = props;
+    useEffect(() => {
+        if (session && syncsWallet && session.wallet !== wallet)
+            session.setWallet(wallet);
+    }, [session, syncsWallet, wallet]);
+    const ready = useCallback(() => deferredFor(keyRef.current).promise, [deferredFor]);
+    const retry = useCallback(() => {
+        setAttempt((current) => current + 1);
+    }, []);
+    const value = useMemo(() => ({ session, status, error, ready, retry }), [session, status, error, ready, retry]);
+    return (React.createElement(AreteSessionContext.Provider, { value: value }, props.children));
+}
+/**
+ * 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`.
+ */
+function useAreteSession() {
+    const value = useContext(AreteSessionContext);
+    if (!value) {
+        throw new Error('useAreteSession must be used within AreteSessionProvider');
+    }
+    return value;
+}
+/** The nearest `AreteSessionProvider`'s value, or `null` outside one. */
+function useOptionalAreteSession() {
+    return useContext(AreteSessionContext);
+}
+
 function isMarkedDefaultReconciliation(value) {
     return (typeof value === 'function'
         && value.areteDefaultReconciliation === true
@@ -1662,12 +1936,17 @@ function useQuery(client, query, snapshotEnabled, enabled, initialData) {
             return current;
         }
         catch (value) {
-            state.fallback = {
-                ...state.fallback,
-                isLoading: false,
-                isRefreshing: false,
-                error: queryError(value, 'Subscription snapshot failed'),
-            };
+            // A lease whose client was disconnected under it (its owner closed
+            // it) throws on every read: report the error once and keep returning
+            // the same snapshot, so React sees a stable value.
+            if (!state.fallback.error) {
+                state.fallback = {
+                    ...state.fallback,
+                    isLoading: false,
+                    isRefreshing: false,
+                    error: queryError(value, 'Subscription snapshot failed'),
+                };
+            }
             return state.fallback;
         }
         // state is replaced whenever either listed identity changes.
@@ -1878,12 +2157,588 @@ function createListViewHook(viewDef, client) {
     return { use, useOne, refresh };
 }
 
+/** The typed failure of a {@link useOperationMutation} run. */
+class OperationMutationError extends Error {
+    constructor(input) {
+        super(input.message);
+        this.name = 'OperationMutationError';
+        this.kind = input.kind;
+        this.cause = input.cause;
+        this.failure = input.failure ?? null;
+        this.prepared = input.prepared ?? null;
+        this.completedSignatures = [...(input.completedSignatures ?? [])];
+        this.signature = this.failure && 'signature' in this.failure
+            ? this.failure.signature
+            : undefined;
+        this.programError = this.failure?.status === 'chain-failed'
+            ? this.failure.programError
+            : undefined;
+    }
+}
+/** The `cause` chain of `error`, outermost first. */
+function causeChain(error) {
+    const chain = [];
+    let current = error;
+    while (current !== undefined && current !== null && chain.length < 10 && !chain.includes(current)) {
+        chain.push(current);
+        current = typeof current === 'object' ? current.cause : undefined;
+    }
+    return chain;
+}
+/** Error codes wallets report a declined prompt with (EIP-1193 4001 and kin). */
+const USER_REJECTION_CODES = [4001, 'ACTION_REJECTED', 'USER_REJECTED'];
+/**
+ * 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.
+ */
+function isWalletRejection(error) {
+    return causeChain(error).some((item) => {
+        if (typeof item !== 'object' || item === null)
+            return false;
+        const { code, name, message } = item;
+        if (USER_REJECTION_CODES.includes(code))
+            return true;
+        if (name === 'WalletStandardSignerError')
+            return code === 'user_rejected';
+        if (typeof name === 'string' && /rejected/i.test(name))
+            return true;
+        return typeof message === 'string'
+            && /user (rejected|declined|denied|cancel)|rejected the request|request (was )?(rejected|declined)/i
+                .test(message);
+    });
+}
+/** The `code` of a `WalletStandardSignerError` in the cause chain, if any. */
+function walletSignerErrorCode(error) {
+    for (const item of causeChain(error)) {
+        if (item instanceof Error
+            && item.name === 'WalletStandardSignerError'
+            && typeof item.code === 'string') {
+            return item.code;
+        }
+    }
+    return null;
+}
+function messageOf(error) {
+    if (error instanceof Error && error.message)
+        return error.message;
+    if (typeof error === 'string' && error)
+        return error;
+    return 'The operation failed';
+}
+/**
+ * Classify an execution failure. Exported so code outside the hook (an
+ * imperative `session.execute`) can show the same messages.
+ */
+function toOperationMutationError(error, prepared = null, completedSignatures = []) {
+    if (error instanceof OperationMutationError)
+        return error;
+    const failure = getTransactionFailureOutcome(error);
+    const completed = error instanceof OperationExecutionError
+        ? error.completedReceipts.map((receipt) => receipt.signature)
+        : completedSignatures;
+    const make = (kind) => new OperationMutationError({
+        kind,
+        message: messageOf(error),
+        cause: error,
+        failure,
+        prepared,
+        completedSignatures: completed,
+    });
+    if (failure?.status === 'chain-failed')
+        return make('chain-failed');
+    if (failure?.status === 'submitted-unknown')
+        return make('submitted-unknown');
+    switch (walletSignerErrorCode(error)) {
+        case 'wallet_returned_invalid_transaction':
+            return make('wallet-modified');
+        case 'sign_transaction_unsupported':
+            return make('wallet-feature-unsupported');
+        case 'chain_unsupported':
+            return make('wallet-chain-unsupported');
+        case 'transaction_version_unsupported':
+            return make('wallet-version-unsupported');
+        case 'user_rejected':
+            return make('wallet-rejected');
+    }
+    if (isWalletRejection(error))
+        return make('wallet-rejected');
+    return make('not-submitted');
+}
+function hasActivity(wallet) {
+    return typeof wallet?.onActivity === 'function';
+}
+/**
+ * The wallet as one run hands it to the executor: every `signAndSend` it
+ * makes carries `listener` as that send's `onActivity`, after any listener
+ * the caller's send options already set.
+ */
+function withSendActivity(wallet, listener) {
+    const signAndSend = (instructions, options, ...rest) => {
+        const own = options?.onActivity;
+        const onActivity = typeof own === 'function'
+            ? (activity) => {
+                try {
+                    own(activity);
+                }
+                finally {
+                    listener(activity);
+                }
+            }
+            : listener;
+        return wallet.signAndSend(instructions, { ...(options ?? {}), onActivity }, ...rest);
+    };
+    return new Proxy(wallet, {
+        get(target, property) {
+            if (property === 'signAndSend')
+                return signAndSend;
+            const value = Reflect.get(target, property, target);
+            return typeof value === 'function' ? value.bind(target) : value;
+        },
+    });
+}
+function isPreparedWithSigners(value) {
+    return typeof value === 'object'
+        && value !== null
+        && 'operation' in value
+        && !('kind' in value && 'plan' in value);
+}
+async function resolveExecutor(source) {
+    if (!source)
+        return null;
+    if (typeof source === 'function')
+        return (await source()) ?? null;
+    return source;
+}
+const IDLE_STATE = {
+    status: 'idle',
+    prepared: null,
+    result: undefined,
+    error: null,
+    signatures: [],
+    transactionIndex: null,
+};
+/**
+ * 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.
+ */
+function useOperationMutation(prepare, options) {
+    const [state, setState] = useState(IDLE_STATE);
+    const sessionContext = useOptionalAreteSession();
+    const prepareRef = useRef(prepare);
+    const optionsRef = useRef(options);
+    const sessionReadyRef = useRef(sessionContext?.ready);
+    prepareRef.current = prepare;
+    optionsRef.current = options;
+    sessionReadyRef.current = sessionContext?.ready;
+    const generationRef = useRef(0);
+    // The run that holds the lock, if any. A run releases only its own lock,
+    // so a run that finishes its callbacks late never frees a newer run's.
+    const runningRef = useRef(null);
+    const mountedRef = useRef(true);
+    useEffect(() => {
+        mountedRef.current = true;
+        return () => {
+            mountedRef.current = false;
+            generationRef.current += 1;
+        };
+    }, []);
+    const run = useCallback(async (input, runOptions = {}) => {
+        if (runningRef.current) {
+            throw new OperationMutationError({
+                kind: 'busy',
+                message: 'This operation is already running',
+                cause: undefined,
+            });
+        }
+        const lock = {};
+        runningRef.current = lock;
+        const release = () => {
+            if (runningRef.current === lock)
+                runningRef.current = null;
+        };
+        const generation = ++generationRef.current;
+        const hookOptions = optionsRef.current;
+        let lastStatus = 'idle';
+        let transactionIndex = null;
+        const update = (patch) => {
+            if (!mountedRef.current || generation !== generationRef.current)
+                return;
+            if (patch.transactionIndex !== undefined)
+                transactionIndex = patch.transactionIndex;
+            setState((current) => ({ ...current, ...patch }));
+            if (patch.status && patch.status !== lastStatus) {
+                lastStatus = patch.status;
+                try {
+                    hookOptions.onStatusChange?.(patch.status, { transactionIndex });
+                }
+                catch {
+                    // Observational only.
+                }
+            }
+        };
+        let prepared = null;
+        const signatures = [];
+        const fail = async (error) => {
+            // The run is over once `error` is published: `isBusy` turns false and
+            // the hook takes the next run, even while `onError` is still pending.
+            release();
+            update({ status: 'error', error, prepared, signatures: [...signatures] });
+            try {
+                await hookOptions.onError?.(error);
+            }
+            catch {
+                // The callback observes the failure; it does not replace it.
+            }
+            return error;
+        };
+        setState(IDLE_STATE);
+        update({ status: 'preparing' });
+        try {
+            let executor;
+            const source = hookOptions.executor !== undefined
+                ? hookOptions.executor
+                : sessionReadyRef.current ?? null;
+            try {
+                executor = await resolveExecutor(source);
+            }
+            catch (cause) {
+                throw await fail(new OperationMutationError({
+                    kind: 'not-ready', message: messageOf(cause), cause,
+                }));
+            }
+            if (!executor) {
+                throw await fail(new OperationMutationError({
+                    kind: 'not-ready',
+                    message: 'Nothing to execute the operation with yet',
+                    cause: undefined,
+                }));
+            }
+            // No wallet, no run: nothing is prepared, nothing is signed.
+            const wallet = runOptions.wallet
+                ?? hookOptions.wallet
+                ?? (hookOptions.allowExecutorWallet
+                    ? executor.wallet
+                    : undefined);
+            if (!wallet) {
+                throw await fail(new OperationMutationError({
+                    kind: 'not-ready',
+                    message: 'Connect a wallet to run this operation',
+                    cause: undefined,
+                }));
+            }
+            let extraSigners = [];
+            try {
+                const built = await prepareRef.current(input);
+                if (isPreparedWithSigners(built)) {
+                    prepared = built.operation;
+                    extraSigners = built.signers ?? [];
+                }
+                else {
+                    prepared = built;
+                }
+            }
+            catch (cause) {
+                throw await fail(new OperationMutationError({
+                    kind: 'prepare-failed', message: messageOf(cause), cause,
+                }));
+            }
+            update({ prepared });
+            // A wallet that reports its activity says when its prompt opens; until
+            // then the transaction is still being built (blockhash, budgets). The
+            // run listens to its own sends only, and only until they settle, so
+            // another run on the same wallet, or one that starts while this run's
+            // callbacks are pending, cannot move this run's status.
+            const reportsActivity = hasActivity(wallet);
+            let listening = reportsActivity;
+            const runWallet = reportsActivity
+                ? withSendActivity(wallet, (activity) => {
+                    if (!listening)
+                        return;
+                    if (activity.stage === 'signing' || activity.stage === 'sending'
+                        || activity.stage === 'confirming') {
+                        update({ status: activity.stage });
+                    }
+                })
+                : wallet;
+            const signers = [
+                ...(hookOptions.signers ?? []),
+                ...extraSigners,
+                ...(runOptions.signers ?? []),
+            ];
+            const send = runOptions.send ?? hookOptions.send;
+            let result;
+            try {
+                result = await executor.execute(prepared, {
+                    wallet: runWallet,
+                    ...(signers.length > 0 ? { signers } : {}),
+                    ...(send ? { send } : {}),
+                    onTransactionStart: (event) => {
+                        update({
+                            status: reportsActivity ? 'preparing' : 'signing',
+                            transactionIndex: event.transactionIndex,
+                        });
+                    },
+                    onTransactionSuccess: (event) => {
+                        signatures.push(event.receipt.signature);
+                        update({ signatures: [...signatures] });
+                    },
+                });
+            }
+            catch (cause) {
+                listening = false;
+                throw await fail(toOperationMutationError(cause, prepared, signatures));
+            }
+            listening = false;
+            // As in `fail`: `done` releases the lock, so `isBusy` and `run()` agree
+            // while `onSuccess` runs. Activity listening has already stopped, so a
+            // run started from (or during) the callback cannot move this one.
+            release();
+            update({
+                status: 'done',
+                result,
+                signatures: [...result.signatures],
+                transactionIndex: null,
+            });
+            try {
+                await hookOptions.onSuccess?.(result, prepared);
+            }
+            catch {
+                // The operation confirmed; a failing callback does not undo that.
+            }
+            return result;
+        }
+        finally {
+            release();
+        }
+    }, []);
+    const mutate = useCallback((input, runOptions) => {
+        void run(input, runOptions).catch(() => undefined);
+    }, [run]);
+    const reset = useCallback(() => {
+        if (runningRef.current)
+            return;
+        generationRef.current += 1;
+        setState(IDLE_STATE);
+    }, []);
+    const busy = state.status === 'preparing' || state.status === 'signing'
+        || state.status === 'sending' || state.status === 'confirming';
+    return {
+        run,
+        mutate,
+        reset,
+        status: state.status,
+        isBusy: busy,
+        isAwaitingWallet: state.status === 'signing',
+        prepared: state.prepared,
+        artifacts: state.prepared?.artifacts,
+        result: state.result,
+        error: state.error,
+        signatures: state.signatures,
+        transactionIndex: state.transactionIndex,
+        transactionCount: state.prepared ? state.prepared.plan.transactions.length : null,
+    };
+}
+
+function isStackClient(value) {
+    return typeof value === 'object'
+        && value !== null
+        && typeof value.getSubscriptionRegistry === 'function'
+        && typeof value.onConnectionStateChange === 'function';
+}
+function isMemberOptions(value) {
+    const stack = value?.stack;
+    return typeof stack === 'object' && stack !== null && 'views' in stack;
+}
+function zustandStoreOf(client) {
+    return client?.store?.store ?? null;
+}
+/**
+ * `useArete` for a client the caller (usually a session) connected and
+ * owns. It reads the member's own connection and store: nothing connects,
+ * and nothing is disconnected when the component unmounts or the member is
+ * replaced. A `null` member reads as the connecting state `useArete(stack)`
+ * reports before its client exists.
+ */
+function useMemberArete(member, options) {
+    const client = member;
+    const stack = client?.stack ?? options?.stack;
+    if (!stack) {
+        throw new Error('useArete(member) could not read the stack definition of the member it was given. '
+            + 'Pass it as useArete(member, { stack }).');
+    }
+    // Mutations wait for the streamed slot they landed in only when the member
+    // was connected over the socket.
+    const transport = client?.transport;
+    const placeholderPrograms = options?.programs;
+    const sessionContext = useOptionalAreteSession();
+    const [connection, setConnection] = useState(() => ({
+        client,
+        state: client?.connectionState ?? 'disconnected',
+        error: null,
+        socketIssue: null,
+    }));
+    // A new member (a reopened session) never shows the previous one's state.
+    const current = connection.client === client
+        ? connection
+        : { client, state: client?.connectionState ?? 'disconnected', error: null, socketIssue: null };
+    useEffect(() => {
+        if (!client) {
+            setConnection((previous) => previous.client === null
+                ? previous
+                : { client: null, state: 'disconnected', error: null, socketIssue: null });
+            return undefined;
+        }
+        const update = (next) => {
+            setConnection((previous) => {
+                const base = previous.client === client
+                    ? previous
+                    : { client, state: client.connectionState, error: null, socketIssue: null };
+                return { ...base, ...next };
+            });
+        };
+        update({ state: client.connectionState });
+        const unsubscribeState = client.onConnectionStateChange((state, stateError) => {
+            if (state === 'error') {
+                update({ state, error: normalizeConnectionError(stateError, 'Arete connection entered an error state') });
+            }
+            else if (state === 'connected') {
+                update({ state, error: null, socketIssue: null });
+            }
+            else {
+                update({ state });
+            }
+        });
+        const unsubscribeIssue = client.onSocketIssue((socketIssue) => {
+            update({ socketIssue });
+        });
+        // Only listeners are removed: the member's connection is its owner's.
+        return () => {
+            unsubscribeIssue();
+            unsubscribeState();
+        };
+    }, [client]);
+    const views = useMemo(() => buildViewHooks(stack, client), [stack, client]);
+    const programs = useMemo(() => {
+        if (!client) {
+            return buildDisconnectedProgramHooks(stack.programs, placeholderPrograms);
+        }
+        return buildProgramHookInterfaces(client.programs, client, useInstructionMutation, { defaultReconciliation: transport !== 'http' });
+    }, [client, stack, transport, placeholderPrograms]);
+    const connectedRead = (client?.read ?? null);
+    const readArgCounts = getStackRuntimeExtensions(stack)?.readArgCounts;
+    const read = useMemo(() => buildReadInterfaces(connectedRead, readArgCounts), [connectedRead, readArgCounts]);
+    const sessionStatus = sessionContext?.status;
+    const sessionError = sessionContext?.error ?? null;
+    const sessionRetry = sessionContext?.retry;
+    const sessionFailed = !client && sessionStatus === 'error';
+    const retry = useCallback(async () => {
+        // The member's connection belongs to its session: retrying reopens a
+        // session that failed to open, and does nothing otherwise.
+        if (sessionFailed)
+            sessionRetry?.();
+    }, [sessionFailed, sessionRetry]);
+    const status = client
+        ? current.error && current.state !== 'connected' ? 'error' : current.state
+        : sessionFailed ? 'error' : 'connecting';
+    const error = client ? current.error : sessionFailed ? sessionError : null;
+    const extension = (name) => client?.[name]
+        ?? stack[name];
+    return {
+        views,
+        queries: client?.queries ?? {},
+        programs,
+        chain: client?.chain ?? null,
+        zustandStore: zustandStoreOf(client),
+        client,
+        read,
+        reads: read,
+        addresses: extension('addresses'),
+        constants: extension('constants'),
+        defaults: extension('defaults'),
+        math: extension('math'),
+        connectionState: client ? current.state : 'disconnected',
+        status,
+        isConnected: Boolean(client) && current.state === 'connected',
+        isLoading: !client && !sessionFailed,
+        canRetry: sessionFailed,
+        error,
+        socketIssue: client ? current.socketIssue : null,
+        retry,
+    };
+}
+function buildViewHooks(stack, client) {
+    const result = {};
+    for (const [viewName, viewGroup] of Object.entries(stack.views)) {
+        result[viewName] = {};
+        if (typeof viewGroup === 'object' && viewGroup !== null) {
+            for (const [subViewName, viewDef] of Object.entries(viewGroup)) {
+                if (!viewDef || typeof viewDef !== 'object' || !('mode' in viewDef))
+                    continue;
+                if (viewDef.mode === 'state') {
+                    result[viewName][subViewName] = createStateViewHook(viewDef, client);
+                }
+                else if (viewDef.mode === 'list') {
+                    result[viewName][subViewName] = createListViewHook(viewDef, client);
+                }
+            }
+        }
+    }
+    return result;
+}
 function normalizeConnectionError(value, fallback) {
     if (value instanceof Error)
         return value;
     return new Error(typeof value === 'string' && value.length > 0 ? value : fallback);
 }
-function useArete(stack, 
+function useArete(stackOrMember, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+options
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+) {
+    // A call site keeps one form for its lifetime (a stack definition, or a
+    // session member that may be null while the session opens), so the hooks
+    // either branch calls stay in the same order.
+    if (isStackClient(stackOrMember)) {
+        // eslint-disable-next-line react-hooks/rules-of-hooks -- one form per call site
+        return useMemberArete(stackOrMember, options);
+    }
+    if (stackOrMember == null && isMemberOptions(options)) {
+        // eslint-disable-next-line react-hooks/rules-of-hooks -- one form per call site
+        return useMemberArete(null, options);
+    }
+    // eslint-disable-next-line react-hooks/rules-of-hooks -- one form per call site
+    return useStackArete((stackOrMember ?? undefined), options);
+}
+function useStackArete(stack, 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 options
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -2046,25 +2901,7 @@ options
         retryPromiseRef.current = { lookupKey, promise: tracked };
         return tracked;
     }, [lookupKey, lookupOptions, retryClient, resolvedStack]);
-    const views = useMemo(() => {
-        const result = {};
-        for (const [viewName, viewGroup] of Object.entries(resolvedStack.views)) {
-            result[viewName] = {};
-            if (typeof viewGroup === 'object' && viewGroup !== null) {
-                for (const [subViewName, viewDef] of Object.entries(viewGroup)) {
-                    if (!viewDef || typeof viewDef !== 'object' || !('mode' in viewDef))
-                        continue;
-                    if (viewDef.mode === 'state') {
-                        result[viewName][subViewName] = createStateViewHook(viewDef, client);
-                    }
-                    else if (viewDef.mode === 'list') {
-                        result[viewName][subViewName] = createListViewHook(viewDef, client);
-                    }
-                }
-            }
-        }
-        return result;
-    }, [resolvedStack, client]);
+    const views = useMemo(() => buildViewHooks(resolvedStack, client), [resolvedStack, client]);
     const programs = useMemo(() => {
         if (!client) {
             // Placeholder hooks so components can render (and keep hook order)
@@ -2091,7 +2928,7 @@ options
         queries: (client?.queries ?? {}),
         programs: programs,
         chain: client?.chain ?? null,
-        zustandStore: client?.store?.store ?? null,
+        zustandStore: zustandStoreOf(client),
         client,
         read,
         reads: read,
@@ -2171,6 +3008,38 @@ function summarizeStatuses(sources) {
 /** @deprecated Use summarizeStatuses; it also accepts connection and read results. */
 const summarizeViews = summarizeStatuses;
 
+/**
+ * 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`.
+ */
+function usePlatformHttpClient(options = {}) {
+    const { config } = useAreteContext();
+    const auth = options.auth ?? config.auth;
+    const fetchImpl = config.fetch;
+    const { apiUrl } = options;
+    return useMemo(() => createPlatformHttpClient({
+        ...(apiUrl !== undefined ? { apiUrl } : {}),
+        ...(auth ? { auth } : {}),
+        ...(fetchImpl ? { fetch: fetchImpl } : {}),
+    }), [apiUrl, auth, fetchImpl]);
+}
+
 const chainIds = new WeakMap();
 let nextChainId = 1;
 function chainKey(chain) {
@@ -2386,5 +3255,5 @@ function useProtocolEvents(client, instanceId, options) {
     }, [client, instanceId, enabled]);
 }
 
-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 { 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 };
 //# sourceMappingURL=index.esm.js.map