@idealyst/mcp-server 1.2.106 → 1.2.108

package/dist/index.cjs

@@ -5245,6 +5245,7 @@ Cross-platform storage solution for React and React Native applications. Provide
 - **React Native** - Uses MMKV for high-performance storage
 - **Web** - Uses localStorage with proper error handling
 - **TypeScript** - Full type safety and IntelliSense support
+- **Secure Storage** - Optional encrypted storage via \`createSecureStorage()\` (Keychain on native, Web Crypto on web)
 
 ## Installation
 
@@ -5648,6 +5649,127 @@ async function safeStorageOperation() {
 6. **Data Size** - Keep stored objects reasonably sized
 7. **Cleanup** - Periodically clean up unused data
 8. **Type Safety** - Create typed wrapper functions for better TypeScript support
+9. **Use Secure Storage for Secrets** - Use \`createSecureStorage()\` for auth tokens, API keys, and sensitive data
+`,
+  "idealyst://storage/secure": `# Secure Storage
+
+Encrypted storage for sensitive data like auth tokens, API keys, and secrets. Uses the same \`IStorage\` interface as regular storage \u2014 drop-in replacement.
+
+## Installation
+
+\`\`\`bash
+yarn add @idealyst/storage
+
+# React Native also needs (for secure storage):
+yarn add react-native-keychain react-native-mmkv
+cd ios && pod install
+\`\`\`
+
+## Quick Start
+
+\`\`\`tsx
+import { createSecureStorage } from '@idealyst/storage';
+
+// Create a secure storage instance
+const secureStorage = createSecureStorage();
+
+// Same API as regular storage
+await secureStorage.setItem('authToken', 'eyJhbGciOiJIUzI1NiIs...');
+const token = await secureStorage.getItem('authToken');
+await secureStorage.removeItem('authToken');
+await secureStorage.clear();
+const keys = await secureStorage.getAllKeys();
+
+// Listeners work too
+const unsubscribe = secureStorage.addListener((key, value) => {
+  console.log('Secure storage changed:', key);
+});
+\`\`\`
+
+## Options
+
+\`\`\`tsx
+import { createSecureStorage, SecureStorageOptions } from '@idealyst/storage';
+
+const secureStorage = createSecureStorage({
+  prefix: 'myapp', // Namespace for keys (default: 'secure')
+});
+\`\`\`
+
+The \`prefix\` option controls:
+- **Native**: Keychain service name and MMKV instance ID
+- **Web**: localStorage key prefix and IndexedDB key name
+
+Use different prefixes to create isolated secure storage instances.
+
+## How It Works
+
+### React Native
+1. A random 16-byte encryption key is generated on first use
+2. The key is stored in the **iOS Keychain** / **Android Keystore** (hardware-backed)
+3. An encrypted MMKV instance is created using that key
+4. All data is encrypted at rest by MMKV's native AES encryption
+5. Keychain accessibility is set to \`WHEN_UNLOCKED_THIS_DEVICE_ONLY\` (not backed up, only accessible when device is unlocked)
+
+### Web
+1. A non-extractable AES-256-GCM \`CryptoKey\` is generated on first use
+2. The key is stored in **IndexedDB** (non-extractable \u2014 cannot be read as raw bytes)
+3. Each value is encrypted with a unique random IV before storing in localStorage
+4. Requires a **secure context** (HTTPS) for \`crypto.subtle\` access
+
+## Usage Example: Secure Auth Service
+
+\`\`\`tsx
+import { createSecureStorage } from '@idealyst/storage';
+
+const secureStorage = createSecureStorage({ prefix: 'auth' });
+
+interface AuthTokens {
+  accessToken: string;
+  refreshToken: string;
+  expiresAt: number;
+}
+
+class SecureAuthService {
+  static async saveTokens(tokens: AuthTokens) {
+    await secureStorage.setItem('tokens', JSON.stringify(tokens));
+  }
+
+  static async getTokens(): Promise<AuthTokens | null> {
+    const data = await secureStorage.getItem('tokens');
+    return data ? JSON.parse(data) as AuthTokens : null;
+  }
+
+  static async clearTokens() {
+    await secureStorage.removeItem('tokens');
+  }
+
+  static async saveApiKey(key: string) {
+    await secureStorage.setItem('apiKey', key);
+  }
+
+  static async getApiKey(): Promise<string | null> {
+    return secureStorage.getItem('apiKey');
+  }
+}
+\`\`\`
+
+## When to Use Secure vs Regular Storage
+
+| Data Type | Use |
+|-----------|-----|
+| Auth tokens, refresh tokens | \`createSecureStorage()\` |
+| API keys, client secrets | \`createSecureStorage()\` |
+| User preferences, theme | \`storage\` (regular) |
+| Cache data | \`storage\` (regular) |
+| Session IDs | \`createSecureStorage()\` |
+| Language preference | \`storage\` (regular) |
+
+## Platform Requirements
+
+- **React Native**: Requires \`react-native-keychain\` (>=9.0.0) and \`react-native-mmkv\` (>=4.0.0)
+- **Web**: Requires secure context (HTTPS) and IndexedDB support
+- **Web limitation**: IndexedDB may not be available in some private browsing modes
 `
 };
 
@@ -6899,6 +7021,156 @@ function UploadForm() {
       "Use customMimeTypes for specific formats like 'application/pdf'"
     ],
     relatedPackages: ["components", "camera", "storage"]
+  },
+  clipboard: {
+    name: "Clipboard",
+    npmName: "@idealyst/clipboard",
+    description: "Cross-platform clipboard and OTP autofill for React and React Native. Copy/paste text and auto-detect SMS verification codes on mobile.",
+    category: "utility",
+    platforms: ["web", "native"],
+    documentationStatus: "full",
+    installation: "yarn add @idealyst/clipboard",
+    peerDependencies: [
+      "@react-native-clipboard/clipboard (native)",
+      "react-native-otp-verify (Android OTP, optional)"
+    ],
+    features: [
+      "Cross-platform copy/paste with async API",
+      "Android SMS OTP auto-read via SMS Retriever API (no permissions)",
+      "iOS OTP keyboard autofill via TextInput props",
+      "Clipboard change listeners",
+      "Graceful degradation when native modules missing"
+    ],
+    quickStart: `import { clipboard } from '@idealyst/clipboard';
+
+// Copy text
+await clipboard.copy('Hello, world!');
+
+// Paste text
+const text = await clipboard.paste();
+
+// OTP auto-fill (mobile)
+import { useOTPAutoFill, OTP_INPUT_PROPS } from '@idealyst/clipboard';
+
+function OTPScreen() {
+  const { code, startListening } = useOTPAutoFill({
+    codeLength: 6,
+    onCodeReceived: (otp) => verifyOTP(otp),
+  });
+
+  useEffect(() => { startListening(); }, []);
+
+  return <TextInput value={code ?? ''} {...OTP_INPUT_PROPS} />;
+}`,
+    apiHighlights: [
+      "clipboard.copy(text) - Copy text to clipboard",
+      "clipboard.paste() - Read text from clipboard",
+      "clipboard.hasText() - Check if clipboard has text",
+      "clipboard.addListener(fn) - Listen for copy events",
+      "useOTPAutoFill({ codeLength, onCodeReceived }) - Auto-detect SMS OTP codes (Android)",
+      "OTP_INPUT_PROPS - TextInput props for iOS OTP keyboard autofill"
+    ],
+    relatedPackages: ["storage", "components"]
+  },
+  biometrics: {
+    name: "Biometrics",
+    npmName: "@idealyst/biometrics",
+    description: "Cross-platform biometric authentication and passkeys (WebAuthn/FIDO2) for React and React Native. FaceID, TouchID, fingerprint, iris, and passwordless login.",
+    category: "auth",
+    platforms: ["web", "native"],
+    documentationStatus: "full",
+    installation: "yarn add @idealyst/biometrics",
+    peerDependencies: [
+      "expo-local-authentication (native biometrics)",
+      "react-native-passkeys (native passkeys, optional)"
+    ],
+    features: [
+      "Local biometric auth \u2014 FaceID, TouchID, fingerprint, iris",
+      "Passkeys (WebAuthn/FIDO2) \u2014 passwordless login with cryptographic credentials",
+      "Cross-platform \u2014 single API for web and React Native",
+      "Web biometrics via WebAuthn userVerification",
+      "Web passkeys via navigator.credentials",
+      "Graceful degradation when native modules missing",
+      "Base64url encoding helpers for WebAuthn data"
+    ],
+    quickStart: `import { isBiometricAvailable, authenticate } from '@idealyst/biometrics';
+
+// Check biometric availability
+const available = await isBiometricAvailable();
+
+// Authenticate
+if (available) {
+  const result = await authenticate({ promptMessage: 'Verify your identity' });
+  if (result.success) {
+    // Authenticated!
+  }
+}
+
+// Passkeys
+import { isPasskeySupported, createPasskey, getPasskey } from '@idealyst/biometrics';
+
+const credential = await createPasskey({
+  challenge: serverChallenge,
+  rp: { id: 'example.com', name: 'My App' },
+  user: { id: userId, name: email, displayName: name },
+});`,
+    apiHighlights: [
+      "isBiometricAvailable() - Check biometric hardware and enrollment",
+      "getBiometricTypes() - Get available biometric types",
+      "getSecurityLevel() - Get device security level",
+      "authenticate(options) - Prompt for biometric auth",
+      "cancelAuthentication() - Cancel auth (Android)",
+      "isPasskeySupported() - Check passkey support",
+      "createPasskey(options) - Register a new passkey",
+      "getPasskey(options) - Authenticate with passkey"
+    ],
+    relatedPackages: ["oauth-client", "storage"]
+  },
+  payments: {
+    name: "Payments",
+    npmName: "@idealyst/payments",
+    description: "Cross-platform payment provider abstractions for React and React Native. Wraps Stripe Platform Pay API for Apple Pay and Google Pay on mobile. Web provides a stub directing to Stripe Elements.",
+    category: "utility",
+    platforms: ["web", "native"],
+    documentationStatus: "full",
+    installation: "yarn add @idealyst/payments @stripe/stripe-react-native",
+    peerDependencies: [
+      "@stripe/stripe-react-native (native)"
+    ],
+    features: [
+      "Apple Pay via Stripe Platform Pay (iOS)",
+      "Google Pay via Stripe Platform Pay (Android)",
+      "Flat function API + usePayments convenience hook",
+      "PaymentIntent confirmation flow",
+      "Payment method creation flow",
+      "Normalized error handling across platforms",
+      "Graceful degradation when Stripe SDK missing",
+      "Web stub with guidance to Stripe Elements"
+    ],
+    quickStart: `import { usePayments } from '@idealyst/payments';
+
+const { isReady, isApplePayAvailable, confirmPayment } = usePayments({
+  config: {
+    publishableKey: 'pk_test_xxx',
+    merchantIdentifier: 'merchant.com.myapp',
+    merchantName: 'My App',
+    merchantCountryCode: 'US',
+  },
+});
+
+const result = await confirmPayment({
+  clientSecret: 'pi_xxx_secret_xxx',
+  amount: { amount: 1099, currencyCode: 'usd' },
+});`,
+    apiHighlights: [
+      "initializePayments(config) - Initialize Stripe SDK",
+      "checkPaymentAvailability() - Check Apple Pay / Google Pay / card",
+      "confirmPayment(request) - Present sheet and confirm PaymentIntent",
+      "createPaymentMethod(request) - Present sheet and create payment method",
+      "getPaymentStatus() - Get current provider status",
+      "usePayments(options?) - Convenience hook with state management"
+    ],
+    relatedPackages: ["biometrics", "oauth-client"]
   }
 };
 function getPackagesByCategory() {
@@ -9471,8 +9743,8 @@ var getStorageGuideDefinition = {
     properties: {
       topic: {
         type: "string",
-        description: "Topic to get docs for: 'overview', 'api', 'examples'",
-        enum: ["overview", "api", "examples"]
+        description: "Topic to get docs for: 'overview', 'api', 'examples', 'secure'",
+        enum: ["overview", "api", "examples", "secure"]
       }
     },
     required: ["topic"]
@@ -9643,6 +9915,51 @@ var getChartsGuideDefinition = {
     required: ["topic"]
   }
 };
+var getClipboardGuideDefinition = {
+  name: "get_clipboard_guide",
+  description: "Get documentation for @idealyst/clipboard cross-platform clipboard and OTP autofill package. Covers copy/paste API, useOTPAutoFill hook, and examples.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      topic: {
+        type: "string",
+        description: "Topic to get docs for: 'overview', 'api', 'examples'",
+        enum: ["overview", "api", "examples"]
+      }
+    },
+    required: ["topic"]
+  }
+};
+var getBiometricsGuideDefinition = {
+  name: "get_biometrics_guide",
+  description: "Get documentation for @idealyst/biometrics cross-platform biometric authentication and passkeys (WebAuthn/FIDO2) package. Covers local biometric auth, passkey registration/login, and examples.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      topic: {
+        type: "string",
+        description: "Topic to get docs for: 'overview', 'api', 'examples'",
+        enum: ["overview", "api", "examples"]
+      }
+    },
+    required: ["topic"]
+  }
+};
+var getPaymentsGuideDefinition = {
+  name: "get_payments_guide",
+  description: "Get documentation for @idealyst/payments cross-platform payment provider package. Covers Apple Pay, Google Pay, Stripe Platform Pay, usePayments hook, and examples.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      topic: {
+        type: "string",
+        description: "Topic to get docs for: 'overview', 'api', 'examples'",
+        enum: ["overview", "api", "examples"]
+      }
+    },
+    required: ["topic"]
+  }
+};
 var listPackagesDefinition = {
   name: "list_packages",
   description: "List all available Idealyst packages with descriptions, categories, and documentation status. Use this to discover what packages are available in the framework.",
@@ -9797,6 +10114,9 @@ var toolDefinitions = [
   getMarkdownGuideDefinition,
   getConfigGuideDefinition,
   getChartsGuideDefinition,
+  getClipboardGuideDefinition,
+  getBiometricsGuideDefinition,
+  getPaymentsGuideDefinition,
   // Package tools
   listPackagesDefinition,
   getPackageDocsDefinition,
@@ -10589,7 +10909,8 @@ yarn add @idealyst/audio
 1. **PCM Streaming** \u2014 Audio data is delivered as \`PCMData\` chunks via callbacks, not as files
 2. **Audio Session** \u2014 On iOS/Android, configure the audio session category before recording/playback
 3. **Audio Profiles** \u2014 Pre-configured \`AudioConfig\` presets: \`speech\`, \`highQuality\`, \`studio\`, \`phone\`
-4. **Session Presets** \u2014 Pre-configured \`AudioSessionConfig\` presets: \`playback\`, \`record\`, \`voiceChat\`, \`ambient\`, \`default\`
+4. **Session Presets** \u2014 Pre-configured \`AudioSessionConfig\` presets: \`playback\`, \`record\`, \`voiceChat\`, \`ambient\`, \`default\`, \`backgroundRecord\`
+5. **Background Recording** \u2014 \`useBackgroundRecorder\` hook for recording that continues when the app is backgrounded (iOS/Android). Requires app-level native entitlements.
 
 ## Exports
 
@@ -10598,10 +10919,14 @@ import {
   useRecorder,
   usePlayer,
   useAudio,
+  useBackgroundRecorder,
   AUDIO_PROFILES,
   SESSION_PRESETS,
 } from '@idealyst/audio';
-import type { PCMData, AudioConfig, AudioLevel } from '@idealyst/audio';
+import type {
+  PCMData, AudioConfig, AudioLevel,
+  BackgroundRecorderStatus, BackgroundLifecycleInfo,
+} from '@idealyst/audio';
 \`\`\`
 `,
   "idealyst://audio/api": `# @idealyst/audio \u2014 API Reference
@@ -10711,6 +11036,84 @@ interface UseAudioOptions {
 
 ---
 
+### useBackgroundRecorder(options?)
+
+Background-aware recording hook. Wraps \`useRecorder\` with app lifecycle management for recording that continues when the app is backgrounded on iOS/Android. On web, works identically to \`useRecorder\` (background events never fire).
+
+> **Requires app-level native configuration** \u2014 see "Background Recording Setup" below.
+
+\`\`\`typescript
+interface UseBackgroundRecorderOptions {
+  config?: Partial<AudioConfig>;              // Audio config
+  session?: Partial<AudioSessionConfig>;      // Session config (default: SESSION_PRESETS.backgroundRecord)
+  autoRequestPermission?: boolean;            // Auto-request mic permission on mount
+  levelUpdateInterval?: number;               // Level update interval in ms (default: 100)
+  maxBackgroundDuration?: number;             // Max background recording time in ms (undefined = no limit)
+  autoConfigureSession?: boolean;             // Auto-configure session for background (default: true)
+  onLifecycleEvent?: BackgroundLifecycleCallback; // Lifecycle event callback
+}
+\`\`\`
+
+**Returns \`UseBackgroundRecorderResult\`:**
+
+All properties from \`useRecorder\`, plus:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| isInBackground | boolean | Whether the app is currently backgrounded |
+| wasInterrupted | boolean | Whether recording was interrupted (phone call, Siri, etc.) |
+| backgroundDuration | number | Total time spent recording in background (ms) |
+| appState | AppStateStatus | Current app state (\`'active' \\| 'background' \\| 'inactive'\`) |
+
+**Lifecycle events** (via \`onLifecycleEvent\`):
+
+| Event | When | Extra fields |
+|-------|------|-------------|
+| \`'backgrounded'\` | App enters background while recording | \u2014 |
+| \`'foregrounded'\` | App returns to foreground while recording | \`backgroundDuration\` |
+| \`'interrupted'\` | OS interrupts recording (phone call, Siri) | \u2014 |
+| \`'interruptionEnded'\` | OS interruption ends | \`shouldResume\` |
+| \`'maxDurationReached'\` | Background recording hit \`maxBackgroundDuration\` | \`backgroundDuration\` |
+| \`'stopped'\` | Recording stopped while in background | \`backgroundDuration\` |
+
+> **Note:** Interruptions use notify-only \u2014 the hook does NOT auto-resume. The consumer decides via the \`shouldResume\` flag.
+
+#### Background Recording Setup
+
+The OS will not allow background recording without app-level entitlements:
+
+**iOS** \u2014 \`Info.plist\`:
+\`\`\`xml
+<key>UIBackgroundModes</key>
+<array><string>audio</string></array>
+\`\`\`
+
+**Android** \u2014 \`AndroidManifest.xml\`:
+\`\`\`xml
+<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MICROPHONE" />
+<uses-permission android:name="android.permission.RECORD_AUDIO" />
+<service
+  android:name="com.swmansion.audioapi.system.CentralizedForegroundService"
+  android:foregroundServiceType="microphone" />
+\`\`\`
+
+**Expo** \u2014 \`app.json\` plugin:
+\`\`\`json
+["react-native-audio-api", {
+  "iosBackgroundMode": true,
+  "androidForegroundService": true,
+  "androidFSTypes": ["microphone"],
+  "androidPermissions": [
+    "android.permission.FOREGROUND_SERVICE",
+    "android.permission.FOREGROUND_SERVICE_MICROPHONE",
+    "android.permission.RECORD_AUDIO"
+  ]
+}]
+\`\`\`
+
+---
+
 ## Types
 
 ### AudioConfig
@@ -10772,6 +11175,7 @@ type AudioErrorCode =
   | 'DEVICE_NOT_FOUND' | 'DEVICE_IN_USE' | 'NOT_SUPPORTED'
   | 'SOURCE_NOT_FOUND' | 'FORMAT_NOT_SUPPORTED' | 'DECODE_ERROR' | 'PLAYBACK_ERROR' | 'BUFFER_UNDERRUN'
   | 'RECORDING_ERROR'
+  | 'BACKGROUND_NOT_SUPPORTED' | 'BACKGROUND_MAX_DURATION'
   | 'INITIALIZATION_FAILED' | 'INVALID_STATE' | 'INVALID_CONFIG' | 'UNKNOWN';
 
 interface AudioError {
@@ -10800,11 +11204,12 @@ const AUDIO_PROFILES: AudioProfiles = {
 
 \`\`\`typescript
 const SESSION_PRESETS: SessionPresets = {
-  playback:  { category: 'playback', mode: 'default' },
-  record:    { category: 'record', mode: 'default' },
-  voiceChat: { category: 'playAndRecord', mode: 'voiceChat', categoryOptions: ['allowBluetooth', 'defaultToSpeaker'] },
-  ambient:   { category: 'ambient', mode: 'default' },
-  default:   { category: 'soloAmbient', mode: 'default' },
+  playback:        { category: 'playback', mode: 'default' },
+  record:          { category: 'record', mode: 'default' },
+  voiceChat:       { category: 'playAndRecord', mode: 'voiceChat', categoryOptions: ['allowBluetooth', 'defaultToSpeaker'] },
+  ambient:         { category: 'ambient', mode: 'default' },
+  default:         { category: 'soloAmbient', mode: 'default' },
+  backgroundRecord: { category: 'playAndRecord', mode: 'spokenAudio', categoryOptions: ['defaultToSpeaker', 'allowBluetooth', 'allowBluetoothA2DP', 'mixWithOthers'] },
 };
 \`\`\`
 `,
@@ -10977,6 +11382,77 @@ function VoiceChatScreen() {
 }
 \`\`\`
 
+## Background Recording for Transcription
+
+\`\`\`tsx
+import React, { useEffect } from 'react';
+import { View, Button, Text } from '@idealyst/components';
+import { useBackgroundRecorder, AUDIO_PROFILES } from '@idealyst/audio';
+import type { PCMData, BackgroundLifecycleInfo } from '@idealyst/audio';
+
+function BackgroundTranscriber() {
+  const recorder = useBackgroundRecorder({
+    config: AUDIO_PROFILES.speech,
+    maxBackgroundDuration: 5 * 60 * 1000, // 5 min max in background
+    onLifecycleEvent: (info: BackgroundLifecycleInfo) => {
+      switch (info.event) {
+        case 'backgrounded':
+          console.log('Recording continues in background');
+          break;
+        case 'foregrounded':
+          console.log(\`Back from background after \${info.backgroundDuration}ms\`);
+          break;
+        case 'interrupted':
+          console.log('Recording interrupted (phone call?)');
+          break;
+        case 'interruptionEnded':
+          if (info.shouldResume) {
+            recorder.resume(); // Consumer decides whether to resume
+          }
+          break;
+        case 'maxDurationReached':
+          console.log('Max background duration reached');
+          break;
+      }
+    },
+  });
+
+  // Stream PCM chunks to your speech-to-text service
+  useEffect(() => {
+    const unsub = recorder.subscribeToData((pcm: PCMData) => {
+      // Send to STT API (e.g., Whisper, Deepgram)
+      sendToTranscriptionService(pcm.toBase64());
+    });
+    return unsub;
+  }, [recorder.subscribeToData]);
+
+  const handleToggle = async () => {
+    if (recorder.isRecording) {
+      await recorder.stop();
+    } else {
+      await recorder.start();
+    }
+  };
+
+  return (
+    <View padding="md" gap="md">
+      <Button
+        onPress={handleToggle}
+        intent={recorder.isRecording ? 'error' : 'primary'}
+      >
+        {recorder.isRecording ? 'Stop' : 'Record'}
+      </Button>
+      <Text>Duration: {Math.round(recorder.duration / 1000)}s</Text>
+      {recorder.isInBackground && <Text>Recording in background...</Text>}
+      {recorder.wasInterrupted && <Text>Recording was interrupted</Text>}
+      <Text>Background time: {Math.round(recorder.backgroundDuration / 1000)}s</Text>
+    </View>
+  );
+}
+\`\`\`
+
+> **Important:** Background recording requires native entitlements. See the \`useBackgroundRecorder\` API docs for iOS, Android, and Expo setup instructions.
+
 ## Audio Level Visualization
 
 \`\`\`tsx
@@ -14424,192 +14900,1708 @@ type CurveType =
 > - \`tickFormat\` signature is \`(value: number | string | Date) => string\` \u2014 NOT \`(v: number) => string\`.
 > - \`AxisConfig\` uses \`show\` (NOT \`visible\`) to control axis visibility.
 
-## Line Chart
+## Line Chart
+
+\`\`\`tsx
+import React from 'react';
+import { View, Text } from '@idealyst/components';
+import { LineChart } from '@idealyst/charts';
+import type { ChartDataSeries } from '@idealyst/charts';
+
+const monthlySales = [
+  { x: 'Jan', y: 4200 },
+  { x: 'Feb', y: 5100 },
+  { x: 'Mar', y: 4800 },
+  { x: 'Apr', y: 6200 },
+  { x: 'May', y: 5900 },
+  { x: 'Jun', y: 7100 },
+];
+
+// Series uses 'name' for display \u2014 NOT 'label'
+const revenueData: ChartDataSeries[] = [
+  { id: 'revenue', name: 'Revenue', data: monthlySales, color: '#4CAF50' },
+];
+
+function SalesOverview() {
+  return (
+    <View padding="md" gap="md">
+      <Text typography="h6" weight="bold">Monthly Sales</Text>
+      <LineChart
+        data={revenueData}
+        height={300}
+        curve="monotone"
+        showDots
+        showArea
+        areaOpacity={0.15}
+        animate
+        xAxis={{ label: 'Month' }}
+        yAxis={{
+          label: 'Revenue ($)',
+          // tickFormat param type is (value: number | string | Date) => string
+          tickFormat: (value: number | string | Date) => \`$\${Number(value) / 1000}k\`,
+        }}
+      />
+    </View>
+  );
+}
+\`\`\`
+
+## Multi-Series Line Chart
+
+\`\`\`tsx
+import React from 'react';
+import { LineChart } from '@idealyst/charts';
+import type { ChartDataSeries } from '@idealyst/charts';
+
+// Each series has: id, name, data, color? \u2014 NO 'label' property
+const series: ChartDataSeries[] = [
+  {
+    id: 'product-a',
+    name: 'Product A',   // Use 'name' \u2014 NOT 'label'
+    data: [
+      { x: 'Q1', y: 120 },
+      { x: 'Q2', y: 150 },
+      { x: 'Q3', y: 180 },
+      { x: 'Q4', y: 210 },
+    ],
+    color: '#2196F3',
+  },
+  {
+    id: 'product-b',
+    name: 'Product B',   // Use 'name' \u2014 NOT 'label'
+    data: [
+      { x: 'Q1', y: 80 },
+      { x: 'Q2', y: 110 },
+      { x: 'Q3', y: 95 },
+      { x: 'Q4', y: 140 },
+    ],
+    color: '#FF9800',
+  },
+];
+
+function ComparisonChart() {
+  return (
+    <LineChart
+      data={series}
+      height={350}
+      curve="monotone"
+      showDots
+      animate
+    />
+  );
+}
+\`\`\`
+
+## Bar Chart
+
+\`\`\`tsx
+import React from 'react';
+import { View, Text } from '@idealyst/components';
+import { BarChart } from '@idealyst/charts';
+
+const categories = [
+  { x: 'Electronics', y: 45 },
+  { x: 'Clothing', y: 32 },
+  { x: 'Books', y: 18 },
+  { x: 'Food', y: 56 },
+  { x: 'Sports', y: 28 },
+];
+
+function CategoryBreakdown() {
+  return (
+    <View padding="md" gap="md">
+      <Text typography="h6" weight="bold">Sales by Category</Text>
+      <BarChart
+        data={[{ id: 'units', name: 'Units Sold', data: categories }]}
+        height={300}
+        barRadius={4}
+        animate
+        yAxis={{ tickFormat: (value: number | string | Date) => \`\${value} units\` }}
+      />
+    </View>
+  );
+}
+\`\`\`
+
+## Stacked Bar Chart
+
+\`\`\`tsx
+import React from 'react';
+import { BarChart } from '@idealyst/charts';
+
+function StackedBarExample() {
+  return (
+    <BarChart
+      data={[
+        {
+          id: 'online',
+          name: 'Online',
+          data: [
+            { x: 'Q1', y: 100 },
+            { x: 'Q2', y: 120 },
+            { x: 'Q3', y: 90 },
+          ],
+          color: '#4CAF50',
+        },
+        {
+          id: 'in-store',
+          name: 'In-Store',
+          data: [
+            { x: 'Q1', y: 60 },
+            { x: 'Q2', y: 80 },
+            { x: 'Q3', y: 70 },
+          ],
+          color: '#2196F3',
+        },
+      ]}
+      height={300}
+      stacked
+      animate
+    />
+  );
+}
+\`\`\`
+
+## Horizontal Bar Chart
+
+\`\`\`tsx
+import React from 'react';
+import { BarChart } from '@idealyst/charts';
+
+function HorizontalBarExample() {
+  const data = [
+    { x: 'React', y: 85 },
+    { x: 'Vue', y: 62 },
+    { x: 'Angular', y: 45 },
+    { x: 'Svelte', y: 38 },
+  ];
+
+  return (
+    <BarChart
+      data={[{ id: 'popularity', name: 'Popularity', data }]}
+      height={250}
+      orientation="horizontal"
+      animate
+    />
+  );
+}
+\`\`\`
+`
+};
+
+// src/data/clipboard-guides.ts
+var clipboardGuides = {
+  "idealyst://clipboard/overview": `# @idealyst/clipboard Overview
+
+Cross-platform clipboard and OTP autofill for React and React Native applications. Provides a consistent async API for copy/paste operations, plus a mobile-only hook for automatic SMS OTP code detection.
+
+## Features
+
+- **Cross-Platform Clipboard** - Copy and paste text on React Native and Web
+- **Simple API** - Async/await based with consistent interface
+- **React Native** - Uses @react-native-clipboard/clipboard
+- **Web** - Uses navigator.clipboard API
+- **OTP Auto-Fill (Android)** - Automatically reads OTP codes from SMS via SMS Retriever API (no permissions needed)
+- **OTP Auto-Fill (iOS)** - Provides TextInput props for native iOS keyboard OTP suggestion
+- **TypeScript** - Full type safety and IntelliSense support
+
+## Installation
+
+\`\`\`bash
+yarn add @idealyst/clipboard
+
+# React Native also needs:
+yarn add @react-native-clipboard/clipboard
+cd ios && pod install
+
+# For OTP autofill on Android (optional):
+yarn add react-native-otp-verify
+\`\`\`
+
+## Quick Start
+
+\`\`\`tsx
+import { clipboard } from '@idealyst/clipboard';
+
+// Copy text
+await clipboard.copy('Hello, world!');
+
+// Paste text
+const text = await clipboard.paste();
+
+// Check if clipboard has text
+const hasText = await clipboard.hasText();
+\`\`\`
+
+## OTP Auto-Fill Quick Start
+
+\`\`\`tsx
+import { useOTPAutoFill, OTP_INPUT_PROPS } from '@idealyst/clipboard';
+import { TextInput } from 'react-native';
+
+function OTPScreen() {
+  const { code, startListening, hash } = useOTPAutoFill({
+    codeLength: 6,
+    onCodeReceived: (otp) => verifyOTP(otp),
+  });
+
+  useEffect(() => {
+    startListening();
+  }, []);
+
+  return (
+    <TextInput
+      value={code ?? ''}
+      {...OTP_INPUT_PROPS}
+    />
+  );
+}
+\`\`\`
+
+## Import Options
+
+\`\`\`tsx
+// Named import (recommended)
+import { clipboard } from '@idealyst/clipboard';
+
+// Default import
+import clipboard from '@idealyst/clipboard';
+
+// OTP hook and helpers
+import { useOTPAutoFill, OTP_INPUT_PROPS } from '@idealyst/clipboard';
+\`\`\`
+
+## Platform Details
+
+- **React Native**: Uses \`@react-native-clipboard/clipboard\` for clipboard operations
+- **Web**: Uses \`navigator.clipboard\` API (requires secure context / HTTPS)
+- **OTP (Android)**: Uses SMS Retriever API via \`react-native-otp-verify\` \u2014 zero permissions
+- **OTP (iOS)**: Native keyboard autofill via \`textContentType="oneTimeCode"\`
+- **OTP (Web)**: No-op \u2014 returns null values and noop functions
+`,
+  "idealyst://clipboard/api": `# Clipboard API Reference
+
+Complete API reference for @idealyst/clipboard.
+
+## clipboard.copy
+
+Copy text to the system clipboard.
+
+\`\`\`tsx
+await clipboard.copy(text: string): Promise<void>
+
+// Examples
+await clipboard.copy('Hello, world!');
+await clipboard.copy(inviteCode);
+await clipboard.copy(JSON.stringify(data));
+\`\`\`
+
+## clipboard.paste
+
+Read text from the system clipboard.
+
+\`\`\`tsx
+await clipboard.paste(): Promise<string>
+
+// Examples
+const text = await clipboard.paste();
+const url = await clipboard.paste();
+\`\`\`
+
+## clipboard.hasText
+
+Check if the clipboard contains text content.
+
+\`\`\`tsx
+await clipboard.hasText(): Promise<boolean>
+
+// Example
+const canPaste = await clipboard.hasText();
+if (canPaste) {
+  const text = await clipboard.paste();
+}
+\`\`\`
+
+## clipboard.addListener
+
+Listen for copy events (triggered when \`clipboard.copy()\` is called).
+
+\`\`\`tsx
+const unsubscribe = clipboard.addListener((content: string) => {
+  console.log('Copied:', content);
+});
+
+// Later, unsubscribe
+unsubscribe();
+\`\`\`
+
+---
+
+## useOTPAutoFill
+
+React hook for automatic OTP code detection from SMS on mobile.
+
+**Android**: Uses SMS Retriever API to auto-read OTP from incoming SMS (no permissions required). SMS must include your app hash.
+
+**iOS**: OTP is handled natively by the iOS keyboard. Use \`OTP_INPUT_PROPS\` on your TextInput to enable it.
+
+**Web**: Returns no-op values.
+
+\`\`\`tsx
+const {
+  code,           // string | null - received OTP code (Android only)
+  startListening, // () => void - begin listening for SMS (Android only)
+  stopListening,  // () => void - stop listening (Android only)
+  hash,           // string | null - app hash for SMS body (Android only)
+} = useOTPAutoFill(options?: {
+  codeLength?: number;           // default: 6
+  onCodeReceived?: (code: string) => void;
+});
+\`\`\`
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| codeLength | number | 6 | Expected digit count of OTP code |
+| onCodeReceived | (code: string) => void | \u2014 | Callback when OTP is detected |
+
+### Return Value
+
+| Property | Type | Description |
+|----------|------|-------------|
+| code | string \\| null | Detected OTP code (Android). Null on iOS/web. |
+| startListening | () => void | Start SMS listener (Android). No-op on iOS/web. |
+| stopListening | () => void | Stop SMS listener (Android). No-op on iOS/web. |
+| hash | string \\| null | App hash for SMS Retriever (Android). Null on iOS/web. |
+
+### Android SMS Format
+
+For the SMS Retriever API to detect the message, the SMS must:
+1. Start with \`<#>\`
+2. Contain the OTP code as a sequence of digits
+3. End with your app's 11-character hash (available via \`hash\`)
+
+Example SMS:
+\`\`\`
+<#> Your verification code is: 123456
+FA+9qCX9VSu
+\`\`\`
+
+---
+
+## OTP_INPUT_PROPS
+
+Constant with TextInput props to enable native OTP keyboard autofill.
+
+\`\`\`tsx
+import { OTP_INPUT_PROPS } from '@idealyst/clipboard';
+
+// Value:
+// {
+//   textContentType: 'oneTimeCode',
+//   autoComplete: 'sms-otp',
+// }
+
+<TextInput
+  {...OTP_INPUT_PROPS}
+  value={code}
+  onChangeText={setCode}
+/>
+\`\`\`
+
+- **iOS**: Enables the keyboard to suggest OTP codes from received SMS (iOS 12+)
+- **Android**: Maps to the correct \`autoComplete\` value
+- **Web**: Harmless \u2014 ignored by web TextInput
+`,
+  "idealyst://clipboard/examples": `# Clipboard Examples
+
+Complete code examples for common @idealyst/clipboard patterns.
+
+## Copy to Clipboard with Feedback
+
+\`\`\`tsx
+import { clipboard } from '@idealyst/clipboard';
+import { useState, useCallback } from 'react';
+
+function CopyButton({ text }: { text: string }) {
+  const [copied, setCopied] = useState(false);
+
+  const handleCopy = useCallback(async () => {
+    await clipboard.copy(text);
+    setCopied(true);
+    setTimeout(() => setCopied(false), 2000);
+  }, [text]);
+
+  return (
+    <Button
+      label={copied ? 'Copied!' : 'Copy'}
+      intent={copied ? 'positive' : 'neutral'}
+      onPress={handleCopy}
+    />
+  );
+}
+\`\`\`
+
+## Share / Copy Link
+
+\`\`\`tsx
+import { clipboard } from '@idealyst/clipboard';
+
+async function copyShareLink(itemId: string) {
+  const url = \`https://myapp.com/items/\${itemId}\`;
+  await clipboard.copy(url);
+}
+\`\`\`
+
+## Paste from Clipboard
+
+\`\`\`tsx
+import { clipboard } from '@idealyst/clipboard';
+
+function PasteInput() {
+  const [value, setValue] = useState('');
+
+  const handlePaste = useCallback(async () => {
+    const hasText = await clipboard.hasText();
+    if (hasText) {
+      const text = await clipboard.paste();
+      setValue(text);
+    }
+  }, []);
+
+  return (
+    <View>
+      <Input value={value} onChangeText={setValue} placeholder="Enter or paste text" />
+      <Button label="Paste" onPress={handlePaste} iconName="content-paste" />
+    </View>
+  );
+}
+\`\`\`
+
+## useClipboard Hook
+
+\`\`\`tsx
+import { clipboard } from '@idealyst/clipboard';
+import { useState, useCallback } from 'react';
+
+export function useClipboard() {
+  const [copiedText, setCopiedText] = useState<string | null>(null);
+
+  const copy = useCallback(async (text: string) => {
+    await clipboard.copy(text);
+    setCopiedText(text);
+  }, []);
+
+  const paste = useCallback(async () => {
+    return clipboard.paste();
+  }, []);
+
+  const reset = useCallback(() => {
+    setCopiedText(null);
+  }, []);
+
+  return { copy, paste, copiedText, reset };
+}
+\`\`\`
+
+## OTP Verification Screen
+
+\`\`\`tsx
+import { useOTPAutoFill, OTP_INPUT_PROPS } from '@idealyst/clipboard';
+import { useEffect, useState } from 'react';
+import { TextInput, Platform } from 'react-native';
+
+function OTPVerificationScreen({ phoneNumber, onVerify }: {
+  phoneNumber: string;
+  onVerify: (code: string) => void;
+}) {
+  const [code, setCode] = useState('');
+
+  const otp = useOTPAutoFill({
+    codeLength: 6,
+    onCodeReceived: (receivedCode) => {
+      setCode(receivedCode);
+      onVerify(receivedCode);
+    },
+  });
+
+  // Start listening when screen mounts
+  useEffect(() => {
+    otp.startListening();
+    return () => otp.stopListening();
+  }, []);
+
+  // Auto-fill from hook on Android
+  useEffect(() => {
+    if (otp.code) {
+      setCode(otp.code);
+    }
+  }, [otp.code]);
+
+  return (
+    <View>
+      <Text>Enter the code sent to {phoneNumber}</Text>
+
+      <TextInput
+        value={code}
+        onChangeText={(text) => {
+          setCode(text);
+          if (text.length === 6) onVerify(text);
+        }}
+        keyboardType="number-pad"
+        maxLength={6}
+        {...OTP_INPUT_PROPS}
+      />
+
+      {Platform.OS === 'android' && otp.hash && (
+        <Text style={{ fontSize: 10, color: '#999' }}>
+          App hash (for SMS setup): {otp.hash}
+        </Text>
+      )}
+    </View>
+  );
+}
+\`\`\`
+
+## Copy Invite Code
+
+\`\`\`tsx
+import { clipboard } from '@idealyst/clipboard';
+
+function InviteCard({ code }: { code: string }) {
+  const [copied, setCopied] = useState(false);
+
+  return (
+    <Card>
+      <Text>Your invite code</Text>
+      <Text variant="headline">{code}</Text>
+      <Button
+        label={copied ? 'Copied!' : 'Copy Code'}
+        iconName={copied ? 'check' : 'content-copy'}
+        onPress={async () => {
+          await clipboard.copy(code);
+          setCopied(true);
+          setTimeout(() => setCopied(false), 2000);
+        }}
+      />
+    </Card>
+  );
+}
+\`\`\`
+
+## Error Handling
+
+\`\`\`tsx
+import { clipboard } from '@idealyst/clipboard';
+
+async function safeCopy(text: string): Promise<boolean> {
+  try {
+    await clipboard.copy(text);
+    return true;
+  } catch (error) {
+    console.error('Clipboard copy failed:', error);
+    // On web, this can fail if not in a secure context or without user gesture
+    return false;
+  }
+}
+
+async function safePaste(): Promise<string | null> {
+  try {
+    const hasText = await clipboard.hasText();
+    if (!hasText) return null;
+    return await clipboard.paste();
+  } catch (error) {
+    console.error('Clipboard paste failed:', error);
+    // Browser may deny permission
+    return null;
+  }
+}
+\`\`\`
+
+## Best Practices
+
+1. **Always use try-catch** \u2014 Clipboard operations can fail (permissions, secure context)
+2. **Provide visual feedback** \u2014 Show a "Copied!" confirmation after copying
+3. **Use OTP_INPUT_PROPS** \u2014 Always spread these on OTP text inputs for cross-platform autofill
+4. **Start OTP listener on mount** \u2014 Call \`startListening()\` in useEffect, clean up with \`stopListening()\`
+5. **Log the Android hash** \u2014 During development, log \`hash\` to configure your SMS gateway
+6. **Graceful degradation** \u2014 OTP features degrade gracefully if native modules aren't installed
+7. **Secure context (web)** \u2014 Clipboard API requires HTTPS on web
+`
+};
+
+// src/data/biometrics-guides.ts
+var biometricsGuides = {
+  "idealyst://biometrics/overview": `# @idealyst/biometrics Overview
+
+Cross-platform biometric authentication and passkeys (WebAuthn/FIDO2) for React and React Native applications.
+
+## Features
+
+- **Local Biometric Auth** \u2014 FaceID, TouchID, fingerprint, iris to gate access
+- **Passkeys (WebAuthn/FIDO2)** \u2014 Passwordless login with cryptographic credentials
+- **Cross-Platform** \u2014 Single API for React Native (iOS/Android) and Web
+- **React Native** \u2014 Uses expo-local-authentication for biometrics, react-native-passkeys for passkeys
+- **Web** \u2014 Uses WebAuthn API for both biometrics and passkeys
+- **Graceful Degradation** \u2014 Falls back cleanly when native modules aren't installed
+- **TypeScript** \u2014 Full type safety and IntelliSense support
+
+## Installation
+
+\`\`\`bash
+yarn add @idealyst/biometrics
+
+# React Native \u2014 biometric auth:
+yarn add expo-local-authentication
+cd ios && pod install
+
+# React Native \u2014 passkeys (optional):
+yarn add react-native-passkeys
+cd ios && pod install
+\`\`\`
+
+## Quick Start \u2014 Biometric Auth
+
+\`\`\`tsx
+import { isBiometricAvailable, authenticate } from '@idealyst/biometrics';
+
+// Check availability
+const available = await isBiometricAvailable();
+
+// Prompt user
+if (available) {
+  const result = await authenticate({
+    promptMessage: 'Verify your identity',
+  });
+
+  if (result.success) {
+    // Authenticated!
+  } else {
+    console.log(result.error, result.message);
+  }
+}
+\`\`\`
+
+## Quick Start \u2014 Passkeys
+
+\`\`\`tsx
+import { isPasskeySupported, createPasskey, getPasskey } from '@idealyst/biometrics';
+
+// Check support
+const supported = await isPasskeySupported();
+
+// Register a new passkey
+const credential = await createPasskey({
+  challenge: serverChallenge,
+  rp: { id: 'example.com', name: 'My App' },
+  user: { id: userId, name: email, displayName: name },
+});
+// Send credential to server for verification
+
+// Sign in with passkey
+const assertion = await getPasskey({
+  challenge: serverChallenge,
+  rpId: 'example.com',
+});
+// Send assertion to server for verification
+\`\`\`
+
+## Platform Details
+
+- **React Native (biometrics)**: Uses \`expo-local-authentication\` \u2014 FaceID, TouchID, fingerprint, iris
+- **React Native (passkeys)**: Uses \`react-native-passkeys\` \u2014 system passkey UI on iOS 16+ and Android 9+
+- **Web (biometrics)**: Uses WebAuthn with \`userVerification: 'required'\` to trigger platform authenticator
+- **Web (passkeys)**: Uses \`navigator.credentials.create/get\` with the PublicKey API
+`,
+  "idealyst://biometrics/api": `# Biometrics API Reference
+
+Complete API reference for @idealyst/biometrics.
+
+---
+
+## Biometric Authentication Functions
+
+### isBiometricAvailable
+
+Check whether biometric auth hardware is available and enrolled.
+
+\`\`\`tsx
+await isBiometricAvailable(): Promise<boolean>
+
+// Native: checks hardware + enrollment via expo-local-authentication
+// Web: checks PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable()
+\`\`\`
+
+### getBiometricTypes
+
+Return the biometric types available on this device.
+
+\`\`\`tsx
+await getBiometricTypes(): Promise<BiometricType[]>
+
+type BiometricType = 'fingerprint' | 'facial_recognition' | 'iris';
+
+// Native: returns specific types (fingerprint, facial_recognition, iris)
+// Web: returns ['fingerprint'] as generic indicator, or [] if unavailable
+\`\`\`
+
+### getSecurityLevel
+
+Get the security level of biometric authentication on the device.
+
+\`\`\`tsx
+await getSecurityLevel(): Promise<SecurityLevel>
+
+type SecurityLevel = 'none' | 'device_credential' | 'biometric_weak' | 'biometric_strong';
+
+// Native: maps expo-local-authentication SecurityLevel enum
+// Web: returns 'biometric_strong' if platform authenticator available, else 'none'
+\`\`\`
+
+### authenticate
+
+Prompt the user for biometric authentication.
+
+\`\`\`tsx
+await authenticate(options?: AuthenticateOptions): Promise<AuthResult>
+\`\`\`
+
+**AuthenticateOptions:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| promptMessage | string | 'Authenticate' | Message shown alongside the biometric prompt |
+| cancelLabel | string | \u2014 | Label for the cancel button |
+| fallbackLabel | string | \u2014 | iOS: label for passcode fallback button |
+| disableDeviceFallback | boolean | false | Prevent PIN/passcode fallback after biometric failure |
+| requireStrongBiometric | boolean | false | Android: require Class 3 (strong) biometric |
+
+**AuthResult:**
+
+\`\`\`tsx
+type AuthResult =
+  | { success: true }
+  | { success: false; error: AuthError; message?: string };
+
+type AuthError =
+  | 'not_available'
+  | 'not_enrolled'
+  | 'user_cancel'
+  | 'lockout'
+  | 'system_cancel'
+  | 'passcode_not_set'
+  | 'authentication_failed'
+  | 'unknown';
+\`\`\`
+
+### cancelAuthentication
+
+Cancel an in-progress authentication prompt (Android only). No-op on iOS and web.
+
+\`\`\`tsx
+await cancelAuthentication(): Promise<void>
+\`\`\`
+
+---
+
+## Passkey Functions
+
+### isPasskeySupported
+
+Check if passkeys (WebAuthn/FIDO2) are supported on this device/browser.
+
+\`\`\`tsx
+await isPasskeySupported(): Promise<boolean>
+
+// Web: checks PublicKeyCredential + isUserVerifyingPlatformAuthenticatorAvailable
+// Native: checks react-native-passkeys Passkey.isSupported()
+\`\`\`
+
+### createPasskey
+
+Create a new passkey credential (registration / attestation ceremony).
+
+\`\`\`tsx
+await createPasskey(options: PasskeyCreateOptions): Promise<PasskeyCreateResult>
+\`\`\`
+
+**PasskeyCreateOptions:**
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| challenge | string | Yes | Base64url-encoded challenge from server |
+| rp | { id: string; name: string } | Yes | Relying party info |
+| user | { id: string; name: string; displayName: string } | Yes | User info (id is base64url) |
+| pubKeyCredParams | PublicKeyCredentialParam[] | No | Defaults to ES256 + RS256 |
+| timeout | number | No | Timeout in ms (default 60000) |
+| authenticatorSelection | object | No | Authenticator criteria |
+| excludeCredentials | CredentialDescriptor[] | No | Prevent re-registration |
+| attestation | string | No | 'none' \\| 'indirect' \\| 'direct' \\| 'enterprise' |
+
+**PasskeyCreateResult:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| id | string | Credential ID (base64url) |
+| rawId | string | Raw credential ID (base64url) |
+| type | 'public-key' | Always 'public-key' |
+| response.clientDataJSON | string | Client data (base64url) |
+| response.attestationObject | string | Attestation object (base64url) |
+
+### getPasskey
+
+Authenticate with an existing passkey (assertion ceremony).
+
+\`\`\`tsx
+await getPasskey(options: PasskeyGetOptions): Promise<PasskeyGetResult>
+\`\`\`
+
+**PasskeyGetOptions:**
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| challenge | string | Yes | Base64url-encoded challenge from server |
+| rpId | string | No | Relying party ID |
+| allowCredentials | CredentialDescriptor[] | No | Allowed credentials (empty = discoverable) |
+| timeout | number | No | Timeout in ms (default 60000) |
+| userVerification | string | No | 'required' \\| 'preferred' \\| 'discouraged' |
+
+**PasskeyGetResult:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| id | string | Credential ID (base64url) |
+| rawId | string | Raw credential ID (base64url) |
+| type | 'public-key' | Always 'public-key' |
+| response.clientDataJSON | string | Client data (base64url) |
+| response.authenticatorData | string | Authenticator data (base64url) |
+| response.signature | string | Signature (base64url) |
+| response.userHandle | string \\| undefined | User handle (base64url) |
+
+### PasskeyError
+
+Both \`createPasskey\` and \`getPasskey\` throw a \`PasskeyError\` on failure:
+
+\`\`\`tsx
+interface PasskeyError {
+  code: 'not_supported' | 'cancelled' | 'invalid_state' | 'not_allowed' | 'unknown';
+  message: string;
+}
+
+try {
+  const result = await createPasskey(options);
+} catch (err) {
+  const passkeyErr = err as PasskeyError;
+  console.log(passkeyErr.code, passkeyErr.message);
+}
+\`\`\`
+
+---
+
+## Base64url Helpers
+
+Shared utilities for encoding/decoding WebAuthn binary data.
+
+\`\`\`tsx
+import { base64urlToBuffer, bufferToBase64url } from '@idealyst/biometrics';
+
+// Convert base64url string to ArrayBuffer
+const buffer: ArrayBuffer = base64urlToBuffer(base64urlString);
+
+// Convert ArrayBuffer to base64url string
+const str: string = bufferToBase64url(arrayBuffer);
+\`\`\`
+`,
+  "idealyst://biometrics/examples": `# Biometrics Examples
+
+Complete code examples for common @idealyst/biometrics patterns.
+
+## Gate Screen Access with Biometrics
+
+\`\`\`tsx
+import { isBiometricAvailable, authenticate } from '@idealyst/biometrics';
+import { useEffect, useState } from 'react';
+
+function ProtectedScreen({ children }: { children: React.ReactNode }) {
+  const [unlocked, setUnlocked] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const unlock = async () => {
+    const available = await isBiometricAvailable();
+    if (!available) {
+      // No biometrics \u2014 fall back to PIN or allow access
+      setUnlocked(true);
+      return;
+    }
+
+    const result = await authenticate({
+      promptMessage: 'Unlock to continue',
+      cancelLabel: 'Cancel',
+    });
+
+    if (result.success) {
+      setUnlocked(true);
+    } else {
+      setError(result.message ?? 'Authentication failed');
+    }
+  };
+
+  useEffect(() => {
+    unlock();
+  }, []);
+
+  if (!unlocked) {
+    return (
+      <View>
+        <Text>Please authenticate to continue</Text>
+        {error && <Text intent="negative">{error}</Text>}
+        <Button label="Try Again" onPress={unlock} />
+      </View>
+    );
+  }
+
+  return <>{children}</>;
+}
+\`\`\`
+
+## Confirm Sensitive Action
+
+\`\`\`tsx
+import { authenticate } from '@idealyst/biometrics';
+
+async function confirmTransfer(amount: number, recipient: string) {
+  const result = await authenticate({
+    promptMessage: \`Confirm transfer of $\${amount} to \${recipient}\`,
+    disableDeviceFallback: false,
+  });
+
+  if (!result.success) {
+    throw new Error(result.message ?? 'Authentication required');
+  }
+
+  // Proceed with transfer
+  await api.transfer({ amount, recipient });
+}
+\`\`\`
+
+## Show Biometric Info
+
+\`\`\`tsx
+import {
+  isBiometricAvailable,
+  getBiometricTypes,
+  getSecurityLevel,
+} from '@idealyst/biometrics';
+
+function BiometricSettings() {
+  const [info, setInfo] = useState({
+    available: false,
+    types: [] as string[],
+    level: 'none',
+  });
+
+  useEffect(() => {
+    async function load() {
+      const [available, types, level] = await Promise.all([
+        isBiometricAvailable(),
+        getBiometricTypes(),
+        getSecurityLevel(),
+      ]);
+      setInfo({ available, types, level });
+    }
+    load();
+  }, []);
+
+  return (
+    <Card>
+      <Text>Biometric available: {info.available ? 'Yes' : 'No'}</Text>
+      <Text>Types: {info.types.join(', ') || 'None'}</Text>
+      <Text>Security level: {info.level}</Text>
+    </Card>
+  );
+}
+\`\`\`
+
+## Passkey Registration Flow
+
+\`\`\`tsx
+import { isPasskeySupported, createPasskey } from '@idealyst/biometrics';
+import type { PasskeyError } from '@idealyst/biometrics';
+
+async function registerPasskey(user: { id: string; email: string; name: string }) {
+  const supported = await isPasskeySupported();
+  if (!supported) {
+    alert('Passkeys are not supported on this device');
+    return;
+  }
+
+  // 1. Get challenge from server
+  const { challenge, rpId, rpName } = await api.getRegistrationChallenge();
+
+  try {
+    // 2. Create the passkey
+    const credential = await createPasskey({
+      challenge,
+      rp: { id: rpId, name: rpName },
+      user: {
+        id: user.id,
+        name: user.email,
+        displayName: user.name,
+      },
+      authenticatorSelection: {
+        residentKey: 'required',
+        userVerification: 'required',
+      },
+    });
+
+    // 3. Send to server for verification and storage
+    await api.verifyRegistration({
+      id: credential.id,
+      rawId: credential.rawId,
+      clientDataJSON: credential.response.clientDataJSON,
+      attestationObject: credential.response.attestationObject,
+    });
+
+    alert('Passkey registered successfully!');
+  } catch (err) {
+    const passkeyErr = err as PasskeyError;
+    if (passkeyErr.code === 'cancelled') {
+      // User cancelled \u2014 do nothing
+      return;
+    }
+    alert(\`Failed to register passkey: \${passkeyErr.message}\`);
+  }
+}
+\`\`\`
+
+## Passkey Login Flow
+
+\`\`\`tsx
+import { getPasskey } from '@idealyst/biometrics';
+import type { PasskeyError } from '@idealyst/biometrics';
+
+async function loginWithPasskey() {
+  // 1. Get challenge from server
+  const { challenge, rpId } = await api.getAuthenticationChallenge();
+
+  try {
+    // 2. Authenticate with passkey
+    const assertion = await getPasskey({
+      challenge,
+      rpId,
+      userVerification: 'required',
+    });
+
+    // 3. Send to server for verification
+    const session = await api.verifyAuthentication({
+      id: assertion.id,
+      rawId: assertion.rawId,
+      clientDataJSON: assertion.response.clientDataJSON,
+      authenticatorData: assertion.response.authenticatorData,
+      signature: assertion.response.signature,
+      userHandle: assertion.response.userHandle,
+    });
+
+    return session;
+  } catch (err) {
+    const passkeyErr = err as PasskeyError;
+    if (passkeyErr.code === 'cancelled') return null;
+    throw passkeyErr;
+  }
+}
+\`\`\`
+
+## Login Screen with Passkey + Fallback
+
+\`\`\`tsx
+import { isPasskeySupported, getPasskey } from '@idealyst/biometrics';
+import type { PasskeyError } from '@idealyst/biometrics';
+
+function LoginScreen() {
+  const [passkeyAvailable, setPasskeyAvailable] = useState(false);
+  const [loading, setLoading] = useState(false);
+
+  useEffect(() => {
+    isPasskeySupported().then(setPasskeyAvailable);
+  }, []);
+
+  const handlePasskeyLogin = async () => {
+    setLoading(true);
+    try {
+      const { challenge, rpId } = await api.getAuthenticationChallenge();
+      const assertion = await getPasskey({ challenge, rpId });
+      const session = await api.verifyAuthentication(assertion);
+      navigateToHome(session);
+    } catch (err) {
+      const e = err as PasskeyError;
+      if (e.code !== 'cancelled') {
+        showError(e.message);
+      }
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <View>
+      <Text variant="headline">Welcome Back</Text>
+
+      {passkeyAvailable && (
+        <Button
+          label="Sign in with Passkey"
+          iconName="fingerprint"
+          onPress={handlePasskeyLogin}
+          loading={loading}
+        />
+      )}
+
+      <Button
+        label="Sign in with Email"
+        intent="neutral"
+        onPress={navigateToEmailLogin}
+      />
+    </View>
+  );
+}
+\`\`\`
+
+## Best Practices
+
+1. **Always check availability first** \u2014 Call \`isBiometricAvailable()\` or \`isPasskeySupported()\` before prompting
+2. **Provide fallbacks** \u2014 Not all devices support biometrics. Offer PIN/password alternatives
+3. **Handle cancellation gracefully** \u2014 Users may cancel the prompt. Don't show errors for \`user_cancel\` / \`cancelled\`
+4. **Use try/catch for passkeys** \u2014 Passkey functions throw \`PasskeyError\` on failure
+5. **Server-side validation** \u2014 Always verify passkey responses on your server. The client is untrusted
+6. **Base64url encoding** \u2014 All binary WebAuthn data is encoded as base64url strings for transport
+7. **Set rpId correctly** \u2014 The relying party ID must match your domain. On native, it's your associated domain
+8. **Lockout handling** \u2014 After too many failed biometric attempts, the device locks out. Handle the \`lockout\` error
+9. **iOS permissions** \u2014 FaceID requires \`NSFaceIDUsageDescription\` in Info.plist
+10. **Android associated domains** \u2014 Passkeys on Android require a Digital Asset Links file at \`/.well-known/assetlinks.json\`
+`
+};
+
+// src/data/payments-guides.ts
+var paymentsGuides = {
+  "idealyst://payments/overview": `# @idealyst/payments Overview
+
+Cross-platform payment provider abstractions for React and React Native. Wraps Stripe's Platform Pay API for Apple Pay and Google Pay on mobile.
+
+## Features
+
+- **Apple Pay** \u2014 Native iOS payment sheet via Stripe SDK
+- **Google Pay** \u2014 Native Android payment sheet via Stripe SDK
+- **Cross-Platform** \u2014 Single API for React Native and web (web is stub/noop)
+- **Flat Functions + Hook** \u2014 Use \`initializePayments()\`, \`confirmPayment()\` directly, or \`usePayments()\` hook
+- **Stripe Platform Pay** \u2014 Wraps \`@stripe/stripe-react-native\` Platform Pay API
+- **Graceful Degradation** \u2014 Falls back cleanly when Stripe SDK isn't installed
+- **TypeScript** \u2014 Full type safety
+
+## Installation
+
+\`\`\`bash
+yarn add @idealyst/payments
+
+# React Native \u2014 required for mobile payments:
+yarn add @stripe/stripe-react-native
+cd ios && pod install
+\`\`\`
+
+## Web Support
+
+Web provides a functional stub \u2014 \`initializePayments()\` succeeds but all payment methods report as unavailable. Payment actions throw descriptive errors pointing to Stripe Elements (\`@stripe/react-stripe-js\`).
+
+## Quick Start
+
+\`\`\`tsx
+import { usePayments } from '@idealyst/payments';
+
+function CheckoutScreen() {
+  const {
+    isReady,
+    isApplePayAvailable,
+    isGooglePayAvailable,
+    isProcessing,
+    confirmPayment,
+  } = usePayments({
+    config: {
+      publishableKey: 'pk_test_xxx',
+      merchantIdentifier: 'merchant.com.myapp',
+      merchantName: 'My App',
+      merchantCountryCode: 'US',
+    },
+  });
+
+  const handlePay = async () => {
+    const result = await confirmPayment({
+      clientSecret: 'pi_xxx_secret_xxx', // from server
+      amount: { amount: 1099, currencyCode: 'usd' },
+    });
+    console.log('Paid:', result.paymentIntentId);
+  };
+
+  if (!isReady) return null;
+
+  return (
+    <Button
+      onPress={handlePay}
+      disabled={isProcessing}
+      label={isApplePayAvailable ? 'Apple Pay' : 'Google Pay'}
+    />
+  );
+}
+\`\`\`
+
+## Platform Support
+
+| Feature | iOS | Android | Web |
+|---------|-----|---------|-----|
+| Apple Pay | Yes | \u2014 | \u2014 |
+| Google Pay | \u2014 | Yes | \u2014 |
+| usePayments hook | Yes | Yes | Stub |
+| confirmPayment | Yes | Yes | Throws |
+| createPaymentMethod | Yes | Yes | Throws |
+`,
+  "idealyst://payments/api": `# Payments API Reference
+
+Complete API reference for @idealyst/payments.
+
+---
+
+## Flat Functions
+
+### initializePayments
+
+Initialize the Stripe SDK for platform payments.
+
+\`\`\`tsx
+import { initializePayments } from '@idealyst/payments';
+
+await initializePayments({
+  publishableKey: 'pk_test_xxx',
+  merchantIdentifier: 'merchant.com.myapp', // iOS Apple Pay
+  merchantName: 'My App',
+  merchantCountryCode: 'US',
+  urlScheme: 'com.myapp',       // for 3D Secure redirects
+  testEnvironment: true,         // Google Pay test mode
+});
+\`\`\`
+
+**PaymentConfig:**
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| publishableKey | string | Yes | Stripe publishable key |
+| merchantIdentifier | string | No | Apple Pay merchant ID (iOS) |
+| merchantName | string | Yes | Display name on payment sheet |
+| merchantCountryCode | string | Yes | ISO 3166-1 alpha-2 country |
+| urlScheme | string | No | URL scheme for 3D Secure |
+| testEnvironment | boolean | No | Google Pay test mode (default: false) |
+
+### checkPaymentAvailability
+
+Check which payment methods are available on the current device.
+
+\`\`\`tsx
+import { checkPaymentAvailability } from '@idealyst/payments';
+
+const methods = await checkPaymentAvailability();
+// [
+//   { type: 'apple_pay', isAvailable: true },
+//   { type: 'google_pay', isAvailable: false, unavailableReason: '...' },
+//   { type: 'card', isAvailable: true },
+// ]
+\`\`\`
+
+### confirmPayment
+
+Present the platform payment sheet and confirm a PaymentIntent. Requires a \`clientSecret\` from a server-created PaymentIntent.
+
+\`\`\`tsx
+import { confirmPayment } from '@idealyst/payments';
+
+const result = await confirmPayment({
+  clientSecret: 'pi_xxx_secret_xxx',
+  amount: { amount: 1099, currencyCode: 'usd' },
+  lineItems: [
+    { label: 'Widget', amount: 999 },
+    { label: 'Tax', amount: 100 },
+  ],
+  billingAddress: {
+    isRequired: true,
+    format: 'FULL',
+  },
+});
+
+console.log(result.paymentIntentId); // 'pi_xxx'
+console.log(result.status);          // 'succeeded'
+\`\`\`
+
+### createPaymentMethod
+
+Present the payment sheet and create a payment method without confirming. Returns a payment method ID for server-side processing.
+
+\`\`\`tsx
+import { createPaymentMethod } from '@idealyst/payments';
+
+const result = await createPaymentMethod({
+  amount: { amount: 1099, currencyCode: 'usd' },
+});
+
+console.log(result.paymentMethodId); // 'pm_xxx'
+// Send to your server for processing
+\`\`\`
+
+### getPaymentStatus
+
+Get the current payment provider status.
+
+\`\`\`tsx
+import { getPaymentStatus } from '@idealyst/payments';
+
+const status = getPaymentStatus();
+// { state: 'ready', availablePaymentMethods: [...], isPaymentAvailable: true }
+\`\`\`
+
+---
+
+## usePayments Hook
+
+Convenience hook that wraps the flat functions with React state management.
+
+\`\`\`tsx
+import { usePayments } from '@idealyst/payments';
+
+const {
+  // State
+  status,              // PaymentProviderStatus
+  isReady,             // boolean
+  isProcessing,        // boolean
+  availablePaymentMethods, // PaymentMethodAvailability[]
+  isApplePayAvailable, // boolean
+  isGooglePayAvailable,// boolean
+  isPaymentAvailable,  // boolean
+  error,               // PaymentError | null
+
+  // Actions
+  initialize,          // (config: PaymentConfig) => Promise<void>
+  checkAvailability,   // () => Promise<PaymentMethodAvailability[]>
+  confirmPayment,      // (request: PaymentSheetRequest) => Promise<PaymentResult>
+  createPaymentMethod, // (request: PaymentSheetRequest) => Promise<PaymentResult>
+  clearError,          // () => void
+} = usePayments(options?);
+\`\`\`
+
+**UsePaymentsOptions:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| config | PaymentConfig | \u2014 | Auto-initialize with this config |
+| autoCheckAvailability | boolean | true | Check availability after init |
+
+---
+
+## Types
+
+### PaymentMethodType
+
+\`\`\`tsx
+type PaymentMethodType = 'apple_pay' | 'google_pay' | 'card';
+\`\`\`
+
+### PaymentAmount
 
 \`\`\`tsx
-import React from 'react';
-import { View, Text } from '@idealyst/components';
-import { LineChart } from '@idealyst/charts';
-import type { ChartDataSeries } from '@idealyst/charts';
+interface PaymentAmount {
+  amount: number;        // smallest currency unit (cents)
+  currencyCode: string;  // ISO 4217 (e.g., 'usd')
+}
+\`\`\`
 
-const monthlySales = [
-  { x: 'Jan', y: 4200 },
-  { x: 'Feb', y: 5100 },
-  { x: 'Mar', y: 4800 },
-  { x: 'Apr', y: 6200 },
-  { x: 'May', y: 5900 },
-  { x: 'Jun', y: 7100 },
-];
+### PaymentSheetRequest
 
-// Series uses 'name' for display \u2014 NOT 'label'
-const revenueData: ChartDataSeries[] = [
-  { id: 'revenue', name: 'Revenue', data: monthlySales, color: '#4CAF50' },
-];
+\`\`\`tsx
+interface PaymentSheetRequest {
+  clientSecret?: string;              // required for confirmPayment
+  amount: PaymentAmount;
+  lineItems?: PaymentLineItem[];
+  billingAddress?: BillingAddressConfig;
+  allowedPaymentMethods?: PaymentMethodType[];
+}
+\`\`\`
 
-function SalesOverview() {
-  return (
-    <View padding="md" gap="md">
-      <Text typography="h6" weight="bold">Monthly Sales</Text>
-      <LineChart
-        data={revenueData}
-        height={300}
-        curve="monotone"
-        showDots
-        showArea
-        areaOpacity={0.15}
-        animate
-        xAxis={{ label: 'Month' }}
-        yAxis={{
-          label: 'Revenue ($)',
-          // tickFormat param type is (value: number | string | Date) => string
-          tickFormat: (value: number | string | Date) => \`$\${Number(value) / 1000}k\`,
-        }}
-      />
-    </View>
-  );
+### PaymentResult
+
+\`\`\`tsx
+interface PaymentResult {
+  paymentMethodType: PaymentMethodType;
+  paymentMethodId?: string;   // for createPaymentMethod
+  paymentIntentId?: string;   // for confirmPayment
+  status?: string;            // 'succeeded', 'requires_capture', etc.
 }
 \`\`\`
 
-## Multi-Series Line Chart
+### PaymentError
 
 \`\`\`tsx
-import React from 'react';
-import { LineChart } from '@idealyst/charts';
-import type { ChartDataSeries } from '@idealyst/charts';
+interface PaymentError {
+  code: PaymentErrorCode;
+  message: string;
+  originalError?: unknown;
+}
 
-// Each series has: id, name, data, color? \u2014 NO 'label' property
-const series: ChartDataSeries[] = [
-  {
-    id: 'product-a',
-    name: 'Product A',   // Use 'name' \u2014 NOT 'label'
-    data: [
-      { x: 'Q1', y: 120 },
-      { x: 'Q2', y: 150 },
-      { x: 'Q3', y: 180 },
-      { x: 'Q4', y: 210 },
-    ],
-    color: '#2196F3',
-  },
-  {
-    id: 'product-b',
-    name: 'Product B',   // Use 'name' \u2014 NOT 'label'
-    data: [
-      { x: 'Q1', y: 80 },
-      { x: 'Q2', y: 110 },
-      { x: 'Q3', y: 95 },
-      { x: 'Q4', y: 140 },
-    ],
-    color: '#FF9800',
-  },
-];
+type PaymentErrorCode =
+  | 'not_initialized'
+  | 'not_available'
+  | 'not_supported'
+  | 'user_cancelled'
+  | 'payment_failed'
+  | 'network_error'
+  | 'invalid_config'
+  | 'invalid_request'
+  | 'provider_error'
+  | 'unknown';
+\`\`\`
+`,
+  "idealyst://payments/examples": `# Payments Examples
+
+Complete code examples for common @idealyst/payments patterns.
+
+## Basic Checkout with Hook
+
+\`\`\`tsx
+import { usePayments } from '@idealyst/payments';
+import { Button, View, Text } from '@idealyst/components';
+
+function CheckoutScreen({ clientSecret }: { clientSecret: string }) {
+  const {
+    isReady,
+    isApplePayAvailable,
+    isGooglePayAvailable,
+    isProcessing,
+    error,
+    confirmPayment,
+    clearError,
+  } = usePayments({
+    config: {
+      publishableKey: 'pk_test_xxx',
+      merchantIdentifier: 'merchant.com.myapp',
+      merchantName: 'My App',
+      merchantCountryCode: 'US',
+      testEnvironment: __DEV__,
+    },
+  });
+
+  const handlePay = async () => {
+    try {
+      const result = await confirmPayment({
+        clientSecret,
+        amount: { amount: 1099, currencyCode: 'usd' },
+        lineItems: [
+          { label: 'Widget', amount: 999 },
+          { label: 'Tax', amount: 100 },
+        ],
+      });
+
+      // Payment succeeded
+      console.log('Payment confirmed:', result.paymentIntentId);
+    } catch (err) {
+      // Error is automatically set in hook state
+      console.error('Payment failed:', err);
+    }
+  };
+
+  if (!isReady) {
+    return <Text>Loading payment methods...</Text>;
+  }
+
+  const canPay = isApplePayAvailable || isGooglePayAvailable;
 
-function ComparisonChart() {
   return (
-    <LineChart
-      data={series}
-      height={350}
-      curve="monotone"
-      showDots
-      animate
-    />
+    <View>
+      {canPay ? (
+        <Button
+          onPress={handlePay}
+          disabled={isProcessing}
+          intent="primary"
+        >
+          {isApplePayAvailable ? 'Pay with Apple Pay' : 'Pay with Google Pay'}
+        </Button>
+      ) : (
+        <Text>No payment methods available</Text>
+      )}
+
+      {error && (
+        <View>
+          <Text intent="danger">{error.message}</Text>
+          <Button onPress={clearError}>Dismiss</Button>
+        </View>
+      )}
+    </View>
   );
 }
 \`\`\`
 
-## Bar Chart
+## Create Payment Method (Server-Side Confirm)
 
 \`\`\`tsx
-import React from 'react';
-import { View, Text } from '@idealyst/components';
-import { BarChart } from '@idealyst/charts';
+import { usePayments } from '@idealyst/payments';
+
+function DonateScreen() {
+  const { isReady, isPaymentAvailable, createPaymentMethod } = usePayments({
+    config: {
+      publishableKey: 'pk_test_xxx',
+      merchantName: 'Charity',
+      merchantCountryCode: 'US',
+    },
+  });
 
-const categories = [
-  { x: 'Electronics', y: 45 },
-  { x: 'Clothing', y: 32 },
-  { x: 'Books', y: 18 },
-  { x: 'Food', y: 56 },
-  { x: 'Sports', y: 28 },
-];
+  const handleDonate = async (amountCents: number) => {
+    const result = await createPaymentMethod({
+      amount: { amount: amountCents, currencyCode: 'usd' },
+    });
+
+    // Send payment method to your server
+    await fetch('/api/donate', {
+      method: 'POST',
+      body: JSON.stringify({
+        paymentMethodId: result.paymentMethodId,
+        amount: amountCents,
+      }),
+    });
+  };
 
-function CategoryBreakdown() {
   return (
-    <View padding="md" gap="md">
-      <Text typography="h6" weight="bold">Sales by Category</Text>
-      <BarChart
-        data={[{ id: 'units', name: 'Units Sold', data: categories }]}
-        height={300}
-        barRadius={4}
-        animate
-        yAxis={{ tickFormat: (value: number | string | Date) => \`\${value} units\` }}
-      />
+    <View>
+      <Button onPress={() => handleDonate(500)} disabled={!isPaymentAvailable}>
+        Donate $5
+      </Button>
+      <Button onPress={() => handleDonate(1000)} disabled={!isPaymentAvailable}>
+        Donate $10
+      </Button>
     </View>
   );
 }
 \`\`\`
 
-## Stacked Bar Chart
+## Flat Functions (No Hook)
 
 \`\`\`tsx
-import React from 'react';
-import { BarChart } from '@idealyst/charts';
+import {
+  initializePayments,
+  checkPaymentAvailability,
+  confirmPayment,
+  getPaymentStatus,
+} from '@idealyst/payments';
+import type { PaymentError } from '@idealyst/payments';
+
+// Initialize once at app startup
+async function setupPayments() {
+  await initializePayments({
+    publishableKey: 'pk_test_xxx',
+    merchantIdentifier: 'merchant.com.myapp',
+    merchantName: 'My App',
+    merchantCountryCode: 'US',
+  });
 
-function StackedBarExample() {
-  return (
-    <BarChart
-      data={[
-        {
-          id: 'online',
-          name: 'Online',
-          data: [
-            { x: 'Q1', y: 100 },
-            { x: 'Q2', y: 120 },
-            { x: 'Q3', y: 90 },
-          ],
-          color: '#4CAF50',
-        },
-        {
-          id: 'in-store',
-          name: 'In-Store',
-          data: [
-            { x: 'Q1', y: 60 },
-            { x: 'Q2', y: 80 },
-            { x: 'Q3', y: 70 },
-          ],
-          color: '#2196F3',
-        },
-      ]}
-      height={300}
-      stacked
-      animate
-    />
-  );
+  const status = getPaymentStatus();
+  console.log('Payment ready:', status.state === 'ready');
+}
+
+// Check availability
+async function canPay() {
+  const methods = await checkPaymentAvailability();
+  return methods.some(m => m.isAvailable);
+}
+
+// Process payment
+async function processPayment(clientSecret: string, totalCents: number) {
+  try {
+    const result = await confirmPayment({
+      clientSecret,
+      amount: { amount: totalCents, currencyCode: 'usd' },
+    });
+    return result;
+  } catch (err) {
+    const paymentErr = err as PaymentError;
+    if (paymentErr.code === 'user_cancelled') {
+      return null; // User cancelled \u2014 not an error
+    }
+    throw paymentErr;
+  }
 }
 \`\`\`
 
-## Horizontal Bar Chart
+## Platform-Conditional UI
 
 \`\`\`tsx
-import React from 'react';
-import { BarChart } from '@idealyst/charts';
+import { usePayments } from '@idealyst/payments';
+import { Platform } from 'react-native';
 
-function HorizontalBarExample() {
-  const data = [
-    { x: 'React', y: 85 },
-    { x: 'Vue', y: 62 },
-    { x: 'Angular', y: 45 },
-    { x: 'Svelte', y: 38 },
-  ];
+function PaymentButtons({ clientSecret }: { clientSecret: string }) {
+  const {
+    isApplePayAvailable,
+    isGooglePayAvailable,
+    confirmPayment,
+    isProcessing,
+  } = usePayments({
+    config: {
+      publishableKey: 'pk_test_xxx',
+      merchantName: 'My Store',
+      merchantCountryCode: 'US',
+    },
+  });
+
+  const handlePlatformPay = () =>
+    confirmPayment({
+      clientSecret,
+      amount: { amount: 2499, currencyCode: 'usd' },
+    });
 
   return (
-    <BarChart
-      data={[{ id: 'popularity', name: 'Popularity', data }]}
-      height={250}
-      orientation="horizontal"
-      animate
-    />
+    <View>
+      {isApplePayAvailable && (
+        <Button
+          onPress={handlePlatformPay}
+          disabled={isProcessing}
+          iconName="apple"
+        >
+          Apple Pay
+        </Button>
+      )}
+
+      {isGooglePayAvailable && (
+        <Button
+          onPress={handlePlatformPay}
+          disabled={isProcessing}
+          iconName="google"
+        >
+          Google Pay
+        </Button>
+      )}
+
+      {/* Always show a card fallback */}
+      <Button
+        onPress={() => navigateToCardForm()}
+        intent="secondary"
+      >
+        Pay with Card
+      </Button>
+    </View>
   );
 }
 \`\`\`
+
+## Best Practices
+
+1. **Server-side PaymentIntent** \u2014 Always create PaymentIntents on your server, never on the client
+2. **Handle cancellation** \u2014 \`user_cancelled\` is not an error, don't show error UI for it
+3. **Test environment** \u2014 Set \`testEnvironment: true\` during development for Google Pay
+4. **Apple Pay merchant ID** \u2014 Requires Apple Developer Program and Xcode capability setup
+5. **Amounts in cents** \u2014 All amounts are in the smallest currency unit (1099 = $10.99)
+6. **Web fallback** \u2014 On web, use \`@stripe/react-stripe-js\` (Stripe Elements) directly
+7. **3D Secure** \u2014 Set \`urlScheme\` in config for 3D Secure / bank redirect flows on native
+8. **Error handling** \u2014 Always wrap \`confirmPayment\` / \`createPaymentMethod\` in try/catch
 `
 };
 
@@ -24323,7 +26315,7 @@ function getStorageGuide(args) {
   const guide = storageGuides[uri];
   if (!guide) {
     return textResponse(
-      `Topic "${topic}" not found. Available topics: overview, api, examples`
+      `Topic "${topic}" not found. Available topics: overview, api, examples, secure`
     );
   }
   return textResponse(guide);
@@ -24449,6 +26441,39 @@ function getChartsGuide(args) {
   }
   return textResponse(guide);
 }
+function getClipboardGuide(args) {
+  const topic = args.topic;
+  const uri = `idealyst://clipboard/${topic}`;
+  const guide = clipboardGuides[uri];
+  if (!guide) {
+    return textResponse(
+      `Topic "${topic}" not found. Available topics: overview, api, examples`
+    );
+  }
+  return textResponse(guide);
+}
+function getBiometricsGuide(args) {
+  const topic = args.topic;
+  const uri = `idealyst://biometrics/${topic}`;
+  const guide = biometricsGuides[uri];
+  if (!guide) {
+    return textResponse(
+      `Topic "${topic}" not found. Available topics: overview, api, examples`
+    );
+  }
+  return textResponse(guide);
+}
+function getPaymentsGuide(args) {
+  const topic = args.topic;
+  const uri = `idealyst://payments/${topic}`;
+  const guide = paymentsGuides[uri];
+  if (!guide) {
+    return textResponse(
+      `Topic "${topic}" not found. Available topics: overview, api, examples`
+    );
+  }
+  return textResponse(guide);
+}
 function listPackages(args = {}) {
   const category = args.category;
   if (category) {
@@ -24694,6 +26719,9 @@ var toolHandlers = {
   get_markdown_guide: getMarkdownGuide,
   get_config_guide: getConfigGuide,
   get_charts_guide: getChartsGuide,
+  get_clipboard_guide: getClipboardGuide,
+  get_biometrics_guide: getBiometricsGuide,
+  get_payments_guide: getPaymentsGuide,
   list_packages: listPackages,
   get_package_docs: getPackageDocs,
   search_packages: searchPackages2,