@usearete/react 0.24.0 → 0.25.0

package/README.md

@@ -10,7 +10,7 @@ Built on top of [`@usearete/sdk`](https://www.npmjs.com/package/@usearete/sdk),
 npm install @usearete/react @usearete/sdk zod
 ```
 
-`@usearete/react` installs `zustand` as a normal dependency, so do not install it separately. React remains an application dependency. Generated consumers install the core SDK and Zod because generated stack files import their types and schemas directly.
+`@usearete/react` installs `zustand` as a normal dependency, so do not install it separately. React and `@usearete/sdk` are peer dependencies: the application owns exactly one copy of the core SDK, on the same release as `@usearete/react`, so error and outcome checks see one set of classes. Generated consumers install the core SDK and Zod because generated stack files import their types and schemas directly.
 
 ### Hooks linting
 
@@ -126,7 +126,7 @@ Supported props:
 - `auth`
 - `fetch`
 - `validateFrames` — set `false` to suppress rejected-frame warnings; generated schemas still normalize and validate entities
-- `onFrameValidationError` — structured callback for generated-schema rejections
+- `onFrameValidationError` — structured callback for frames that were not stored: schema rejections (`reason: 'schema'`) and patches for keys the client holds no entity for (`reason: 'unknown-key'`)
 - `reconnectIntervals`
 - `maxReconnectAttempts`
 - `maxEntriesPerView`
@@ -357,7 +357,7 @@ deploy.submit(args, { reconcile: { timeoutMs: 10_000 } });
 deploy.submit(args, { reconcile: async (context) => { /* ... */ } });
 ```
 
-The mutation `phase` field is the discriminated status to branch on for busy labels (`'preparing'`, `'awaiting-wallet'`, `'submitted'`, `'confirmed'`, `'reconciling'`, `'reconciled'`, plus the failure outcomes); `status` remains `'pending'` until the mutation settles. Generated operation hooks publish each completed receipt and signature during `submitted`, before the final operation receipt resolves. `onConfirmed` runs immediately after chain confirmation; `onSuccess` runs only after successful reconciliation (or immediately when reconciliation is disabled/skipped). Reconciliation failure, including a refreshed snapshot timeout, is exposed through `reconciliationError`, does not call `onSuccess`, and does not reject the confirmed `submit()` result. The confirmed transaction remains landed. `retryReconciliation()` repeats only post-confirmation watermark/refresh work using the saved receipts and targets; it never rebuilds, signs, or submits. Convenience booleans (`isPreparing`, `isAwaitingWallet`, `isReconciling`, `canRetryReconciliation`) remain available.
+The mutation `phase` field is the discriminated status to branch on. Its values are exactly `'idle'`, `'preparing'`, `'awaiting-wallet'`, `'submitted'`, `'confirmed'`, `'reconciling'`, `'reconciled'`, `'confirmed-unreconciled'`, `'not-submitted'`, `'submitted-unknown'` and `'chain-failed'`. There is no `'submitting'` or `'confirming'` phase: `'awaiting-wallet'` covers signing, sending and confirming, because the wallet adapter does all three in one call. `status` remains `'pending'` until the mutation settles. Generated operation hooks publish each completed receipt and signature during `submitted`, before the final operation receipt resolves. `onConfirmed` runs immediately after chain confirmation; `onSuccess` runs only after successful reconciliation (or immediately when reconciliation is disabled/skipped). Reconciliation failure, including a refreshed snapshot timeout, is exposed through `reconciliationError`, does not call `onSuccess`, and does not reject the confirmed `submit()` result. The confirmed transaction remains landed. `retryReconciliation()` repeats only post-confirmation watermark/refresh work using the saved receipts and targets; it never rebuilds, signs, or submits. Convenience booleans (`isPreparing`, `isAwaitingWallet`, `isReconciling`, `canRetryReconciliation`) remain available.
 
 ## Migration notes (0.3 → next)
 
@@ -380,6 +380,22 @@ The mutation `phase` field is the discriminated status to branch on for busy lab
 - Stack reads expose imperative calls and hooks together under `arete.read.<name>`; `arete.reads` remains a deprecated alias.
 - Repeated `useArete` calls now share a provider-managed client when stack and option identities match; remove component-local connection ownership workarounds.
 
+## Testing
+
+`@usearete/react/testing` re-exports every `@usearete/sdk/testing` helper and adds:
+
+- `createAreteTestConfig(harness, props?)` — `<AreteProvider>` props that connect every client to a `createWebSocketHarness()` server, with no reconnects or batching delay.
+- `createMutationResultFixture(phase, overrides?)` — a complete, consistent `useMutation()` result for any of the `MUTATION_PHASES`, for rendering phase-specific UI without a wallet.
+
+```tsx
+import { createAreteTestConfig, createWebSocketHarness } from '@usearete/react/testing';
+
+const ws = createWebSocketHarness();
+render(<AreteProvider {...createAreteTestConfig(ws)}><Dashboard /></AreteProvider>);
+const subscription = await ws.waitForSubscription('OreRound/latest'); // flush renders between polls
+ws.serve(subscription, [{ key: '1', data: round }]);
+```
+
 ## Low-Level Hooks
 
 The React SDK also exports:

package/dist/index.d.ts

@@ -56,7 +56,11 @@ interface AreteConfig {
     flushIntervalMs?: number;
     fetch?: ConnectOptions['fetch'];
     validateFrames?: boolean;
-    /** Receives structured details when a generated schema rejects a frame. */
+    /**
+     * Receives structured details when a frame is not stored: a generated schema
+     * rejected it (`reason: 'schema'`), or it was a patch for a key the client
+     * holds no entity for (`reason: 'unknown-key'`).
+     */
     onFrameValidationError?: ConnectOptions['onFrameValidationError'];
     /** Authentication configuration */
     auth?: AuthConfig;

package/dist/testing.cjs

@@ -0,0 +1,165 @@
+'use strict';
+
+var testing = require('@usearete/sdk/testing');
+
+/** Every value `useMutation().phase` can take, in lifecycle order. */
+const MUTATION_PHASES = [
+    'idle',
+    'preparing',
+    'awaiting-wallet',
+    'submitted',
+    'confirmed',
+    'reconciling',
+    'reconciled',
+    'confirmed-unreconciled',
+    'not-submitted',
+    'submitted-unknown',
+    'chain-failed',
+];
+const LANDED_PHASES = new Set([
+    'submitted',
+    'confirmed',
+    'reconciling',
+    'reconciled',
+    'confirmed-unreconciled',
+]);
+function failureFor(phase) {
+    const outcomes = testing.createTransactionOutcomeFixtures();
+    switch (phase) {
+        case 'not-submitted':
+            return outcomes['not-submitted:wallet'];
+        case 'submitted-unknown':
+            return outcomes['submitted-unknown:send'];
+        case 'chain-failed':
+            return outcomes['chain-failed:chain'];
+        default:
+            return null;
+    }
+}
+function statusFor(phase) {
+    if (phase === 'idle')
+        return 'idle';
+    if (phase === 'reconciled' || phase === 'confirmed-unreconciled')
+        return 'success';
+    if (failureFor(phase))
+        return 'error';
+    return 'pending';
+}
+function displayErrorFor(failure) {
+    if (!failure)
+        return null;
+    if (failure.status === 'chain-failed' && failure.programError) {
+        return `${failure.programError.name}: ${failure.programError.message}`;
+    }
+    return failure.cause instanceof Error ? failure.cause.message : 'Transaction failed';
+}
+/**
+ * A complete, internally consistent `useMutation()` result for one phase, as
+ * the hook reports it: status, receipts, signatures, outcome, failure, display
+ * error and the derived `is*` flags all agree. Use it to render and test UI
+ * for every phase without a wallet or a chain. `overrides` replace any field.
+ *
+ * `submit`/`mutateAsync` resolve with the fixture result on landed phases and
+ * reject with the phase's failure otherwise; `mutate`, `reset` and
+ * `retryReconciliation` do nothing.
+ */
+function createMutationResultFixture(phase, overrides = {}) {
+    const failure = failureFor(phase);
+    const landed = LANDED_PHASES.has(phase);
+    const receipt = {
+        transactionIndex: 0,
+        transactionName: 'fixture',
+        signature: testing.FIXTURE_SIGNATURE,
+        slot: testing.FIXTURE_SLOT,
+    };
+    const completedReceipts = landed ? [receipt] : [];
+    const signatures = landed || (failure && 'signature' in failure && failure.signature)
+        ? [testing.FIXTURE_SIGNATURE]
+        : [];
+    const outcome = failure
+        ?? (landed && phase !== 'submitted'
+            ? { status: 'confirmed', phase: 'confirmation', signature: testing.FIXTURE_SIGNATURE, slot: testing.FIXTURE_SLOT }
+            : null);
+    const result = (landed && phase !== 'submitted'
+        ? { signature: testing.FIXTURE_SIGNATURE, slot: testing.FIXTURE_SLOT, transaction: receipt }
+        : undefined);
+    const displayError = displayErrorFor(failure);
+    const reconciliationError = phase === 'confirmed-unreconciled'
+        ? new Error('Fixture: the stream did not reach the confirmed slot in time')
+        : null;
+    const status = statusFor(phase);
+    const settle = async () => {
+        if (failure)
+            throw testing.transactionFailureError(failure);
+        return result;
+    };
+    return {
+        mutate: () => undefined,
+        mutateAsync: settle,
+        submit: settle,
+        status,
+        phase,
+        latestEvent: phase === 'idle'
+            ? null
+            : {
+                phase,
+                prepared: null,
+                ...(result !== undefined ? { result } : {}),
+                ...(failure ? { failure } : {}),
+            },
+        error: displayError,
+        displayError,
+        failure,
+        outcome,
+        prepared: null,
+        data: result,
+        result,
+        signatures,
+        signature: signatures.length === 1 ? signatures[0] : null,
+        completedReceipts,
+        callbackError: null,
+        callbackErrors: [],
+        reconciliationError,
+        isLoading: status === 'pending',
+        isConfirmed: outcome?.status === 'confirmed',
+        isSubmittedUnknown: failure?.status === 'submitted-unknown',
+        isPreparing: phase === 'preparing',
+        isAwaitingWallet: phase === 'awaiting-wallet',
+        isReconciling: phase === 'reconciling',
+        canRetryReconciliation: phase === 'confirmed-unreconciled',
+        retryReconciliation: async () => undefined,
+        reset: () => undefined,
+        ...overrides,
+    };
+}
+/**
+ * `<AreteProvider>` props that connect every client to a
+ * {@link WebSocketHarness} instead of the network: no reconnects, no
+ * batching delay, so frames a test sends are visible on the next render.
+ *
+ * ```tsx
+ * const ws = createWebSocketHarness();
+ * render(<AreteProvider {...createAreteTestConfig(ws, { wallet })}><App /></AreteProvider>);
+ * const subscription = await ws.waitForSubscription('OreRound/latest');
+ * ws.serve(subscription, [{ key: '1', data: round }]);
+ * ```
+ */
+function createAreteTestConfig(harness, overrides = {}) {
+    return {
+        autoReconnect: false,
+        flushIntervalMs: 0,
+        ...overrides,
+        auth: { ...overrides.auth, websocketFactory: harness.websocketFactory },
+    };
+}
+
+exports.MUTATION_PHASES = MUTATION_PHASES;
+exports.createAreteTestConfig = createAreteTestConfig;
+exports.createMutationResultFixture = createMutationResultFixture;
+Object.keys(testing).forEach(function (k) {
+    if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
+        enumerable: true,
+        get: function () { return testing[k]; }
+    });
+});
+//# sourceMappingURL=testing.cjs.map

package/dist/testing.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.cjs","sources":["../src/testing.ts"],"sourcesContent":[null],"names":["createTransactionOutcomeFixtures","FIXTURE_SIGNATURE","FIXTURE_SLOT","transactionFailureError"],"mappings":"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"}

package/dist/testing.d.ts

@@ -0,0 +1,198 @@
+import { PreparedOperation, TransactionFailureOutcome, TransactionOutcome, OperationTransactionReceipt, OperationExecutionEvent, OperationExecutionSuccessEvent, StackDefinition, WalletAdapter, ConnectOptions, AuthConfig, ProgramSdkDefinition } from '@usearete/sdk';
+import { WebSocketHarness } from '@usearete/sdk/testing';
+export * from '@usearete/sdk/testing';
+
+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> {
+    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;
+}
+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}.
+ *
+ * `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, 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 ProgramMap = Record<string, ProgramSdkDefinition>;
+/**
+ * Global configuration for AreteProvider.
+ *
+ * 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;
+    maxEntriesPerView?: number | null;
+    flushIntervalMs?: number;
+    fetch?: ConnectOptions['fetch'];
+    validateFrames?: boolean;
+    /**
+     * Receives structured details when a frame is not stored: a generated schema
+     * rejected it (`reason: 'schema'`), or it was a patch for a key the client
+     * holds no entity for (`reason: 'unknown-key'`).
+     */
+    onFrameValidationError?: ConnectOptions['onFrameValidationError'];
+    /** Authentication configuration */
+    auth?: AuthConfig;
+}
+/**
+ * Client lookup/connect options for React hooks.
+ */
+interface ClientLookupOptions<TPrograms extends ProgramMap | 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'];
+    /** Override the chain transport independently from the stack HTTP endpoint. */
+    chain?: ConnectOptions<TPrograms>['chain'];
+    /** Attach additional program SDKs to the connected client. */
+    programs?: TPrograms;
+}
+
+/**
+ * `@usearete/react/testing`: supported helpers for testing React components
+ * built on `@usearete/react`. It re-exports every `@usearete/sdk/testing`
+ * helper and adds React-specific fixtures.
+ */
+
+/** Every value `useMutation().phase` can take, in lifecycle order. */
+declare const MUTATION_PHASES: readonly ["idle", "preparing", "awaiting-wallet", "submitted", "confirmed", "reconciling", "reconciled", "confirmed-unreconciled", "not-submitted", "submitted-unknown", "chain-failed"];
+/**
+ * A complete, internally consistent `useMutation()` result for one phase, as
+ * the hook reports it: status, receipts, signatures, outcome, failure, display
+ * error and the derived `is*` flags all agree. Use it to render and test UI
+ * for every phase without a wallet or a chain. `overrides` replace any field.
+ *
+ * `submit`/`mutateAsync` resolve with the fixture result on landed phases and
+ * reject with the phase's failure otherwise; `mutate`, `reset` and
+ * `retryReconciliation` do nothing.
+ */
+declare function createMutationResultFixture<TParams = Record<string, unknown>, TResult = unknown, TOptions extends object = Record<string, unknown>, TPrepared extends PreparedOperation = PreparedOperation>(phase: MutationPhase, overrides?: Partial<UseMutationResult<TParams, TResult, TOptions, TPrepared>>): UseMutationResult<TParams, TResult, TOptions, TPrepared>;
+/**
+ * `<AreteProvider>` props that connect every client to a
+ * {@link WebSocketHarness} instead of the network: no reconnects, no
+ * batching delay, so frames a test sends are visible on the next render.
+ *
+ * ```tsx
+ * const ws = createWebSocketHarness();
+ * render(<AreteProvider {...createAreteTestConfig(ws, { wallet })}><App /></AreteProvider>);
+ * const subscription = await ws.waitForSubscription('OreRound/latest');
+ * ws.serve(subscription, [{ key: '1', data: round }]);
+ * ```
+ */
+declare function createAreteTestConfig(harness: Pick<WebSocketHarness, 'websocketFactory'>, overrides?: AreteConfig): AreteConfig;
+
+export { MUTATION_PHASES, createAreteTestConfig, createMutationResultFixture };

package/dist/testing.esm.js

@@ -0,0 +1,156 @@
+import { FIXTURE_SIGNATURE, FIXTURE_SLOT, createTransactionOutcomeFixtures, transactionFailureError } from '@usearete/sdk/testing';
+export * from '@usearete/sdk/testing';
+
+/** Every value `useMutation().phase` can take, in lifecycle order. */
+const MUTATION_PHASES = [
+    'idle',
+    'preparing',
+    'awaiting-wallet',
+    'submitted',
+    'confirmed',
+    'reconciling',
+    'reconciled',
+    'confirmed-unreconciled',
+    'not-submitted',
+    'submitted-unknown',
+    'chain-failed',
+];
+const LANDED_PHASES = new Set([
+    'submitted',
+    'confirmed',
+    'reconciling',
+    'reconciled',
+    'confirmed-unreconciled',
+]);
+function failureFor(phase) {
+    const outcomes = createTransactionOutcomeFixtures();
+    switch (phase) {
+        case 'not-submitted':
+            return outcomes['not-submitted:wallet'];
+        case 'submitted-unknown':
+            return outcomes['submitted-unknown:send'];
+        case 'chain-failed':
+            return outcomes['chain-failed:chain'];
+        default:
+            return null;
+    }
+}
+function statusFor(phase) {
+    if (phase === 'idle')
+        return 'idle';
+    if (phase === 'reconciled' || phase === 'confirmed-unreconciled')
+        return 'success';
+    if (failureFor(phase))
+        return 'error';
+    return 'pending';
+}
+function displayErrorFor(failure) {
+    if (!failure)
+        return null;
+    if (failure.status === 'chain-failed' && failure.programError) {
+        return `${failure.programError.name}: ${failure.programError.message}`;
+    }
+    return failure.cause instanceof Error ? failure.cause.message : 'Transaction failed';
+}
+/**
+ * A complete, internally consistent `useMutation()` result for one phase, as
+ * the hook reports it: status, receipts, signatures, outcome, failure, display
+ * error and the derived `is*` flags all agree. Use it to render and test UI
+ * for every phase without a wallet or a chain. `overrides` replace any field.
+ *
+ * `submit`/`mutateAsync` resolve with the fixture result on landed phases and
+ * reject with the phase's failure otherwise; `mutate`, `reset` and
+ * `retryReconciliation` do nothing.
+ */
+function createMutationResultFixture(phase, overrides = {}) {
+    const failure = failureFor(phase);
+    const landed = LANDED_PHASES.has(phase);
+    const receipt = {
+        transactionIndex: 0,
+        transactionName: 'fixture',
+        signature: FIXTURE_SIGNATURE,
+        slot: FIXTURE_SLOT,
+    };
+    const completedReceipts = landed ? [receipt] : [];
+    const signatures = landed || (failure && 'signature' in failure && failure.signature)
+        ? [FIXTURE_SIGNATURE]
+        : [];
+    const outcome = failure
+        ?? (landed && phase !== 'submitted'
+            ? { status: 'confirmed', phase: 'confirmation', signature: FIXTURE_SIGNATURE, slot: FIXTURE_SLOT }
+            : null);
+    const result = (landed && phase !== 'submitted'
+        ? { signature: FIXTURE_SIGNATURE, slot: FIXTURE_SLOT, transaction: receipt }
+        : undefined);
+    const displayError = displayErrorFor(failure);
+    const reconciliationError = phase === 'confirmed-unreconciled'
+        ? new Error('Fixture: the stream did not reach the confirmed slot in time')
+        : null;
+    const status = statusFor(phase);
+    const settle = async () => {
+        if (failure)
+            throw transactionFailureError(failure);
+        return result;
+    };
+    return {
+        mutate: () => undefined,
+        mutateAsync: settle,
+        submit: settle,
+        status,
+        phase,
+        latestEvent: phase === 'idle'
+            ? null
+            : {
+                phase,
+                prepared: null,
+                ...(result !== undefined ? { result } : {}),
+                ...(failure ? { failure } : {}),
+            },
+        error: displayError,
+        displayError,
+        failure,
+        outcome,
+        prepared: null,
+        data: result,
+        result,
+        signatures,
+        signature: signatures.length === 1 ? signatures[0] : null,
+        completedReceipts,
+        callbackError: null,
+        callbackErrors: [],
+        reconciliationError,
+        isLoading: status === 'pending',
+        isConfirmed: outcome?.status === 'confirmed',
+        isSubmittedUnknown: failure?.status === 'submitted-unknown',
+        isPreparing: phase === 'preparing',
+        isAwaitingWallet: phase === 'awaiting-wallet',
+        isReconciling: phase === 'reconciling',
+        canRetryReconciliation: phase === 'confirmed-unreconciled',
+        retryReconciliation: async () => undefined,
+        reset: () => undefined,
+        ...overrides,
+    };
+}
+/**
+ * `<AreteProvider>` props that connect every client to a
+ * {@link WebSocketHarness} instead of the network: no reconnects, no
+ * batching delay, so frames a test sends are visible on the next render.
+ *
+ * ```tsx
+ * const ws = createWebSocketHarness();
+ * render(<AreteProvider {...createAreteTestConfig(ws, { wallet })}><App /></AreteProvider>);
+ * const subscription = await ws.waitForSubscription('OreRound/latest');
+ * ws.serve(subscription, [{ key: '1', data: round }]);
+ * ```
+ */
+function createAreteTestConfig(harness, overrides = {}) {
+    return {
+        autoReconnect: false,
+        flushIntervalMs: 0,
+        ...overrides,
+        auth: { ...overrides.auth, websocketFactory: harness.websocketFactory },
+    };
+}
+
+export { MUTATION_PHASES, createAreteTestConfig, createMutationResultFixture };
+//# sourceMappingURL=testing.esm.js.map

package/dist/testing.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.esm.js","sources":["../src/testing.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/package.json

@@ -1,11 +1,33 @@
 {
   "name": "@usearete/react",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "type": "module",
   "description": "React SDK for the Arete Solana developer platform",
   "main": "dist/index.cjs",
   "module": "dist/index.esm.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.esm.js",
+      "require": "./dist/index.cjs"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.esm.js",
+      "require": "./dist/testing.cjs"
+    },
+    "./eslint-plugin.cjs": "./eslint-plugin.cjs",
+    "./eslint-rules/*": "./eslint-rules/*",
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "testing": [
+        "./dist/testing.d.ts"
+      ]
+    }
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/AreteA4/arete.git",
@@ -39,10 +61,10 @@
     "node": ">=16.0.0"
   },
   "peerDependencies": {
+    "@usearete/sdk": "^0.25.0",
     "react": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@usearete/sdk": "^0.24.0",
     "zustand": "^4.0.0 || ^5.0.0"
   },
   "devDependencies": {
@@ -54,6 +76,7 @@
     "@types/react-test-renderer": "^19.1.0",
     "@typescript-eslint/eslint-plugin": "^6.21.0",
     "@typescript-eslint/parser": "^6.21.0",
+    "@usearete/sdk": "^0.25.0",
     "eslint": "^8.0.0",
     "eslint-plugin-react-hooks": "^5.2.0",
     "jest": "^29.0.0",