@fiber-pay/react 0.2.5 → 0.2.6

package/README.md

@@ -5,9 +5,63 @@ React hooks and components for browser payment flows on Fiber.
 ## Install
 
 ```bash
-pnpm add @fiber-pay/react react
+pnpm add @fiber-pay/react @nervosnetwork/fiber-js react
+# optional, for QR codes in NodeInfoPanel
+pnpm add qrcode.react
 ```
 
+`@nervosnetwork/fiber-js` is a peer dependency used by the browser WASM runtime.
+If you provide a custom `wasmFactory`, you can manage that dependency yourself.
+
+## Browser Requirements (WASM + Passkey)
+
+For multithreaded WASM runtime (`SharedArrayBuffer`) in modern browsers, serve your app with:
+
+- `Cross-Origin-Opener-Policy: same-origin`
+- `Cross-Origin-Embedder-Policy: require-corp`
+
+Without these headers, Fiber WASM startup may fail with browser/runtime errors.
+
+Vite example:
+
+```ts
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { defineConfig, type Plugin } from 'vite';
+import react from '@vitejs/plugin-react';
+
+function crossOriginIsolation(): Plugin {
+  return {
+    name: 'cross-origin-isolation',
+    configureServer(server) {
+      server.middlewares.use((_req: IncomingMessage, res: ServerResponse, next: () => void) => {
+        res.setHeader('Cross-Origin-Opener-Policy', 'same-origin');
+        res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp');
+        next();
+      });
+    },
+  };
+}
+
+export default defineConfig({
+  plugins: [react(), crossOriginIsolation()],
+});
+```
+
+Note: `configureServer` only applies to Vite dev server. For production builds,
+set these headers on your web server or CDN (for example Nginx, Cloudflare, Vercel).
+
+## Bundle Size Notes
+
+Browser Fiber WASM artifacts are large by nature. In the current examples, a production build includes
+an additional ~14 MB JS chunk (~6.5 MB gzip) for WASM/runtime assets.
+
+Recommended integration strategy:
+
+- Lazy-mount payment-heavy UI (for example route-level split).
+- Keep WASM-dependent flows behind user intent (open panel, start node, pay flow).
+- Accept a separate large chunk for WASM and tune warnings with `build.chunkSizeWarningLimit` when needed.
+- Document expected bundle budgets in your downstream app so this chunk is intentional, not surprising.
+
 ## One-line import
 
 ```tsx
@@ -24,15 +78,35 @@ export function App() {
 }
 ```
 
+For a complete browser passkey + payment walkthrough, see [docs/wasm-passkey-payment-component-quickstart.md](./docs/wasm-passkey-payment-component-quickstart.md).
+
 ## Component customization
 
 `FiberPayQuickCard` supports lightweight integration hooks:
 
+- `fiber` (reuse existing `useFiberNode()` session)
 - `className`, `style`, `title`
 - `onInvoiceCreated(invoice)`
 - `onPaymentResult(result)`
 - `onError({ scope, message })`
 
+When you already manage connection state (for example with `ConnectButton`), pass the same hook result into `FiberPayQuickCard` so invoices and payments run on the same node session:
+
+```tsx
+import { ConnectButton, FiberPayQuickCard, useFiberNode } from '@fiber-pay/react';
+
+export function UnifiedFlow() {
+  const fiber = useFiberNode({ network: 'testnet', walletId: 'demo-wallet' });
+
+  return (
+    <>
+      <ConnectButton fiber={fiber} strategy="passkey" />
+      <FiberPayQuickCard fiber={fiber} network="testnet" title="Quick Card" />
+    </>
+  );
+}
+```
+
 ## ConnectButton
 
 Use `ConnectButton` with an existing `useFiberNode` result for drop-in integration.
@@ -47,6 +121,118 @@ export function HeaderWallet() {
 }
 ```
 
+## FiberNodeButton
+
+`FiberNodeButton` is a higher-level button + dropdown panel for day-to-day node operations.
+It wraps `ConnectButton` and provides default sections for:
+
+- Connection state and disconnect
+- Channel management (peer connect / open channel)
+- Payment management (create invoice / pay invoice)
+- Optional connector section (custom renderer)
+
+```tsx
+import { FiberNodeButton, useFiberNode } from '@fiber-pay/react';
+
+export function WalletEntry() {
+  const fiber = useFiberNode({ network: 'testnet', walletId: 'demo-wallet' });
+
+  return (
+    <FiberNodeButton
+      fiber={fiber}
+      strategy="passkey"
+      onLog={(message) => console.log(message)}
+    />
+  );
+}
+```
+
+For external funding, pass `externalFunding` with an async `resolve` callback that returns
+`signFundingTx` and optional script / dep overrides.
+
+If you use CCC wallets, `@fiber-pay/sdk/browser` provides
+`createCccExternalFundingResolver(...)` so you do not need to handwrite resolve logic:
+
+```tsx
+import { ccc } from '@ckb-ccc/connector-react';
+import { createCccExternalFundingResolver } from '@fiber-pay/sdk/browser';
+
+const resolveExternalFunding = createCccExternalFundingResolver({
+  signer: cccSigner,
+  knownScripts: Object.values(ccc.KnownScript),
+  ckbRpcUrl: 'https://testnet.ckbapp.dev/',
+});
+```
+
+### Customizing The Panel
+
+`FiberNodeButton` now supports additive panel customization without forking the component:
+
+- `tabs`: reorder / hide built-in tabs and add custom tabs
+- `renderTabContent(tabId, context)`: override tab body rendering
+- `renderAction(context)`: replace default action button UI/behavior for selected actions (context includes `state`)
+- `t(key, fallback, vars?)`: localize labels and copy
+
+Render precedence for a tab body is:
+1. `renderTabContent(tabId, context)` when it returns a value other than `undefined`
+2. `tabs[i].render(context)` for the selected tab (including built-in tab ids)
+3. built-in tab body (`Workbench`, `Channels`, `Diagnostics`)
+
+`renderTabContent` semantics:
+- return `undefined` to fall back to the next renderer
+- return `null` to intentionally render an empty tab body
+
+```tsx
+import { FiberNodeButton, useFiberNode } from '@fiber-pay/react';
+
+export function CustomPanelDemo() {
+  const fiber = useFiberNode({ network: 'testnet', walletId: 'custom-panel-demo' });
+
+  return (
+    <FiberNodeButton
+      fiber={fiber}
+      strategy="passkey"
+      tabs={[
+        { id: 'workbench' },
+        {
+          id: 'my-stats',
+          label: 'My Stats',
+          render: ({ state }) => <div>Peers: {state.connectedPeers.length}</div>,
+        },
+        { id: 'channels' },
+        { id: 'diagnostics', hidden: true },
+      ]}
+      renderAction={({ id, defaultProps }) => {
+        if (id !== 'pay-invoice') {
+          return undefined;
+        }
+
+        return (
+          <button
+            type="button"
+            disabled={defaultProps.disabled}
+            onClick={() => {
+              void defaultProps.onTrigger();
+            }}
+          >
+            {defaultProps.loading ? 'Paying...' : 'Pay Now'}
+          </button>
+        );
+      }}
+      t={(key, fallback) => {
+        const zh: Record<string, string> = {
+          'tabs.workbench': '操作台',
+          'tabs.channels': '通道',
+          'actions.payInvoice': '立即支付',
+        };
+
+        return zh[key] ?? fallback;
+      }}
+    />
+  );
+}
+```
+
 `ConnectButton` uses explicit strategy selection and supports only `"passkey"` or `"password"`.
 
 For custom connected-state panels (for example peer/channel controls), use `renderConnectedDropdown`:
@@ -78,3 +264,48 @@ For custom connected-state panels (for example peer/channel controls), use `rend
 - `useFiberPayment(node)`
 
 `useFiberNode` exposes passkey/password startup, node lifecycle methods, and passkey diagnostics (`passkeySupportReason`, `passkeyUnavailableReason`).
+
+`useFiberPayment` supports both convenience and staged flows:
+
+- `payInvoice(invoice)` (parse + send + wait in one call)
+- `parseInvoice(invoice)`
+- `sendPayment(invoice)`
+- `waitForPayment(paymentHash)`
+
+Staged flow example:
+
+```tsx
+const { parseInvoice, sendPayment, waitForPayment, error } = useFiberPayment(node);
+
+const confirmAndPay = async (invoice: string) => {
+  const parsed = await parseInvoice(invoice);
+  // Render your own confirmation UI before actually sending
+  console.log('Will pay hash:', parsed.invoice.data.payment_hash);
+
+  await sendPayment(invoice);
+  const result = await waitForPayment(parsed.invoice.data.payment_hash);
+  console.log('Payment status:', result.status);
+};
+```
+
+## Error Recovery Pattern
+
+If `useFiberNode` startup fails, `state` may enter `error` and `error` will contain the raw failure message.
+You can retry with the same hook instance (no unmount/remount required):
+
+```tsx
+const { state, error, startWithPasskey, startWithPassword } = useFiberNode({
+  network: 'testnet',
+  walletId: 'demo-wallet',
+});
+
+const retry = async () => {
+  if (state === 'error') {
+    await startWithPasskey();
+    // or: await startWithPassword('your-password');
+  }
+};
+```
+
+For production UIs, map `error` to actionable guidance (for example: COOP/COEP missing, invalid password,
+passkey canceled, secure-context requirement).

package/dist/index.d.ts

@@ -1,13 +1,15 @@
-import { BrowserNodeState, FiberBrowserNode, NodeInfoResult, PasskeySupportReason, FiberBrowserNodeConfig, FiberWasmFactory, GetPaymentResult } from '@fiber-pay/sdk/browser';
+import { BrowserNodeState, FiberBrowserNode, NodeInfoResult, PasskeySupportReason, FiberBrowserNodeConfig, FiberWasmFactory, Script, CellDep, HexString, IFiberClient, Channel, GetPaymentResult, ListPeersResult, GraphNodesResult, GraphChannelsResult, ParseInvoiceResult, SendPaymentResult, PaymentHash } from '@fiber-pay/sdk/browser';
 export { BrowserNodeState, ChannelState, ConfigBuilder, FiberBrowserNode, FiberBrowserNodeConfig, FiberRpcError, FiberWasmFactory, NodeInfoResult, PasskeyCredentialProvider, PasskeySupportReason, PasswordCredentialProvider, RawKeyCredentialProvider, ckbHash, ckbToShannons, derivePublicKey, formatShannonsAsCkb, fromHex, getLockBalanceShannons, scriptToAddress, shannonsToCkb, toHex } from '@fiber-pay/sdk/browser';
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { CSSProperties, ReactNode } from 'react';
+import { CSSProperties, ReactNode, Dispatch, SetStateAction } from 'react';
 
 interface UseFiberNodeOptions {
     network: 'testnet' | 'mainnet';
     walletId?: string;
     nodeConfig?: FiberBrowserNodeConfig['nodeConfig'];
     wasmFactory?: FiberWasmFactory;
+    /** If true, CKB signing key is omitted and external wallet is expected for funding/signing. */
+    externalWallet?: boolean;
     /** If false, suppresses initialization effects (like passkey detection). Default true. */
     enabled?: boolean;
 }
@@ -42,8 +44,13 @@ interface ConnectButtonProps {
      * When provided, the button delegates to this instead of creating its own hook.
      */
     fiber?: UseFiberNodeResult;
-    /** Credential strategy. Explicitly choose either `"passkey"` or `"password"`. */
-    strategy: ConnectStrategy;
+    /** Credential strategy. Defaults to `"passkey"`. */
+    strategy?: ConnectStrategy;
+    /**
+     * Enable external wallet mode (no internal CKB key derivation).
+     * Only applies when ConnectButton manages its own `useFiberNode` instance.
+     */
+    externalWallet?: boolean;
     /** Password for the "password" strategy. */
     password?: string;
     /** Wallet identifier for IndexedDB isolation. */
@@ -85,7 +92,217 @@ interface ConnectButtonConnectedDropdownContext {
 }
 declare function ConnectButton(props: ConnectButtonProps): react_jsx_runtime.JSX.Element;
 
+interface ChannelOpenFlowParams {
+    pubkey: string;
+    fundingAmountCkb: string;
+    externalWallet: boolean;
+    shutdownScript?: Script;
+    fundingLockScript?: Script;
+    fundingLockScriptCellDeps?: CellDep[];
+    signFundingTx?: (txForSigner: unknown) => Promise<unknown>;
+    ckbRpcUrl?: string;
+}
+interface ChannelOpenFlowResult {
+    mode: 'internal' | 'external';
+    channelId: HexString;
+    fundingTxHash?: HexString;
+    unsignedFundingTx?: unknown;
+    signedFundingTx?: Record<string, unknown>;
+}
+interface UseChannelOpenFlowOptions {
+    node: IFiberClient | null;
+    onLog?: (message: string) => void;
+}
+interface UseChannelOpenFlowResult {
+    openChannel: (params: ChannelOpenFlowParams) => Promise<ChannelOpenFlowResult | null>;
+    reset: () => void;
+    isOpening: boolean;
+    error: string | null;
+    diagnostic: string | null;
+    suggestedFundingAmountCkb: string | null;
+    lastResult: ChannelOpenFlowResult | null;
+}
+declare function useChannelOpenFlow(options: UseChannelOpenFlowOptions): UseChannelOpenFlowResult;
+
+interface PanelStatusNotice {
+    tone: 'info' | 'success';
+    text: string;
+}
+interface PanelChannelCounts {
+    active: number;
+    pending: number;
+    closed: number;
+    all: number;
+}
+interface FiberNodeButtonPanelState {
+    activeTab: PanelTab;
+    switchTab: (next: PanelTab) => void;
+    tabPanelId: string;
+    peerPubkey: string;
+    setPeerPubkey: Dispatch<SetStateAction<string>>;
+    peerAddress: string;
+    setPeerAddress: Dispatch<SetStateAction<string>>;
+    fundingAmountCkb: string;
+    setFundingAmountCkb: Dispatch<SetStateAction<string>>;
+    peerListId: string;
+    connectedPeers: PeerInfo[];
+    isRefreshingPeers: boolean;
+    isConnectingPeer: boolean;
+    refreshConnectedPeers: () => Promise<void>;
+    connectPeerByAddress: () => Promise<void>;
+    graphNodes: GraphNodeInfo[];
+    graphChannels: GraphChannelInfo[];
+    isRefreshingGraph: boolean;
+    refreshGraph: () => Promise<void>;
+    channels: Channel[];
+    channelFilter: ChannelFilter;
+    setChannelFilter: Dispatch<SetStateAction<ChannelFilter>>;
+    isRefreshingChannels: boolean;
+    refreshChannels: () => Promise<void>;
+    closeChannel: (channelId: string, force?: boolean) => Promise<void>;
+    selectedChannelId: string | null;
+    setSelectedChannelId: Dispatch<SetStateAction<string | null>>;
+    selectedChannel: Channel | null;
+    selectedPending: boolean;
+    selectedCanClose: boolean;
+    selectedIsClosing: boolean;
+    forceCloseConfirmOpen: boolean;
+    setForceCloseConfirmOpen: Dispatch<SetStateAction<boolean>>;
+    channelCounts: PanelChannelCounts;
+    visibleChannels: Channel[];
+    activeChannelCount: number;
+    invoiceInput: string;
+    setInvoiceInput: Dispatch<SetStateAction<string>>;
+    createdInvoice: string;
+    isCreatingInvoice: boolean;
+    createInvoice: () => Promise<void>;
+    submitPayment: () => Promise<void>;
+    isPaying: boolean;
+    paymentResult: GetPaymentResult | null;
+    channelOpenFlow: UseChannelOpenFlowResult;
+    openChannel: () => Promise<void>;
+    latestError: string | null;
+    statusNotice: PanelStatusNotice | null;
+    refreshDiagnostics: () => Promise<void>;
+    isNodeReady: boolean;
+    connectorContext: FiberNodeButtonConnectorSectionContext;
+}
+
+type ChannelFilter = 'active' | 'pending' | 'closed' | 'all';
+type PanelTab = string;
+type FiberNodeButtonTabId = PanelTab;
+type GraphChannelInfo = GraphChannelsResult['channels'][number];
+type GraphNodeInfo = GraphNodesResult['nodes'][number];
+type PeerInfo = ListPeersResult['peers'][number];
+type FiberNodeButtonI18n = (key: string, fallback: string, vars?: Record<string, string | number>) => string;
+type FiberNodeButtonActionId = 'open-channel' | 'create-invoice' | 'pay-invoice' | 'close-channel' | 'force-close-channel';
+interface FiberNodeButtonActionDefaultPropsBase {
+    label: string;
+    loadingLabel?: string;
+    disabled: boolean;
+    loading?: boolean;
+    onTrigger: () => void | Promise<void>;
+}
+interface FiberNodeButtonOpenChannelActionDefaultProps extends FiberNodeButtonActionDefaultPropsBase {
+    id: 'open-channel';
+}
+interface FiberNodeButtonCreateInvoiceActionDefaultProps extends FiberNodeButtonActionDefaultPropsBase {
+    id: 'create-invoice';
+}
+interface FiberNodeButtonPayInvoiceActionDefaultProps extends FiberNodeButtonActionDefaultPropsBase {
+    id: 'pay-invoice';
+}
+interface FiberNodeButtonCloseChannelActionDefaultProps extends FiberNodeButtonActionDefaultPropsBase {
+    id: 'close-channel';
+    channelId?: string;
+}
+interface FiberNodeButtonForceCloseChannelActionDefaultProps extends FiberNodeButtonActionDefaultPropsBase {
+    id: 'force-close-channel';
+    channelId?: string;
+}
+type FiberNodeButtonActionDefaultProps = FiberNodeButtonOpenChannelActionDefaultProps | FiberNodeButtonCreateInvoiceActionDefaultProps | FiberNodeButtonPayInvoiceActionDefaultProps | FiberNodeButtonCloseChannelActionDefaultProps | FiberNodeButtonForceCloseChannelActionDefaultProps;
+interface FiberNodeButtonTabActions {
+    openChannel: () => Promise<void>;
+    createInvoice: () => Promise<void>;
+    payInvoice: () => Promise<void>;
+    closeChannel: (channelId: string) => Promise<void>;
+    forceCloseChannel: (channelId: string) => Promise<void>;
+}
+interface FiberNodeButtonTabContext {
+    fiber: UseFiberNodeResult;
+    state: FiberNodeButtonPanelState;
+    externalFundingEnabled: boolean;
+    t: FiberNodeButtonI18n;
+    actions: FiberNodeButtonTabActions;
+}
+interface FiberNodeButtonTabConfig {
+    id: FiberNodeButtonTabId;
+    label?: string | ((t: FiberNodeButtonI18n) => string);
+    hidden?: boolean;
+    render?: (context: FiberNodeButtonTabContext) => ReactNode;
+}
+interface FiberNodeButtonRenderActionContext {
+    id: FiberNodeButtonActionId;
+    defaultProps: FiberNodeButtonActionDefaultProps;
+    fiber: UseFiberNodeResult;
+    state: FiberNodeButtonPanelState;
+    t: FiberNodeButtonI18n;
+}
+type FiberNodeButtonRenderAction = (context: FiberNodeButtonRenderActionContext) => ReactNode | undefined;
+interface FiberNodeButtonExternalFundingResolved {
+    signFundingTx: (txForSigner: unknown) => Promise<unknown>;
+    shutdownScript?: Script;
+    fundingLockScript?: Script;
+    fundingLockScriptCellDeps?: CellDep[];
+    ckbRpcUrl?: string;
+}
+interface FiberNodeButtonExternalFundingResolverContext {
+    node: FiberBrowserNode;
+    pubkey: HexString;
+    fundingAmountCkb: string;
+}
+interface FiberNodeButtonExternalFundingConfig {
+    enabled: boolean;
+    resolve: (context: FiberNodeButtonExternalFundingResolverContext) => Promise<FiberNodeButtonExternalFundingResolved>;
+}
+interface FiberNodeButtonConnectorSectionContext {
+    fiber: UseFiberNodeResult;
+    externalFundingEnabled: boolean;
+    isOpeningChannel: boolean;
+}
+interface FiberNodeButtonProps {
+    network?: 'testnet' | 'mainnet';
+    fiber?: UseFiberNodeResult;
+    strategy?: ConnectStrategy;
+    externalWallet?: boolean;
+    password?: string;
+    walletId?: string;
+    passkeyUsername?: string;
+    wasmFactory?: FiberWasmFactory;
+    nodeConfig?: UseFiberNodeOptions['nodeConfig'];
+    className?: string;
+    style?: CSSProperties;
+    dropdownStyle?: CSSProperties;
+    onConnect?: (node: FiberBrowserNode, nodeInfo: NodeInfoResult) => void;
+    onDisconnect?: () => void;
+    onError?: (error: string) => void;
+    onLog?: (message: string) => void;
+    initialPeerPubkey?: string;
+    initialPeerAddress?: string;
+    initialFundingAmountCkb?: string;
+    externalFunding?: FiberNodeButtonExternalFundingConfig;
+    renderConnectorSection?: (context: FiberNodeButtonConnectorSectionContext) => ReactNode;
+    tabs?: ReadonlyArray<FiberNodeButtonTabConfig>;
+    renderTabContent?: (tabId: FiberNodeButtonTabId, context: FiberNodeButtonTabContext) => ReactNode | undefined;
+    renderAction?: FiberNodeButtonRenderAction;
+    t?: FiberNodeButtonI18n;
+}
+
+declare function FiberNodeButton(props: FiberNodeButtonProps): react_jsx_runtime.JSX.Element;
+
 interface FiberPayQuickCardProps {
+    /** Reuse an existing useFiberNode() result instead of creating a new session. */
+    fiber?: UseFiberNodeResult;
     network?: 'testnet' | 'mainnet';
     walletId?: string;
     passkeyUsername?: string;
@@ -124,6 +341,9 @@ interface NodeInfoPanelProps {
 declare function NodeInfoPanel(props: NodeInfoPanelProps): react_jsx_runtime.JSX.Element;
 
 interface UseFiberPaymentResult {
+    parseInvoice: (invoice: string) => Promise<ParseInvoiceResult>;
+    sendPayment: (invoice: string) => Promise<SendPaymentResult>;
+    waitForPayment: (paymentHash: PaymentHash) => Promise<GetPaymentResult>;
     payInvoice: (invoice: string) => Promise<void>;
     isPaying: boolean;
     paymentResult: GetPaymentResult | null;
@@ -131,4 +351,4 @@ interface UseFiberPaymentResult {
 }
 declare function useFiberPayment(node: FiberBrowserNode | null): UseFiberPaymentResult;
 
-export { ConnectButton, type ConnectButtonConnectedDropdownContext, type ConnectButtonProps, type ConnectStrategy, FiberPayQuickCard, type FiberPayQuickCardProps, NodeInfoPanel, type NodeInfoPanelProps, type UseFiberNodeOptions, type UseFiberNodeResult, type UseFiberPaymentResult, useFiberNode, useFiberPayment };
+export { type ChannelOpenFlowParams, type ChannelOpenFlowResult, ConnectButton, type ConnectButtonConnectedDropdownContext, type ConnectButtonProps, type ConnectStrategy, FiberNodeButton, type FiberNodeButtonActionDefaultProps, type FiberNodeButtonActionId, type FiberNodeButtonConnectorSectionContext, type FiberNodeButtonExternalFundingConfig, type FiberNodeButtonExternalFundingResolved, type FiberNodeButtonExternalFundingResolverContext, type FiberNodeButtonI18n, type FiberNodeButtonProps, type FiberNodeButtonRenderAction, type FiberNodeButtonRenderActionContext, type FiberNodeButtonTabActions, type FiberNodeButtonTabConfig, type FiberNodeButtonTabContext, type FiberNodeButtonTabId, FiberPayQuickCard, type FiberPayQuickCardProps, NodeInfoPanel, type NodeInfoPanelProps, type UseChannelOpenFlowOptions, type UseChannelOpenFlowResult, type UseFiberNodeOptions, type UseFiberNodeResult, type UseFiberPaymentResult, useChannelOpenFlow, useFiberNode, useFiberPayment };