react-native-audio-browser 0.1.1 → 0.2.0-next.2

package/nitrogen/generated/shared/c++/TransformableRequestConfig.hpp

@@ -49,6 +49,7 @@ namespace margelo::nitro::audiobrowser {
   struct TransformableRequestConfig final {
   public:
     std::optional<std::function<std::shared_ptr<Promise<std::shared_ptr<Promise<RequestConfig>>>>(const RequestConfig& /* request */, const std::optional<std::unordered_map<std::string, std::string>>& /* routeParams */)>> transform     SWIFT_PRIVATE;
+    std::optional<std::function<std::shared_ptr<Promise<RequestConfig>>(const RequestConfig& /* request */, const std::optional<std::unordered_map<std::string, std::string>>& /* routeParams */)>> transformSync     SWIFT_PRIVATE;
     std::optional<HttpMethod> method     SWIFT_PRIVATE;
     std::optional<std::string> path     SWIFT_PRIVATE;
     std::optional<std::string> baseUrl     SWIFT_PRIVATE;
@@ -60,10 +61,10 @@ namespace margelo::nitro::audiobrowser {
 
   public:
     TransformableRequestConfig() = default;
-    explicit TransformableRequestConfig(std::optional<std::function<std::shared_ptr<Promise<std::shared_ptr<Promise<RequestConfig>>>>(const RequestConfig& /* request */, const std::optional<std::unordered_map<std::string, std::string>>& /* routeParams */)>> transform, std::optional<HttpMethod> method, std::optional<std::string> path, std::optional<std::string> baseUrl, std::optional<std::unordered_map<std::string, std::string>> headers, std::optional<std::unordered_map<std::string, std::string>> query, std::optional<std::string> body, std::optional<std::string> contentType, std::optional<std::string> userAgent): transform(transform), method(method), path(path), baseUrl(baseUrl), headers(headers), query(query), body(body), contentType(contentType), userAgent(userAgent) {}
+    explicit TransformableRequestConfig(std::optional<std::function<std::shared_ptr<Promise<std::shared_ptr<Promise<RequestConfig>>>>(const RequestConfig& /* request */, const std::optional<std::unordered_map<std::string, std::string>>& /* routeParams */)>> transform, std::optional<std::function<std::shared_ptr<Promise<RequestConfig>>(const RequestConfig& /* request */, const std::optional<std::unordered_map<std::string, std::string>>& /* routeParams */)>> transformSync, std::optional<HttpMethod> method, std::optional<std::string> path, std::optional<std::string> baseUrl, std::optional<std::unordered_map<std::string, std::string>> headers, std::optional<std::unordered_map<std::string, std::string>> query, std::optional<std::string> body, std::optional<std::string> contentType, std::optional<std::string> userAgent): transform(transform), transformSync(transformSync), method(method), path(path), baseUrl(baseUrl), headers(headers), query(query), body(body), contentType(contentType), userAgent(userAgent) {}
 
   public:
-    // TransformableRequestConfig is not equatable because these properties are not equatable: transform
+    // TransformableRequestConfig is not equatable because these properties are not equatable: transform, transformSync
   };
 
 } // namespace margelo::nitro::audiobrowser
@@ -77,6 +78,7 @@ namespace margelo::nitro {
       jsi::Object obj = arg.asObject(runtime);
       return margelo::nitro::audiobrowser::TransformableRequestConfig(
         JSIConverter<std::optional<std::function<std::shared_ptr<Promise<std::shared_ptr<Promise<margelo::nitro::audiobrowser::RequestConfig>>>>(const margelo::nitro::audiobrowser::RequestConfig&, const std::optional<std::unordered_map<std::string, std::string>>&)>>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "transform"))),
+        JSIConverter<std::optional<std::function<std::shared_ptr<Promise<margelo::nitro::audiobrowser::RequestConfig>>(const margelo::nitro::audiobrowser::RequestConfig&, const std::optional<std::unordered_map<std::string, std::string>>&)>>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "transformSync"))),
         JSIConverter<std::optional<margelo::nitro::audiobrowser::HttpMethod>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "method"))),
         JSIConverter<std::optional<std::string>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "path"))),
         JSIConverter<std::optional<std::string>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "baseUrl"))),
@@ -90,6 +92,7 @@ namespace margelo::nitro {
     static inline jsi::Value toJSI(jsi::Runtime& runtime, const margelo::nitro::audiobrowser::TransformableRequestConfig& arg) {
       jsi::Object obj(runtime);
       obj.setProperty(runtime, PropNameIDCache::get(runtime, "transform"), JSIConverter<std::optional<std::function<std::shared_ptr<Promise<std::shared_ptr<Promise<margelo::nitro::audiobrowser::RequestConfig>>>>(const margelo::nitro::audiobrowser::RequestConfig&, const std::optional<std::unordered_map<std::string, std::string>>&)>>>::toJSI(runtime, arg.transform));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "transformSync"), JSIConverter<std::optional<std::function<std::shared_ptr<Promise<margelo::nitro::audiobrowser::RequestConfig>>(const margelo::nitro::audiobrowser::RequestConfig&, const std::optional<std::unordered_map<std::string, std::string>>&)>>>::toJSI(runtime, arg.transformSync));
       obj.setProperty(runtime, PropNameIDCache::get(runtime, "method"), JSIConverter<std::optional<margelo::nitro::audiobrowser::HttpMethod>>::toJSI(runtime, arg.method));
       obj.setProperty(runtime, PropNameIDCache::get(runtime, "path"), JSIConverter<std::optional<std::string>>::toJSI(runtime, arg.path));
       obj.setProperty(runtime, PropNameIDCache::get(runtime, "baseUrl"), JSIConverter<std::optional<std::string>>::toJSI(runtime, arg.baseUrl));
@@ -109,6 +112,7 @@ namespace margelo::nitro {
         return false;
       }
       if (!JSIConverter<std::optional<std::function<std::shared_ptr<Promise<std::shared_ptr<Promise<margelo::nitro::audiobrowser::RequestConfig>>>>(const margelo::nitro::audiobrowser::RequestConfig&, const std::optional<std::unordered_map<std::string, std::string>>&)>>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "transform")))) return false;
+      if (!JSIConverter<std::optional<std::function<std::shared_ptr<Promise<margelo::nitro::audiobrowser::RequestConfig>>(const margelo::nitro::audiobrowser::RequestConfig&, const std::optional<std::unordered_map<std::string, std::string>>&)>>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "transformSync")))) return false;
       if (!JSIConverter<std::optional<margelo::nitro::audiobrowser::HttpMethod>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "method")))) return false;
       if (!JSIConverter<std::optional<std::string>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "path")))) return false;
       if (!JSIConverter<std::optional<std::string>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "baseUrl")))) return false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-audio-browser",
-  "version": "0.1.1",
+  "version": "0.2.0-next.2",
   "description": "react-native-audio-browser is a react native package built with Nitro",
   "keywords": [
     "react-native",
@@ -14,7 +14,7 @@
   "source": "src/index",
   "workspaces": [
     "apps/*",
-    "docs"
+    "website"
   ],
   "files": [
     "src",
@@ -50,7 +50,7 @@
     "android:test": "yarn workspace example-native android:test",
     "build": "yarn prepare",
     "clean": "del-cli android/build example/android/build example/android/app/build example/ios/build lib",
-    "codegen": "node codegen/index.js --logLevel=\"debug\" && node post-script.cjs && yarn build",
+    "codegen": "node codegen/index.js --logLevel=\"debug\" && node post-script.cjs && node codegen/strip-struct-equality.cjs && yarn build",
     "prepare": "bob build",
     "example": "yarn workspace example-native",
     "ci:format": "oxfmt --check src",
@@ -69,6 +69,7 @@
     "@react-native-community/cli": "15.0.0-alpha.2",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
+    "@types/node": "^22",
     "@types/react": "19.1.1",
     "conventional-changelog-conventionalcommits": "^9.3.0",
     "del-cli": "^5.1.0",
@@ -83,7 +84,7 @@
     "react-native-nitro-modules": "0.35.0",
     "semantic-release": "^25.0.3",
     "shaka-player": "^4.15.4",
-    "typescript": "^5.8.3",
+    "typescript": "^7.0.2",
     "vitest": "^4.0.18"
   },
   "peerDependencies": {
@@ -97,17 +98,21 @@
       "optional": true
     }
   },
-  "packageManager": "yarn@4.12.0",
+  "packageManager": "yarn@4.18.0",
   "react-native-builder-bob": {
     "source": "src",
     "output": "lib",
+    "exclude": [
+      "**/{__tests__,__fixtures__,__mocks__}/**",
+      "**/*.{spec,test}.{js,jsx,ts,tsx}"
+    ],
     "targets": [
       "commonjs",
       "module",
       [
         "typescript",
         {
-          "project": "tsconfig.json"
+          "project": "tsconfig.build.json"
         }
       ]
     ]

package/src/codegen-no-config-variant.test.ts

@@ -0,0 +1,70 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { describe, it, expect } from 'vitest'
+
+/**
+ * Regression guard for the original "async config callback returns an empty
+ * config" bug.
+ *
+ * A callback typed `(...) => RequestConfig | Promise<RequestConfig>` lowers to a
+ * Nitro `variant<RequestConfig, Promise<RequestConfig>>`. Because `RequestConfig`
+ * is all-optional, its generated `canConvert` ALSO accepts a Promise (every field
+ * reads `undefined`, which is "convertible"), and the struct arm is tried first —
+ * so an async callback's returned Promise is decoded as an all-null struct.
+ *
+ * The fix is to never union a config struct with its own Promise: sync and async
+ * are separate fields (`transform`/`transformSync`, `resolve`/`resolveSync`, and a
+ * Promise-only resolver). This test fails if codegen ever re-emits that variant —
+ * i.e. if someone reintroduces a `Config | Promise<Config>` callback return type.
+ *
+ * It's the one layer a pure-JS test can see: the bug itself lives in the native
+ * JS↔C++ bridge and is invisible to unit tests on either side, but its *source*
+ * is the generated variant, which we can assert against here.
+ */
+const GENERATED = join(process.cwd(), 'nitrogen', 'generated')
+
+const BANNED: Array<{ re: RegExp; what: string }> = [
+  {
+    re: /Variant_RequestConfig_Promise_RequestConfig_/,
+    what: 'RequestConfig | Promise<RequestConfig> (Swift/Kotlin variant)'
+  },
+  {
+    re: /Variant_TransformableRequestConfig_Promise_TransformableRequestConfig_/,
+    what: 'TransformableRequestConfig | Promise<TransformableRequestConfig> (Swift/Kotlin variant)'
+  },
+  {
+    re: /std::variant<\s*RequestConfig\b/,
+    what: 'std::variant<RequestConfig, ...> (C++)'
+  },
+  {
+    re: /std::variant<\s*TransformableRequestConfig\b/,
+    what: 'std::variant<TransformableRequestConfig, ...> (C++)'
+  }
+]
+
+function* walk(dir: string): Generator<string> {
+  for (const entry of readdirSync(dir)) {
+    const p = join(dir, entry)
+    if (statSync(p).isDirectory()) yield* walk(p)
+    else yield p
+  }
+}
+
+describe('codegen: no ambiguous config variant', () => {
+  it('never generates variant<Config, Promise<Config>> for an all-optional config struct', () => {
+    const offenders: string[] = []
+    for (const file of walk(GENERATED)) {
+      if (!/\.(swift|hpp|cpp|kt)$/.test(file)) continue
+      const text = readFileSync(file, 'utf8')
+      const hit = BANNED.find(({ re }) => re.test(text))
+      if (hit) offenders.push(`${file}  →  ${hit.what}`)
+    }
+    expect(
+      offenders,
+      'A `Config | Promise<Config>` callback union was reintroduced — it regenerates the ' +
+        'ambiguous Nitro variant whose struct arm swallows a Promise (async returns become {}). ' +
+        'Use separate sync/async fields instead. Offending generated files:\n' +
+        offenders.join('\n')
+    ).toEqual([])
+  })
+})

package/src/features/browser-config.test.ts

@@ -0,0 +1,110 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { toNativeConfig, validateBrowserConfiguration } from './browser-config'
+
+function entryFor(
+  routes: Parameters<typeof toNativeConfig>[0]['routes'],
+  path: string
+) {
+  return toNativeConfig({ routes })?.routes?.find((r) => r.path === path)
+}
+
+describe('toNativeConfig route classification', () => {
+  it('treats an artwork-only RouteConfig as a route config, not static content', () => {
+    const artwork = { baseUrl: 'https://img.example.com' }
+    const entry = entryFor({ '/x': { artwork } }, '/x')
+    expect(entry?.artwork).toEqual(artwork)
+    expect(entry?.browseStatic).toBeUndefined()
+  })
+
+  it('keeps a static page with a string artwork out of the RouteConfig branch', () => {
+    const page = {
+      url: '/x',
+      title: 'X',
+      artwork: 'https://img.example.com/x.png',
+      children: []
+    }
+    const entry = entryFor({ '/x': page }, '/x')
+    expect(entry?.browseStatic).toEqual(page)
+    expect(entry?.artwork).toBeUndefined()
+  })
+
+  it('classifies a method-only request config as a request config', () => {
+    const entry = entryFor({ '/x': { method: 'POST' } }, '/x')
+    expect(entry?.browseConfig).toEqual({ method: 'POST' })
+    expect(entry?.browseStatic).toBeUndefined()
+  })
+
+  it('still classifies media-only RouteConfig as a route config', () => {
+    const media = { baseUrl: 'https://audio.example.com' }
+    const entry = entryFor({ '/x': { media } }, '/x')
+    expect(entry?.media).toEqual(media)
+    expect(entry?.browseStatic).toBeUndefined()
+  })
+
+  it('maps the "*" key to the __default__ entry', () => {
+    const native = toNativeConfig({
+      routes: { '*': { baseUrl: 'https://api.example.com' } }
+    })
+    expect(native.routes?.[0]?.path).toBe('__default__')
+  })
+})
+
+describe('validateBrowserConfiguration', () => {
+  let warnings: string[]
+
+  beforeEach(() => {
+    warnings = []
+    vi.spyOn(console, 'warn').mockImplementation((message: unknown) => {
+      warnings.push(String(message))
+    })
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('is silent for a valid configuration', () => {
+    validateBrowserConfiguration({
+      routes: {
+        '/favorites': async () => ({ url: '/favorites', title: 'Favorites' }),
+        '/albums/{id}': { baseUrl: 'https://api.example.com' },
+        '*': { baseUrl: 'https://api.example.com' }
+      },
+      tabs: [
+        { title: 'Home', url: '/' },
+        { title: 'Search', url: '/search' }
+      ]
+    })
+    expect(warnings).toEqual([])
+  })
+
+  it('warns on reserved "__" route keys', () => {
+    validateBrowserConfiguration({
+      routes: { __tabs__: { baseUrl: 'https://api.example.com' } }
+    })
+    expect(warnings.some((w) => w.includes('reserved'))).toBe(true)
+  })
+
+  it('warns when a route value matches no source shape', () => {
+    validateBrowserConfiguration({
+      routes: { '/x': {} as never }
+    })
+    expect(warnings.some((w) => w.includes('matched no source shape'))).toBe(
+      true
+    )
+  })
+
+  it('does not flag a valid static page as unclassifiable', () => {
+    validateBrowserConfiguration({
+      routes: { '/x': { url: '/x', title: 'X', children: [] } }
+    })
+    expect(warnings).toEqual([])
+  })
+
+  it('warns on more than 4 static tabs', () => {
+    validateBrowserConfiguration({
+      tabs: [1, 2, 3, 4, 5].map((n) => ({ title: `Tab ${n}`, url: `/${n}` }))
+    })
+    expect(warnings.some((w) => w.includes('at most 4'))).toBe(true)
+  })
+})

package/src/features/browser-config.ts

@@ -0,0 +1,293 @@
+import type {
+  BrowserConfiguration,
+  BrowserSource,
+  BrowserSourceCallback,
+  RequestConfigResolver,
+  ResolvedTrack,
+  RouteConfig,
+  SearchSource,
+  SearchSourceCallback,
+  TabsSource,
+  Track,
+  TransformableRequestConfig
+} from '../types'
+import type {
+  NativeBrowserConfiguration,
+  NativeRouteEntry
+} from '../types/browser-native'
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Configuration Transformation
+//
+// Lowers the public BrowserConfiguration into the flattened native shape.
+// Deliberately NOT re-exported from features/index.ts — these helpers are
+// internal (and unit-tested directly), not public API.
+// ─────────────────────────────────────────────────────────────────────────────
+
+function isCallback(
+  source: unknown
+): source is (...args: unknown[]) => unknown {
+  return typeof source === 'function'
+}
+
+function isObjectValue(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+function isTransformableRequestConfig(
+  source: unknown
+): source is TransformableRequestConfig {
+  if (!isObjectValue(source)) return false
+  // Any RequestConfig key marks a request config. A static ResolvedTrack
+  // shares none of these at the top level (its per-track request override is
+  // nested under `request`).
+  return (
+    'baseUrl' in source ||
+    'path' in source ||
+    'headers' in source ||
+    'query' in source ||
+    'method' in source ||
+    'body' in source ||
+    'contentType' in source ||
+    'userAgent' in source ||
+    'transform' in source ||
+    'transformSync' in source
+  )
+}
+
+function isRouteConfig(source: unknown): source is RouteConfig {
+  if (!isObjectValue(source)) return false
+  // `browse`/`media` keys only exist on RouteConfig. `artwork` also exists on
+  // a static ResolvedTrack — but there it is a string URL, while RouteConfig's
+  // is a config object, so only an object-valued `artwork` marks a RouteConfig.
+  return (
+    'browse' in source || 'media' in source || isObjectValue(source.artwork)
+  )
+}
+
+function splitLayer(
+  layer: TransformableRequestConfig | RequestConfigResolver | undefined
+): {
+  config?: TransformableRequestConfig
+  resolver?: () => Promise<TransformableRequestConfig>
+} {
+  if (!layer) return {}
+  // A function is a resolver thunk; an object is a static layer config. (The
+  // `request`/`browse` layer fields are object-only today, so this is
+  // unambiguous — unlike route/search sources which already accept a callback.)
+  if (isCallback(layer)) {
+    const resolve = layer as RequestConfigResolver
+    // Normalize the sync-or-async resolver to Promise-only for the bridge so it
+    // never sees a `T | Promise<T>` variant (which misreads the async case).
+    // Resolvers run once per content generation, so the wrap costs nothing.
+    return { resolver: () => Promise.resolve(resolve()) }
+  }
+  return { config: layer as TransformableRequestConfig }
+}
+
+function flattenBrowseSource(source: BrowserSource | undefined): {
+  browseCallback?: NativeRouteEntry['browseCallback']
+  browseConfig?: NativeRouteEntry['browseConfig']
+  browseStatic?: NativeRouteEntry['browseStatic']
+} {
+  if (!source) return {}
+  if (isCallback(source))
+    return { browseCallback: source as NativeRouteEntry['browseCallback'] }
+  if (isTransformableRequestConfig(source))
+    return { browseConfig: source as NativeRouteEntry['browseConfig'] }
+  return { browseStatic: source as NativeRouteEntry['browseStatic'] }
+}
+
+/**
+ * Converts a SearchSource to a NativeRouteEntry for the __search__ path.
+ */
+function searchSourceToRouteEntry(source: SearchSource): NativeRouteEntry {
+  if (isCallback(source)) {
+    return {
+      path: SEARCH_ROUTE_PATH,
+      searchCallback: source as SearchSourceCallback
+    }
+  }
+  return {
+    path: SEARCH_ROUTE_PATH,
+    searchConfig: source as TransformableRequestConfig
+  }
+}
+
+/**
+ * Wraps a Track[] into a ResolvedTrack for tabs.
+ * Tabs are represented as a special route that returns children.
+ */
+function wrapTracksAsResolvedTrack(tracks: Track[]): ResolvedTrack {
+  return {
+    url: TABS_ROUTE_PATH,
+    title: 'Tabs',
+    children: tracks
+  }
+}
+
+/**
+ * Converts a TabsSource to a NativeRouteEntry for the __tabs__ path.
+ * Track[] is wrapped in ResolvedTrack, callbacks are wrapped to return ResolvedTrack.
+ */
+function tabsSourceToRouteEntry(source: TabsSource): NativeRouteEntry {
+  if (Array.isArray(source)) {
+    // Static Track[] - wrap as ResolvedTrack
+    return {
+      path: TABS_ROUTE_PATH,
+      browseStatic: wrapTracksAsResolvedTrack(source)
+    }
+  }
+
+  if (isCallback(source)) {
+    // Callback returning Track[] - wrap to return ResolvedTrack
+    const wrappedCallback: BrowserSourceCallback = async () => {
+      const tracks = await source()
+      return wrapTracksAsResolvedTrack(tracks)
+    }
+    return {
+      path: TABS_ROUTE_PATH,
+      browseCallback: wrappedCallback
+    }
+  }
+
+  // TransformableRequestConfig — the endpoint returns a page object whose
+  // children are the tabs (same shape as a browse endpoint).
+  return {
+    path: TABS_ROUTE_PATH,
+    browseConfig: source
+  }
+}
+
+function flattenRouteEntry(
+  path: string,
+  source: BrowserSource | RouteConfig
+): NativeRouteEntry {
+  if (isRouteConfig(source)) {
+    return {
+      path,
+      ...flattenBrowseSource(source.browse),
+      media: source.media,
+      artwork: source.artwork
+    }
+  }
+  return { path, ...flattenBrowseSource(source) }
+}
+
+/** Internal path used for the default/root browse source */
+const DEFAULT_ROUTE_PATH = '__default__'
+
+/** Internal path used for navigation tabs */
+const TABS_ROUTE_PATH = '__tabs__'
+
+// Exported for hasSearch() in browser.ts, which inspects the lowered config.
+// DEFAULT_ROUTE_PATH and TABS_ROUTE_PATH are not needed outside this module.
+export const SEARCH_ROUTE_PATH = '__search__'
+
+function flattenRoutes(
+  routes: Record<string, BrowserSource | RouteConfig> | undefined,
+  tabs: TabsSource | undefined,
+  search: SearchSource | undefined
+): NativeRouteEntry[] | undefined {
+  const entries: NativeRouteEntry[] = []
+
+  // Add explicit routes. The '*' key is the optional custom default — it maps to
+  // the __default__ entry (used when no other route matches). Without it, an
+  // unmatched browse path is fetched via request + browse config applied to the
+  // path (handled natively), so no __default__ entry is needed.
+  if (routes) {
+    for (const [path, source] of Object.entries(routes)) {
+      entries.push(
+        flattenRouteEntry(path === '*' ? DEFAULT_ROUTE_PATH : path, source)
+      )
+    }
+  }
+
+  // Add tabs as special route
+  if (tabs) {
+    entries.push(tabsSourceToRouteEntry(tabs))
+  }
+
+  // Add search as special route
+  if (search) {
+    entries.push(searchSourceToRouteEntry(search))
+  }
+
+  return entries.length > 0 ? entries : undefined
+}
+
+/** Android Auto / CarPlay display at most this many tabs. */
+const MAX_TABS = 4
+
+/**
+ * Dev-only sanity checks for a BrowserConfiguration. Warns (never throws) on
+ * mistakes the type system cannot catch: reserved route keys, route values
+ * that match no source shape (and would be served as garbage static content),
+ * and platform display limits. Called by configureBrowser under __DEV__.
+ */
+export function validateBrowserConfiguration(
+  config: BrowserConfiguration
+): void {
+  const warn = (message: string) =>
+    console.warn(`[react-native-audio-browser] configureBrowser: ${message}`)
+
+  if (config.routes) {
+    for (const [path, source] of Object.entries(config.routes)) {
+      if (path !== '*' && path.startsWith('__')) {
+        warn(
+          `route "${path}" uses the reserved "__" prefix and will conflict ` +
+            `with internal routing entries. Rename the route.`
+        )
+        continue
+      }
+      if (
+        !isCallback(source) &&
+        !isRouteConfig(source) &&
+        !isTransformableRequestConfig(source)
+      ) {
+        // Falls through to the static-page branch; a page needs url + title.
+        const page = source as Partial<ResolvedTrack>
+        if (typeof page.url !== 'string' || typeof page.title !== 'string') {
+          warn(
+            `route "${path}" matched no source shape — expected a callback, ` +
+              `a request config ({ baseUrl, path, headers, ... }), a ` +
+              `RouteConfig ({ browse, media, artwork }), or a static page ` +
+              `({ url, title, children? }). It will be served as static ` +
+              `content and likely render a blank screen.`
+          )
+        }
+      }
+    }
+  }
+
+  if (Array.isArray(config.tabs) && config.tabs.length > MAX_TABS) {
+    warn(
+      `${config.tabs.length} tabs configured; Android Auto and CarPlay ` +
+        `display at most ${MAX_TABS} — extra tabs will not be shown.`
+    )
+  }
+}
+
+export function toNativeConfig(
+  config: BrowserConfiguration
+): NativeBrowserConfiguration {
+  const request = splitLayer(config.request)
+  const browse = splitLayer(config.browse)
+  return {
+    path: config.path,
+    request: request.config,
+    requestResolver: request.resolver,
+    browse: browse.config,
+    browseResolver: browse.resolver,
+    media: config.media,
+    artwork: config.artwork,
+    nowPlayingArtwork: config.nowPlayingArtwork,
+    routes: flattenRoutes(config.routes, config.tabs, config.search),
+    singleTrack: config.singleTrack,
+    handleTrackLoad: config.handleTrackLoad,
+    androidControllerOfflineError: config.androidControllerOfflineError,
+    carPlayLoadingTitle: config.carPlayLoadingTitle,
+    resolveAlbumUrl: config.resolveAlbumUrl,
+    formatNavigationError: config.formatNavigationError
+  }
+}

package/src/features/browser.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it, vi } from 'vitest'
+
+vi.mock('../native', () => ({
+  nativeBrowser: { configuration: undefined }
+}))
+
+import { configureBrowser, getBrowserConfiguration } from './browser'
+
+describe('getBrowserConfiguration', () => {
+  it('returns undefined before the browser is configured', () => {
+    expect(getBrowserConfiguration()).toBeUndefined()
+  })
+
+  it('returns the last configuration in its public shape', () => {
+    const config = { tabs: [{ title: 'Home', url: '/' }] }
+    configureBrowser(config)
+    expect(getBrowserConfiguration()).toBe(config)
+  })
+})