@lightninglabs/wavelength-react 0.1.0

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (C) 2026 Lightning Labs and The Lightning Network Developers
+
+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,68 @@
+# @lightninglabs/wavelength-react
+
+React provider and hooks for [Wavelength](https://wavelength.lightning.engineering): embed a
+self-custodial Lightning wallet directly in your app. Your users send and
+receive Lightning payments with no node to run, no channels to open, and no
+inbound liquidity to manage, while their keys stay on their own device.
+
+This package is transport-agnostic. It depends only on
+[`@lightninglabs/wavelength-core`](https://www.npmjs.com/package/@lightninglabs/wavelength-core) and takes an injected engine, so the
+same binding runs over both the web and React Native transports. Build the
+engine with the transport you use, and pass it to `WavelengthProvider`.
+
+## Install
+
+```sh
+# Web (React + the browser transport)
+npm install @lightninglabs/wavelength-react @lightninglabs/wavelength-web
+```
+
+On React Native, install
+[`@lightninglabs/wavelength-react-native`](https://www.npmjs.com/package/@lightninglabs/wavelength-react-native) instead of the web
+transport.
+
+## Quick start
+
+```tsx
+import { WavelengthProvider, useWallet, useWalletBalance, useWalletSend } from "@lightninglabs/wavelength-react";
+import { createWebWalletEngine, defaultConfig } from "@lightninglabs/wavelength-web";
+
+const engine = createWebWalletEngine({
+  runtimeBaseUrl: "https://your-host/wavewalletdk/",
+  config: defaultConfig("signet"),
+  autoStart: true,
+});
+
+function Root() {
+  return (
+    <WavelengthProvider engine={engine}>
+      <Wallet />
+    </WavelengthProvider>
+  );
+}
+
+function Wallet() {
+  const { phase } = useWallet();
+  const balance = useWalletBalance();
+  const { send } = useWalletSend();
+
+  if (phase !== "ready") return <p>Loading… ({phase})</p>;
+
+  return (
+    <div>
+      <p>Spendable: {balance?.confirmedSat ?? 0} sats</p>
+      <button onClick={() => send({ invoice: "lnbc…" })}>Pay</button>
+    </div>
+  );
+}
+```
+
+State-reading hooks like `useWalletBalance()` and `useWalletActivity()` return
+their value directly. Mutation hooks like `useWalletSend()`,
+`useWalletReceive()`, and `useWalletDeposit()` each expose an action plus
+verb-prefixed state, for example `useWalletSend()` returns
+`{ send, sendPending, sendError, sendData, resetSend }`. `useWalletEngine()` is
+the escape hatch for anything the hooks don't cover.
+
+See the [documentation](https://wavelength.lightning.engineering) for the full
+hook reference.

package/dist/hooks.d.ts

@@ -0,0 +1,274 @@
+import type { Balance, CreateWalletRequest, CreateWalletResult, DepositRequest, DepositResult, Entry, ExitBatchEvent, ExitBatchOptions, ExitBatchResult, ExitRequest, ExitResult, ExitStatusResult, ExitSummaryResult, GetExitPlanRequest, GetExitPlanResult, ListRequest, ListResult, PrepareSendResult, ReceiveRequest, ReceiveResult, RecoveryState, RestoreWalletRequest, RuntimeConfig, RuntimePhase, SendRequest, SendResult, SweepWalletRequest, SweepWalletResult, UnlockWalletRequest, UnlockWalletResult, WavelengthLogPayload, WalletInfo } from "@lightninglabs/wavelength-core";
+/**
+ * The application-shell hook: the lifecycle phase to route on, the last fatal
+ * runtime error, and the runtime actions. There are no pending flags here:
+ * phase === 'starting' / 'stopping' already encode them.
+ */
+export declare function useWallet(): {
+    phase: RuntimePhase;
+    error: Error | null;
+    start: (config?: RuntimeConfig) => Promise<WalletInfo>;
+    stop: () => Promise<void>;
+};
+/** The most recent complete wallet info, or null before the runtime reports it. */
+export declare function useWalletInfo(): WalletInfo | null;
+/** The most recent wallet balance, or null before it is known. */
+export declare function useWalletBalance(): Balance | null;
+/** The most recent activity entries, newest-first as returned by the daemon. */
+export declare function useWalletActivity(): readonly Entry[];
+/** The background recovery status and its acknowledge action. */
+export declare function useWalletRecovery(): {
+    recovery: RecoveryState;
+    acknowledge: () => void;
+};
+/** The buffered runtime log tail and a clear action. */
+export declare function useWalletLogs(): {
+    logs: readonly WavelengthLogPayload[];
+    clear: () => void;
+};
+/** The result of {@link useWalletCreate}. */
+export type UseWalletCreateResult = {
+    /** Creates a new wallet. */
+    create: (req: CreateWalletRequest) => Promise<CreateWalletResult>;
+    /** True while a create is in flight. */
+    createPending: boolean;
+    /** The last create failure, or null. */
+    createError: Error | null;
+    /** The last successful create result, or null. */
+    createData: CreateWalletResult | null;
+    /** Clears the create error and data. */
+    resetCreate: () => void;
+};
+/**
+ * Creates a new wallet, exposing `createPending` / `createError` /
+ * `createData`. This hook and {@link useWalletPasskey} both expose a
+ * `create` verb, and destructuring both collides on all four of `create`,
+ * `createPending`, `createError`, and `resetCreate`; components composing
+ * both should keep one as a namespaced object (e.g.
+ * `const passkey = useWalletPasskey(...)`) instead of destructuring both.
+ */
+export declare function useWalletCreate(): UseWalletCreateResult;
+/** The result of {@link useWalletRestore}. */
+export type UseWalletRestoreResult = {
+    /** Restores a wallet from a mnemonic. */
+    restore: (req: RestoreWalletRequest) => Promise<WalletInfo>;
+    /** True while a restore is in flight. */
+    restorePending: boolean;
+    /** The last restore failure, or null. */
+    restoreError: Error | null;
+    /** The last successful restore result, or null. */
+    restoreData: WalletInfo | null;
+    /** Clears the restore error and data. */
+    resetRestore: () => void;
+};
+/**
+ * Restores a wallet from a mnemonic, exposing `restorePending` /
+ * `restoreError` / `restoreData`. The promise (and `restorePending`)
+ * resolve when the wallet is usable, not when the optional recovery scan
+ * finishes; observe the scan through useWalletRecovery.
+ */
+export declare function useWalletRestore(): UseWalletRestoreResult;
+/** The result of {@link useWalletUnlock}. */
+export type UseWalletUnlockResult = {
+    /** Unlocks an existing wallet. */
+    unlock: (req: UnlockWalletRequest) => Promise<UnlockWalletResult>;
+    /** True while an unlock is in flight. */
+    unlockPending: boolean;
+    /** The last unlock failure, or null. */
+    unlockError: Error | null;
+    /** The last successful unlock result, or null. */
+    unlockData: UnlockWalletResult | null;
+    /** Clears the unlock error and data. */
+    resetUnlock: () => void;
+};
+/** Unlocks an existing wallet, exposing `unlockPending` / `unlockError` / `unlockData`. */
+export declare function useWalletUnlock(): UseWalletUnlockResult;
+/** The result of {@link useWalletDeposit}. */
+export type UseWalletDepositResult = {
+    /** Requests an on-chain deposit address. */
+    deposit: (req?: DepositRequest) => Promise<DepositResult>;
+    /** True while a deposit request is in flight. */
+    depositPending: boolean;
+    /** The last deposit failure, or null. */
+    depositError: Error | null;
+    /** The last successful deposit result, or null. */
+    depositData: DepositResult | null;
+    /** Clears the deposit error and data. */
+    resetDeposit: () => void;
+};
+/** Requests an on-chain deposit address, exposing `depositPending` / `depositError` / `depositData`. */
+export declare function useWalletDeposit(): UseWalletDepositResult;
+/** The result of {@link useWalletReceive}. */
+export type UseWalletReceiveResult = {
+    /** Requests a Lightning receive. */
+    receive: (req: ReceiveRequest) => Promise<ReceiveResult>;
+    /** True while a receive is in flight. */
+    receivePending: boolean;
+    /** The last receive failure, or null. */
+    receiveError: Error | null;
+    /** The last successful receive result, or null. */
+    receiveData: ReceiveResult | null;
+    /** Clears the receive error and data. */
+    resetReceive: () => void;
+};
+/** Requests a Lightning receive, exposing `receivePending` / `receiveError` / `receiveData`. */
+export declare function useWalletReceive(): UseWalletReceiveResult;
+/** The result of {@link useWalletPrepareSend}. */
+export type UseWalletPrepareSendResult = {
+    /** Quotes a payment without dispatching it. */
+    prepare: (req: SendRequest) => Promise<PrepareSendResult>;
+    /** True while a prepare is in flight. */
+    preparePending: boolean;
+    /** The last prepare failure, or null. */
+    prepareError: Error | null;
+    /** The last successful prepare result, or null. */
+    prepareData: PrepareSendResult | null;
+    /** Clears the prepare error and data. */
+    resetPrepare: () => void;
+};
+/**
+ * Quotes a payment without dispatching it. `prepareData` holds the latest
+ * quote for a review screen; pair with useWalletSend's `sendPrepared` to
+ * dispatch.
+ */
+export declare function useWalletPrepareSend(): UseWalletPrepareSendResult;
+/** The result of {@link useWalletSend}. */
+export type UseWalletSendResult = {
+    /** Dispatches a payment in one shot. */
+    send: (req: SendRequest) => Promise<SendResult>;
+    /** Dispatches a payment from a quote returned by useWalletPrepareSend. */
+    sendPrepared: (prepared: PrepareSendResult) => Promise<SendResult>;
+    /** True while a send is in flight. */
+    sendPending: boolean;
+    /** The last send failure, or null. */
+    sendError: Error | null;
+    /** The last successful send result, or null. */
+    sendData: SendResult | null;
+    /** Clears the send error and data. */
+    resetSend: () => void;
+};
+/**
+ * Dispatches a payment: `send` is the one-shot path, `sendPrepared` confirms
+ * a quote from useWalletPrepareSend. The two verbs are alternative dispatch
+ * paths for the same payment and share one `sendPending` / `sendError` /
+ * `sendData` slot.
+ */
+export declare function useWalletSend(): UseWalletSendResult;
+/** The result of {@link useWalletRefresh}. */
+export type UseWalletRefreshResult = {
+    /** Re-fetches info, balance, and activity. */
+    refresh: () => Promise<void>;
+    /** True while a refresh triggered by this hook instance is in flight. */
+    refreshPending: boolean;
+    /** The last refresh failure, or null. */
+    refreshError: Error | null;
+    /** Clears the refresh error. */
+    resetRefresh: () => void;
+};
+/**
+ * Re-fetches info, balance, and activity. `refreshPending` tracks this hook
+ * instance's own calls only (what a pull-to-refresh spinner should show);
+ * engine-initiated background refreshes never flip it.
+ */
+export declare function useWalletRefresh(): UseWalletRefreshResult;
+/** The result of {@link useWalletExit}. */
+export type UseWalletExitResult = {
+    /** Starts a single exit (cooperative or unilateral). */
+    exit: (req: ExitRequest) => Promise<ExitResult>;
+    exitPending: boolean;
+    exitError: Error | null;
+    exitData: ExitResult | null;
+    resetExit: () => void;
+};
+/** Starts a single exit for one outpoint. Takes the full request union. */
+export declare function useWalletExit(): UseWalletExitResult;
+/** The result of {@link useWalletExitPlan}. */
+export type UseWalletExitPlanResult = {
+    /** Previews unilateral-exit readiness and funding for a set of outpoints. */
+    plan: (req: GetExitPlanRequest) => Promise<GetExitPlanResult>;
+    planPending: boolean;
+    planError: Error | null;
+    planData: GetExitPlanResult | null;
+    resetPlan: () => void;
+};
+/** Previews unilateral-exit readiness. Pair with useWalletExitBatch to start. */
+export declare function useWalletExitPlan(): UseWalletExitPlanResult;
+/** The result of {@link useWalletList}. */
+export type UseWalletListResult = {
+    /** Lists wallet activity, VTXOs, or on-chain outputs. */
+    list: (req: ListRequest) => Promise<ListResult>;
+    listPending: boolean;
+    listError: Error | null;
+    listData: ListResult | null;
+    resetList: () => void;
+};
+/** Lists wallet data on demand (e.g. VTXOs for an exit picker). */
+export declare function useWalletList(): UseWalletListResult;
+/** The result of {@link useWalletExitBatch}. */
+export type UseWalletExitBatchResult = {
+    /**
+     * Starts a batch of exits. Resolves once every exit has STARTED, not
+     * completed: a unilateral exit runs for hours or days afterward.
+     */
+    exitBatch: (opts: ExitBatchOptions) => Promise<ExitBatchResult>;
+    exitBatchPending: boolean;
+    exitBatchError: Error | null;
+    exitBatchData: ExitBatchResult | null;
+    /** The batch's progress events, in order, for the current or last run. */
+    exitBatchEvents: readonly ExitBatchEvent[];
+    resetExitBatch: () => void;
+};
+/**
+ * Orchestrates a multi-outpoint exit with funding-contention guards. Guards
+ * against re-entrancy: calling `exitBatch` again while a run is already in
+ * flight returns the same in-flight promise instead of starting a second
+ * concurrent run (which would otherwise reset the shared event log out from
+ * under the first run).
+ */
+export declare function useWalletExitBatch(): UseWalletExitBatchResult;
+/** The result of {@link useWalletExits}. */
+export type UseWalletExitsResult = {
+    /** The wallet-wide in-progress exit portfolio, or null before first load. */
+    summary: ExitSummaryResult | null;
+    summaryPending: boolean;
+    summaryError: Error | null;
+    /** Refetches the summary on demand. */
+    refreshSummary: () => Promise<ExitSummaryResult>;
+};
+/**
+ * Reads the in-progress exit portfolio. Fetches on mount and whenever wallet
+ * activity changes (so a completed exit clears without manual refresh).
+ */
+export declare function useWalletExits(): UseWalletExitsResult;
+/** The result of {@link useWalletExitStatus}. */
+export type UseWalletExitStatusResult = {
+    /** The exit's status, or null before first load. */
+    status: ExitStatusResult | null;
+    statusPending: boolean;
+    statusError: Error | null;
+    /** Refetches the status on demand. */
+    refreshStatus: () => Promise<ExitStatusResult>;
+};
+/**
+ * Reads one exit's status. Defaults to the cheap phase-only call; pass
+ * `{ detailed: true }` for tree progress, CSV countdown, and fees (a live
+ * round-trip). Pass `{ pollMs }` to poll while the hook is mounted (a plain
+ * `setInterval` with no visibility/focus gating; polling stops on unmount).
+ * Fetches on mount and whenever `outpoint` or the options change.
+ */
+export declare function useWalletExitStatus(outpoint: string, opts?: {
+    detailed?: boolean;
+    pollMs?: number;
+}): UseWalletExitStatusResult;
+/** The result of {@link useWalletSweep}. */
+export type UseWalletSweepResult = {
+    /** Previews (broadcast:false) or broadcasts (broadcast:true) a backing-wallet sweep to an address. */
+    sweep: (req: SweepWalletRequest) => Promise<SweepWalletResult>;
+    sweepPending: boolean;
+    sweepError: Error | null;
+    sweepData: SweepWalletResult | null;
+    resetSweep: () => void;
+};
+/** Previews or broadcasts a sweep of the backing on-chain wallet. */
+export declare function useWalletSweep(): UseWalletSweepResult;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"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"}

package/dist/hooks.js

@@ -0,0 +1,310 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useWalletEngine } from "./provider.js";
+import { useWalletMutationState } from "./useWalletMutation.js";
+import { useWalletSelector } from "./useWalletSelector.js";
+/**
+ * The application-shell hook: the lifecycle phase to route on, the last fatal
+ * runtime error, and the runtime actions. There are no pending flags here:
+ * phase === 'starting' / 'stopping' already encode them.
+ */
+export function useWallet() {
+    const engine = useWalletEngine();
+    const phase = useWalletSelector((s) => s.phase);
+    const error = useWalletSelector((s) => s.error);
+    const start = useCallback((config) => engine.start(config), [engine]);
+    const stop = useCallback(() => engine.stop(), [engine]);
+    return { phase, error, start, stop };
+}
+/** The most recent complete wallet info, or null before the runtime reports it. */
+export function useWalletInfo() {
+    return useWalletSelector((s) => s.info);
+}
+/** The most recent wallet balance, or null before it is known. */
+export function useWalletBalance() {
+    return useWalletSelector((s) => s.balance);
+}
+/** The most recent activity entries, newest-first as returned by the daemon. */
+export function useWalletActivity() {
+    return useWalletSelector((s) => s.activity);
+}
+/** The background recovery status and its acknowledge action. */
+export function useWalletRecovery() {
+    const engine = useWalletEngine();
+    const recovery = useWalletSelector((s) => s.recovery);
+    const acknowledge = useCallback(() => engine.acknowledgeRecovery(), [engine]);
+    return { recovery, acknowledge };
+}
+/** The buffered runtime log tail and a clear action. */
+export function useWalletLogs() {
+    const engine = useWalletEngine();
+    const logs = useWalletSelector((s) => s.logs);
+    const clear = useCallback(() => engine.clearLogs(), [engine]);
+    return { logs, clear };
+}
+/**
+ * Creates a new wallet, exposing `createPending` / `createError` /
+ * `createData`. This hook and {@link useWalletPasskey} both expose a
+ * `create` verb, and destructuring both collides on all four of `create`,
+ * `createPending`, `createError`, and `resetCreate`; components composing
+ * both should keep one as a namespaced object (e.g.
+ * `const passkey = useWalletPasskey(...)`) instead of destructuring both.
+ */
+export function useWalletCreate() {
+    const engine = useWalletEngine();
+    const m = useWalletMutationState();
+    const create = useCallback((req) => m.track(() => engine.createWallet(req)), [engine, m.track]);
+    return {
+        create,
+        createPending: m.pending,
+        createError: m.error,
+        createData: m.data,
+        resetCreate: m.reset,
+    };
+}
+/**
+ * Restores a wallet from a mnemonic, exposing `restorePending` /
+ * `restoreError` / `restoreData`. The promise (and `restorePending`)
+ * resolve when the wallet is usable, not when the optional recovery scan
+ * finishes; observe the scan through useWalletRecovery.
+ */
+export function useWalletRestore() {
+    const engine = useWalletEngine();
+    const m = useWalletMutationState();
+    const restore = useCallback((req) => m.track(() => engine.restoreWallet(req)), [engine, m.track]);
+    return {
+        restore,
+        restorePending: m.pending,
+        restoreError: m.error,
+        restoreData: m.data,
+        resetRestore: m.reset,
+    };
+}
+/** Unlocks an existing wallet, exposing `unlockPending` / `unlockError` / `unlockData`. */
+export function useWalletUnlock() {
+    const engine = useWalletEngine();
+    const m = useWalletMutationState();
+    const unlock = useCallback((req) => m.track(() => engine.unlockWallet(req)), [engine, m.track]);
+    return {
+        unlock,
+        unlockPending: m.pending,
+        unlockError: m.error,
+        unlockData: m.data,
+        resetUnlock: m.reset,
+    };
+}
+/** Requests an on-chain deposit address, exposing `depositPending` / `depositError` / `depositData`. */
+export function useWalletDeposit() {
+    const engine = useWalletEngine();
+    const m = useWalletMutationState();
+    const deposit = useCallback((req) => m.track(() => engine.deposit(req)), [engine, m.track]);
+    return {
+        deposit,
+        depositPending: m.pending,
+        depositError: m.error,
+        depositData: m.data,
+        resetDeposit: m.reset,
+    };
+}
+/** Requests a Lightning receive, exposing `receivePending` / `receiveError` / `receiveData`. */
+export function useWalletReceive() {
+    const engine = useWalletEngine();
+    const m = useWalletMutationState();
+    const receive = useCallback((req) => m.track(() => engine.receive(req)), [engine, m.track]);
+    return {
+        receive,
+        receivePending: m.pending,
+        receiveError: m.error,
+        receiveData: m.data,
+        resetReceive: m.reset,
+    };
+}
+/**
+ * Quotes a payment without dispatching it. `prepareData` holds the latest
+ * quote for a review screen; pair with useWalletSend's `sendPrepared` to
+ * dispatch.
+ */
+export function useWalletPrepareSend() {
+    const engine = useWalletEngine();
+    const m = useWalletMutationState();
+    const prepare = useCallback((req) => m.track(() => engine.prepareSend(req)), [engine, m.track]);
+    return {
+        prepare,
+        preparePending: m.pending,
+        prepareError: m.error,
+        prepareData: m.data,
+        resetPrepare: m.reset,
+    };
+}
+/**
+ * Dispatches a payment: `send` is the one-shot path, `sendPrepared` confirms
+ * a quote from useWalletPrepareSend. The two verbs are alternative dispatch
+ * paths for the same payment and share one `sendPending` / `sendError` /
+ * `sendData` slot.
+ */
+export function useWalletSend() {
+    const engine = useWalletEngine();
+    const m = useWalletMutationState();
+    const send = useCallback((req) => m.track(() => engine.send(req)), [engine, m.track]);
+    const sendPrepared = useCallback((prepared) => m.track(() => engine.sendPrepared(prepared)), [engine, m.track]);
+    return {
+        send,
+        sendPrepared,
+        sendPending: m.pending,
+        sendError: m.error,
+        sendData: m.data,
+        resetSend: m.reset,
+    };
+}
+/**
+ * Re-fetches info, balance, and activity. `refreshPending` tracks this hook
+ * instance's own calls only (what a pull-to-refresh spinner should show);
+ * engine-initiated background refreshes never flip it.
+ */
+export function useWalletRefresh() {
+    const engine = useWalletEngine();
+    const m = useWalletMutationState();
+    const refresh = useCallback(() => m.track(() => engine.refresh()), [engine, m.track]);
+    return {
+        refresh,
+        refreshPending: m.pending,
+        refreshError: m.error,
+        resetRefresh: m.reset,
+    };
+}
+/** Starts a single exit for one outpoint. Takes the full request union. */
+export function useWalletExit() {
+    const engine = useWalletEngine();
+    const m = useWalletMutationState();
+    const exit = useCallback((req) => m.track(() => engine.exit(req)), [engine, m.track]);
+    return {
+        exit,
+        exitPending: m.pending,
+        exitError: m.error,
+        exitData: m.data,
+        resetExit: m.reset,
+    };
+}
+/** Previews unilateral-exit readiness. Pair with useWalletExitBatch to start. */
+export function useWalletExitPlan() {
+    const engine = useWalletEngine();
+    const m = useWalletMutationState();
+    const plan = useCallback((req) => m.track(() => engine.getExitPlan(req)), [engine, m.track]);
+    return {
+        plan,
+        planPending: m.pending,
+        planError: m.error,
+        planData: m.data,
+        resetPlan: m.reset,
+    };
+}
+/** Lists wallet data on demand (e.g. VTXOs for an exit picker). */
+export function useWalletList() {
+    const engine = useWalletEngine();
+    const m = useWalletMutationState({ keepPreviousData: true });
+    const list = useCallback((req) => m.track(() => engine.list(req)), [engine, m.track]);
+    return {
+        list,
+        listPending: m.pending,
+        listError: m.error,
+        listData: m.data,
+        resetList: m.reset,
+    };
+}
+/**
+ * Orchestrates a multi-outpoint exit with funding-contention guards. Guards
+ * against re-entrancy: calling `exitBatch` again while a run is already in
+ * flight returns the same in-flight promise instead of starting a second
+ * concurrent run (which would otherwise reset the shared event log out from
+ * under the first run).
+ */
+export function useWalletExitBatch() {
+    const engine = useWalletEngine();
+    const m = useWalletMutationState();
+    const [events, setEvents] = useState([]);
+    const inFlight = useRef(null);
+    const exitBatch = useCallback((opts) => {
+        if (inFlight.current)
+            return inFlight.current;
+        setEvents([]);
+        const p = m.track(() => engine.exitBatch({
+            ...opts,
+            onEvent: (event) => setEvents((prev) => [...prev, event]),
+        }));
+        inFlight.current = p;
+        // Clear on settle (both branches) so we never leave a stale in-flight
+        // promise, and never surface an unhandled rejection here.
+        void p.then(() => { inFlight.current = null; }, () => { inFlight.current = null; });
+        return p;
+    }, [engine, m.track]);
+    const resetExitBatch = useCallback(() => {
+        setEvents([]);
+        m.reset();
+    }, [m.reset]);
+    return {
+        exitBatch,
+        exitBatchPending: m.pending,
+        exitBatchError: m.error,
+        exitBatchData: m.data,
+        exitBatchEvents: events,
+        resetExitBatch,
+    };
+}
+/**
+ * Reads the in-progress exit portfolio. Fetches on mount and whenever wallet
+ * activity changes (so a completed exit clears without manual refresh).
+ */
+export function useWalletExits() {
+    const engine = useWalletEngine();
+    const m = useWalletMutationState({ keepPreviousData: true });
+    const activity = useWalletSelector((s) => s.activity);
+    const refreshSummary = useCallback(() => m.track(() => engine.exitSummary()), [engine, m.track]);
+    useEffect(() => {
+        void refreshSummary();
+        // Refetch when the activity slice changes reference (a stream push).
+    }, [refreshSummary, activity]);
+    return {
+        summary: m.data,
+        summaryPending: m.pending,
+        summaryError: m.error,
+        refreshSummary,
+    };
+}
+/**
+ * Reads one exit's status. Defaults to the cheap phase-only call; pass
+ * `{ detailed: true }` for tree progress, CSV countdown, and fees (a live
+ * round-trip). Pass `{ pollMs }` to poll while the hook is mounted (a plain
+ * `setInterval` with no visibility/focus gating; polling stops on unmount).
+ * Fetches on mount and whenever `outpoint` or the options change.
+ */
+export function useWalletExitStatus(outpoint, opts = {}) {
+    const engine = useWalletEngine();
+    const m = useWalletMutationState({ keepPreviousData: true });
+    const { detailed, pollMs } = opts;
+    const refreshStatus = useCallback(() => m.track(() => engine.exitStatus({ outpoint, detailed })), [engine, m.track, outpoint, detailed]);
+    useEffect(() => {
+        void refreshStatus();
+        if (!pollMs)
+            return;
+        const id = setInterval(() => void refreshStatus(), pollMs);
+        return () => clearInterval(id);
+    }, [refreshStatus, pollMs]);
+    return {
+        status: m.data,
+        statusPending: m.pending,
+        statusError: m.error,
+        refreshStatus,
+    };
+}
+/** Previews or broadcasts a sweep of the backing on-chain wallet. */
+export function useWalletSweep() {
+    const engine = useWalletEngine();
+    const m = useWalletMutationState();
+    const sweep = useCallback((req) => m.track(() => engine.sweepWallet(req)), [engine, m.track]);
+    return {
+        sweep,
+        sweepPending: m.pending,
+        sweepError: m.error,
+        sweepData: m.data,
+        resetSweep: m.reset,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from "@lightninglabs/wavelength-core";
+export { WavelengthProvider, useWalletEngine } from "./provider.tsx";
+export * from "./hooks.ts";
+export { useWalletPasskey } from "./useWalletPasskey.ts";
+export type { PasskeyWalletOutcome } from "./useWalletPasskey.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.tsx"],"names":[],"mappings":"AAKA,cAAc,gCAAgC,CAAC;AAG/C,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAGrE,cAAc,YAAY,CAAC;AAG3B,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,YAAY,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -0,0 +1,12 @@
+// Re-export the core contract so a React host can import every type and enum
+// from this one package. Transports are NOT re-exported: create an engine
+// with createWebWalletEngine (wavelength-web) or createNativeWalletEngine
+// (wavelength-react-native) and pass it to WavelengthProvider. Keeping this
+// binding transport-agnostic is what lets it run over web or React Native.
+export * from "@lightninglabs/wavelength-core";
+// The provider and the engine escape hatch.
+export { WavelengthProvider, useWalletEngine } from "./provider.js";
+// The granular state and mutation hooks.
+export * from "./hooks.js";
+// The passkey hook and its outcome type.
+export { useWalletPasskey } from "./useWalletPasskey.js";

package/dist/provider.d.ts

@@ -0,0 +1,22 @@
+import type { WalletEngine } from "@lightninglabs/wavelength-core";
+import { ReactNode } from "react";
+/**
+ * Provides a WalletEngine to descendants. The provider owns nothing: the
+ * consumer creates the engine (typically once, at module scope, via
+ * createWebWalletEngine or createNativeWalletEngine) and owns its lifetime.
+ */
+export declare function WavelengthProvider({ children, engine, }: {
+    /** The subtree that gains access to the wallet engine. */
+    children: ReactNode;
+    /**
+     * A WalletEngine from any transport, e.g. createWebWalletEngine() from
+     * \@lightninglabs/wavelength-web.
+     */
+    engine: WalletEngine;
+}): import("react").JSX.Element;
+/**
+ * Returns the engine from the nearest WavelengthProvider: the escape hatch for
+ * anything the granular hooks do not cover. Throws outside a provider.
+ */
+export declare function useWalletEngine(): WalletEngine;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,EAAE,SAAS,EAA6B,MAAM,OAAO,CAAC;AAI7D;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,QAAQ,EACR,MAAM,GACP,EAAE;IACD,0DAA0D;IAC1D,QAAQ,EAAE,SAAS,CAAC;IACpB;;;OAGG;IACH,MAAM,EAAE,YAAY,CAAC;CACtB,+BAcA;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,YAAY,CAO9C"}

package/dist/provider.js

@@ -0,0 +1,27 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+const WalletEngineContext = createContext(null);
+/**
+ * Provides a WalletEngine to descendants. The provider owns nothing: the
+ * consumer creates the engine (typically once, at module scope, via
+ * createWebWalletEngine or createNativeWalletEngine) and owns its lifetime.
+ */
+export function WavelengthProvider({ children, engine, }) {
+    if (!engine) {
+        throw new Error("WavelengthProvider requires an `engine` prop. Create one with " +
+            "createWebWalletEngine() from @lightninglabs/wavelength-web (or " +
+            "createNativeWalletEngine() from @lightninglabs/wavelength-react-native).");
+    }
+    return (_jsx(WalletEngineContext.Provider, { value: engine, children: children }));
+}
+/**
+ * Returns the engine from the nearest WavelengthProvider: the escape hatch for
+ * anything the granular hooks do not cover. Throws outside a provider.
+ */
+export function useWalletEngine() {
+    const engine = useContext(WalletEngineContext);
+    if (!engine) {
+        throw new Error("useWalletEngine must be used inside WavelengthProvider");
+    }
+    return engine;
+}

package/dist/usePasskeyWallet.d.ts

@@ -0,0 +1,38 @@
+import type { OpenWalletFromPasskeyResult, PasskeyCeremony } from "@lightninglabs/walletdk-core";
+/**
+ * Pairs the Go-side open result with the credential id that was used, so the app
+ * can persist it and scope future unlocks.
+ */
+export type PasskeyWalletOutcome = {
+    /** The result returned by opening the wallet from the passkey. */
+    result: OpenWalletFromPasskeyResult;
+    /** The credential id used in the ceremony, for persistence and scoping. */
+    credentialId: string;
+};
+/** The state and actions returned by {@link usePasskeyWallet}. */
+export type UsePasskeyWallet = {
+    /** Whether the environment supports passkey PRF. */
+    supported: boolean;
+    /** True while a ceremony is in flight. */
+    busy: boolean;
+    /** The last error message, or "" when there is none. */
+    error: string;
+    /** Registers a passkey and creates the wallet from it. */
+    createPasskeyWallet: (appName: string) => Promise<PasskeyWalletOutcome | null>;
+    /**
+     * Asserts a passkey (scoped when allowCredentialId is set, discoverable
+     * otherwise) and imports/unlocks the wallet.
+     */
+    openPasskeyWallet: (allowCredentialId?: string) => Promise<PasskeyWalletOutcome | null>;
+    /** Clears the current error message. */
+    clearError: () => void;
+};
+/**
+ * Drives a passkey ceremony and opens the wallet through the provider's client,
+ * refreshing provider state on success so the phase advances automatically. The
+ * ceremony is injected (browser: webPasskeyCeremony from walletdk-web; native
+ * transports supply their own), which keeps walletdk-react free of any transport
+ * dependency. Must be used inside a {@link WalletDKProvider}.
+ */
+export declare function usePasskeyWallet(ceremony: PasskeyCeremony): UsePasskeyWallet;
+//# sourceMappingURL=usePasskeyWallet.d.ts.map

package/dist/usePasskeyWallet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePasskeyWallet.d.ts","sourceRoot":"","sources":["../src/usePasskeyWallet.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,2BAA2B,EAC3B,eAAe,EAChB,MAAM,8BAA8B,CAAC;AAGtC;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,kEAAkE;IAClE,MAAM,EAAE,2BAA2B,CAAC;IACpC,2EAA2E;IAC3E,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,kEAAkE;AAClE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,oDAAoD;IACpD,SAAS,EAAE,OAAO,CAAC;IACnB,0CAA0C;IAC1C,IAAI,EAAE,OAAO,CAAC;IACd,wDAAwD;IACxD,KAAK,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,mBAAmB,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAAC;IAC/E;;;OAGG;IACH,iBAAiB,EAAE,CACjB,iBAAiB,CAAC,EAAE,MAAM,KACvB,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAAC;IAC1C,wCAAwC;IACxC,UAAU,EAAE,MAAM,IAAI,CAAC;CACxB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,eAAe,GAAG,gBAAgB,CAyE5E"}

package/dist/usePasskeyWallet.js

@@ -0,0 +1,65 @@
+import { useCallback, useEffect, useState } from "react";
+import { useWalletDK } from "./provider";
+/**
+ * Drives a passkey ceremony and opens the wallet through the provider's client,
+ * refreshing provider state on success so the phase advances automatically. The
+ * ceremony is injected (browser: webPasskeyCeremony from walletdk-web; native
+ * transports supply their own), which keeps walletdk-react free of any transport
+ * dependency. Must be used inside a {@link WalletDKProvider}.
+ */
+export function usePasskeyWallet(ceremony) {
+    const { client, refresh } = useWalletDK();
+    const [supported, setSupported] = useState(false);
+    const [busy, setBusy] = useState(false);
+    const [error, setError] = useState("");
+    useEffect(() => {
+        let cancelled = false;
+        ceremony.supportsPasskeyPrf().then((v) => {
+            if (!cancelled)
+                setSupported(v);
+        }, () => {
+            // An injected ceremony whose probe rejects degrades to unsupported
+            // rather than leaving an unhandled rejection.
+            if (!cancelled)
+                setSupported(false);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [ceremony]);
+    const run = useCallback(async (fn) => {
+        setError("");
+        setBusy(true);
+        try {
+            return await fn();
+        }
+        catch (err) {
+            setError(err instanceof Error ? err.message : String(err));
+            return null;
+        }
+        finally {
+            setBusy(false);
+        }
+    }, []);
+    const createPasskeyWallet = useCallback((appName) => run(async () => {
+        const { prfOutput, credentialId } = await ceremony.registerPasskeyWallet(appName);
+        const result = await client.openWalletFromPasskey({ prfOutput });
+        await refresh().catch(() => undefined);
+        return { result, credentialId };
+    }), [run, client, refresh, ceremony]);
+    const openPasskeyWallet = useCallback((allowCredentialId) => run(async () => {
+        const { prfOutput, credentialId } = await ceremony.assertPasskeyPrf(allowCredentialId);
+        const result = await client.openWalletFromPasskey({ prfOutput });
+        await refresh().catch(() => undefined);
+        return { result, credentialId };
+    }), [run, client, refresh, ceremony]);
+    const clearError = useCallback(() => setError(""), []);
+    return {
+        supported,
+        busy,
+        error,
+        createPasskeyWallet,
+        openPasskeyWallet,
+        clearError,
+    };
+}

package/dist/useWalletMutation.d.ts

@@ -0,0 +1,41 @@
+type MutationState<R> = {
+    pending: boolean;
+    error: Error | null;
+    data: R | null;
+};
+/**
+ * Hook-local mutation state shared by every mutation hook: `track` runs one
+ * async operation, clearing the previous error and data up front, capturing a failure
+ * into `error`, and rethrowing the same Error instance so imperative callers
+ * can await/catch (throw-and-capture). A cancelled passkey ceremony rethrows
+ * without being recorded: a dismissed OS prompt is not a failure to display.
+ * `isPasskeyCancelled` (rather than a bare `instanceof`) is used because a
+ * consumer bundle can end up with a duplicate copy of core (e.g. two resolved
+ * package versions), which breaks `instanceof` across the boundary; the
+ * predicate falls back to matching `err.name` for that case.
+ *
+ * Overlapping `track` calls are resolved by call order, not settlement order:
+ * each call is stamped with a monotonically increasing generation, and only
+ * the latest call is allowed to write state. An older call that settles
+ * after a newer one still rethrows to its own caller; it just cannot clobber
+ * the newer call's `pending: true` or its result.
+ *
+ * By default, a new call blanks `data` back to null the moment it starts:
+ * right for a mutation, where a fresh submit should not keep showing the
+ * previous result while it is in flight. Pass `{ keepPreviousData: true }`
+ * for a polling read hook instead, where the same call shape is reused to
+ * refetch: blanking `data` on every refetch would flicker a rendered result
+ * to null on each poll. With the option set, `track` preserves the existing
+ * `data` while `pending` flips true, and keeps preserving it if the call
+ * errors: a transient poll failure surfaces through `error` without blanking
+ * a still-valid last-good result. `data` is only overwritten once a new
+ * result lands.
+ */
+export declare function useWalletMutationState<R>(opts?: {
+    keepPreviousData?: boolean;
+}): {
+    track: (operation: () => Promise<R>) => Promise<R>;
+    reset: () => void;
+} & MutationState<R>;
+export {};
+//# sourceMappingURL=useWalletMutation.d.ts.map

package/dist/useWalletMutation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useWalletMutation.d.ts","sourceRoot":"","sources":["../src/useWalletMutation.ts"],"names":[],"mappings":"AAGA,KAAK,aAAa,CAAC,CAAC,IAAI;IACtB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;CAChB,CAAC;AAIF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE;IAC/C,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,GAAG;IACF,KAAK,EAAE,CAAC,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IACnD,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB,GAAG,aAAa,CAAC,CAAC,CAAC,CA4CnB"}

package/dist/useWalletMutation.js

@@ -0,0 +1,75 @@
+import { isPasskeyCancelled, toError } from "@lightninglabs/wavelength-core";
+import { useCallback, useRef, useState } from "react";
+const IDLE = { pending: false, error: null, data: null };
+/**
+ * Hook-local mutation state shared by every mutation hook: `track` runs one
+ * async operation, clearing the previous error and data up front, capturing a failure
+ * into `error`, and rethrowing the same Error instance so imperative callers
+ * can await/catch (throw-and-capture). A cancelled passkey ceremony rethrows
+ * without being recorded: a dismissed OS prompt is not a failure to display.
+ * `isPasskeyCancelled` (rather than a bare `instanceof`) is used because a
+ * consumer bundle can end up with a duplicate copy of core (e.g. two resolved
+ * package versions), which breaks `instanceof` across the boundary; the
+ * predicate falls back to matching `err.name` for that case.
+ *
+ * Overlapping `track` calls are resolved by call order, not settlement order:
+ * each call is stamped with a monotonically increasing generation, and only
+ * the latest call is allowed to write state. An older call that settles
+ * after a newer one still rethrows to its own caller; it just cannot clobber
+ * the newer call's `pending: true` or its result.
+ *
+ * By default, a new call blanks `data` back to null the moment it starts:
+ * right for a mutation, where a fresh submit should not keep showing the
+ * previous result while it is in flight. Pass `{ keepPreviousData: true }`
+ * for a polling read hook instead, where the same call shape is reused to
+ * refetch: blanking `data` on every refetch would flicker a rendered result
+ * to null on each poll. With the option set, `track` preserves the existing
+ * `data` while `pending` flips true, and keeps preserving it if the call
+ * errors: a transient poll failure surfaces through `error` without blanking
+ * a still-valid last-good result. `data` is only overwritten once a new
+ * result lands.
+ */
+export function useWalletMutationState(opts) {
+    const [state, setState] = useState(IDLE);
+    const generationRef = useRef(0);
+    const keepPreviousData = opts?.keepPreviousData ?? false;
+    const track = useCallback(async (operation) => {
+        const generation = ++generationRef.current;
+        if (keepPreviousData) {
+            setState((s) => ({ ...s, pending: true, error: null }));
+        }
+        else {
+            setState({ pending: true, error: null, data: null });
+        }
+        try {
+            const data = await operation();
+            if (generation === generationRef.current) {
+                setState({ pending: false, error: null, data });
+            }
+            return data;
+        }
+        catch (err) {
+            if (isPasskeyCancelled(err)) {
+                if (generation === generationRef.current) {
+                    setState(IDLE);
+                }
+                throw err;
+            }
+            const error = toError(err);
+            if (generation === generationRef.current) {
+                if (keepPreviousData) {
+                    setState((s) => ({ ...s, pending: false, error }));
+                }
+                else {
+                    setState({ pending: false, error, data: null });
+                }
+            }
+            throw error;
+        }
+    }, [keepPreviousData]);
+    const reset = useCallback(() => {
+        generationRef.current += 1;
+        setState(IDLE);
+    }, []);
+    return { track, reset, ...state };
+}

package/dist/useWalletPasskey.d.ts

@@ -0,0 +1,43 @@
+import type { OpenWalletFromPasskeyResult, PasskeyCeremony } from "@lightninglabs/wavelength-core";
+/**
+ * Pairs the daemon-side open result with the credential id that was used, so
+ * the app can persist it and scope future unlocks.
+ */
+export type PasskeyWalletOutcome = {
+    /** The result returned by opening the wallet from the passkey. */
+    result: OpenWalletFromPasskeyResult;
+    /** The credential id used in the ceremony, for persistence and scoping. */
+    credentialId: string;
+};
+/**
+ * Drives a passkey ceremony and opens the wallet through the engine, which
+ * refetches info and refreshes in the background so the phase advances
+ * automatically. The ceremony is injected (browser: webPasskeyCeremony from
+ * wavelength-web; native transports supply their own), which keeps
+ * wavelength-react transport-free.
+ * Creation and opening track separately because apps render them on different
+ * screens. A cancelled ceremony (PasskeyCancelledError) rejects but is never
+ * recorded into createError/openError. Must be used inside WavelengthProvider.
+ */
+export declare function useWalletPasskey(ceremony: PasskeyCeremony): {
+    /**
+     * Whether the environment supports passkey PRF. Null while the support
+     * probe is in flight; render a brief loading state rather than assuming
+     * either answer.
+     */
+    supported: boolean | null;
+    /** Registers a passkey and creates the wallet from it. */
+    create: (appName: string) => Promise<PasskeyWalletOutcome>;
+    createPending: boolean;
+    createError: Error | null;
+    resetCreate: () => void;
+    /**
+     * Asserts a passkey (scoped when credentialId is set, discoverable
+     * otherwise) and imports/unlocks the wallet.
+     */
+    open: (credentialId?: string) => Promise<PasskeyWalletOutcome>;
+    openPending: boolean;
+    openError: Error | null;
+    resetOpen: () => void;
+};
+//# sourceMappingURL=useWalletPasskey.d.ts.map

package/dist/useWalletPasskey.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useWalletPasskey.d.ts","sourceRoot":"","sources":["../src/useWalletPasskey.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,2BAA2B,EAC3B,eAAe,EAChB,MAAM,gCAAgC,CAAC;AAKxC;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,kEAAkE;IAClE,MAAM,EAAE,2BAA2B,CAAC;IACpC,2EAA2E;IAC3E,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,eAAe,GAAG;IAC3D;;;;OAIG;IACH,SAAS,EAAE,OAAO,GAAG,IAAI,CAAC;IAC1B,0DAA0D;IAC1D,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAC3D,aAAa,EAAE,OAAO,CAAC;IACvB,WAAW,EAAE,KAAK,GAAG,IAAI,CAAC;IAC1B,WAAW,EAAE,MAAM,IAAI,CAAC;IACxB;;;OAGG;IACH,IAAI,EAAE,CAAC,YAAY,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAC/D,WAAW,EAAE,OAAO,CAAC;IACrB,SAAS,EAAE,KAAK,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,MAAM,IAAI,CAAC;CACvB,CAiEA"}

package/dist/useWalletPasskey.js

@@ -0,0 +1,57 @@
+import { useCallback, useEffect, useState } from "react";
+import { useWalletEngine } from "./provider.js";
+import { useWalletMutationState } from "./useWalletMutation.js";
+/**
+ * Drives a passkey ceremony and opens the wallet through the engine, which
+ * refetches info and refreshes in the background so the phase advances
+ * automatically. The ceremony is injected (browser: webPasskeyCeremony from
+ * wavelength-web; native transports supply their own), which keeps
+ * wavelength-react transport-free.
+ * Creation and opening track separately because apps render them on different
+ * screens. A cancelled ceremony (PasskeyCancelledError) rejects but is never
+ * recorded into createError/openError. Must be used inside WavelengthProvider.
+ */
+export function useWalletPasskey(ceremony) {
+    const engine = useWalletEngine();
+    const [supported, setSupported] = useState(null);
+    const createM = useWalletMutationState();
+    const openM = useWalletMutationState();
+    useEffect(() => {
+        let cancelled = false;
+        ceremony.supportsPasskeyPrf().then((v) => {
+            if (!cancelled)
+                setSupported(v);
+        }, () => {
+            // An injected ceremony whose probe rejects degrades to unsupported
+            // rather than leaving an unhandled rejection.
+            if (!cancelled)
+                setSupported(false);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [ceremony]);
+    const openFromPrf = useCallback(async (prfOutput, credentialId) => {
+        const result = await engine.openWalletFromPasskey({ prfOutput });
+        return { result, credentialId };
+    }, [engine]);
+    const create = useCallback((appName) => createM.track(async () => {
+        const { prfOutput, credentialId } = await ceremony.registerPasskeyWallet(appName);
+        return openFromPrf(prfOutput, credentialId);
+    }), [createM.track, ceremony, openFromPrf]);
+    const open = useCallback((credentialId) => openM.track(async () => {
+        const assertion = await ceremony.assertPasskeyPrf(credentialId);
+        return openFromPrf(assertion.prfOutput, assertion.credentialId);
+    }), [openM.track, ceremony, openFromPrf]);
+    return {
+        supported,
+        create,
+        createPending: createM.pending,
+        createError: createM.error,
+        resetCreate: createM.reset,
+        open,
+        openPending: openM.pending,
+        openError: openM.error,
+        resetOpen: openM.reset,
+    };
+}

package/dist/useWalletSelector.d.ts

@@ -0,0 +1,3 @@
+import type { WalletSnapshot } from "@lightninglabs/wavelength-core";
+export declare function useWalletSelector<T>(select: (snap: WalletSnapshot) => T): T;
+//# sourceMappingURL=useWalletSelector.d.ts.map

package/dist/useWalletSelector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useWalletSelector.d.ts","sourceRoot":"","sources":["../src/useWalletSelector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAUrE,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,CAAC,GAAG,CAAC,CAQ3E"}

package/dist/useWalletSelector.js

@@ -0,0 +1,12 @@
+import { useSyncExternalStore } from "react";
+import { useWalletEngine } from "./provider.js";
+// Subscribes a component to one slice of the engine snapshot. The engine
+// keeps slices referentially stable, so useSyncExternalStore's Object.is
+// check makes unrelated changes free. Selectors must return references
+// stored in the snapshot, never freshly built objects; hooks needing several
+// fields call this once per field. The third argument serves the same
+// snapshot during server rendering.
+export function useWalletSelector(select) {
+    const engine = useWalletEngine();
+    return useSyncExternalStore(engine.subscribe, () => select(engine.getSnapshot()), () => select(engine.getSnapshot()));
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@lightninglabs/wavelength-react",
+  "version": "0.1.0",
+  "private": false,
+  "description": "React provider and hooks for the Wavelength self-custodial Lightning wallet SDK.",
+  "license": "MIT",
+  "homepage": "https://wavelength.lightning.engineering",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lightninglabs/wavelength-sdk.git",
+    "directory": "packages/react"
+  },
+  "bugs": "https://github.com/lightninglabs/wavelength-sdk/issues",
+  "keywords": [
+    "lightning",
+    "bitcoin",
+    "wallet",
+    "self-custodial",
+    "payments",
+    "react",
+    "hooks"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "@lightninglabs/wavelength-core": "0.1.0"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@happy-dom/global-registrator": "^20.10.6",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "tsx": "^4.23.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --import tsx --import ./src/testing/setup.ts --test"
+  }
+}