react-native-audio-browser 0.0.1 → 0.1.0-next.1

package/lib/typescript/src/types/browser.d.ts

@@ -0,0 +1,742 @@
+import type { NavigationError } from '../features/errors';
+import type { ResolvedTrack, Track } from './browser-nodes.ts';
+/**
+ * Event fired when a track is about to be loaded via navigateTrack.
+ */
+export interface TrackLoadEvent {
+    /** The track that will be loaded */
+    track: Track;
+    /** The resolved queue of tracks */
+    queue: Track[];
+    /** The index of the track in the queue */
+    startIndex: number;
+}
+/**
+ * Callback for handling track load events.
+ * When set on BrowserConfiguration, navigateTrack() will call this handler
+ * instead of auto-loading/playing the track. The native side awaits completion
+ * before proceeding (e.g., showing Now Playing in CarPlay).
+ */
+export type HandleTrackLoadCallback = (event: TrackLoadEvent) => Promise<void>;
+export type BrowserSourceCallbackParam = {
+    path: string;
+    routeParams?: Record<string, string>;
+};
+/**
+ * Return BrowseError from a browse callback to display an error to the user.
+ * The error message will be shown in an error dialog in CarPlay and Android Auto.
+ *
+ * On the app side, the error is surfaced as a `NavigationError` with
+ * `code: 'callback-error'`. Use `useNavigationError()` to get the error details,
+ * or `useFormattedNavigationError()` for a display-friendly version.
+ *
+ * @example
+ * ```ts
+ * browse: async ({ path }) => {
+ *   if (!user.subscribed) {
+ *     return { error: 'Please subscribe to access this content' }
+ *   }
+ *   return fetchContent(path)
+ * }
+ * ```
+ */
+export type BrowseError = {
+    error: string;
+};
+/**
+ * Result type for browse callbacks.
+ * Can be either a ResolvedTrack (success) or BrowseError (failure).
+ */
+export type BrowseResult = ResolvedTrack | BrowseError;
+export type BrowserSourceCallback = (param: BrowserSourceCallbackParam) => Promise<BrowseResult>;
+/**
+ * Search mode types for structured voice search.
+ *
+ * - `any`: Play any content - smart shuffle or last playlist (query will be empty string)
+ * - `genre`: Search by genre
+ * - `artist`: Search by artist
+ * - `album`: Search by album
+ * - `song`: Search by song/track title
+ * - `playlist`: Search by playlist name
+ *
+ * @see BrowserConfiguration.search
+ * @see SearchParams
+ */
+export type SearchMode = 'any' | 'genre' | 'artist' | 'album' | 'song' | 'playlist';
+/**
+ * Structured search parameters from voice commands.
+ *
+ * Voice commands are parsed by Android into structured parameters:
+ * - "play something" → mode=null, query="something"
+ * - "play music" → mode='any', query=""
+ * - "play jazz" → mode='genre', genre="jazz", query="jazz"
+ * - "play michael jackson" → mode='artist', artist="michael jackson", query="michael jackson"
+ * - "play thriller by michael jackson" → mode='album', album="thriller", artist="michael jackson"
+ * - "play billie jean" → mode='song', title="billie jean", query="billie jean"
+ */
+export interface SearchParams {
+    /** The search mode indicating what type of search is being performed, or null for unstructured search */
+    mode?: SearchMode;
+    /**
+     * The original search query string (always present, but may be empty string "").
+     * When mode='any' with empty string query, return any content you think the user would like
+     * (e.g., recently played, favorites, or smart shuffle).
+     */
+    query: string;
+    /** Genre name for genre-specific search */
+    genre?: string;
+    /** Artist name for artist/album/song search */
+    artist?: string;
+    /** Album name for album-specific search */
+    album?: string;
+    /** Song title for song-specific search */
+    title?: string;
+    /** Playlist name for playlist-specific search */
+    playlist?: string;
+}
+export type SearchSourceCallback = (params: SearchParams) => Promise<Track[]>;
+export type RequestConfigTransformer = (request: RequestConfig, routeParams?: Record<string, string>) => Promise<RequestConfig>;
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
+export interface RequestConfig {
+    method?: HttpMethod;
+    /**
+     * The request path.
+     * - For browser requests, this is the track's `url`
+     * - For media requests, this is the track's `src` value
+     * - For artwork requests, this is the track's `artwork` URL
+     */
+    path?: string;
+    baseUrl?: string;
+    headers?: Record<string, string>;
+    query?: Record<string, string>;
+    body?: string;
+    contentType?: string;
+    userAgent?: string;
+}
+/**
+ * Context for image loading requests.
+ * Provides pixel dimensions and appearance info from Android Auto/CarPlay.
+ *
+ * @example
+ * ```typescript
+ * // Use transform for custom URL manipulation
+ * transform: async ({ request, context }) => ({
+ *   ...request,
+ *   query: {
+ *     ...request.query,
+ *     variant: context?.width && context.width < 200 ? 'thumb' : 'full'
+ *   }
+ * })
+ *
+ * // Or use imageQueryParams for simple declarative mapping
+ * artwork: {
+ *   imageQueryParams: { width: 'w', height: 'h' }
+ * }
+ * ```
+ */
+export interface ImageContext {
+    /**
+     * Requested image width in pixels.
+     * Only provided when the display size is known (e.g., CarPlay, Android Auto, Now Playing).
+     * Undefined at browse-time when display size is unknown.
+     */
+    width?: number;
+    /**
+     * Requested image height in pixels.
+     * Only provided when the display size is known (e.g., CarPlay, Android Auto, Now Playing).
+     * Undefined at browse-time when display size is unknown.
+     */
+    height?: number;
+}
+/**
+ * Parameters for the media request transform callback.
+ */
+export interface MediaTransformParams {
+    /** The merged request configuration to transform */
+    request: RequestConfig;
+    /** Optional image context with size hints from Android Auto/CarPlay */
+    context?: ImageContext;
+}
+/**
+ * Transform callback for media/artwork requests.
+ * Unlike the route-based RequestConfigTransformer, this receives ImageContext
+ * for size-aware transformations instead of route parameters.
+ *
+ * Use this when your CDN uses named variants or size presets. For simple
+ * pixel-based query params, use `imageQueryParams` instead.
+ *
+ * @param params - The transform parameters containing request and optional context
+ * @returns Modified request configuration
+ *
+ * @example
+ * ```typescript
+ * artwork: {
+ *   transform: async ({ request, context }) => ({
+ *     ...request,
+ *     query: {
+ *       ...request.query,
+ *       // Use semantic size for CDN variant selection
+ *       variant: context?.width && context.width < 200 ? 'thumb' : 'full',
+ *       sig: await signUrl(request.path)
+ *     }
+ *   })
+ * }
+ * ```
+ */
+export type MediaRequestConfigTransformer = (params: MediaTransformParams) => Promise<RequestConfig>;
+/**
+ * Request configuration that supports async transformation.
+ * Extends RequestConfig with a transform callback for dynamic request modification.
+ *
+ * The transform callback receives the merged request config and can modify it
+ * before the request is made. This is useful for adding dynamic headers,
+ * signing URLs, or other request-time modifications.
+ *
+ * @example
+ * ```typescript
+ * const config: TransformableRequestConfig = {
+ *   baseUrl: 'https://api.example.com',
+ *   transform: async (request) => ({
+ *     ...request,
+ *     headers: {
+ *       ...request.headers,
+ *       'Authorization': `Bearer ${await getAccessToken()}`
+ *     }
+ *   })
+ * }
+ * ```
+ */
+export interface TransformableRequestConfig extends RequestConfig {
+    transform?: RequestConfigTransformer;
+}
+/**
+ * Configuration for artwork image requests
+ *
+ * ## Configuration Hierarchy
+ *
+ * When a request is made, configs are merged in this order (later overrides earlier):
+ * 1. `request` (base config) - shared settings like user agent, common headers
+ * 2. `artwork` config - resource-specific settings
+ * 3. `resolve(track)` result - per-track overrides (if provided)
+ * 4. `imageQueryParams` - automatic size query param injection (if configured)
+ * 5. `transform(request, context)` result - final modifications (if provided)
+ *
+ * ## Usage Patterns
+ *
+ * **Simple CDN configuration:**
+ * ```typescript
+ * media: {
+ *   baseUrl: 'https://audio.cdn.example.com',
+ *   headers: { 'X-API-Key': 'your-api-key' }
+ * }
+ * ```
+ *
+ * **Per-track URL resolution:**
+ * ```typescript
+ * media: {
+ *   resolve: async (track) => ({
+ *     baseUrl: 'https://audio.cdn.example.com',
+ *     path: `/streams/${track.src}`,
+ *     query: { token: await getSignedToken(track.src) }
+ *   })
+ * }
+ * ```
+ *
+ * **Size-aware transformation (for artwork):**
+ * ```typescript
+ * artwork: {
+ *   baseUrl: 'https://images.cdn.example.com',
+ *   transform: async ({ request, context }) => ({
+ *     ...request,
+ *     query: {
+ *       ...request.query,
+ *       w: context?.width ? String(context.width) : '600',
+ *       sig: await signUrl(request.path)
+ *     }
+ *   })
+ * }
+ * ```
+ *
+ * **Simple size params (declarative alternative):**
+ * ```typescript
+ * artwork: {
+ *   baseUrl: 'https://images.cdn.example.com',
+ *   imageQueryParams: { width: 'w', height: 'h' }
+ * }
+ * ```
+ *
+ * @see BrowserConfiguration.media - Audio stream configuration
+ * @see BrowserConfiguration.artwork - Image/artwork configuration
+ */
+/**
+ * Query parameter names for automatic context injection from CarPlay/Android Auto.
+ * Maps ImageContext fields to query parameter names for your CDN.
+ */
+export interface ImageQueryParams {
+    /** Query parameter name for width (e.g., 'w', 'width', 'size') */
+    width?: string;
+    /** Query parameter name for height (e.g., 'h', 'height'). If omitted, only width is added. */
+    height?: string;
+}
+/**
+ * Configuration for media resource requests (audio streams, artwork images).
+ * Extends TransformableRequestConfig with per-track resolution capabilities.
+ *
+ * Used for both `media` (audio streaming) and `artwork` (image loading) configuration
+ * in BrowserConfiguration.
+ *
+ * ## Configuration Hierarchy
+ *
+ * When a request is made, configs are merged in this order (later overrides earlier):
+ * 1. `request` (base config) - shared settings like user agent, common headers
+ * 2. `media`/`artwork` config - resource-specific settings
+ * 3. `resolve(track)` result - per-track overrides (if provided)
+ * 4. `transform(request)` result - final modifications (if provided)
+ *
+ * ## Usage Patterns
+ *
+ * **Simple CDN configuration:**
+ * ```typescript
+ * media: {
+ *   baseUrl: 'https://audio.cdn.example.com',
+ *   headers: { 'X-API-Key': 'your-api-key' }
+ * }
+ * ```
+ *
+ * **Per-track URL resolution:**
+ * ```typescript
+ * media: {
+ *   resolve: async (track) => ({
+ *     baseUrl: 'https://audio.cdn.example.com',
+ *     path: `/streams/${track.src}`,
+ *     query: { token: await getSignedToken(track.src) }
+ *   })
+ * }
+ * ```
+ *
+ * **Dynamic request signing:**
+ * ```typescript
+ * artwork: {
+ *   baseUrl: 'https://images.cdn.example.com',
+ *   transform: async (request) => ({
+ *     ...request,
+ *     query: { ...request.query, sig: await signUrl(request.path) }
+ *   })
+ * }
+ * ```
+ *
+ * @see BrowserConfiguration.media - Audio stream configuration
+ * @see BrowserConfiguration.artwork - Image/artwork configuration
+ */
+export interface MediaRequestConfig extends TransformableRequestConfig {
+    /**
+     * Per-track request resolution callback.
+     *
+     * Called for each track to generate the final request configuration.
+     * Receives the full Track object, allowing URL generation based on
+     * track metadata (artist, album, src, etc.).
+     *
+     * The returned config is merged with base configs, then passed to
+     * `transform` if provided.
+     *
+     * @param track - The track being requested
+     * @returns Request configuration for this specific track
+     *
+     * @example
+     * ```typescript
+     * resolve: async (track) => ({
+     *   path: `/audio/${track.artist}/${track.album}/${track.src}`,
+     *   query: { quality: 'high' }
+     * })
+     * ```
+     */
+    resolve?: (track: Track) => Promise<RequestConfig>;
+}
+export interface ArtworkRequestConfig extends RequestConfig {
+    /**
+     * Per-track request resolution callback.
+     *
+     * Called for each track to generate the request configuration based on
+     * track metadata (artist, album, src, etc.).
+     *
+     * The returned config is merged with base configs, then passed to
+     * `transform` if provided.
+     *
+     * @param track - The track being requested
+     * @returns Request configuration for this specific track
+     *
+     * @example
+     * ```typescript
+     * artwork: {
+     *   resolve: async (track) => ({
+     *     path: `/covers/${track.artist}/${track.album}.jpg`,
+     *     query: { quality: 'high' }
+     *   })
+     * }
+     * ```
+     */
+    resolve?: (track: Track) => Promise<RequestConfig>;
+    /**
+     * Final transformation callback for media/artwork requests.
+     *
+     * Called after `resolve` (if provided) with the merged request config.
+     * Receives optional ImageContext with size hints from Android Auto/CarPlay.
+     *
+     * Use this for:
+     * - Adding size query params dynamically
+     * - URL signing
+     * - Adding authentication tokens
+     *
+     * @param request - The merged request configuration
+     * @param context - Optional image context with size hints
+     * @returns Modified request configuration
+     *
+     * @example
+     * ```typescript
+     * artwork: {
+     *   transform: async ({ request, context }) => ({
+     *     ...request,
+     *     query: {
+     *       ...request.query,
+     *       w: context?.width ? String(context.width) : '600',
+     *       sig: await signUrl(request.path)
+     *     }
+     *   })
+     * }
+     * ```
+     */
+    transform?: MediaRequestConfigTransformer;
+    /**
+     * Query parameter names for automatic context injection from CarPlay/Android Auto.
+     *
+     * When configured, the image context (size, color scheme) from CarPlay/Android Auto
+     * is automatically added as query parameters to artwork URLs.
+     *
+     * This is a simpler alternative to using `transform` for context-aware URLs.
+     *
+     * @example
+     * ```typescript
+     * // CDN expects ?w=400&h=400
+     * artwork: {
+     *   baseUrl: 'https://images.cdn.com',
+     *   imageQueryParams: { width: 'w', height: 'h' }
+     * }
+     *
+     * // CDN expects single size param ?size=400
+     * artwork: {
+     *   baseUrl: 'https://images.cdn.com',
+     *   imageQueryParams: { width: 'size' }
+     * }
+     * ```
+     */
+    imageQueryParams?: ImageQueryParams;
+}
+export type BrowserSource = ResolvedTrack | BrowserSourceCallback | TransformableRequestConfig;
+export type RouteSource = BrowserSourceCallback | TransformableRequestConfig;
+/**
+ * Route configuration with per-route media and artwork overrides.
+ *
+ * @example
+ * ```typescript
+ * routes: {
+ *   '/premium': {
+ *     browse: async () => fetchPremiumContent(),
+ *     media: { baseUrl: 'https://premium-audio.cdn.com' },
+ *     artwork: { baseUrl: 'https://premium-images.cdn.com' }
+ *   }
+ * }
+ * ```
+ */
+export type RouteConfig = {
+    /** Override browse config for this route. */
+    browse?: BrowserSource;
+    /** Override media config for this route. */
+    media?: MediaRequestConfig;
+    /** Override artwork config for this route. */
+    artwork?: ArtworkRequestConfig;
+};
+export type TabsSourceCallback = () => Promise<Track[]>;
+/**
+ * Tab source configuration for navigation tabs.
+ *
+ * When using API configuration (TransformableRequestConfig), the request path defaults to '/'
+ * and should return an array of Track objects with urls representing the tabs.
+ */
+export type TabsSource = Track[] | TabsSourceCallback | TransformableRequestConfig;
+/**
+ * Search source configuration for handling search requests.
+ *
+ * @see BrowserConfiguration.search
+ */
+export type SearchSource = SearchSourceCallback | TransformableRequestConfig;
+export type BrowserConfiguration = {
+    /**
+     * Initial navigation path. Setting this triggers initial navigation to the specified path.
+     */
+    path?: string | undefined;
+    /**
+     * Shared request settings applied to all HTTP requests (browse, search, media, artwork).
+     * Specific configs override these defaults.
+     */
+    request?: TransformableRequestConfig;
+    /** Default browse source when no matching route is found. */
+    browse?: BrowserSource;
+    /** Media/audio stream request configuration. */
+    media?: MediaRequestConfig;
+    /**
+     * Configuration for artwork/image requests.
+     * Used to transform artwork URLs for CDNs that require different authentication tokens,
+     * base URLs, or query parameters than audio requests.
+     *
+     * Artwork URLs are transformed when tracks are processed (before being passed to media controllers
+     * like Android Auto). This is different from media requests which are transformed at playback time.
+     *
+     * Note: Since media controllers load images directly from URLs, HTTP headers cannot be applied
+     * to artwork requests. Use query parameters for authentication tokens if your CDN supports it.
+     *
+     * @example
+     * ```typescript
+     * // Different CDN for images with signed URL parameters
+     * artwork: {
+     *   baseUrl: 'https://images.cdn.example.com',
+     *   query: { token: 'image-auth-token' }
+     * }
+     *
+     * // Per-track artwork URL resolution using track metadata
+     * artwork: {
+     *   resolve: async (track) => ({
+     *     baseUrl: 'https://images.cdn.example.com',
+     *     path: `/covers/${track.artist}/${track.album}.jpg`,
+     *     query: { token: await getSignedToken(track) }
+     *   })
+     * }
+     * ```
+     */
+    artwork?: ArtworkRequestConfig;
+    /**
+     * Configuration for search functionality.
+     * Enables search capabilities in the media browser, typically accessed through voice commands or search UI.
+     *
+     * Optional - if not provided, search functionality will be disabled.
+     * Required for Android Auto/CarPlay voice search integration with support for structured voice commands.
+     *
+     * Search receives structured parameters from voice commands like:
+     * - "play music" → mode='any', query=""
+     * - "play jazz" → mode='genre', genre="jazz", query="jazz"
+     * - "play michael jackson" → mode='artist', artist="michael jackson", query="michael jackson"
+     * - "play thriller by michael jackson" → mode='album', album="thriller", artist="michael jackson"
+     * - "play billie jean" → mode='song', title="billie jean", query="billie jean"
+     *
+     * Can be either:
+     * - SearchSourceCallback: Receives SearchParams with query, and optional mode/artist/album/genre/title/playlist fields
+     * - TransformableRequestConfig: API endpoint where all search parameters are automatically added to request.query:
+     *   - q: search query string (always present)
+     *   - mode: search mode (any/genre/artist/album/song/playlist) - omitted for unstructured search
+     *   - artist, album, genre, title, playlist: included when present
+     *
+     * @example
+     * ```typescript
+     * // Callback approach - direct access to structured parameters
+     * search: async (params) => {
+     *   // Use structured fields for precise searches
+     *   if (params.mode === 'artist' && params.artist) {
+     *     return await db.query('SELECT * FROM tracks WHERE artist = ?', [params.artist]);
+     *   }
+     *   if (params.mode === 'album' && params.album && params.artist) {
+     *     return await db.query('SELECT * FROM tracks WHERE album = ? AND artist = ?',
+     *       [params.album, params.artist]);
+     *   }
+     *   // Fall back to full-text search
+     *   return await searchByQuery(params.query);
+     * }
+     *
+     * // API configuration - parameters automatically added to query string
+     * search: {
+     *   baseUrl: 'https://api.example.com/search',
+     *   // GET /search?q=thriller&mode=album&album=thriller&artist=michael+jackson&limit=20
+     *   transform(request) {
+     *     return {
+     *       ...request,
+     *       query: { ...request.query, limit: 20 }
+     *     };
+     *   }
+     * }
+     * ```
+     */
+    search?: SearchSource;
+    /**
+     * Configuration for navigation tabs in the media browser.
+     * The first tab's URL is automatically loaded when the browser starts.
+     *
+     * Optional - if not provided, no tab navigation will be available.
+     * Limited to maximum 4 tabs for automotive platform compatibility (Android Auto/CarPlay).
+     *
+     * Can provide static array of Track objects with urls as tabs, API configuration, or custom callback.
+     */
+    tabs?: TabsSource;
+    /**
+     * Route-specific configurations. Maps URL paths to browse sources.
+     * Routes match by prefix, most specific (most slashes) wins.
+     *
+     * Can be a simple `BrowserSource` or extended `RouteConfig` with media/artwork overrides.
+     *
+     * @example
+     * ```typescript
+     * routes: {
+     *   '/favorites': async () => getFavorites(),
+     *   '/artists': { baseUrl: 'https://music-api.com' },
+     *   '/premium': {
+     *     browse: { baseUrl: 'https://premium-api.com' },
+     *     artwork: { baseUrl: 'https://premium-images.cdn.com' }
+     *   }
+     * }
+     * ```
+     */
+    routes?: Record<string, BrowserSource | RouteConfig>;
+    /**
+     * When true, only play the selected track without queuing siblings.
+     * When false (default), replace queue with all tracks from parent context and start at selected track.
+     *
+     * @default false
+     */
+    singleTrack?: boolean;
+    /**
+     * Custom handler for track load events.
+     * When set, navigateTrack() will call this handler instead of auto-loading/playing the track.
+     * Pass undefined to restore default behavior.
+     *
+     * @param event - The track load event containing the track, queue, and startIndex
+     */
+    handleTrackLoad?: HandleTrackLoadCallback;
+    /**
+     * Show an offline error message in external controllers (Android Auto, Wear OS, Automotive)
+     * when network connectivity is lost.
+     *
+     * When enabled, displays a standard offline error item in the media browser
+     * instead of the normal content when the network is offline.
+     *
+     * Only applies to external Media3 controllers, not in-app browsing.
+     *
+     * @default true
+     * @platform android
+     */
+    androidControllerOfflineError?: boolean;
+    /**
+     * Enable the "Up Next" button on the CarPlay Now Playing screen.
+     *
+     * When enabled, tapping "Up Next" shows the current playback queue,
+     * allowing users to see upcoming tracks and jump to a specific position.
+     *
+     * The button is automatically hidden when the queue has only one track.
+     *
+     * @default true
+     * @platform ios
+     */
+    carPlayUpNextButton?: boolean;
+    /**
+     * Configure up to 5 buttons on the CarPlay Now Playing screen. These buttons
+     * are arranged using the array order from left to right.
+     *
+     * @example
+     * ```typescript
+     * carPlayNowPlayingButtons: ['repeat']
+     * ```
+     *
+     * @default []
+     * @platform ios
+     */
+    carPlayNowPlayingButtons?: CarPlayNowPlayingButton[];
+    /**
+     * Callback to customize error messages for navigation errors.
+     * Used by CarPlay and available via `useFormattedNavigationError()` for app UI.
+     *
+     * If not provided or returns undefined, default English messages are used.
+     *
+     * @example
+     * ```typescript
+     * formatNavigationError: (error) => ({
+     *   title: t(`error.${error.code}`),
+     *   message: error.code === 'http-error'
+     *     ? t('error.httpMessage', { status: error.statusCode })
+     *     : error.message
+     * })
+     * ```
+     */
+    formatNavigationError?: FormatNavigationErrorCallback;
+};
+/**
+ * Custom button types for CarPlay Now Playing screen.
+ *
+ * - `'shuffle'`: Shuffle button that toggles shuffle mode on/off
+ * - `'repeat'`: Repeat button that cycles through off → track → queue → off
+ * - `'favorite'`: Heart button to toggle favorite state of current track
+ * - `'playback-rate'`: Playback speed button that cycles through rate options
+ *
+ * @platform ios
+ */
+export type CarPlayNowPlayingButton = 'shuffle' | 'repeat' | 'favorite' | 'playback-rate';
+/**
+ * Position of the "Ask Siri to Play Audio" assistant cell on a CarPlay list template.
+ *
+ * @platform ios
+ */
+export type CarPlaySiriListButtonPosition = 'top' | 'bottom';
+/**
+ * Formatted navigation error for display in UI.
+ * Used by CarPlay/Android Auto and available via `useFormattedNavigationError()` for app UI.
+ */
+export type FormattedNavigationError = {
+    /**
+     * Title shown in the error action sheet header.
+     *
+     * Default values:
+     * - `'content-not-found'`: "Content Not Found" (English)
+     * - `'network-error'`: "Network Error" (English)
+     * - `'http-error'`: System-localized status text (e.g., "Not Found", "Service Unavailable")
+     * - `'callback-error'`: "Error" (English)
+     * - `'unknown-error'`: "Error" (English)
+     */
+    title: string;
+    /**
+     * Message body shown below the title in the error action sheet.
+     *
+     * Default value: `error.message`
+     */
+    message: string;
+};
+/**
+ * Parameters passed to the formatNavigationError callback.
+ */
+export type FormatNavigationErrorParams = {
+    /** The navigation error that occurred */
+    error: NavigationError;
+    /** The default formatted error (useful for selective overrides) */
+    defaultFormatted: FormattedNavigationError;
+    /** The path that was being navigated to when the error occurred */
+    path: string;
+};
+/**
+ * Callback to customize navigation error display.
+ * Return localized title and message for error presentation.
+ *
+ * @param params - Object containing error details and context
+ * @returns Display information for the error, or undefined to use defaults
+ *
+ * @example
+ * ```typescript
+ * // Override only specific error types or routes
+ * formatNavigationError: ({ error, defaultFormatted, path }) => {
+ *   // Custom message for local server routes
+ *   if (error.code === 'network-error' && path.startsWith('/errors')) {
+ *     return {
+ *       title: 'Server Not Running',
+ *       message: 'Start the local server with: yarn server'
+ *     }
+ *   }
+ *   // Use default for other errors
+ *   return defaultFormatted
+ * }
+ * ```
+ */
+export type FormatNavigationErrorCallback = (params: FormatNavigationErrorParams) => FormattedNavigationError | undefined;
+//# sourceMappingURL=browser.d.ts.map