@kheopskit/core 5.3.0 → 6.0.0-rc.0

package/dist/types-Dkyt9bf4.d.ts

@@ -0,0 +1,683 @@
+import { Observable } from "rxjs";
+//#region src/utils/WalletAccountId.d.ts
+type WalletAccountId = string;
+declare const getWalletAccountId: (walletId: string, address: string) => WalletAccountId;
+declare const parseWalletAccountId: (accountId: string) => {
+  walletId: string;
+  address: string;
+};
+//#endregion
+//#region src/utils/WalletId.d.ts
+type WalletId = string;
+declare const getWalletId: (platform: WalletPlatform, identifier: string) => WalletId;
+declare const parseWalletId: (walletId: string) => {
+  platform: WalletPlatform;
+  identifier: string;
+};
+/**
+ * Non-throwing variant of {@link parseWalletId}. Use when validating untrusted
+ * input (e.g. cached state persisted by an older version) before parsing.
+ */
+declare const isValidWalletId: (walletId: unknown) => walletId is WalletId;
+//#endregion
+//#region src/api/errors.d.ts
+/**
+ * Stable error codes thrown by kheopskit. Catch a {@link KheopskitError} and
+ * branch on `error.code` instead of matching message strings.
+ */
+type KheopskitErrorCode =
+/**
+ * This `connect()` or `disconnect()` call was abandoned. For `connect()`:
+ * its `signal` fired before the platform answered, `disconnect()` was
+ * called while it pended, its wallet disappeared, or the last `kheopskit$`
+ * subscriber unsubscribed.
+ * For either call on an injected wallet: the wallet object came from a
+ * subscription that had already ended, in which case the call rejects
+ * without asking the platform and without changing the remembered list. A
+ * placeholder's `connect()` rejects the same way, its `disconnect()`
+ * resolves, and the WalletConnect connector still calls AppKit.
+ */
+"ABORTED" |
+/** The user refused the wallet's connect prompt. `cause` holds the platform error. */
+"USER_REJECTED" |
+/** The wallet's connect call failed for another reason. `cause` holds the platform error. */
+"CONNECT_FAILED" |
+/**
+ * `connect()` was called on a placeholder wallet restored from the cache:
+ * on `kheopskit$`, hydration ended without kheopskit discovering that
+ * wallet; on `getHydratedSnapshot` and the React provider's initial
+ * snapshot, always.
+ */
+"WALLET_PENDING" |
+/** The wallet does not advertise a capability kheopskit needs to proceed. */
+"FEATURE_NOT_SUPPORTED" |
+/** No active WalletConnect session for the requested operation. */
+"NO_SESSION" |
+/** No provider available for the requested namespace. */
+"NO_PROVIDER" |
+/** The installed polkadot-api version exposes neither `getTxCreatorFromPjs` (v3) nor `getPolkadotSignerFromPjs` (v2). */
+"UNSUPPORTED_VERSION" |
+/** The requested chain cannot be used for this operation (e.g. a Solana cluster with no CAIP-2 id over WalletConnect). */
+"UNSUPPORTED_CHAIN" |
+/** `getKheopskit$` received a config value it cannot use. The message names the fix. */
+"INVALID_CONFIG";
+/**
+ * Error thrown by kheopskit wallet/account operations. Carries a stable
+ * {@link KheopskitErrorCode} and, when relevant, the offending wallet id.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await wallet.connect();
+ * } catch (error) {
+ *   if (error instanceof KheopskitError && error.code === "USER_REJECTED") {
+ *     // the user closed or refused the wallet prompt
+ *   } else throw error;
+ * }
+ * ```
+ */
+declare class KheopskitError extends Error {
+  readonly code: KheopskitErrorCode;
+  /** The wallet id this error relates to, when applicable. */
+  readonly walletId?: WalletId;
+  constructor(code: KheopskitErrorCode, message: string, options?: {
+    walletId?: WalletId;
+    cause?: unknown;
+  });
+}
+//#endregion
+//#region src/api/types.d.ts
+type WalletPlatform = "polkadot" | "ethereum" | "solana";
+/**
+ * Minimal structural view of a WalletConnect `UniversalProvider`, the subset
+ * kheopskit reads. Declared locally so core never depends on
+ * `@walletconnect/universal-provider`. The concrete instance comes from
+ * `@reown/appkit` at runtime.
+ */
+type WalletConnectProvider = {
+  session?: {
+    topic: string;
+    namespaces: Record<string, {
+      accounts?: string[];
+    }>;
+  };
+  client: {
+    request<T = unknown>(args: {
+      topic: string;
+      chainId: string;
+      request: {
+        method: string;
+        params: unknown;
+      };
+    }): Promise<T>;
+  };
+  request(args: {
+    method: string;
+    params?: unknown;
+  }): Promise<unknown>;
+  on(event: string, listener: (...args: unknown[]) => void): void;
+  off(event: string, listener: (...args: unknown[]) => void): void;
+};
+/**
+ * Minimal structural view of the Reown AppKit instance, the subset kheopskit's
+ * account factories use. Exposed as the `appKit` escape hatch on AppKit wallets;
+ * cast it to `@reown/appkit`'s `AppKit` type for the full API. Declared locally
+ * so core never depends on `@reown/appkit`'s types (it's an optional peer).
+ */
+type AppKitInstance = {
+  getProvider<T = WalletConnectProvider>(namespace: string): T | undefined;
+  getAccount(namespace: string): {
+    allAccounts: {
+      address: string;
+    }[];
+  } | undefined;
+  getCaipNetworks(namespace: string): {
+    caipNetworkId?: string;
+  }[];
+};
+type WalletType = "injected" | "walletconnect";
+/**
+ * Where a wallet stands with the dapp. `connecting` covers a `connect()` call
+ * in flight and an auto-reconnect in flight alike.
+ */
+type WalletStatus = "disconnected" | "connecting" | "connected";
+type PolkadotAccountType = "sr25519" | "ed25519" | "ecdsa" | "ethereum";
+/** Options accepted by {@link BaseWallet.connect}. */
+type ConnectOptions = {
+  /**
+   * Ends this caller's wait for the platform's answer: its promise rejects
+   * with a `KheopskitError` of code `ABORTED`. An abort after the platform
+   * has granted the connect changes nothing, and a Polkadot extension counts
+   * as granted only once its account list has been read. Other callers
+   * sharing the attempt keep waiting. Once no caller waits any more,
+   * kheopskit drops a handle the platform hands back afterwards without
+   * revoking the platform's grant, and the wallet is neither connected nor
+   * remembered. The
+   * extension's own prompt may stay open: nothing can withdraw it from the
+   * page. Kheopskit sets no timeout of its own, because an extension prompt
+   * pends only while the user has not answered it; pass
+   * `AbortSignal.timeout(ms)` to cap the wait.
+   */
+  signal?: AbortSignal;
+};
+/**
+ * SDK-free fields common to every wallet, regardless of platform. Platform
+ * packages (`@kheopskit/core/<platform>`) extend this with SDK-typed fields
+ * (the injected provider/extension/standard-wallet handle).
+ */
+type BaseWallet = {
+  /** `<platform>:<identifier>`, e.g. `polkadot:talisman`. Stable across reloads. */
+  id: WalletId;
+  /** The platform whose registry listed the wallet. */
+  platform: WalletPlatform;
+  /**
+   * `"injected"`, for a browser extension or Wallet Standard wallet. The
+   * WalletConnect connector is the separate {@link WalletConnectWallet}.
+   */
+  type: WalletType;
+  /** Display name, e.g. `Talisman`. */
+  name: string;
+  /** Icon URL or data URI. `""` when the wallet exposes none. */
+  icon: string;
+  /**
+   * `true` for a wallet restored from the cache that kheopskit has not
+   * discovered yet: its SDK handle and `sourceId` are absent and it is never
+   * connected. On `kheopskit$` its `connect()` waits for the live wallet and
+   * connects that one, rejecting with `WALLET_PENDING` if hydration ends first
+   * and `ABORTED` if its `signal` fires or the subscription ends. On
+   * `getHydratedSnapshot` it rejects with `WALLET_PENDING`. Its `disconnect()`
+   * resolves at once. Set on every wallet of `kheopskit$` and of the hydrated
+   * snapshot; plugins leave it unset.
+   */
+  isPlaceholder?: boolean;
+  /**
+   * `connecting` while a `connect()` call or an auto-reconnect waits for the
+   * platform, `connected` once the platform granted it, `disconnected`
+   * otherwise. On a reload, a remembered wallet kheopskit will reconnect is
+   * `connecting` from the first frame when the cache recorded it connected,
+   * which the cache does 1 s after the state settles.
+   */
+  status: WalletStatus;
+  /**
+   * The last `connect()` or auto-reconnect that the platform refused or
+   * failed (`USER_REJECTED` or `CONNECT_FAILED`, or `FEATURE_NOT_SUPPORTED`
+   * for a Wallet Standard wallet without `standard:connect`). Cleared when
+   * the next attempt starts. An aborted attempt sets nothing.
+   */
+  error?: KheopskitError;
+  /** `status === "connected"`. */
+  isConnected: boolean;
+  /**
+   * Connects the wallet.
+   *
+   * - **Shared in flight.** Concurrent calls on one wallet share a single
+   *   platform attempt and the platform is asked once. Each call gets its own
+   *   promise: aborting a caller's `signal` rejects only that caller with code
+   *   `ABORTED`. The attempt itself is abandoned only when every caller that
+   *   passed a signal has aborted and no caller without one joined, when
+   *   `disconnect()` is called, or when the last `kheopskit$` subscriber
+   *   unsubscribes; those reject every remaining caller with `ABORTED`.
+   * - **Idempotent.** On a connected wallet it resolves at once without
+   *   touching the platform, unless a `disconnect()` still waits for the
+   *   platform. It then waits for that disconnect to settle and connects
+   *   again if the wallet ended up disconnected.
+   * - **Abortable.** See {@link ConnectOptions.signal}. There is no default
+   *   timeout.
+   * - **Settles with the state.** It resolves only after `kheopskit$` has
+   *   emitted a state in which this wallet has `isConnected: true`, so the
+   *   consumer-visible state already reflects the connect. On platforms that
+   *   list accounts asynchronously (Ethereum `eth_accounts`), the accounts may
+   *   arrive in a later emission. No emission shows a disconnected wallet
+   *   still listing live accounts, or a connected wallet listing the accounts
+   *   of a previous connection. During hydration a wallet's cached
+   *   placeholder accounts stay listed whatever its status. Another wallet's
+   *   pending `eth_accounts` request never delays them. A `disconnect()` that
+   *   completes while it waits for that state rejects it with `ABORTED`. If
+   *   the platform's disconnect is still pending or refuses, it resolves once
+   *   the state shows the wallet connected (today only Solana has a platform
+   *   disconnect). A `connect()`
+   *   whose wallet disappears before the platform grants it (an extension
+   *   removed, a Wallet Standard wallet unregistered) rejects `ABORTED`;
+   *   granted first, it resolves and the wallet stays remembered. Once the last `kheopskit$`
+   *   subscriber has unsubscribed, a call on a wallet object from that
+   *   subscription rejects with `ABORTED` without asking the platform,
+   *   placeholders included.
+   * - **Typed rejections.** A platform rejection is wrapped in a
+   *   `KheopskitError` carrying the original error as `cause` and the
+   *   `walletId`: `USER_REJECTED` when the user refused the prompt,
+   *   `CONNECT_FAILED` otherwise. A Wallet Standard wallet without
+   *   `standard:connect` rejects with `FEATURE_NOT_SUPPORTED`.
+   */
+  connect: (options?: ConnectOptions) => Promise<void>;
+  /**
+   * Disconnects the wallet.
+   *
+   * On a disconnected wallet it resolves at once. While a `connect()` waits
+   * for the platform to grant it, it aborts that connect (its promise rejects
+   * with `ABORTED`) and never waits for the extension prompt. Otherwise it
+   * first waits for the platform's disconnect and rejects if that fails, so
+   * callers can surface or retry. It then resolves once `kheopskit$` has
+   * emitted a state in which this wallet has `isConnected: false`, or once a
+   * later `connect()`, the wallet leaving the list or the end of the
+   * subscription makes that emission impossible. Once the last `kheopskit$`
+   * subscriber has unsubscribed, a call on a wallet object from that
+   * subscription rejects with `ABORTED` without asking the platform and
+   * without changing the remembered list, except on a placeholder, whose
+   * `disconnect()` resolves. A `disconnect()` started before that point
+   * settles once the platform has answered: the wallet was
+   * forgotten when it was called, and nothing else is written once the
+   * subscription has ended.
+   */
+  disconnect: () => Promise<void>;
+};
+/**
+ * SDK-free fields common to every account, regardless of platform. Platform
+ * packages extend this with their SDK-typed signer/client.
+ */
+type BaseWalletAccount = {
+  /** `<walletId>::<address>`, e.g. `polkadot:talisman::5Grw…`. */
+  id: WalletAccountId;
+  /**
+   * `true` for an account restored from the cache that the live wallet has
+   * not listed yet: its signing surface is absent. Set on every account of
+   * `kheopskit$` and of the hydrated snapshot; plugins leave it unset.
+   */
+  isPlaceholder?: boolean;
+  /** The platform of the wallet that lists the account. */
+  platform: WalletPlatform;
+  /** Base58 (Solana), SS58 (Polkadot) or 0x-hex (Ethereum) address. */
+  address: string;
+  /** Friendly account name, when the wallet exposes one (e.g. Polkadot). */
+  name?: string;
+  /** `name` of the wallet that lists the account. */
+  walletName: string;
+  /** `id` of the wallet that lists the account. */
+  walletId: WalletId;
+};
+type LiveWalletConnectWallet = {
+  /** See {@link BaseWallet.isPlaceholder}. */
+  isPlaceholder?: false;
+  /** `"walletconnect"`, the one connector shared by every platform. */
+  id: WalletId;
+  /** Narrow with {@link isWalletConnectWallet}. */
+  type: "walletconnect";
+  /**
+   * Platforms (namespaces) the live session currently carries. Empty until
+   * connected; populated with whatever the wallet approved (e.g. just
+   * `["ethereum"]`, or `["polkadot", "ethereum"]`).
+   */
+  platforms: WalletPlatform[];
+  /**
+   * Raw Reown AppKit instance, exposed as an escape hatch for advanced use
+   * (custom modal control, reading providers directly). Most consumers should
+   * use `connect`/`disconnect` and the derived accounts instead.
+   */
+  appKit: AppKitInstance;
+  /** The name AppKit reports for the paired wallet, `"WalletConnect"` when it reports none. */
+  name: string;
+  /** The icon AppKit reports for the paired wallet, the WalletConnect logo when it reports none. */
+  icon: string;
+  /**
+   * `connecting` while `connect()` opens the modal, `connected` while a
+   * session is live, `disconnected` otherwise. On a reload with a cached
+   * session it is `connecting` until AppKit restores the session or hydration
+   * ends.
+   */
+  status: WalletStatus;
+  /** The last `connect()` whose modal failed to open. Cleared by the next call. */
+  error?: KheopskitError;
+  /** `status === "connected"`. */
+  isConnected: boolean;
+  /**
+   * Opens the WalletConnect modal and resolves once it is open; `isConnected`
+   * follows when the user approves a session. Unlike injected wallets, this
+   * promise does not wait for the state to show the connector connected, and
+   * `signal` is accepted for signature compatibility only.
+   */
+  connect: (options?: ConnectOptions) => Promise<void>;
+  /** Ends the live session when there is one; resolves at once otherwise. */
+  disconnect: () => Promise<void>;
+};
+/**
+ * The single WalletConnect connector, shared across every platform.
+ *
+ * Unlike injected wallets, it is **not tied to a platform**: one WalletConnect
+ * session spans whichever namespaces the remote wallet approves in a single
+ * pairing (a namespace can't be added to a live session afterwards). So there is
+ * exactly one of these in `wallets`, discriminated by `type: "walletconnect"`.
+ * Its accounts appear in `accounts`, each carrying its own `platform`.
+ *
+ * A placeholder (see {@link BaseWallet.isPlaceholder}) has no `appKit`.
+ */
+type WalletConnectWallet = LiveWalletConnectWallet | PlaceholderWallet<LiveWalletConnectWallet, "appKit">;
+/**
+ * The cached stand-in for a live item `T`: `isPlaceholder: true`, and the
+ * fields `K`, which only the live item carries, absent. Platform account and
+ * wallet types are `T | Placeholder<T, K>`, so narrow on `isPlaceholder`
+ * before reading a field of `K`.
+ */
+type Placeholder<T, K extends keyof T> = Omit<T, K | "isPlaceholder"> & {
+  /** Restored from the cache and not yet replaced by the live item. */
+  isPlaceholder: true;
+} & { [P in K]?: undefined; };
+/** A {@link Placeholder} wallet, which is never connected. */
+type PlaceholderWallet<T extends {
+  isConnected: boolean;
+}, K extends keyof T> = Omit<Placeholder<T, K>, "isConnected"> & {
+  isConnected: false;
+};
+/** Narrows a wallet to the platform-less {@link WalletConnectWallet}. */
+declare const isWalletConnectWallet: (wallet: BaseWallet | WalletConnectWallet) => wallet is WalletConnectWallet;
+/**
+ * Narrows a wallet to an injected (browser-extension / Wallet Standard) wallet,
+ * the complement of {@link isWalletConnectWallet}. `state.wallets` is
+ * `(InjectedWallet | WalletConnectWallet)[]`, so use this to recover the
+ * injected-only fields when iterating: `platform`, `sourceId`, and the SDK
+ * handle (`provider` on Ethereum, `extension` on Polkadot, `wallet` on Solana).
+ *
+ * @example
+ * ```ts
+ * for (const wallet of wallets.filter(isInjectedWallet)) {
+ *   console.log(wallet.platform, wallet.sourceId); // typed, no WC widening
+ * }
+ * ```
+ */
+declare const isInjectedWallet: <W extends BaseWallet | WalletConnectWallet>(wallet: W) => wallet is Exclude<W, WalletConnectWallet>;
+/**
+ * Dapp metadata shown in the WalletConnect modal. Mirrors WalletConnect's
+ * `Metadata`, declared locally so core doesn't depend on
+ * `@walletconnect/universal-provider`.
+ */
+type WalletConnectMetadata = {
+  name: string;
+  description: string;
+  url: string;
+  icons: string[];
+};
+/**
+ * The WalletConnect connector for `config.walletConnect`. Create it with
+ * `walletConnect()` from `@kheopskit/core/walletconnect`; that entry is the only
+ * one that loads Reown AppKit.
+ */
+type WalletConnectPlugin = {
+  readonly type: "walletconnect";
+  readonly metadata: WalletConnectMetadata;
+  getWallet$(ctx: PlatformContext): Observable<WalletConnectWallet | null>;
+};
+/**
+ * Context passed to a platform plugin's `getWallets$`. Carries the shared store
+ * and the resolved core config (for WalletConnect / debug).
+ */
+type PlatformContext = {
+  store: KheopskitStore;
+  config: KheopskitConfig;
+};
+/**
+ * A platform plugin. Created by the per-platform factories exported from
+ * `@kheopskit/core/polkadot`, `/ethereum`, `/solana`. Core iterates plugins
+ * generically and never imports a platform SDK itself.
+ *
+ * @typeParam TPlatform - the platform discriminant
+ * @typeParam TWallet - the platform's wallet type (extends {@link BaseWallet})
+ * @typeParam TAccount - the platform's account type (extends {@link BaseWalletAccount})
+ */
+type KheopskitPlatform<TPlatform extends WalletPlatform = WalletPlatform, TWallet extends BaseWallet = BaseWallet, TAccount extends BaseWalletAccount = BaseWalletAccount> = {
+  readonly platform: TPlatform;
+  getWallets$(ctx: PlatformContext): Observable<TWallet[]>;
+  getAccounts$(wallets$: Observable<(TWallet | WalletConnectWallet)[]>): Observable<TAccount[]>;
+  /**
+   * Optional hydration filter. Cached accounts for which this returns false are
+   * dropped during SSR hydration (Polkadot uses it to honour `accountTypes`).
+   */
+  acceptsCachedAccount?(cached: CachedAccount): boolean;
+};
+type ElementOf<T> = T extends readonly (infer E)[] ? E : never;
+/** The account type produced by a plugin (inferred from its `getAccounts$`). */
+type AccountOf<T> = T extends {
+  getAccounts$: (wallets$: never) => Observable<infer R>;
+} ? ElementOf<R> : never;
+/** The wallet type produced by a plugin (inferred from its `getWallets$`). */
+type WalletOf<T> = T extends {
+  getWallets$: (ctx: never) => Observable<infer R>;
+} ? ElementOf<R> : never;
+type KheopskitConfig<P extends readonly KheopskitPlatform[] = readonly KheopskitPlatform[]> = {
+  /**
+   * Which remembered injected wallets kheopskit reconnects after a reload.
+   *
+   * A wallet is remembered on every successful `connect()` and forgotten on
+   * `disconnect()`, whatever this option says; the list is the store's
+   * `remembered`. `true` reconnects every remembered injected wallet, `false`
+   * none, and a function is asked for each cached connected injected wallet
+   * on the first frame, then for each remembered one with its live object
+   * before the attempt. The function must be synchronous and pure. It runs on
+   * the server and on the client for the same input and both must agree, or
+   * the markup diverges. It receives the {@link BaseWallet} fields only, so
+   * key on `id`.
+   *
+   * The WalletConnect row is not governed by this option: AppKit restores its
+   * own session on load, and the row hydrates `connecting` while it does.
+   *
+   * A reconnect opens no connect prompt while the site stays authorised in
+   * the extension. When the authorisation was revoked the extension prompts
+   * once; a refusal forgets the wallet, so the next load stays silent. A manual
+   * `connect()` or `disconnect()` on a remembered wallet ends its automatic
+   * reconnect for the session. A `disconnect()` while the automatic reconnect
+   * still waits for the extension aborts it without forgetting the wallet, so
+   * the next load reconnects it.
+   * Automatic reconnect also ends when the wallet disappears mid-attempt; the
+   * wallet stays remembered for the next load.
+   *
+   * A cached connected wallet this accepts shows `status: "connecting"` from
+   * the first frame until its attempt settles. A wallet this rejects shows
+   * `disconnected` from the first frame, without its cached accounts, so
+   * nothing flashes from connected to disconnected.
+   *
+   * @default true
+   */
+  autoReconnect: boolean | ((wallet: BaseWallet) => boolean);
+  /**
+   * Platform plugins to enable, e.g. `[polkadot(), solana({ chain })]`.
+   * Import factories from `@kheopskit/core/<platform>`.
+   */
+  platforms: P;
+  /** Create with `walletConnect()` from `@kheopskit/core/walletconnect`. */
+  walletConnect?: WalletConnectPlugin;
+  /**
+   * Dapp name sent to Polkadot injected extensions on connect. Some
+   * extensions (e.g. polkadot.js) warn about a suspicious origin when it's
+   * empty.
+   *
+   * @default walletConnect.metadata.name, then window.location.hostname
+   */
+  appName?: string;
+  /**
+   * Logs the resolved config, every state emission and the hydration and
+   * persistence steps with `console.debug`.
+   *
+   * @default false
+   */
+  debug: boolean;
+  /**
+   * Custom storage key for persisting wallet connection state.
+   * Useful when running multiple kheopskit instances on the same domain
+   * to prevent state conflicts between different dapps.
+   *
+   * @default "kheopskit"
+   */
+  storageKey: string;
+  /**
+   * Minimum time in milliseconds the cached placeholders are shown after a
+   * reload, so the wallet list does not flash while extensions inject and
+   * remembered wallets reconnect. Hydration goes on past it until the rule
+   * documented on {@link KheopskitConfig.hydrationTimeout} ends it, and that
+   * timeout wins over a longer grace period. The old cap of six times this
+   * value is gone, so an app that raises it sets `hydrationTimeout` as well.
+   *
+   * `0` disables placeholders: `isHydrating` is `false` from the first
+   * emission.
+   *
+   * @default 500
+   */
+  hydrationGracePeriod: number;
+  /**
+   * Upper bound in milliseconds on {@link KheopskitState.isHydrating}.
+   *
+   * `isHydrating` turns `false` once `hydrationGracePeriod` has elapsed,
+   * discovery has ended ({@link KheopskitState.isDiscovering} is `false`),
+   * and every wallet that hydrated as `connecting` has settled. A wallet has
+   * settled when it is absent from the discovered wallets, connected once its
+   * account list has been read (an empty list counts) or connected with no
+   * cached accounts, disconnected with `error` set, or disconnected and not
+   * remembered when hydration began. At `hydrationTimeout` hydration ends
+   * whatever is pending, and a wallet whose reconnect is still pending stays
+   * `connecting`.
+   *
+   * - Discovery ends only after the page fires `load`, so a page with a cache
+   *   hydrates until `load` or `hydrationTimeout`, whichever comes first,
+   *   even when no wallet reconnects.
+   * - A wallet that reconnects without sharing any account with the site
+   *   settles as soon as it answers; its cached accounts leave the list when
+   *   hydration ends.
+   * - A failed reconnect ends that wallet's wait, even when the reconnect
+   *   policy still permits a retry. A retry runs only when the wallet list next
+   *   changes (a wallet discovered or removed, or any wallet's status, error
+   *   or name changing), which may never happen, so waiting for it would
+   *   hold most failed reconnects until `hydrationTimeout`. A retry that
+   *   does run shows on the live wallet's `status`, not as a placeholder.
+   * - A remembered wallet the user disconnects during or right after its
+   *   reconnect holds hydration, and shows its cached accounts, until
+   *   `hydrationTimeout`.
+   * - A prompt the extension opens for a revoked site holds hydration until
+   *   the user answers or `hydrationTimeout` elapses.
+   *
+   * @default 3000
+   */
+  hydrationTimeout: number;
+};
+/**
+ * The current kheopskit state.
+ *
+ * @remarks
+ * While {@link KheopskitState.isHydrating} is `true`, `wallets` and `accounts`
+ * may contain placeholders restored from the cache, flagged
+ * `isPlaceholder: true`. Each platform type is a union on that flag: a
+ * placeholder lacks the SDK handles (`account.txCreator` or `polkadotSigner`
+ * on Polkadot, `account.client` on Ethereum, `account.signer` / `getSigner` on
+ * Solana, `wallet.extension` / `provider` / `wallet` and `sourceId`). Reading
+ * one without narrowing yields a possibly-`undefined` value, so the compiler
+ * rejects using it as present until you narrow:
+ *
+ * ```ts
+ * if (account.isPlaceholder) return;
+ * account.txCreator; // TxCreator
+ * ```
+ *
+ * A placeholder wallet's `connect()` waits for the live wallet and connects
+ * it, rejecting with `WALLET_PENDING` if hydration ends first. No item is a
+ * placeholder once `isHydrating` is `false`.
+ *
+ * The plain, serializable platform data that is persisted in the cache IS
+ * restored on the placeholders (Ethereum `chainId`, Polkadot key `type`), so it
+ * renders immediately on reload without flashing. Solana `chains` is not
+ * cached: a placeholder account's is empty.
+ */
+type KheopskitState<P extends readonly KheopskitPlatform[] = readonly KheopskitPlatform[]> = {
+  /**
+   * Every discovered wallet, connected or not, then the WalletConnect
+   * connector once AppKit has loaded, when `config.walletConnect` is set.
+   * While `isHydrating` is `true`, also the cached placeholders. Sorted by
+   * platform (Polkadot, Ethereum, Solana, WalletConnect), then Talisman
+   * first, then by name.
+   */
+  wallets: (WalletOf<P[number]> | WalletConnectWallet)[];
+  /**
+   * The accounts of every connected wallet. While `isHydrating` is `true`,
+   * also the cached placeholders of every wallet that has no live account
+   * yet. Grouped by platform, then by wallet (Talisman first, then by wallet
+   * name); inside a wallet, in the order the wallet lists them.
+   */
+  accounts: AccountOf<P[number]>[];
+  /** The resolved config, with every default filled in. */
+  config: KheopskitConfig<P>;
+  /**
+   * Whether the state is still being hydrated from cache.
+   *
+   * During hydration, cached wallets/accounts may be displayed before the
+   * actual wallet extensions have injected. See the type-level remarks: those
+   * are flagged `isPlaceholder: true` and carry no SDK handle.
+   */
+  isHydrating: boolean;
+  /**
+   * Whether wallet discovery may still be incomplete.
+   *
+   * `true` when the subscription started before `document.readyState` was
+   * `"complete"`. It turns `false` in the first emission after `window` fired
+   * `load` and the Polkadot registry (`window.injectedWeb3`) was read again,
+   * so that emission already lists every extension injected by `load`. When the
+   * subscription starts after `load`, it is `false` from the first emission.
+   * Always `true` on the server.
+   *
+   * This rests on wallets injecting `injectedWeb3` before `load`. It says
+   * nothing about wallets that inject after `load`. Ethereum (EIP-6963) and
+   * Solana (Wallet Standard) registries are event-driven and need no re-read.
+   */
+  isDiscovering: boolean;
+};
+/** Shape of the persisted store data (localStorage, or cookies in compact form). */
+type KheopskitStoreData = {
+  /** Wallets the user connected and has not disconnected */
+  remembered?: WalletId[];
+  /** Cached wallet state for SSR hydration to prevent UI flash */
+  cachedWallets?: CachedWallet[];
+  /** Cached account state for SSR hydration to prevent UI flash */
+  cachedAccounts?: CachedAccount[];
+};
+/**
+ * The persisted settings store shared between core and framework bindings.
+ * Declared structurally here (implemented by `createKheopskitStore`) so modules
+ * can depend on the interface without importing the implementation.
+ */
+type KheopskitStore = {
+  observable: Observable<KheopskitStoreData>;
+  rememberWallet: (walletId: WalletId) => void;
+  forgetWallet: (walletId: WalletId) => void;
+  getCachedState: () => {
+    wallets: CachedWallet[];
+    accounts: CachedAccount[];
+  };
+  setCachedState: (wallets: CachedWallet[], accounts: CachedAccount[]) => void;
+  /** Stops cross-tab storage sync and completes `observable`. */
+  destroy: () => void;
+};
+/**
+ * Serializable wallet data for SSR hydration cache.
+ * Contains only the data needed to render wallet UI without flash.
+ * Note: icon is NOT stored to save cookie space - it's looked up at hydration time.
+ */
+type CachedWallet = {
+  id: WalletId;
+  /** Absent for the platform-less WalletConnect connector. */
+  platform?: WalletPlatform;
+  type: WalletType;
+  name: string;
+  isConnected: boolean;
+};
+/**
+ * Serializable account data for SSR hydration cache.
+ * Contains only the data needed to render account UI without flash.
+ */
+type CachedAccount = {
+  id: string;
+  platform: WalletPlatform;
+  address: string;
+  name?: string;
+  /** Cached chain ID for Ethereum accounts. */
+  chainId?: number;
+  /** Cached key type for Polkadot accounts. */
+  polkadotAccountType?: PolkadotAccountType;
+  walletId: WalletId;
+  walletName: string;
+};
+//#endregion
+export { getWalletId as A, WalletStatus as C, KheopskitError as D, isWalletConnectWallet as E, parseWalletAccountId as F, parseWalletId as M, WalletAccountId as N, KheopskitErrorCode as O, getWalletAccountId as P, WalletPlatform as S, isInjectedWallet as T, WalletConnectMetadata as _, CachedAccount as a, WalletConnectWallet as b, KheopskitConfig as c, KheopskitStore as d, KheopskitStoreData as f, PolkadotAccountType as g, PlatformContext as h, BaseWalletAccount as i, isValidWalletId as j, WalletId as k, KheopskitPlatform as l, PlaceholderWallet as m, AppKitInstance as n, CachedWallet as o, Placeholder as p, BaseWallet as r, ConnectOptions as s, AccountOf as t, KheopskitState as u, WalletConnectPlugin as v, WalletType as w, WalletOf as x, WalletConnectProvider as y };
+//# sourceMappingURL=types-Dkyt9bf4.d.ts.map