@idealyst/mcp-server 1.2.117 → 1.2.119

package/dist/index.cjs

@@ -2689,10 +2689,13 @@ Layout components are **web-only**. Native ignores \`layoutComponent\` entirely.
 layouts/
   AppLayout.web.tsx       \u2190 Real layout with Outlet from @idealyst/navigation
   AppLayout.native.tsx    \u2190 No-op mock (return null)
+  index.ts                \u2190 REQUIRED: base export for TypeScript resolution
   index.web.ts            \u2190 export { AppLayout } from './AppLayout.web'
   index.native.ts         \u2190 export { AppLayout } from './AppLayout.native'
 \`\`\`
 
+> **CRITICAL:** You MUST create a base \`index.ts\` alongside \`index.web.ts\` and \`index.native.ts\`. Without it, TypeScript cannot resolve \`import { AppLayout } from './layouts'\` and you get TS2307. The base \`index.ts\` re-exports from the web version (bundlers pick the platform-specific file at runtime).
+
 ### Example Files
 
 **\`AppLayout.web.tsx\`** \u2014 The real layout:
@@ -2730,6 +2733,11 @@ export function AppLayout() {
 }
 \`\`\`
 
+**\`index.ts\`** \u2014 Base export (REQUIRED for TypeScript module resolution):
+\`\`\`ts
+export { AppLayout } from './AppLayout.web';
+\`\`\`
+
 **\`index.web.ts\`**:
 \`\`\`ts
 export { AppLayout } from './AppLayout.web';
@@ -2760,7 +2768,9 @@ const appRouter: NavigatorParam = {
 > **Key rules:**
 > - Import \`Outlet\` from \`@idealyst/navigation\` (NOT from \`react-router-dom\`)
 > - Layout props do NOT include \`children\` \u2014 content renders via \`<Outlet />\`
-> - Always create both \`.web.tsx\` and \`.native.tsx\` files with platform index files
+> - Always create \`.web.tsx\`, \`.native.tsx\`, AND a base \`index.ts\` \u2014 without the base \`index.ts\`, TypeScript reports TS2307 (cannot find module)
+> - The base \`index.ts\` re-exports from the \`.web\` version; bundlers pick the right platform file at runtime
+> - **Web-only CSS** in \`.web.tsx\`: cast with \`as any\`, NOT \`as React.CSSProperties\` \u2014 \`CSSProperties\` is incompatible with \`StyleProp<ViewStyle>\` (TS2322). Example: \`style={{ position: 'fixed', transition: 'width 0.2s' } as any}\`
 
 ## GeneralLayout Component
 
@@ -7449,6 +7459,52 @@ await end(info.id, { dismissalPolicy: 'default' });`,
       "deliveryActivity() / timerActivity() / mediaActivity() / progressActivity() - Template presets"
     ],
     relatedPackages: ["notifications"]
+  },
+  network: {
+    name: "Network",
+    npmName: "@idealyst/network",
+    description: "Cross-platform network connectivity and utilities for React and React Native. Real-time connection monitoring, fetch with timeout, retry with exponential backoff, and wait-for-network primitives.",
+    category: "utility",
+    platforms: ["web", "native"],
+    documentationStatus: "full",
+    installation: "yarn add @idealyst/network",
+    peerDependencies: [
+      "@react-native-community/netinfo (native)"
+    ],
+    features: [
+      "useNetwork hook \u2014 real-time isConnected, connection type, effective speed",
+      "Network state listener for non-React code",
+      "Connection type detection \u2014 WiFi, cellular, ethernet, bluetooth, VPN",
+      "Effective connection speed \u2014 slow-2g, 2g, 3g, 4g",
+      "Cellular generation \u2014 2G, 3G, 4G, 5G (native)",
+      "Internet reachability \u2014 distinguish connected from reachable",
+      "fetchWithTimeout \u2014 fetch with configurable auto-abort",
+      "retry \u2014 exponential backoff with network-aware gating",
+      "waitForNetwork \u2014 promise that resolves when back online",
+      "Data saver detection (web)",
+      "Downlink speed and RTT estimation (web)"
+    ],
+    quickStart: `import { useNetwork } from '@idealyst/network';
+
+function App() {
+  const { isConnected, type, effectiveType } = useNetwork();
+
+  if (!isConnected) {
+    return <Text>You are offline</Text>;
+  }
+
+  return <Text>Connected via {type} ({effectiveType})</Text>;
+}`,
+    apiHighlights: [
+      "useNetwork(options?) - React hook for real-time network state",
+      "getNetworkState() - One-time state snapshot (sync on web, async on native)",
+      "addNetworkStateListener(cb) - Subscribe to changes (returns unsubscribe)",
+      "fetchWithTimeout(url, options) - Fetch with auto-abort timeout",
+      "retry(fn, options) - Exponential backoff retry",
+      "waitForNetwork(options) - Promise that resolves when online",
+      "NetworkState { isConnected, isInternetReachable, type, effectiveType, cellularGeneration, downlink, rtt, isDataSaving }"
+    ],
+    relatedPackages: ["storage", "config"]
   }
 };
 function getPackagesByCategory() {
@@ -10940,6 +10996,21 @@ var getLiveActivityGuideDefinition = {
     required: ["topic"]
   }
 };
+var getNetworkGuideDefinition = {
+  name: "get_network_guide",
+  description: "Get documentation for @idealyst/network cross-platform network connectivity and utilities package. Covers useNetwork hook, fetchWithTimeout, retry, waitForNetwork, 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 toolDefinitions = [
   // Component tools
   listComponentsDefinition,
@@ -10975,6 +11046,7 @@ var toolDefinitions = [
   getPaymentsGuideDefinition,
   getNotificationsGuideDefinition,
   getLiveActivityGuideDefinition,
+  getNetworkGuideDefinition,
   // Package tools
   listPackagesDefinition,
   getPackageDocsDefinition,
@@ -11227,9 +11299,10 @@ var componentMetadata = {
   },
   Image: {
     category: "display",
-    description: "Cross-platform image component with loading and error states",
+    description: "Cross-platform image component for displaying photos, pictures, and remote/local images with loading and error states",
     features: [
-      "Multiple resize modes",
+      "Display photos, pictures, and media from URLs or local sources",
+      "Multiple resize modes (cover, contain, stretch, center)",
       "Loading placeholder",
       "Error fallback",
       "Lazy loading",
@@ -11599,7 +11672,11 @@ var componentAliases = {
   fab: "IconButton",
   modal: "Dialog",
   tooltip: "Tooltip",
-  snackbar: "Toast"
+  snackbar: "Toast",
+  photo: "Image",
+  picture: "Image",
+  img: "Image",
+  thumbnail: "Image"
 };
 function findComponentName(componentName) {
   if (componentMetadata[componentName]) {
@@ -11768,7 +11845,8 @@ yarn add @idealyst/audio
 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\`, \`backgroundRecord\`
-5. **Background Recording** \u2014 \`useBackgroundRecorder\` hook for recording that continues when the app is backgrounded (iOS/Android). Requires app-level native entitlements.
+5. **Audio Level** \u2014 \`recorder.level\` returns \`AudioLevel { current: number, peak: number, rms: number, db: number }\`. All values are 0.0-1.0 except \`db\` (-Infinity to 0).
+6. **Background Recording** \u2014 \`useBackgroundRecorder\` hook for recording that continues when the app is backgrounded (iOS/Android). Requires app-level native entitlements.
 
 ## Exports
 
@@ -11866,6 +11944,22 @@ interface UsePlayerOptions {
 | toggleMute | () => void | Toggle mute |
 
 > **Critical:** \`feedPCMData()\` accepts \`ArrayBufferLike | Int16Array\` \u2014 **NOT strings or base64**.
+> If you receive base64-encoded audio from an external API and need to play it back, you MUST decode it to binary first.
+> **Cross-platform base64 decode** (do NOT use \`atob()\` \u2014 it's browser-only):
+> \`\`\`typescript
+> // Cross-platform: works on web AND React Native
+> function base64ToArrayBuffer(base64: string): ArrayBuffer {
+>   const binaryString = typeof atob !== 'undefined'
+>     ? atob(base64)
+>     : Buffer.from(base64, 'base64').toString('binary');
+>   const bytes = new Uint8Array(binaryString.length);
+>   for (let i = 0; i < binaryString.length; i++) {
+>     bytes[i] = binaryString.charCodeAt(i);
+>   }
+>   return bytes.buffer;
+> }
+> // Then: player.feedPCMData(base64ToArrayBuffer(encodedAudio));
+> \`\`\`
 
 ---
 
@@ -12315,7 +12409,7 @@ function BackgroundTranscriber() {
 
 \`\`\`tsx
 import React from 'react';
-import { View, Text } from '@idealyst/components';
+import { View, Text, Progress } from '@idealyst/components';
 import { useRecorder, AUDIO_PROFILES } from '@idealyst/audio';
 
 function AudioLevelMeter() {
@@ -12329,22 +12423,10 @@ function AudioLevelMeter() {
       <Text>Level: {Math.round(recorder.level.current * 100)}%</Text>
       <Text>Peak: {Math.round(recorder.level.peak * 100)}%</Text>
       <Text>dB: {recorder.level.db.toFixed(1)}</Text>
-      <View
-        style={{
-          height: 20,
-          backgroundColor: '#e0e0e0',
-          borderRadius: 10,
-          overflow: 'hidden',
-        }}
-      >
-        <View
-          style={{
-            width: \`\${recorder.level.current * 100}%\`,
-            height: '100%',
-            backgroundColor: recorder.level.current > 0.8 ? 'red' : 'green',
-          }}
-        />
-      </View>
+      <Progress
+        value={recorder.level.current * 100}
+        intent={recorder.level.current > 0.8 ? 'danger' : 'success'}
+      />
     </View>
   );
 }
@@ -12418,6 +12500,8 @@ function CameraScreen() {
 
 Renders the camera preview. Must receive a camera instance from \`useCamera().cameraRef.current\`.
 
+> **IMPORTANT:** CameraPreview uses \`resizeMode\` ('cover' | 'contain'). But when displaying captured photos, use the **Image** component with \`objectFit\` \u2014 NOT \`resizeMode\`. Image does NOT have a \`resizeMode\` prop. Example: \`<Image source={photo.uri} objectFit="cover" />\`.
+
 \`\`\`typescript
 interface CameraPreviewProps {
   camera: ICamera | null;            // Camera instance from useCamera().cameraRef.current
@@ -12799,7 +12883,9 @@ import {
 \`\`\`
 
 > **Common mistakes:**
+> - **\`pick()\` returns \`FilePickerResult\`, NOT an array.** Access files via \`result.files\`: \`result.files.length\`, \`result.files[0].uri\`. Do NOT write \`result.length\` or \`result[0]\` \u2014 \`FilePickerResult\` is an object: \`{ cancelled: boolean, files: PickedFile[], rejected: RejectedFile[] }\`.
 > - The method is \`pick()\`, NOT \`pickFiles()\`
+> - \`pick()\` accepts overrides DIRECTLY: \`picker.pick({ allowedTypes: ['image'] })\` \u2014 NOT \`picker.pick({ config: { allowedTypes: ['image'] } })\`. The \`{ config: ... }\` wrapper is ONLY for \`useFilePicker()\` initialization.
 > - \`FileType\` values are: \`'image' | 'video' | 'audio' | 'document' | 'archive' | 'any'\` \u2014 NOT \`'pdf'\` or \`'doc'\`
 > - \`PickedFile\` has \`uri\`, \`name\`, \`size\`, \`type\`, \`extension\` \u2014 dimensions are in optional \`dimensions?: { width, height }\`, NOT top-level \`width\`/\`height\`
 
@@ -12854,7 +12940,7 @@ interface UseFilePickerOptions {
 | permission | PermissionResult \\| null | Permission result |
 | error | FilePickerError \\| null | Current error |
 | files | PickedFile[] | Last picked files |
-| pick | (config?) => Promise<FilePickerResult> | **Open file picker** |
+| pick | (overrides?: Partial\\<FilePickerConfig\\>) => Promise<FilePickerResult> | **Open file picker. Overrides go DIRECTLY \u2014 NOT wrapped in \`{ config }\`.** Example: \`picker.pick({ allowedTypes: ['image'] })\` \u2014 NOT \`picker.pick({ config: { allowedTypes: ['image'] } })\` |
 | captureFromCamera | (options?) => Promise<FilePickerResult> | Open camera to capture |
 | clear | () => void | Clear picked files |
 | checkPermission | () => Promise<PermissionResult> | Check permission |
@@ -12991,6 +13077,27 @@ interface PickedFile {
 
 > **Note:** \`dimensions\` is an optional nested object \u2014 NOT top-level \`width\`/\`height\` properties.
 
+### FilePickerResult (returned by pick())
+
+\`\`\`typescript
+interface FilePickerResult {
+  cancelled: boolean;        // Whether user cancelled the picker
+  files: PickedFile[];       // Picked files (empty if cancelled)
+  rejected: RejectedFile[];  // Files rejected by validation
+  error?: FilePickerError;   // Error if picker failed
+}
+\`\`\`
+
+> **CRITICAL:** \`pick()\` returns \`FilePickerResult\`, NOT an array. Always access \`result.files\` to get the array of picked files:
+> \`\`\`typescript
+> const result = await picker.pick();
+> if (!result.cancelled && result.files.length > 0) {
+>   const file = result.files[0]; // \u2705 Correct
+>   console.log(file.uri, file.name);
+> }
+> // \u274C WRONG: result.length, result[0] \u2014 FilePickerResult is NOT an array
+> \`\`\`
+
 ### FilePickerConfig
 
 \`\`\`typescript
@@ -13639,9 +13746,9 @@ Animate any style property changes. Returns an animated style object.
 
 \`\`\`typescript
 interface AnimationOptions {
-  duration?: Duration;    // ms or theme token key
-  easing?: EasingKey;     // Theme easing key
-  delay?: number;         // Delay before animation (ms)
+  duration?: Duration;    // ms or theme token key (e.g., 300, 500)
+  easing?: EasingKey;     // Theme easing key (e.g., 'easeOut', 'spring')
+  delay?: number;         // Delay in ms before animation starts (e.g., 100, 200). Useful for staggered entrance animations.
 }
 
 interface UseAnimatedStyleOptions extends AnimationOptions {
@@ -13668,6 +13775,20 @@ const entranceStyle = useAnimatedStyle(
   { opacity: ready ? 1 : 0, transform: { y: ready ? 0 : 20 } },
   { duration: 400, easing: 'easeOut' }
 );
+
+// Staggered entrance: use delay for each item
+const style1 = useAnimatedStyle(
+  { opacity: ready ? 1 : 0, transform: { y: ready ? 0 : 20 } },
+  { duration: 300, easing: 'easeOut', delay: 0 }
+);
+const style2 = useAnimatedStyle(
+  { opacity: ready ? 1 : 0, transform: { y: ready ? 0 : 20 } },
+  { duration: 300, easing: 'easeOut', delay: 100 }
+);
+const style3 = useAnimatedStyle(
+  { opacity: ready ? 1 : 0, transform: { y: ready ? 0 : 20 } },
+  { duration: 300, easing: 'easeOut', delay: 200 }
+);
 \`\`\`
 
 ---
@@ -13819,16 +13940,18 @@ For expand/collapse, animate \`opacity\` + \`maxHeight\` together. Do NOT includ
 
 ## Transform Syntax
 
-Use simplified object syntax instead of React Native arrays:
+**ALWAYS use object syntax** for transforms in useAnimatedStyle/usePresence:
 
 \`\`\`typescript
-// Recommended: object syntax
+// CORRECT: object syntax (required for animations)
 transform: { x: 10, y: 20, scale: 1.2, rotate: 45 }
 
-// Legacy: array syntax (still supported)
-transform: [{ translateX: 10 }, { translateY: 20 }, { scale: 1.2 }]
+// WRONG in useAnimatedStyle: array syntax does NOT animate correctly
+// transform: [{ translateX: 10 }, { translateY: 20 }]  // \u274C won't animate
 \`\`\`
 
+> **IMPORTANT:** Array-syntax transforms (React Native style) do NOT work with \`useAnimatedStyle\` or \`usePresence\`. Always use the simplified object syntax: \`transform: { x, y, scale, rotate }\`. Array syntax is only valid in static \`style\` props on non-animated elements.
+
 | Property | Type | Maps to |
 |----------|------|---------|
 | x | number | translateX |
@@ -18766,6 +18889,396 @@ function MyScreen() {
 `
 };
 
+// src/data/network-guides.ts
+var networkGuides = {
+  "idealyst://network/overview": `# @idealyst/network Overview
+
+Cross-platform network connectivity and utilities for React and React Native. Know when the user has network, what kind, and react to changes in real time.
+
+## Features
+
+- **useNetwork Hook** \u2014 Real-time network state with isConnected, connection type, effective speed
+- **Network State Listener** \u2014 Subscribe to connectivity changes outside React
+- **Connection Details** \u2014 WiFi, cellular (2G/3G/4G/5G), ethernet, bluetooth, VPN detection
+- **Effective Connection Type** \u2014 slow-2g, 2g, 3g, 4g speed categories
+- **Internet Reachability** \u2014 Distinguish "connected to network" from "can reach internet"
+- **fetchWithTimeout** \u2014 Fetch wrapper with configurable timeout and auto-abort
+- **retry** \u2014 Exponential backoff retry with optional network-aware gating
+- **waitForNetwork** \u2014 Promise that resolves when the device comes back online
+- **Data Saver Detection** \u2014 Detect if user has enabled data-saving mode (web)
+- **Cross-Platform** \u2014 navigator.onLine + Network Information API (web), @react-native-community/netinfo (native)
+- **TypeScript** \u2014 Full type safety and IntelliSense
+
+## Installation
+
+\`\`\`bash
+yarn add @idealyst/network
+
+# React Native also needs:
+yarn add @react-native-community/netinfo
+cd ios && pod install
+\`\`\`
+
+## Quick Start
+
+\`\`\`tsx
+import { useNetwork } from '@idealyst/network';
+
+function App() {
+  const { isConnected, type, effectiveType } = useNetwork();
+
+  if (!isConnected) {
+    return <Text>You are offline</Text>;
+  }
+
+  return (
+    <Text>
+      Connected via {type} ({effectiveType})
+    </Text>
+  );
+}
+\`\`\`
+
+## Platform Details
+
+- **Web**: Uses \`navigator.onLine\`, \`online\`/\`offline\` events, and the Network Information API (\`navigator.connection\`) for connection type, downlink speed, RTT, and data saver detection
+- **React Native**: Uses \`@react-native-community/netinfo\` for connection type, cellular generation, internet reachability, and real-time state changes
+- **SSR**: Safe for server-side rendering \u2014 returns sensible defaults when \`navigator\` is unavailable
+`,
+  "idealyst://network/api": `# Network API Reference
+
+Complete API reference for @idealyst/network.
+
+## useNetwork
+
+React hook for monitoring network connectivity. Returns reactive state that updates automatically.
+
+\`\`\`tsx
+const {
+  state,              // NetworkState \u2014 full state object
+  isConnected,        // boolean \u2014 device has active network
+  isInternetReachable,// boolean | null \u2014 can reach internet (null = unknown)
+  type,               // NetworkConnectionType \u2014 'wifi' | 'cellular' | 'ethernet' | ...
+  effectiveType,      // EffectiveConnectionType \u2014 'slow-2g' | '2g' | '3g' | '4g' | 'unknown'
+  refresh,            // () => Promise<NetworkState> \u2014 manually refresh state
+} = useNetwork(options?: UseNetworkOptions);
+\`\`\`
+
+### UseNetworkOptions
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| fetchOnMount | boolean | true | Fetch initial state on mount |
+| reachabilityUrl | string | (google 204) | URL for reachability pings (web only) |
+| reachabilityPollInterval | number | 0 | Polling interval in ms for reachability checks (web only). 0 = disabled |
+
+---
+
+## getNetworkState
+
+Get a one-time snapshot of the current network state.
+
+\`\`\`tsx
+// Web (synchronous)
+import { getNetworkState } from '@idealyst/network';
+const state: NetworkState = getNetworkState();
+
+// Native (async \u2014 requires NetInfo fetch)
+import { getNetworkState } from '@idealyst/network';
+const state: NetworkState = await getNetworkState();
+\`\`\`
+
+**Note:** On web, \`getNetworkState()\` is synchronous. On native, it returns a Promise.
+
+---
+
+## addNetworkStateListener
+
+Subscribe to network state changes outside of React.
+
+\`\`\`tsx
+import { addNetworkStateListener } from '@idealyst/network';
+
+const unsubscribe = addNetworkStateListener((state) => {
+  console.log('Network changed:', state.isConnected, state.type);
+});
+
+// Later:
+unsubscribe();
+\`\`\`
+
+---
+
+## fetchWithTimeout
+
+Fetch wrapper that automatically aborts if the request exceeds a timeout.
+
+\`\`\`tsx
+import { fetchWithTimeout } from '@idealyst/network';
+
+const response = await fetchWithTimeout('https://api.example.com/data', {
+  timeout: 5000,    // 5 seconds (default: 10000)
+  method: 'GET',
+  headers: { 'Authorization': 'Bearer token' },
+});
+\`\`\`
+
+### FetchWithTimeoutOptions
+
+Extends standard \`RequestInit\` with:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| timeout | number | 10000 | Timeout in milliseconds |
+
+---
+
+## retry
+
+Retry a function with exponential backoff. Optionally waits for network before retrying.
+
+\`\`\`tsx
+import { retry } from '@idealyst/network';
+
+const data = await retry(
+  () => fetch('https://api.example.com/data').then(r => r.json()),
+  {
+    maxRetries: 3,
+    baseDelay: 1000,
+    maxDelay: 30000,
+    retryOnlyWhenConnected: true,
+  },
+);
+\`\`\`
+
+### RetryOptions
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| maxRetries | number | 3 | Maximum retry attempts |
+| baseDelay | number | 1000 | Base delay in ms (doubles each attempt) |
+| maxDelay | number | 30000 | Maximum delay cap in ms |
+| retryOnlyWhenConnected | boolean | true | Wait for network before retrying |
+
+---
+
+## waitForNetwork
+
+Returns a promise that resolves when the device comes back online.
+
+\`\`\`tsx
+import { waitForNetwork } from '@idealyst/network';
+
+// Wait up to 30 seconds for connectivity
+await waitForNetwork({ timeout: 30000 });
+console.log('Back online!');
+\`\`\`
+
+If already online, resolves immediately. Rejects with an error if the timeout is exceeded.
+
+### WaitForNetworkOptions
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| timeout | number | 30000 | Max wait time in ms before rejecting |
+
+---
+
+## NetworkState
+
+Full network state object returned by the hook and listeners.
+
+\`\`\`tsx
+interface NetworkState {
+  isConnected: boolean;                    // Device has active network
+  isInternetReachable: boolean | null;     // Internet reachable (null = unknown)
+  type: NetworkConnectionType;             // 'wifi' | 'cellular' | 'ethernet' | ...
+  effectiveType: EffectiveConnectionType;  // 'slow-2g' | '2g' | '3g' | '4g' | 'unknown'
+  cellularGeneration: CellularGeneration;  // '2g' | '3g' | '4g' | '5g' | null (native only)
+  downlink: number | null;                 // Mbps (web only, from Network Info API)
+  rtt: number | null;                      // Round-trip time ms (web only)
+  isDataSaving: boolean | null;            // Data saver enabled (web only)
+}
+\`\`\`
+
+## Type Aliases
+
+\`\`\`tsx
+type NetworkConnectionType = 'wifi' | 'cellular' | 'ethernet' | 'bluetooth' | 'vpn' | 'other' | 'none' | 'unknown';
+type EffectiveConnectionType = 'slow-2g' | '2g' | '3g' | '4g' | 'unknown';
+type CellularGeneration = '2g' | '3g' | '4g' | '5g' | null;
+\`\`\`
+`,
+  "idealyst://network/examples": `# Network Examples
+
+Complete code examples for common @idealyst/network patterns.
+
+## Offline Banner
+
+\`\`\`tsx
+import { useNetwork } from '@idealyst/network';
+import { View, Text } from '@idealyst/components';
+
+function OfflineBanner() {
+  const { isConnected } = useNetwork();
+
+  if (isConnected) return null;
+
+  return (
+    <View style={{ backgroundColor: '#f44336', padding: 8 }}>
+      <Text style={{ color: '#fff', textAlign: 'center' }}>
+        No internet connection
+      </Text>
+    </View>
+  );
+}
+\`\`\`
+
+## Adaptive Quality Based on Connection
+
+\`\`\`tsx
+import { useNetwork } from '@idealyst/network';
+
+function MediaPlayer({ videoId }: { videoId: string }) {
+  const { effectiveType, isDataSaving } = useNetwork().state;
+
+  const quality = (() => {
+    if (isDataSaving) return 'low';
+    switch (effectiveType) {
+      case 'slow-2g':
+      case '2g':
+        return 'low';
+      case '3g':
+        return 'medium';
+      case '4g':
+      default:
+        return 'high';
+    }
+  })();
+
+  return <VideoPlayer videoId={videoId} quality={quality} />;
+}
+\`\`\`
+
+## Retry API Calls
+
+\`\`\`tsx
+import { retry, fetchWithTimeout } from '@idealyst/network';
+
+async function fetchUserProfile(userId: string) {
+  const response = await retry(
+    () => fetchWithTimeout(\`https://api.example.com/users/\${userId}\`, {
+      timeout: 5000,
+    }),
+    { maxRetries: 3, baseDelay: 1000 },
+  );
+
+  if (!response.ok) {
+    throw new Error(\`Failed to fetch user: \${response.status}\`);
+  }
+
+  return response.json();
+}
+\`\`\`
+
+## Wait for Network Before Action
+
+\`\`\`tsx
+import { waitForNetwork } from '@idealyst/network';
+
+async function syncData() {
+  // If offline, wait up to 60 seconds for connectivity
+  await waitForNetwork({ timeout: 60000 });
+
+  // Now we're online \u2014 sync
+  const response = await fetch('https://api.example.com/sync', {
+    method: 'POST',
+    body: JSON.stringify(pendingChanges),
+  });
+
+  return response.json();
+}
+\`\`\`
+
+## Network State Listener (Outside React)
+
+\`\`\`tsx
+import { addNetworkStateListener } from '@idealyst/network';
+
+// Subscribe to changes (e.g., in a service or module)
+const unsubscribe = addNetworkStateListener((state) => {
+  if (!state.isConnected) {
+    queueManager.pause();
+  } else {
+    queueManager.resume();
+  }
+});
+
+// Cleanup when done
+unsubscribe();
+\`\`\`
+
+## Connection Type Display
+
+\`\`\`tsx
+import { useNetwork } from '@idealyst/network';
+import { View, Text } from '@idealyst/components';
+
+function NetworkInfo() {
+  const { state } = useNetwork();
+
+  return (
+    <View>
+      <Text>Status: {state.isConnected ? 'Online' : 'Offline'}</Text>
+      <Text>Type: {state.type}</Text>
+      <Text>Speed: {state.effectiveType}</Text>
+      {state.cellularGeneration && (
+        <Text>Cellular: {state.cellularGeneration}</Text>
+      )}
+      {state.downlink != null && (
+        <Text>Downlink: {state.downlink} Mbps</Text>
+      )}
+      {state.rtt != null && (
+        <Text>RTT: {state.rtt} ms</Text>
+      )}
+      {state.isDataSaving != null && (
+        <Text>Data Saver: {state.isDataSaving ? 'On' : 'Off'}</Text>
+      )}
+    </View>
+  );
+}
+\`\`\`
+
+## Fetch with Timeout
+
+\`\`\`tsx
+import { fetchWithTimeout } from '@idealyst/network';
+
+async function quickHealthCheck() {
+  try {
+    const response = await fetchWithTimeout('https://api.example.com/health', {
+      timeout: 3000,
+      method: 'HEAD',
+    });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+\`\`\`
+
+## Best Practices
+
+1. **Use \`useNetwork\` for UI** \u2014 The hook handles subscriptions and cleanup automatically
+2. **Use \`addNetworkStateListener\` for services** \u2014 For non-React code (queue managers, sync services)
+3. **Combine retry + fetchWithTimeout** \u2014 For resilient API calls
+4. **Check \`isInternetReachable\`** \u2014 Being "connected" to WiFi doesn't mean you have internet
+5. **Respect data saver** \u2014 Reduce payload sizes and avoid autoplay when \`isDataSaving\` is true
+6. **Don't poll too aggressively** \u2014 If using \`reachabilityPollInterval\`, keep it >= 15000ms
+7. **Use \`waitForNetwork\` for offline-first** \u2014 Queue operations and wait for connectivity to sync
+`
+};
+
 // src/data/install-guides.ts
 var installGuides = {
   // ============================================================================
@@ -20246,16 +20759,23 @@ import { View, Text, Button, TextInput, Card, Icon, ... } from '@idealyst/compon
 
 ## How to Use This MCP Server
 
-This server has tools for every aspect of the framework. **Always look up the API before writing code.**
+This server has tools for every aspect of the framework. **Look up APIs as you need them \u2014 don't research everything upfront.**
+
+### Workflow
+
+Write code iteratively \u2014 **look up one API, write one file, repeat**:
+
+1. Call \`get_intro\` (this response)
+2. Look up the API for your FIRST file only (e.g., \`get_component_types("Button,Card,Text")\`)
+3. **Write that file immediately** using the Write tool
+4. Then look up the next API you need, write the next file, and so on
 
-### Workflow (be efficient \u2014 minimize tool calls)
+- **Before using a component** \u2014 call \`get_component_types\` for its props (supports batching: \`get_component_types("Button,Card,Text")\`)
+- **Before using a package** \u2014 call its dedicated \`get_*_guide\` tool with topic \`api\`
+- **Search icons once** \u2014 batch all terms into one call: \`search_icons("home settings check timer")\`
+- **Check recipes** \u2014 \`search_recipes\` for ready-made patterns you can adapt
 
-1. **Start here** \u2014 this intro covers conventions and gotchas
-2. **Look up components** \u2014 call \`get_component_types\` for EVERY component you plan to use. Call it for each component you need. (Card has NO compound components \u2014 no Card.Content/Card.Header)
-3. **Look up packages** \u2014 call the dedicated \`get_*_guide\` tool with topic \`api\` for each \`@idealyst/*\` package
-4. **Check recipes** \u2014 call \`search_recipes\` to find ready-made patterns for common screens
-5. **Search icons ONCE** \u2014 combine all needed icon terms into ONE \`search_icons\` call (e.g., \`"home settings check timer calendar"\`)
-6. **Then write code** \u2014 only after reading the types and guides. Do NOT make additional icon searches \u2014 pick from what you found
+> **WARNING: Do NOT load multiple package guides, component types, AND icon searches all before writing your first file.** Each tool response is large. If you accumulate 4+ tool responses without writing any code, you WILL exhaust your output token budget and produce zero files. The correct pattern is: **research \u2192 write \u2192 research \u2192 write**, NOT **research \u2192 research \u2192 research \u2192 write**.
 
 ### Component Tools
 - \`list_components\` / \`search_components\` \u2014 Discover available components
@@ -20265,7 +20785,7 @@ This server has tools for every aspect of the framework. **Always look up the AP
 - \`search_icons\` \u2014 Find Material Design icon names (7,447 available). **Batch your needs**: search once with multiple terms like \`"home settings user check"\` rather than making separate calls per icon
 
 ### Package Guide Tools
-**For any \`@idealyst/*\` package, call its dedicated guide tool with topic \`api\` BEFORE writing code.** These return complete TypeScript interfaces, return types, and correct usage. The generic \`get_package_docs\` tool only has summaries.
+Each \`@idealyst/*\` package has a dedicated guide tool that returns complete TypeScript interfaces and correct usage. The generic \`get_package_docs\` tool only has summaries.
 
 | Package | Guide Tool |
 |---------|-----------|
@@ -20330,6 +20850,10 @@ const tabs: { icon: IconName }[] = [{ icon: 'home' }, { icon: 'search' }]; // NO
 
 > **CRITICAL:** Icon names do NOT have an \`mdi:\` prefix. Use bare names like \`'delete'\`, \`'home'\`, \`'check-circle'\` \u2014 NOT \`'mdi:delete'\`, \`'mdi:home'\`, etc.
 > **CRITICAL:** When defining arrays or objects with icon fields, type them as \`IconName\` \u2014 never \`string\`. Using \`string\` will cause TS2322 when passed to component props.
+> **CRITICAL:** Helper functions that return icon names MUST have return type \`IconName\`, not \`string\`. Example: \`function getIcon(type: string): IconName { return type === 'pdf' ? 'file-pdf-box' : 'file-document-outline'; }\` \u2014 NOT \`function getIcon(type: string): string\`.
+> **CRITICAL:** ONLY use icon names returned by \`search_icons\`. Do NOT guess or invent icon names \u2014 unverified names render as blank with runtime warnings. If you need an icon, search for it first.
+
+**Common verified icon names** (use these without searching): \`home\`, \`cog\`, \`account\`, \`magnify\`, \`plus\`, \`close\`, \`check\`, \`chevron-left\`, \`chevron-right\`, \`chevron-down\`, \`chevron-up\`, \`arrow-left\`, \`arrow-right\`, \`menu\`, \`dots-vertical\`, \`pencil\`, \`delete\`, \`heart\`, \`star\`, \`bell\`, \`email\`, \`phone\`, \`camera\`, \`camera-flip\`, \`flash\`, \`flash-off\`, \`image\`, \`send\`, \`share\`, \`download\`, \`upload\`, \`eye\`, \`eye-off\`, \`lock\`, \`logout\`, \`refresh\`, \`calendar\`, \`clock\`, \`map-marker\`, \`chart-line\`, \`view-dashboard\`, \`account-group\`, \`message\`, \`information\`, \`alert\`, \`check-circle\`, \`close-circle\`, \`play\`, \`pause\`, \`stop\`, \`microphone\`, \`microphone-off\`, \`file-document-outline\`. For any icon NOT on this list, use \`search_icons\` to verify.
 
 ---
 
@@ -20339,26 +20863,27 @@ These are mistakes agents make repeatedly. Each one causes TypeScript compilatio
 
 ### Component Props
 1. **Text** does NOT have \`variant\`, \`intent\`, \`size\`, \`fontSize\`, \`numberOfLines\`, \`ellipsizeMode\`, \`selectable\`, \`textColor\`, or \`onPress\`. Use \`typography\` (\`h1\`\u2013\`h6\`, \`subtitle1\`, \`subtitle2\`, \`body1\`, \`body2\`, \`caption\`), \`weight\` (\`light\`, \`normal\`, \`medium\`, \`semibold\`, \`bold\`), and \`color\` (\`primary\`, \`secondary\`, \`tertiary\`, \`inverse\`). **\`textColor\` is an Icon-only prop** \u2014 Text uses \`color\`. For pressable text, wrap in \`Pressable\` or use \`Button type="text"\`.
-2. **TextInput** does NOT have \`label\`, \`error\`, \`editable\`, \`autoComplete\`, \`keyboardType\`, or \`onChange\`. Compose labels/errors with \`Text\` + \`View\`. Use \`onChangeText\`, \`inputMode\` (\`text\`, \`email\`, \`password\`, \`number\`), and \`textContentType\`. TextArea is different \u2014 it DOES support \`label\`, \`error\`, \`rows\`, \`onChange\`.
+2. **TextInput** does NOT have \`label\`, \`error\`, \`editable\`, \`autoComplete\`, \`keyboardType\`, or \`onChange\`. Compose labels/errors with \`Text\` + \`View\`. Use \`onChangeText\`, \`inputMode\` (\`'text' | 'email' | 'password' | 'number'\` \u2014 NOT \`'decimal'\`, \`'numeric'\`, \`'tel'\`, \`'url'\`), and \`textContentType\`. **TextArea has a DIFFERENT API** \u2014 it DOES support \`label\`, \`error\`, \`rows\`, \`onChange\`, but does NOT have \`onBlur\` or \`onChangeText\`. Always look up TextArea types separately.
 3. **Button/IconButton** \`type\` is \`'contained' | 'outlined' | 'text'\` \u2014 NOT \`'ghost'\`, \`'solid'\`, \`'default'\`. Button has \`leftIcon\` and \`rightIcon\` \u2014 NOT \`icon\`.
 4. **View** does NOT have \`direction\`, \`align\`, or \`onPress\` props. For touch handling, wrap content in \`Pressable\` from \`@idealyst/components\` (NOT from \`react-native\`): \`<Pressable onPress={handlePress}><View>...</View></Pressable>\`. For horizontal layout use \`style={{ flexDirection: 'row' }}\`. View spacing shorthand props (all accept Size: \`xs\`|\`sm\`|\`md\`|\`lg\`|\`xl\`): \`padding\`, \`paddingVertical\`, \`paddingHorizontal\`, \`margin\`, \`marginVertical\`, \`marginHorizontal\`, \`gap\`/\`spacing\`. Do NOT use \`paddingTop\`, \`paddingBottom\`, \`paddingLeft\`, \`paddingRight\`, \`marginTop\`, \`marginBottom\`, \`marginLeft\`, \`marginRight\` as shorthand props \u2014 they do NOT exist and will cause TS2353. For single-side spacing, use \`style={{ paddingTop: 16 }}\`. Other View props: \`background\`, \`radius\`, \`border\`, \`scrollable\`. \`border\` is \`'none' | 'thin' | 'thick'\` \u2014 NOT \`'outline'\`, \`'solid'\`.
-5. **Badge** \`type\` is \`'filled' | 'outlined' | 'dot'\` \u2014 NOT \`'soft'\`, \`'subtle'\`, \`'solid'\`.
+5. **Badge** \`type\` is \`'filled' | 'outlined' | 'dot'\` \u2014 NOT \`'soft'\`, \`'subtle'\`, \`'solid'\`. **Intent type narrowing (CRITICAL):** TS widens string literals in objects/arrays to \`string\`, which fails \`intent\` props. Rules: (a) Simple ternaries in JSX work fine: \`<Badge intent={cond ? 'success' : 'danger'}>\`. (b) **Do NOT use \`as const\` on ternary expressions** \u2014 \`(cond ? 'a' : 'b') as const\` causes TS1355. (c) **Arrays/objects with intent values MUST use \`as const\`**: \`const items = [{ intent: 'success' as const, label: 'OK' }]\` or \`const items = [{ intent: 'success', label: 'OK' }] as const\`. Without \`as const\`, \`item.intent\` becomes \`string\` which fails. (d) For computed values, use typed variable: \`const intent: Intent = ...;\` (import Intent from @idealyst/theme). This applies to ALL components with intent/type props.
 6. **Avatar** uses \`src\` for image URL, \`fallback\` for initials \u2014 NOT \`name\`, \`initials\`, \`label\`. Shape: \`'circle' | 'square'\`.
 7. **Link** requires a \`to\` prop (path string) \u2014 it's a navigation link, NOT pressable text.
 8. **List** takes \`children\` \u2014 NOT \`data\`, \`renderItem\`, or \`keyExtractor\`. Map your data: \`<List>{items.map(item => <View key={item.id}>...</View>)}</List>\`
 9. **Skeleton** uses \`shape\` prop (\`'rectangle' | 'circle' | 'rounded'\`) \u2014 NOT \`variant\`. Props: \`width\`, \`height\`, \`shape\`, \`animation\` (\`'pulse' | 'wave' | 'none'\`). Do NOT build custom skeletons with react-native \`Animated\`.
 10. The component is **TextInput**, NOT \`Input\`.
-11. **Card** is a simple container \u2014 there are NO compound components like \`Card.Content\`, \`Card.Header\`, \`Card.Body\`, \`Card.Footer\`, \`Card.Title\`. Just put children directly inside \`<Card>...</Card>\`.
+11. **Card** is a simple container \u2014 there are NO compound components like \`Card.Content\`, \`Card.Header\`, \`Card.Body\`, \`Card.Footer\`, \`Card.Title\`. Just put children directly inside \`<Card>...</Card>\`. **Card does NOT have \`border\`, \`scrollable\`, or \`backgroundColor\` props** (those are View-only). Card styling props: \`type\` (\`'default'|'outlined'|'elevated'|'filled'\`), \`radius\`, \`intent\`, \`background\`, plus spacing (\`padding\`, \`margin\`, \`gap\`). For borders use \`type="outlined"\`.
+12. **Switch** uses \`checked\` and \`onChange\` \u2014 NOT \`value\` and \`onValueChange\` (React Native convention). Also has \`label\`, \`labelPosition\`, \`disabled\`.
 
 ### Navigation
-11. Use \`NavigatorProvider\` \u2014 there is NO \`Router\` export.
+11. **NavigatorProvider** takes a \`route\` prop (SINGULAR) \u2014 NOT \`routes\`: \`<NavigatorProvider route={routeConfig} />\`. There is NO \`Router\` export.
 12. Use \`useNavigator()\` \u2014 NOT \`useNavigate()\`.
-13. \`navigate()\` takes an **object**: \`navigate({ path: '/settings' })\` \u2014 NOT \`navigate('/settings')\` or \`navigate('routeName', params)\`.
+13. \`navigate()\` takes an **object**: \`navigate({ path: '/settings' })\` \u2014 NOT \`navigate('/settings')\` or \`navigate('routeName', params)\`. To pass data use \`vars\`: \`navigate({ path: '/detail/:id', vars: { id: '123' } })\` \u2014 NOT \`params\`: \`navigate({ path: '/detail', params: { id: '123' } })\` (no \`params\` property exists).
 14. \`useNavigationState\` returns \`Record<string, unknown>\` by default. Always provide a type parameter: \`useNavigationState<{ title?: string }>()\`.
 15. \`useParams()\` does NOT accept generic type arguments. It returns \`Record<string, string>\`. Do NOT write \`useParams<{ id: string }>()\` \u2014 that causes TS2558.
 
 ### Imports & Styling
-16. **Never** import from \`react-native\` \u2014 no \`TouchableOpacity\`, \`FlatList\`, \`ScrollView\`, \`Animated\`, \`Dimensions\`, \`Linking\`, \`Platform\`. Idealyst provides cross-platform alternatives for all of these (e.g., \`openExternalLinks\` on Markdown, \`Pressable\` from \`@idealyst/components\`).
+16. **Never** import from \`react-native\` \u2014 no \`TouchableOpacity\`, \`FlatList\`, \`ScrollView\`, \`Animated\`, \`Dimensions\`, \`Linking\`, \`Platform\`. Idealyst provides cross-platform alternatives for all of these (e.g., \`openExternalLinks\` on Markdown, \`Pressable\` from \`@idealyst/components\`). **\`ScrollView\` is NOT exported from \`@idealyst/components\`** \u2014 use \`<View scrollable>\` instead. Do NOT \`import { ScrollView } from '@idealyst/components'\` \u2014 it will cause a TS import error.
 17. **Never** import from \`react-native-unistyles\` \u2014 use \`@idealyst/theme\` (\`configureThemes\`, \`ThemeSettings\`, \`useTheme\`).
 18. **useTheme()** returns the Theme object **directly** (NOT wrapped): \`const theme = useTheme();\`. Do NOT destructure: \`const { theme } = useTheme()\` \u2014 causes TS2339.
 19. **Spacing & Layout**: Use component shorthand props for spacing \u2014 NOT \`theme.spacing\` (which does NOT exist). The correct patterns:
@@ -20369,14 +20894,32 @@ These are mistakes agents make repeatedly. Each one causes TypeScript compilatio
    - \`theme.radii.md\` \u2014 border radius values (this DOES exist)
    - **WRONG**: \`<View paddingTop="md">\` \u2014 does NOT exist as a shorthand prop; use \`style={{ paddingTop: 16 }}\`
    - **WRONG**: \`theme.spacing.md\` \u2014 does NOT exist, causes TS2339
+   - **WRONG**: \`theme.colors.background\` \u2014 does NOT exist. \`theme.colors\` has: \`pallet\`, \`surface\`, \`text\`, \`border\`. Use \`theme.colors.surface.primary\` for background colors.
    - **WRONG**: \`theme.colors.intent.danger\` \u2014 does NOT exist; intents are at \`theme.intents.danger\`
+   - **WRONG**: \`theme.intents.primary.bg\` \u2014 IntentValue does NOT have \`bg\` or \`text\`. IntentValue has: \`primary\` (main color string), \`contrast\` (text-on-bg color), \`light\`, \`dark\`
+   - **CORRECT**: \`theme.intents.primary.primary\` for the color, \`theme.intents.primary.contrast\` for text on that color
+   - **Color key reference** (all keys available):
+     - \`theme.colors.surface\`: \`screen\`, \`primary\`, \`secondary\`, \`tertiary\`, \`inverse\`, \`inverse-secondary\`, \`inverse-tertiary\`
+     - \`theme.colors.text\`: \`primary\`, \`secondary\`, \`tertiary\`, \`inverse\`, \`inverse-secondary\`, \`inverse-tertiary\`
+     - \`theme.colors.border\`: \`primary\`, \`secondary\`, \`tertiary\`, \`disabled\`
+     - \`theme.intents\`: \`primary\`, \`secondary\`, \`success\`, \`warning\`, \`danger\`, \`info\`, \`neutral\` (each has \`.primary\`, \`.contrast\`, \`.light\`, \`.dark\`)
 
 ### Cross-Platform (CRITICAL)
 20. **Never use raw HTML/SVG elements** (\`<svg>\`, \`<circle>\`, \`<canvas>\`, \`<div>\`, \`<span>\`, \`<input>\`) \u2014 they are web-only and will crash on React Native, just like react-native primitives crash on web. Also never use CSS \`transition\` or \`animation\` properties in styles \u2014 they don't exist on native. If you need custom drawing or circular progress, use \`@idealyst/animate\` hooks or \`@idealyst/charts\` \u2014 never raw SVG.
-21. **Avoid web-only CSS** like \`cursor: 'pointer'\` in shared styles \u2014 not valid on native. Use \`Pressable\` or \`Button\` for interactive elements (they handle cursor automatically on web).
+21. **Avoid web-only CSS** like \`cursor: 'pointer'\` in shared styles \u2014 not valid on native. Use \`Pressable\` or \`Button\` for interactive elements (they handle cursor automatically on web). Percentage widths (\`width: '50%'\`) do NOT work reliably on React Native \u2014 use \`flex\` instead.
+23. **Use theme colors, never hardcoded hex** \u2014 import \`useTheme\` from \`@idealyst/theme\` and use \`theme.colors.surface.secondary\` (not \`'#f5f5f5'\`), \`theme.colors.border.primary\` (not \`'#e0e0e0'\`), \`theme.intents.primary.primary\` (not \`'#1976d2'\`). Hardcoded colors break dark mode and branding customization. **Exception:** Semi-transparent overlays for camera/media UIs may use \`rgba(0,0,0,0.5)\` since the theme has no overlay color. For other overlays, prefer \`theme.colors.surface.inverse\` with opacity.
+22. **Platform file barrel exports**: When creating \`Component.web.tsx\` + \`Component.native.tsx\`, you need THREE index files:
+   - \`index.web.ts\` \u2014 \`export { default as Component } from './Component.web';\`
+   - \`index.native.ts\` \u2014 \`export { default as Component } from './Component.native';\`
+   - \`index.ts\` \u2014 \`export { default as Component } from './Component.web';\` (base file for TypeScript resolution)
+   - **WRONG**: \`export { default } from './Component';\` \u2014 no bare \`Component.ts\` exists, only \`.web.tsx\`/\`.native.tsx\`. This causes TS2307.
+   - **Web-only styles in .web.tsx files**: Cast CSS-only properties with \`as any\`, NOT \`as React.CSSProperties\`. Example: \`style={{ position: 'fixed', transition: 'width 0.2s' } as any}\`. \`React.CSSProperties\` is incompatible with \`StyleProp<ViewStyle>\` \u2014 this causes TS2322.
 
 ### React 19 TypeScript
 - **useRef** requires an initial argument: \`useRef<T>(null)\` \u2014 NOT \`useRef<T>()\`. Omitting the argument causes TS2554. For non-null refs use: \`useRef<number>(0)\`, \`useRef<string[]>([])\`.
+- **onLayout** callback: The event shape is \`e.nativeEvent.layout.{x, y, width, height}\` \u2014 NOT \`e.layout.width\`. Always destructure: \`onLayout={(e) => { const { width, height } = e.nativeEvent.layout; }}\`. Writing \`e.layout\` causes TS2339.
+- **Badge children** accepts \`ReactNode\` including numbers \u2014 \`<Badge>{count}</Badge>\` is valid. But if you pass a number to a **string** prop, wrap it: \`<Badge>{String(count)}</Badge>\` or use template literal.
+- **String literals with apostrophes**: Use backticks or double quotes for strings containing apostrophes \u2014 \`\`I'll be back\`\` or \`"I'll be back"\` \u2014 NOT \`'I'll be back'\` (unescaped \`'\` breaks the string and causes cascading TS errors).
 
 ### Scaffolded Project Layout
 When working in a CLI-scaffolded workspace (created with \`idealyst init\` + \`idealyst create\`), files go in specific locations:
@@ -20393,11 +20936,11 @@ When working in a CLI-scaffolded workspace (created with \`idealyst init\` + \`i
 > **TIP:** Before writing backend code, call \`search_recipes({ query: "trpc" })\` to get the \`trpc-feature\` recipe \u2014 it has the complete step-by-step pattern with correct file paths.
 
 ### Package-Specific (call guide tools for full API)
-18. **Audio** (\`@idealyst/audio\`) is **PCM streaming**, NOT file-based. \`recorder.stop()\` returns \`void\`. Data is \`ArrayBufferLike\`, NOT strings. Call \`get_audio_guide\` topic \`api\`.
+18. **Audio** (\`@idealyst/audio\`) is **PCM streaming**, NOT file-based. \`recorder.stop()\` returns \`void\`. Data is \`ArrayBufferLike\`, NOT strings. Do NOT use \`atob()\` for base64 decoding \u2014 it's browser-only. See the guide for cross-platform patterns. Call \`get_audio_guide\` topic \`api\`.
 19. **Camera** (\`@idealyst/camera\`): Component is \`CameraPreview\`, NOT \`Camera\`. Permission is \`requestPermission()\`, NOT \`requestCameraPermission\`. \`CameraStatus\` is an interface (\`.state\`, \`.permission\`), NOT a string. Call \`get_camera_guide\` topic \`api\`.
-20. **Files** (\`@idealyst/files\`): Method is \`pick()\`, NOT \`pickFiles()\`. \`FileType\` is \`'image' | 'video' | 'audio' | 'document' | 'archive' | 'any'\` \u2014 NOT \`'pdf'\` or \`'doc'\`. Call \`get_files_guide\` topic \`api\`.
+20. **Files** (\`@idealyst/files\`): \`pick()\` returns \`FilePickerResult\` (an **object**, NOT an array). Access files via \`result.files\`: \`result.files.length\`, \`result.files[0].uri\`. Do NOT write \`result.length\` or \`result[0]\`. \`useFilePicker()\` takes \`{ config: { allowedTypes: ['image'], multiple: true } }\` \u2014 NOT \`{ type: 'image' }\`. \`FileType\` is \`'image' | 'video' | 'audio' | 'document' | 'archive' | 'any'\` \u2014 NOT \`'pdf'\` or \`'doc'\`. Call \`get_files_guide\` topic \`api\`.
 21. **Storage** (\`@idealyst/storage\`): Methods are \`getItem()\`/\`setItem()\`, NOT \`get()\`/\`set()\`. Values are string-only. Call \`get_storage_guide\` topic \`api\`.
-22. **Animate** (\`@idealyst/animate\`): There is NO \`useSequence\` or \`useKeyframes\` \u2014 only \`useAnimatedStyle\`, \`useAnimatedValue\`, \`usePresence\`, \`useGradientBorder\`. Easing values are **camelCase**: \`'easeOut'\` NOT \`'ease-out'\`. \`useAnimatedValue\` REQUIRES an initial number: \`useAnimatedValue(0)\` \u2014 NOT \`useAnimatedValue()\`. Call \`get_animate_guide\` topic \`api\`.
+22. **Animate** (\`@idealyst/animate\`): There is NO \`useSequence\` or \`useKeyframes\` \u2014 only \`useAnimatedStyle\`, \`useAnimatedValue\`, \`usePresence\`, \`useGradientBorder\`. Easing values are **camelCase**: \`'easeOut'\` NOT \`'ease-out'\`. \`useAnimatedValue\` REQUIRES an initial number: \`useAnimatedValue(0)\` \u2014 NOT \`useAnimatedValue()\`. \`useAnimatedStyle\` supports a \`delay\` option (ms) for staggered entrances. Transform syntax: use **object** format \`{ x, y, scale, rotate }\` \u2014 NOT array format \`[{ translateX }]\` which doesn't animate. Call \`get_animate_guide\` topic \`api\`.
 23. **Charts** (\`@idealyst/charts\`): \`ChartDataSeries\` requires \`id\` and \`name\` (NOT \`label\`). \`AxisConfig\` uses \`show\` (NOT \`visible\`). \`tickFormat\` type is \`(value: number | string | Date) => string\`. Call \`get_charts_guide\` topic \`api\`.
 `;
 
@@ -27863,7 +28406,7 @@ var import_url = require("url");
 // src/generated/types.json
 var types_default = {
   version: "1.0.93",
-  extractedAt: "2026-02-24T16:32:56.796Z",
+  extractedAt: "2026-02-24T21:11:17.058Z",
   components: {
     Accordion: {
       name: "Accordion",
@@ -50164,7 +50707,7 @@ var types_default = {
   navigation: {
     TabBarScreenOptions: 'export type TabBarScreenOptions = {\n    /**\n     * Icon for tab/drawer navigation.\n     *\n     * Can be:\n     * - A **string** (icon name) \u2014 e.g. `"home"`, `"cog"`. The default layout renders\n     *   `<Icon name={tabBarIcon} size="sm" />` automatically.\n     * - A **render function** \u2014 receives `{ focused, color, size }`. The `size` param is\n     *   a number (from native tab bars); **ignore it** and use a Size token instead:\n     *   `tabBarIcon: ({ focused }) => <Icon name={focused ? \'home\' : \'home-outline\'} size="sm" />`\n     */\n    tabBarIcon?: string | ((props: { focused: boolean; color: string; size: string | number }) => React.ReactElement)\n\n    /**\n     * Label for tab/drawer navigation\n     */\n    tabBarLabel?: string;\n    \n    /**\n     * Badge for tab navigation\n     */\n    tabBarBadge?: string | number;\n    \n    /**\n     * Whether to show the tab bar for this screen\n     */\n    tabBarVisible?: boolean;\n} & ScreenOptions',
     NavigatorOptions: "export type NavigatorOptions = {\n\n    \n    /**\n     * Custom header title component or string\n     */\n    headerTitle?: React.ComponentType | React.ReactElement | string;\n    \n    /**\n     * Custom header left component (overrides back button)\n     */\n    headerLeft?: React.ComponentType | React.ReactElement;\n    \n    /**\n     * Whether to show header back button\n     */\n    headerBackVisible?: boolean;\n    \n    /**\n     * Custom header right component\n     */\n    headerRight?: React.ComponentType | React.ReactElement;\n    \n    /**\n     * Whether to hide the native React Navigation header (mobile only)\n     */\n    headerShown?: boolean;\n}",
-    ScreenOptions: "export type ScreenOptions = {\n    /**\n     * Screen title for navigation headers\n     */\n    title?: string;\n    headerShown?: boolean;\n    /**\n     * When true, renders the screen outside of parent layout wrappers.\n     * Useful for fullscreen modals, onboarding flows, or any screen that\n     * should not inherit the parent navigator's layout (header, sidebar, tabs, etc.)\n     *\n     * Web: Screen renders as a sibling route without the parent LayoutComponent\n     * Native: Screen uses fullScreenModal presentation\n     */\n    fullScreen?: boolean;\n\n} & NavigatorOptions;",
+    ScreenOptions: "export type ScreenOptions = {\n    /**\n     * Screen title for navigation headers\n     */\n    title?: string;\n    headerShown?: boolean;\n    /**\n     * Icon name for this screen (used by custom layout components like sidebars, drawers, etc.)\n     */\n    icon?: string;\n    /**\n     * When true, renders the screen outside of parent layout wrappers.\n     * Useful for fullscreen modals, onboarding flows, or any screen that\n     * should not inherit the parent navigator's layout (header, sidebar, tabs, etc.)\n     *\n     * Web: Screen renders as a sibling route without the parent LayoutComponent\n     * Native: Screen uses fullScreenModal presentation\n     */\n    fullScreen?: boolean;\n\n} & NavigatorOptions;",
     NotFoundComponentProps: "export type NotFoundComponentProps = {\n    /** The full path that was attempted */\n    path: string\n    /** Any route parameters that were parsed from the path */\n    params?: Record<string, string>\n}",
     BaseNavigatorParam: "export type BaseNavigatorParam = {\n    path: string\n    type: 'navigator'\n    /**\n     * Navigator options. When this navigator is nested inside a tab or drawer,\n     * you can include TabBarScreenOptions (tabBarIcon, tabBarLabel, tabBarBadge)\n     * so the parent layout can render the tab/drawer entry for this navigator.\n     */\n    options?: TabBarScreenOptions\n    /**\n     * Handler called when an invalid route is accessed.\n     * - Return NavigateParams to redirect to a different route\n     * - Return undefined to show the notFoundComponent (if set)\n     * If not defined, bubbles up to parent navigator.\n     *\n     * @param invalidPath - The path that was attempted but not found\n     * @returns NavigateParams to redirect, or undefined to use notFoundComponent\n     */\n    onInvalidRoute?: (invalidPath: string) => NavigateParams | undefined\n    /**\n     * Component to render/navigate to when route is invalid and onInvalidRoute returns undefined.\n     * - Web: Renders at the current URL via catch-all route\n     * - Native: Navigated to as a screen\n     * - Optional: If not set and nothing handles the route, a warning is logged\n     */\n    notFoundComponent?: React.ComponentType<NotFoundComponentProps>\n}",
     TabNavigatorParam: "export type TabNavigatorParam = {\n    layout: 'tab'\n    routes: RouteParam<TabBarScreenOptions>[]\n    layoutComponent?: TabLayoutComponent\n} & BaseNavigatorParam",
@@ -69799,12 +70342,32 @@ function postProcessComponentTypes(componentName, result) {
   }
   if (componentName.toLowerCase() === "card") {
     if (typeof result === "object" && result !== null) {
-      result.usageNote = 'Card is a SIMPLE CONTAINER \u2014 there are NO compound components. Do NOT use Card.Content, Card.Header, Card.Body, Card.Footer, Card.Title \u2014 they do NOT exist and will cause TS2339. Just put children directly inside <Card>...</Card>. Example: <Card padding="md"><Text>Title</Text><Text>Body</Text></Card>';
+      result.usageNote = "Card is a SIMPLE CONTAINER \u2014 there are NO compound components. Do NOT use Card.Content, Card.Header, Card.Body, Card.Footer, Card.Title \u2014 they do NOT exist and will cause TS2339. Just put children directly inside <Card>...</Card>. Example: <Card padding=\"md\"><Text>Title</Text><Text>Body</Text></Card>. **Card does NOT have `border`, `scrollable`, or `backgroundColor` props** \u2014 those are View-only props. Using `border` on Card causes TS2322. For borders use `type='outlined'`. For elevated cards use `type='elevated'`. Card styling props: padding, paddingVertical, paddingHorizontal, margin, marginVertical, marginHorizontal, gap/spacing, radius, type ('default'|'outlined'|'elevated'|'filled'), intent, background, style, onPress, disabled. For custom shadows use style={{ ...theme.shadows.md }}.";
     }
   }
   if (componentName.toLowerCase() === "view") {
     if (typeof result === "object" && result !== null) {
-      result.usageNote = "View spacing shorthand props: padding, paddingVertical, paddingHorizontal, margin, marginVertical, marginHorizontal, gap/spacing. These accept Size values (xs, sm, md, lg, xl). Do NOT use paddingTop, paddingBottom, paddingLeft, paddingRight, marginTop, marginBottom, marginLeft, marginRight as shorthand props \u2014 they do NOT exist and will cause TS2353. For single-side spacing use style={{ paddingTop: 16 }}.";
+      result.usageNote = "View spacing shorthand props: padding, paddingVertical, paddingHorizontal, margin, marginVertical, marginHorizontal, gap/spacing. These accept Size values (xs, sm, md, lg, xl). Do NOT use paddingTop, paddingBottom, paddingLeft, paddingRight, marginTop, marginBottom, marginLeft, marginRight as shorthand props \u2014 they do NOT exist and will cause TS2353. For single-side spacing use style={{ paddingTop: 16 }}. View does NOT have a `pointerEvents` JSX prop. Use style={{ pointerEvents: 'none' }} instead.";
+    }
+  }
+  if (componentName.toLowerCase() === "textarea") {
+    if (typeof result === "object" && result !== null) {
+      result.usageNote = "TextArea has a DIFFERENT API from TextInput. TextArea uses onChange (not onChangeText) and does NOT have onBlur. TextArea DOES support label, error, and rows props (TextInput does NOT support label/error). Always call get_component_types('TextArea') separately \u2014 do NOT assume it shares TextInput's props.";
+    }
+  }
+  if (componentName.toLowerCase() === "image") {
+    if (typeof result === "object" && result !== null) {
+      result.usageNote = "Image uses `objectFit` (CSS convention) \u2014 NOT `resizeMode` (React Native convention). Valid objectFit values: 'contain', 'cover', 'fill', 'none', 'scale-down'. Image uses `source` prop (accepts URL string or ImageSourcePropType) \u2014 NOT `src`. Example: <Image source=\"https://example.com/photo.jpg\" objectFit=\"cover\" width={200} height={200} />";
+    }
+  }
+  if (componentName.toLowerCase() === "icon") {
+    if (typeof result === "object" && result !== null) {
+      result.usageNote = "Icon color props: Use `intent` for semantic coloring (primary, danger, success, etc.) \u2014 renders the icon in the intent's primary color. Use `textColor` for text-semantic coloring (primary, secondary, tertiary, inverse) \u2014 renders the icon using theme.colors.text[textColor]. Use `color` for arbitrary hex/rgb colors. If the icon represents an action or status, use `intent`. If it should match surrounding text color, use `textColor`.";
+    }
+  }
+  if (componentName.toLowerCase() === "badge") {
+    if (typeof result === "object" && result !== null) {
+      result.usageNote = "Badge `intent` expects Intent: 'primary' | 'success' | 'danger' | 'warning' | 'neutral' | 'info'. Simple ternaries in JSX work fine: `<Badge intent={x > 5 ? 'success' : 'danger'}>` \u2014 TS infers the union. **Do NOT use `as const` on ternary expressions** \u2014 `(cond ? 'a' : 'b') as const` causes TS1355. For arrays of objects, use `as const` on each property value: `{ intent: 'success' as const }`, or use `as const` on the entire array literal. For complex logic, declare a typed variable: `const intent: Intent = cond ? 'success' : 'danger';` (import Intent from @idealyst/theme). This applies to all intent/type props on Badge, Button, Card, Icon, etc.";
     }
   }
   return result;
@@ -70062,8 +70625,8 @@ function getThemeTypes2(args = {}) {
     const result = getThemeTypes(format);
     if (typeof result === "object" && result !== null) {
       const r = result;
-      r.useThemeNote = 'IMPORTANT: useTheme() returns Theme directly \u2014 NOT wrapped in an object. Correct: `const theme = useTheme();` WRONG: `const { theme } = useTheme();` (causes TS2339). Theme top-level keys: intents, radii, shadows, colors, sizes, interaction, breakpoints. For spacing, use component props (padding="md", gap="md") \u2014 NOT theme.spacing (does NOT exist). For colors: `style={{ backgroundColor: theme.colors.surface.primary }}`. For radii: `style={{ borderRadius: theme.radii.md }}`. For intents: `theme.intents.primary` (NOT theme.colors.intent).';
-      r.themeAccessPatterns = "## Theme Access Patterns\n\n```typescript\nimport { useTheme } from '@idealyst/theme';\nconst theme = useTheme();\n\n// Colors (surface, text, border sub-groups)\ntheme.colors.surface.primary    // main background\ntheme.colors.surface.secondary  // card/section background\ntheme.colors.text.primary       // main text color\ntheme.colors.text.secondary     // muted text\ntheme.colors.text.tertiary      // subtle text\ntheme.colors.text.inverse       // text on dark backgrounds\ntheme.colors.border.primary     // standard border\ntheme.colors.border.secondary   // subtle border\n\n// Intents (semantic colors with bg, text, border)\ntheme.intents.primary.bg        // primary background\ntheme.intents.primary.text      // primary text color\ntheme.intents.danger.bg         // danger/error background\n// Available: primary, secondary, success, warning, danger, info, neutral\n\n// Radii\ntheme.radii.none  // 0\ntheme.radii.sm    // small radius\ntheme.radii.md    // medium radius\ntheme.radii.lg    // large radius\ntheme.radii.xl    // extra large\ntheme.radii.full  // fully rounded\n\n// Shadows\ntheme.shadows.sm   // subtle shadow\ntheme.shadows.md   // medium shadow\ntheme.shadows.lg   // prominent shadow\n\n// Breakpoints (responsive)\ntheme.breakpoints.xs  // 0\ntheme.breakpoints.sm  // small screens\ntheme.breakpoints.md  // medium screens\ntheme.breakpoints.lg  // large screens\n```";
+      r.useThemeNote = "IMPORTANT: useTheme() returns Theme directly \u2014 NOT wrapped in an object. Correct: `const theme = useTheme();` WRONG: `const { theme } = useTheme();` (causes TS2339). Theme top-level keys: intents, radii, shadows, colors, sizes, interaction, breakpoints. For spacing, use component props (padding=\"md\", gap=\"md\") \u2014 NOT theme.spacing (does NOT exist). For colors: `style={{ backgroundColor: theme.colors.surface.primary }}`. For radii: `style={{ borderRadius: theme.radii.md }}`. For intents: `theme.intents.primary.primary` (main color), `.contrast`, `.light`, `.dark`. WRONG: `theme.intents.primary.bg` \u2014 'bg' does NOT exist. WRONG: `theme.intents.primary.text` \u2014 'text' does NOT exist. WRONG: `theme.colors.intent.danger` \u2014 intents are at theme.intents, NOT theme.colors.intent.";
+      r.themeAccessPatterns = "## Theme Access Patterns\n\n```typescript\nimport { useTheme } from '@idealyst/theme';\nconst theme = useTheme();\n\n// Colors (surface, text, border sub-groups)\ntheme.colors.surface.primary    // main background\ntheme.colors.surface.secondary  // card/section background\ntheme.colors.text.primary       // main text color\ntheme.colors.text.secondary     // muted text\ntheme.colors.text.tertiary      // subtle text\ntheme.colors.text.inverse       // text on dark backgrounds\ntheme.colors.border.primary     // standard border\ntheme.colors.border.secondary   // subtle border\n\n// Intents \u2014 IntentValue has: primary, contrast, light, dark\ntheme.intents.primary.primary   // primary intent main color (string)\ntheme.intents.primary.contrast  // contrast color for text on primary bg\ntheme.intents.primary.light     // lighter variant\ntheme.intents.primary.dark      // darker variant\ntheme.intents.danger.primary    // danger intent main color\n// Available intents: primary, secondary, success, warning, danger, info, neutral\n// WRONG: theme.intents.primary.bg \u2014 'bg' does NOT exist on IntentValue\n// WRONG: theme.intents.primary.text \u2014 'text' does NOT exist on IntentValue\n\n// Radii\ntheme.radii.none  // 0\ntheme.radii.sm    // small radius\ntheme.radii.md    // medium radius\ntheme.radii.lg    // large radius\ntheme.radii.xl    // extra large\ntheme.radii.full  // fully rounded\n\n// Shadows\ntheme.shadows.sm   // subtle shadow\ntheme.shadows.md   // medium shadow\ntheme.shadows.lg   // prominent shadow\n\n// Breakpoints (responsive)\ntheme.breakpoints.xs  // 0\ntheme.breakpoints.sm  // small screens\ntheme.breakpoints.md  // medium screens\ntheme.breakpoints.lg  // large screens\n```";
       r.themeSetup = "## Theme Setup (app initialization)\n\n```typescript\nimport { configureThemes, lightTheme, darkTheme, fromTheme } from '@idealyst/theme';\n\n// Build themes from defaults\nconst light = fromTheme(lightTheme).build();\nconst dark = fromTheme(darkTheme).build();\n\n// Configure at app startup (call once, before any component renders)\nconfigureThemes({ themes: { light, dark } });\n```\n\n## Theme Switching at Runtime\n\n```typescript\nimport { ThemeSettings, getColorScheme } from '@idealyst/theme';\n\n// Switch theme\nThemeSettings.setTheme('dark', 'dark');       // (themeName, contentColor)\nThemeSettings.setTheme('light', 'light', true); // animated transition\n\n// Get current theme name\nconst current = ThemeSettings.getThemeName(); // 'light' or 'dark'\n\n// Follow system light/dark preference\nThemeSettings.setAdaptiveThemes(true);\n\n// Get device color scheme\nconst scheme = getColorScheme(); // 'light' | 'dark' | null\n```\n\nIMPORTANT: Do NOT import from 'react-native-unistyles' directly. Use configureThemes (NOT StyleSheet.configure or UnistylesRegistry). Use ThemeSettings (NOT UnistylesRuntime).";
     }
     return jsonResponse(result);
@@ -70079,6 +70642,8 @@ function getNavigationTypes2(args = {}) {
     const result = getNavigationTypes(format);
     if (typeof result === "object" && result !== null) {
       result.tabBarIconNote = `IMPORTANT: tabBarIcon can be a string (icon name) or a render function. String form (simplest): tabBarIcon: 'home' \u2014 the layout renders <Icon name="home" size="sm" /> automatically. Function form: tabBarIcon: ({ focused }) => <Icon name={focused ? 'home' : 'home-outline'} size="sm" /> WARNING: The function receives { size: number } from native tab bars, but Icon expects a Size token ('xs'|'sm'|'md'|'lg'|'xl'). Do NOT pass the size param to Icon. Use a fixed size token like 'sm' or 'md' instead.`;
+      result.layoutNote = "IMPORTANT: For custom layouts (sidebar, drawer), import Outlet from @idealyst/navigation \u2014 NOT from react-router-dom. Outlet renders the active route's content inside your layout. Example: import { Outlet, useNavigator } from '@idealyst/navigation'; ScreenOptions has: title, headerShown, icon (string), fullScreen. StackLayoutProps has: options, routes (RouteWithFullPath<ScreenOptions>[]), currentPath. Access route metadata: route.options?.icon, route.options?.title, route.fullPath.";
+      result.usageExample = "## NavigatorProvider Usage\n\n```tsx\nimport { NavigatorProvider } from '@idealyst/navigation';\nimport type { NavigatorParam } from '@idealyst/navigation';\n\nconst routeConfig: NavigatorParam = {\n  path: '/',\n  type: 'navigator',\n  layout: 'tab',\n  routes: [\n    { path: '/home', type: 'screen', component: HomeScreen, options: { title: 'Home', tabBarIcon: 'home' } },\n    { path: '/settings', type: 'screen', component: SettingsScreen, options: { title: 'Settings', tabBarIcon: 'cog' } },\n  ],\n};\n\n// CRITICAL: The prop is \"route\" (SINGULAR), NOT \"routes\"\nexport const App = () => <NavigatorProvider route={routeConfig} />;\n```";
     }
     return jsonResponse(result);
   } catch (error) {
@@ -70288,6 +70853,17 @@ function getLiveActivityGuide(args) {
   }
   return textResponse(guide);
 }
+function getNetworkGuide(args) {
+  const topic = args.topic;
+  const uri = `idealyst://network/${topic}`;
+  const guide = networkGuides[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) {
@@ -70538,6 +71114,7 @@ var toolHandlers = {
   get_payments_guide: getPaymentsGuide,
   get_notifications_guide: getNotificationsGuide,
   get_live_activity_guide: getLiveActivityGuide,
+  get_network_guide: getNetworkGuide,
   list_packages: listPackages,
   get_package_docs: getPackageDocs,
   search_packages: searchPackages2,