@partylayer/testing 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PartyLayer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,141 @@
+# @partylayer/testing
+
+Offline test foundation for PartyLayer: a **mock CIP-0103 wallet provider** with
+configurable failure scenarios, a **controllable transaction lifecycle**, a
+**session-lifecycle harness** over the real `@partylayer/session` store, **TanStack
+Query** test utilities, and **browser/e2e primitives** — so unit, integration, and
+real-browser tests run with no DevNet or live-wallet dependency.
+
+The TanStack Query utilities live in the `@partylayer/testing/query` subpath
+(`@tanstack/query-core` is an optional peer) so the main entry stays
+dependency-free for non-Query consumers.
+
+## A. Mock CIP-0103 wallet — `createMockWallet(config?)`
+
+Returns a real `CIP0103Provider`, built by wrapping a configurable in-memory
+client in the repo's canonical `createProviderBridge`. **The default/happy
+config passes `runCIP0103ConformanceTests` by construction** (it is the
+conformance reference implementation with a mock backend).
+
+```ts
+import { createMockWallet } from '@partylayer/testing';
+
+const provider = createMockWallet();                 // happy path
+await provider.request({ method: 'connect' });        // { isConnected: true }
+
+// connect succeeds but submission fails:
+const flaky = createMockWallet({ scenarios: { submitTransaction: 'synchronizerError' } });
+```
+
+### Failure scenarios (per-method, existing error codes only)
+
+Scenarios are toggled per method. Every named scenario maps to a code that
+**already exists** in `@partylayer/provider`'s error model — no new codes are
+invented. You may also pass a raw `ProviderRpcError` or a `{ code, message }`.
+
+| scenario name | code | constructor |
+|---|---|---|
+| `userRejected` | `4001` (USER_REJECTED) | `userRejected()` |
+| `insufficientTraffic` | `-32002` (RESOURCE_UNAVAILABLE) | `resourceUnavailable()` |
+| `synchronizerError` | `4901` (CHAIN_DISCONNECTED) | `chainDisconnected()` |
+| `transactionTimeout` | `-32003` (TRANSACTION_REJECTED) | `transactionRejected()` |
+| `genericError` | `-32603` (INTERNAL_ERROR) | `internalError()` |
+
+`createMockWalletClient(config?)` exposes the underlying `BridgeableClient` as
+an extension point for advanced wrapping/inspection.
+
+## B. Simulated transaction lifecycle — `createTransactionLifecycle(config?)`
+
+A controllable lifecycle with phase flags
+`isPreparing → isSubmitting → isConfirming → isFinalized` plus a `failed`
+terminal, emitting the same CIP-0103 `txChanged` events the real provider does.
+
+```ts
+import { createTransactionLifecycle } from '@partylayer/testing';
+
+// manual stepping — deterministic, phase by phase
+const lc = createTransactionLifecycle({ commandId: 'cmd-1' });
+lc.on('txChanged', (e) => console.log(e.status));
+lc.advance();   // → 'preparing'  emits { status: 'pending' }
+lc.advance();   // → 'submitting' emits { status: 'signed', payload }
+lc.advance();   // → 'confirming' (no CIP-0103 event — see below)
+lc.advance();   // → 'finalized'  emits { status: 'executed', payload }
+// or lc.fail() at any point → emits { status: 'failed' }
+
+// auto mode — fake-timer friendly
+const auto = createTransactionLifecycle({ delays: { preparing: 10, finalized: 50 } });
+await auto.start();   // walks every phase using the delays
+```
+
+Phase → `txChanged.status`: `preparing→pending`, `submitting→signed`,
+`confirming→`(none)`, `finalized→executed`, `failed→failed`. CIP-0103 has no
+"confirming" status (the union goes signed → executed); `isConfirming` is the
+post-signed waiting flag the session layer surfaces.
+
+## C. Offline helpers
+
+```ts
+import { createMockWallet, recordTxEvents, connectMock } from '@partylayer/testing';
+
+const provider = createMockWallet();
+const rec = recordTxEvents(provider);                 // collect txChanged
+await connectMock(provider);
+await provider.request({ method: 'prepareExecute', params: { tx: {} } });
+rec.statuses();   // ['pending', 'signed', 'executed']
+rec.stop();
+```
+
+Optional `delays` use `setTimeout`, so `vi.useFakeTimers()` +
+`vi.advanceTimersByTimeAsync()` give tests full control over time.
+
+## D. Session-lifecycle harness — `createSessionHarness(config?)`
+
+Drives a **real** `@partylayer/session` store through a controllable provider, so
+each scenario exercises the store's own machinery (no synthetic shortcuts).
+
+```ts
+import { createSessionHarness } from '@partylayer/testing';
+import { vi } from 'vitest';
+
+vi.useFakeTimers();
+const h = createSessionHarness({ ttlMs: 30_000, onReauthRequired, advanceTimers: vi.advanceTimersByTimeAsync });
+await h.connect();
+await h.expire();             // advances the store's REAL expiry timer → session:expired
+h.switchParty('party::b');    // real accountsChanged → party:changed
+h.dropConnection();           // real statusChanged(false) → transient reconnect
+const tabB = h.openTab();     // a 2nd store sharing the broadcast hub (multi-tab)
+h.destroy(); tabB.destroy();  // per-harness teardown (children are separate)
+```
+
+`expire()` advances the store's real `setTimeout`-based expiry — it never emits a
+fake `session:expired`, so pass `advanceTimers` (e.g. `vi.advanceTimersByTimeAsync`)
+and install fake timers.
+
+## E. Offline composition — `createOfflineHarness({ wallet?, session? })`
+
+Wires a mock wallet to a real session store, fully offline:
+
+```ts
+import { createOfflineHarness } from '@partylayer/testing';
+const { provider, store, destroy } = createOfflineHarness({ wallet: { partyId: 'party::a' } });
+```
+
+## F. TanStack Query utilities — `@partylayer/testing/query`
+
+```ts
+import {
+  createTestQueryClient, getQueryState, expectInvalidated, trackOptimisticRollback, createQueryHarness,
+} from '@partylayer/testing/query';
+
+const qc = createTestQueryClient();                     // no retries, gcTime 0
+const t = trackOptimisticRollback<number>(qc, ['count']);
+t.apply(99); /* assert */ t.rollback(); /* assert restore */
+const h = createQueryHarness({ wallet, session, query }); // offline harness + QueryClient
+```
+
+## G. Browser / e2e primitives
+
+Framework-agnostic script strings (no Playwright dependency) for a real-browser
+smoke (`mockWalletInjectionScript()`, `idbEntryCountScript(db)`, `sessionKeyDbName(origin)`),
+injected via Playwright's `page.addInitScript` / `page.evaluate`. The smoke itself
+lives in `apps/demo/e2e` and runs nightly.

package/dist/index.d.mts

@@ -0,0 +1,177 @@
+export { M as MOCK_SCENARIO_NAMES, a as MockMethod, b as MockScenario, c as MockScenarioName, d as MockWalletClient, e as MockWalletConfig, O as OfflineHarness, T as TxEventRecorder, f as connectMock, g as createMockWallet, h as createMockWalletClient, i as createOfflineHarness, r as recordTxEvents, s as scenarioToError } from './offline-CELeTEq9.mjs';
+import { CIP0103Provider, CIP0103TxChangedEvent } from '@partylayer/core';
+import { ChannelFactory, SessionStore, SessionState, ExpiryOptions, RetryPolicy } from '@partylayer/session';
+import '@partylayer/provider';
+
+/**
+ * Simulated, controllable transaction lifecycle.
+ *
+ * Exposes the session-layer view (boolean phase flags
+ * isPreparing → isSubmitting → isConfirming → isFinalized, plus a `failed`
+ * terminal) AND emits the SAME CIP-0103 `txChanged` events the real provider
+ * emits, so tests can assert against either view.
+ *
+ * Two drive modes:
+ *   - manual: `advance()` steps one phase at a time; `fail()` terminates.
+ *   - auto:   `start()` walks all phases using configurable per-phase delays
+ *             (uses setTimeout — fake-timer friendly).
+ *
+ * Phase → CIP-0103 `txChanged.status` mapping:
+ *   preparing  → 'pending'
+ *   submitting → 'signed'   (payload: { signature, signedBy, party })
+ *   confirming → (no CIP-0103 status — see note)
+ *   finalized  → 'executed' (payload: { updateId, completionOffset })
+ *   failed     → 'failed'
+ *
+ * NOTE — 'confirming' has no CIP-0103 `txChanged` status: the spec's tx union
+ * goes signed → executed with no intermediate "confirming" state. We still
+ * model `isConfirming` as the post-signed waiting window because the session
+ * layer surfaces it as a UI flag. The session-lifecycle harness
+ * (`createSessionHarness`) and the TanStack Query utilities
+ * (`@partylayer/testing/query`) build on top of this controller.
+ */
+
+type LifecyclePhase = 'idle' | 'preparing' | 'submitting' | 'confirming' | 'finalized' | 'failed';
+type LifecycleDelays = Partial<Record<'preparing' | 'submitting' | 'confirming' | 'finalized', number>>;
+interface LifecycleConfig {
+    /** Command id stamped on every emitted event. */
+    commandId?: string;
+    /** Party id used in the 'signed' payload. */
+    party?: string;
+    /** Signature used in the 'signed' payload. */
+    signature?: string;
+    /** Update id used in the 'executed' payload. */
+    updateId?: string;
+    /**
+     * Optional provider to ALSO emit `txChanged` onto (in addition to this
+     * controller's own listeners), so events surface on a mock wallet's bus.
+     */
+    provider?: CIP0103Provider;
+    /** Per-phase delays for auto mode (`start()`). Default 0. */
+    delays?: LifecycleDelays;
+}
+interface TransactionLifecycle {
+    readonly commandId: string;
+    readonly phase: LifecyclePhase;
+    readonly isPreparing: boolean;
+    readonly isSubmitting: boolean;
+    readonly isConfirming: boolean;
+    readonly isFinalized: boolean;
+    readonly isFailed: boolean;
+    /** Subscribe to `txChanged`. Returns an unsubscribe function. */
+    on(event: string, listener: (event: CIP0103TxChangedEvent) => void): () => void;
+    /** Manual step to the next phase; emits the mapped event. Returns the new phase. */
+    advance(): LifecyclePhase;
+    /** Terminal failure: emits `txChanged` `{ status: 'failed' }`. */
+    fail(): void;
+    /** Auto mode: walk every phase with configured delays. Resolves at 'finalized'. */
+    start(): Promise<void>;
+    /** Reset back to 'idle' (does not emit). */
+    reset(): void;
+}
+declare function createTransactionLifecycle(config?: LifecycleConfig): TransactionLifecycle;
+
+/**
+ * Session-lifecycle simulation harness.
+ *
+ * Drives a REAL `@partylayer/session` store through a controllable CIP-0103
+ * provider, so every scenario exercises the store's own machinery — not
+ * synthetic shortcuts:
+ *   - `expire()`            advances the store's REAL expiry timer (the
+ *                           `session:expired` / `onReauthRequired` path); it never
+ *                           emits a fake `session:expired`. Requires fake-timer
+ *                           control via `advanceTimers` (the store arms expiry
+ *                           with `setTimeout`).
+ *   - `dropConnection()` /  emit the provider's real `statusChanged` CIP-0103
+ *     `restoreConnection()` event — the same signal a live wallet sends — driving
+ *                           the store's transient-disconnect / reconnect path.
+ *   - `switchParty()`       emits a real `accountsChanged` with a new primary,
+ *                           driving the store's `party:changed` detection.
+ *   - `openTab()`           returns a second harness whose store shares this
+ *                           harness's in-memory BroadcastChannel hub, so a
+ *                           disconnect in one tab propagates to the other.
+ *
+ * Lifecycle: each harness OWNS its own store; `destroy()` is per-harness (a
+ * child from `openTab()` must be destroyed by the caller — it is not torn down
+ * with its parent).
+ */
+
+interface SessionHarnessConfig {
+    /** Initial primary party id. Default `party::harness-1`. */
+    partyId?: string;
+    /** CAIP-2 network id reported by the provider. Default `canton:da-devnet`. */
+    networkId?: string;
+    /** Expiry TTL (ms) armed on connect. Default `60_000`. Drive it with `expire()`. */
+    ttlMs?: number;
+    /** App re-auth hook invoked by the store's real expiry path. */
+    onReauthRequired?: ExpiryOptions['onReauthRequired'];
+    /** Reconnect policy passed straight to the store (default: store default). */
+    reconnect?: RetryPolicy | false;
+    /**
+     * Advance timers to fire the store's REAL `setTimeout`-based expiry/backoff —
+     * e.g. `vi.advanceTimersByTimeAsync`. Required for `expire()` and for
+     * deterministic reconnect timing. Omit only if you don't call `expire()`.
+     */
+    advanceTimers?: (ms: number) => void | Promise<void>;
+    /** @internal shared multi-tab hub (set by `openTab`). */
+    _hub?: ChannelHub;
+}
+interface SessionHarness {
+    /** The live session store under test. */
+    readonly store: SessionStore;
+    /** The controllable CIP-0103 provider backing the store. */
+    readonly provider: CIP0103Provider;
+    /** Connect via the real store flow (arms the expiry timer). */
+    connect(): Promise<SessionState>;
+    /** Fire a real transient `statusChanged(false)` (NOT an explicit disconnect). */
+    dropConnection(): void;
+    /** Fire a real `statusChanged(true)` to restore the connection. */
+    restoreConnection(): void;
+    /** Fire a real `accountsChanged` with a new primary → `party:changed`. */
+    switchParty(partyId: string): void;
+    /** Advance the store's REAL expiry timer past its TTL (no synthetic emit). */
+    expire(): Promise<void>;
+    /** A second harness sharing this one's broadcast hub (simulates another tab). */
+    openTab(config?: Omit<SessionHarnessConfig, '_hub'>): SessionHarness;
+    /** Tear down THIS harness's store/provider (per-harness; children are separate). */
+    destroy(): void;
+}
+/** A synchronous in-memory BroadcastChannel hub shared across tabs. */
+interface ChannelHub {
+    factory: ChannelFactory;
+}
+/** Build a hub whose channels deliver to OTHER instances only (no echo to sender). */
+declare function createChannelHub(): ChannelHub;
+declare function createSessionHarness(config?: SessionHarnessConfig): SessionHarness;
+
+/**
+ * Reusable browser-test primitives for a real-browser (Playwright) smoke —
+ * framework-agnostic: every helper returns a STRING of JS to run via
+ * `page.addInitScript(...)` / `page.evaluate(...)`, so this package takes NO
+ * dependency on Playwright. The actual smoke lives in `apps/demo/e2e`.
+ */
+interface MockWalletInjectionOptions {
+    /** Key on `window.canton` the wallet registers under. Default `mock`. */
+    walletId?: string;
+    /** Primary party id the mock reports. Default `party::e2e-1`. */
+    partyId?: string;
+    /** CAIP-2 network id. Default `canton:da-devnet`. */
+    networkId?: string;
+}
+/**
+ * An init script that installs a minimal CIP-0103-shaped provider at
+ * `window.canton[walletId]` BEFORE the app loads, so a real-browser test can
+ * drive the connect flow with no extension/live wallet. Inject via
+ * `page.addInitScript({ content: mockWalletInjectionScript() })`.
+ */
+declare function mockWalletInjectionScript(options?: MockWalletInjectionOptions): string;
+/**
+ * A script returning the number of object stores' total entries for an IndexedDB
+ * database (or -1 if the DB does not exist) — used to assert encrypted-session
+ * persistence engaged after a connect. Run via `page.evaluate(idbEntryCountScript(db))`.
+ */
+declare function idbEntryCountScript(dbName: string): string;
+/** The origin-bound IndexedDB name the session key store uses for a given origin. */
+declare function sessionKeyDbName(origin: string): string;
+
+export { type ChannelHub, type LifecycleConfig, type LifecycleDelays, type LifecyclePhase, type MockWalletInjectionOptions, type SessionHarness, type SessionHarnessConfig, type TransactionLifecycle, createChannelHub, createSessionHarness, createTransactionLifecycle, idbEntryCountScript, mockWalletInjectionScript, sessionKeyDbName };

package/dist/index.d.ts

@@ -0,0 +1,177 @@
+export { M as MOCK_SCENARIO_NAMES, a as MockMethod, b as MockScenario, c as MockScenarioName, d as MockWalletClient, e as MockWalletConfig, O as OfflineHarness, T as TxEventRecorder, f as connectMock, g as createMockWallet, h as createMockWalletClient, i as createOfflineHarness, r as recordTxEvents, s as scenarioToError } from './offline-CELeTEq9.js';
+import { CIP0103Provider, CIP0103TxChangedEvent } from '@partylayer/core';
+import { ChannelFactory, SessionStore, SessionState, ExpiryOptions, RetryPolicy } from '@partylayer/session';
+import '@partylayer/provider';
+
+/**
+ * Simulated, controllable transaction lifecycle.
+ *
+ * Exposes the session-layer view (boolean phase flags
+ * isPreparing → isSubmitting → isConfirming → isFinalized, plus a `failed`
+ * terminal) AND emits the SAME CIP-0103 `txChanged` events the real provider
+ * emits, so tests can assert against either view.
+ *
+ * Two drive modes:
+ *   - manual: `advance()` steps one phase at a time; `fail()` terminates.
+ *   - auto:   `start()` walks all phases using configurable per-phase delays
+ *             (uses setTimeout — fake-timer friendly).
+ *
+ * Phase → CIP-0103 `txChanged.status` mapping:
+ *   preparing  → 'pending'
+ *   submitting → 'signed'   (payload: { signature, signedBy, party })
+ *   confirming → (no CIP-0103 status — see note)
+ *   finalized  → 'executed' (payload: { updateId, completionOffset })
+ *   failed     → 'failed'
+ *
+ * NOTE — 'confirming' has no CIP-0103 `txChanged` status: the spec's tx union
+ * goes signed → executed with no intermediate "confirming" state. We still
+ * model `isConfirming` as the post-signed waiting window because the session
+ * layer surfaces it as a UI flag. The session-lifecycle harness
+ * (`createSessionHarness`) and the TanStack Query utilities
+ * (`@partylayer/testing/query`) build on top of this controller.
+ */
+
+type LifecyclePhase = 'idle' | 'preparing' | 'submitting' | 'confirming' | 'finalized' | 'failed';
+type LifecycleDelays = Partial<Record<'preparing' | 'submitting' | 'confirming' | 'finalized', number>>;
+interface LifecycleConfig {
+    /** Command id stamped on every emitted event. */
+    commandId?: string;
+    /** Party id used in the 'signed' payload. */
+    party?: string;
+    /** Signature used in the 'signed' payload. */
+    signature?: string;
+    /** Update id used in the 'executed' payload. */
+    updateId?: string;
+    /**
+     * Optional provider to ALSO emit `txChanged` onto (in addition to this
+     * controller's own listeners), so events surface on a mock wallet's bus.
+     */
+    provider?: CIP0103Provider;
+    /** Per-phase delays for auto mode (`start()`). Default 0. */
+    delays?: LifecycleDelays;
+}
+interface TransactionLifecycle {
+    readonly commandId: string;
+    readonly phase: LifecyclePhase;
+    readonly isPreparing: boolean;
+    readonly isSubmitting: boolean;
+    readonly isConfirming: boolean;
+    readonly isFinalized: boolean;
+    readonly isFailed: boolean;
+    /** Subscribe to `txChanged`. Returns an unsubscribe function. */
+    on(event: string, listener: (event: CIP0103TxChangedEvent) => void): () => void;
+    /** Manual step to the next phase; emits the mapped event. Returns the new phase. */
+    advance(): LifecyclePhase;
+    /** Terminal failure: emits `txChanged` `{ status: 'failed' }`. */
+    fail(): void;
+    /** Auto mode: walk every phase with configured delays. Resolves at 'finalized'. */
+    start(): Promise<void>;
+    /** Reset back to 'idle' (does not emit). */
+    reset(): void;
+}
+declare function createTransactionLifecycle(config?: LifecycleConfig): TransactionLifecycle;
+
+/**
+ * Session-lifecycle simulation harness.
+ *
+ * Drives a REAL `@partylayer/session` store through a controllable CIP-0103
+ * provider, so every scenario exercises the store's own machinery — not
+ * synthetic shortcuts:
+ *   - `expire()`            advances the store's REAL expiry timer (the
+ *                           `session:expired` / `onReauthRequired` path); it never
+ *                           emits a fake `session:expired`. Requires fake-timer
+ *                           control via `advanceTimers` (the store arms expiry
+ *                           with `setTimeout`).
+ *   - `dropConnection()` /  emit the provider's real `statusChanged` CIP-0103
+ *     `restoreConnection()` event — the same signal a live wallet sends — driving
+ *                           the store's transient-disconnect / reconnect path.
+ *   - `switchParty()`       emits a real `accountsChanged` with a new primary,
+ *                           driving the store's `party:changed` detection.
+ *   - `openTab()`           returns a second harness whose store shares this
+ *                           harness's in-memory BroadcastChannel hub, so a
+ *                           disconnect in one tab propagates to the other.
+ *
+ * Lifecycle: each harness OWNS its own store; `destroy()` is per-harness (a
+ * child from `openTab()` must be destroyed by the caller — it is not torn down
+ * with its parent).
+ */
+
+interface SessionHarnessConfig {
+    /** Initial primary party id. Default `party::harness-1`. */
+    partyId?: string;
+    /** CAIP-2 network id reported by the provider. Default `canton:da-devnet`. */
+    networkId?: string;
+    /** Expiry TTL (ms) armed on connect. Default `60_000`. Drive it with `expire()`. */
+    ttlMs?: number;
+    /** App re-auth hook invoked by the store's real expiry path. */
+    onReauthRequired?: ExpiryOptions['onReauthRequired'];
+    /** Reconnect policy passed straight to the store (default: store default). */
+    reconnect?: RetryPolicy | false;
+    /**
+     * Advance timers to fire the store's REAL `setTimeout`-based expiry/backoff —
+     * e.g. `vi.advanceTimersByTimeAsync`. Required for `expire()` and for
+     * deterministic reconnect timing. Omit only if you don't call `expire()`.
+     */
+    advanceTimers?: (ms: number) => void | Promise<void>;
+    /** @internal shared multi-tab hub (set by `openTab`). */
+    _hub?: ChannelHub;
+}
+interface SessionHarness {
+    /** The live session store under test. */
+    readonly store: SessionStore;
+    /** The controllable CIP-0103 provider backing the store. */
+    readonly provider: CIP0103Provider;
+    /** Connect via the real store flow (arms the expiry timer). */
+    connect(): Promise<SessionState>;
+    /** Fire a real transient `statusChanged(false)` (NOT an explicit disconnect). */
+    dropConnection(): void;
+    /** Fire a real `statusChanged(true)` to restore the connection. */
+    restoreConnection(): void;
+    /** Fire a real `accountsChanged` with a new primary → `party:changed`. */
+    switchParty(partyId: string): void;
+    /** Advance the store's REAL expiry timer past its TTL (no synthetic emit). */
+    expire(): Promise<void>;
+    /** A second harness sharing this one's broadcast hub (simulates another tab). */
+    openTab(config?: Omit<SessionHarnessConfig, '_hub'>): SessionHarness;
+    /** Tear down THIS harness's store/provider (per-harness; children are separate). */
+    destroy(): void;
+}
+/** A synchronous in-memory BroadcastChannel hub shared across tabs. */
+interface ChannelHub {
+    factory: ChannelFactory;
+}
+/** Build a hub whose channels deliver to OTHER instances only (no echo to sender). */
+declare function createChannelHub(): ChannelHub;
+declare function createSessionHarness(config?: SessionHarnessConfig): SessionHarness;
+
+/**
+ * Reusable browser-test primitives for a real-browser (Playwright) smoke —
+ * framework-agnostic: every helper returns a STRING of JS to run via
+ * `page.addInitScript(...)` / `page.evaluate(...)`, so this package takes NO
+ * dependency on Playwright. The actual smoke lives in `apps/demo/e2e`.
+ */
+interface MockWalletInjectionOptions {
+    /** Key on `window.canton` the wallet registers under. Default `mock`. */
+    walletId?: string;
+    /** Primary party id the mock reports. Default `party::e2e-1`. */
+    partyId?: string;
+    /** CAIP-2 network id. Default `canton:da-devnet`. */
+    networkId?: string;
+}
+/**
+ * An init script that installs a minimal CIP-0103-shaped provider at
+ * `window.canton[walletId]` BEFORE the app loads, so a real-browser test can
+ * drive the connect flow with no extension/live wallet. Inject via
+ * `page.addInitScript({ content: mockWalletInjectionScript() })`.
+ */
+declare function mockWalletInjectionScript(options?: MockWalletInjectionOptions): string;
+/**
+ * A script returning the number of object stores' total entries for an IndexedDB
+ * database (or -1 if the DB does not exist) — used to assert encrypted-session
+ * persistence engaged after a connect. Run via `page.evaluate(idbEntryCountScript(db))`.
+ */
+declare function idbEntryCountScript(dbName: string): string;
+/** The origin-bound IndexedDB name the session key store uses for a given origin. */
+declare function sessionKeyDbName(origin: string): string;
+
+export { type ChannelHub, type LifecycleConfig, type LifecycleDelays, type LifecyclePhase, type MockWalletInjectionOptions, type SessionHarness, type SessionHarnessConfig, type TransactionLifecycle, createChannelHub, createSessionHarness, createTransactionLifecycle, idbEntryCountScript, mockWalletInjectionScript, sessionKeyDbName };