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

package/src/public-surface.test.ts

@@ -0,0 +1,147 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join, relative, resolve } from 'node:path'
+import { describe, it, expect } from 'vitest'
+
+/**
+ * Guard on what `import { … } from 'react-native-audio-browser'` can reach.
+ *
+ * `@internal` hides a value from the published types but not from the bundle:
+ * Metro resolves `"react-native": "src/index"` and compiles the source, where
+ * `stripInternal` never ran. Types are exempt — they have no runtime form.
+ * `CLAUDE.md` in this directory has the full rule.
+ */
+const SRC = join(process.cwd(), 'src')
+const ENTRY = join(SRC, 'index.ts')
+
+const VALUE_KINDS = new Set([
+  'const',
+  'let',
+  'var',
+  'function',
+  'class',
+  'enum'
+])
+
+function resolveModule(fromFile: string, spec: string): string | undefined {
+  const base = resolve(dirname(fromFile), spec.replace(/\.tsx?$/, ''))
+  return [`${base}.ts`, `${base}.tsx`, join(base, 'index.ts')].find(existsSync)
+}
+
+interface Export {
+  name: string
+  file: string
+  internal: boolean
+}
+
+/** Walks the `export *` graph from `entry`, collecting every reachable value export. */
+function collectValueExports(entry: string): Export[] {
+  const found: Export[] = []
+  const seen = new Set<string>()
+
+  const visit = (file: string) => {
+    if (seen.has(file)) return
+    seen.add(file)
+    const source = readFileSync(file, 'utf8')
+
+    for (const [, spec] of source.matchAll(/^export \* from ['"](.+?)['"]/gm)) {
+      const target = resolveModule(file, spec!)
+      if (target) visit(target)
+    }
+
+    const declaration =
+      /^export (?:declare )?(?:async )?(?:abstract )?(const|let|var|function|class|enum) (\w+)/gm
+    for (const match of source.matchAll(declaration)) {
+      if (!VALUE_KINDS.has(match[1]!)) continue
+      // The JSDoc block, if any, is whatever sits directly above the export.
+      const preceding = source.slice(0, match.index)
+      const doc = /\/\*\*(?:(?!\*\/)[\s\S])*\*\/\s*$/.exec(preceding)?.[0] ?? ''
+      found.push({
+        name: match[2]!,
+        file: relative(SRC, file),
+        internal: /@internal\b/.test(doc)
+      })
+    }
+  }
+
+  visit(entry)
+  return found
+}
+
+describe('public surface', () => {
+  const exports = collectValueExports(ENTRY)
+
+  it('reaches the feature modules at all (the walker still works)', () => {
+    // Cheap canary: if the barrel structure changes shape and the walker stops
+    // resolving, every other assertion here would pass vacuously.
+    expect(exports.map((e) => e.name)).toContain('trackPlaybackTime')
+    expect(exports.length).toBeGreaterThan(100)
+  })
+
+  it('exposes no value marked @internal', () => {
+    const leaked = exports
+      .filter((e) => e.internal)
+      .map((e) => `${e.name}  (${e.file})`)
+    expect(
+      leaked,
+      'Reachable from the package root at runtime despite @internal. Move each ' +
+        'to a module the barrels skip, and import it directly:\n' +
+        leaked.join('\n')
+    ).toEqual([])
+  })
+
+  it('exposes no __-prefixed test hook', () => {
+    const hooks = exports
+      .filter((e) => e.name.startsWith('__'))
+      .map((e) => `${e.name}  (${e.file})`)
+    expect(
+      hooks,
+      'Test-only exports ship to consumers. Drive the unit through a seam it ' +
+        'already has — a mocked native slot, say:\n' +
+        hooks.join('\n')
+    ).toEqual([])
+  })
+
+  it('does not re-export the raw Nitro object', () => {
+    expect(exports.map((e) => e.name)).not.toContain('nativeBrowser')
+  })
+
+  it('every public module is covered by the typedoc entry points', () => {
+    // The API reference documents entryPoints, not the export graph — a public
+    // module missing from website/typedoc.json ships undocumented.
+    const config = JSON.parse(
+      readFileSync(join(process.cwd(), 'website', 'typedoc.json'), 'utf8')
+    ) as { entryPoints: string[] }
+    const entries = config.entryPoints.map(
+      (glob) =>
+        new RegExp(
+          '^' +
+            glob
+              .replace(/^\.\.\/src\//, '')
+              .replace(/[.]/g, '\\.')
+              .replace(/\*/g, '[^/]+') +
+            '$'
+        )
+    )
+    const covered = (file: string): boolean => {
+      if (entries.some((e) => e.test(file))) return true
+      // A directory barrel entry (…/index.ts) documents what it re-exports.
+      const dir = file.split('/').slice(0, -1)
+      while (dir.length > 0) {
+        if (entries.some((e) => e.test([...dir, 'index.ts'].join('/'))))
+          return true
+        dir.pop()
+      }
+      return false
+    }
+    const uncovered = [...new Set(exports.map((e) => e.file))].filter(
+      (file) => !covered(file)
+    )
+    expect(
+      uncovered,
+      'Exported to consumers but absent from the API reference. Add each ' +
+        'module (or its directory barrel) to website/typedoc.json ' +
+        'entryPoints:\n' +
+        uncovered.join('\n')
+    ).toEqual([])
+  })
+})

package/src/specs/audio-browser.nitro.ts

@@ -115,7 +115,7 @@ export interface AudioBrowser extends HybridObject<{
   tabs: Track[] | undefined
   navigatePath(path: string): void
   navigateTrack(track: Track): void
-  onSearch(query: string): Promise<Track[]>
+  search(query: string): Promise<Track[]>
   getContent(): ResolvedTrack | undefined
   onPathChanged: (path: string) => void
   onContentChanged: (content: ResolvedTrack | undefined) => void
@@ -229,9 +229,10 @@ export interface AudioBrowser extends HybridObject<{
   seekTo(position: number): void
   seekBy(offset: number): void
   /**
-   * Jump to the live edge of the current track. No-op for non-live tracks.
-   * Live with a seekable window (HLS): seeks to the window end. Live without a
-   * window (non-seekable, e.g. ICY): reconnects to rejoin live.
+   * Jump to the live edge of the current track; no-op unless the track
+   * declares `live: true`. A stream with a seekable live window (HLS) seeks
+   * to the window's edge; a non-seekable stream (e.g. ICY radio) reconnects
+   * to rejoin live — an expired URL re-resolves through `media.resolve`.
    */
   seekToLiveEdge(): void
   setVolume(level: number): void

package/src/style-resolution.test.ts

@@ -0,0 +1,210 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+/**
+ * Completeness guards for the style declaration block (ADR 0011) — the checks
+ * Nitro's `extends`-flattening took out of the type system, in two parts:
+ * every key must be *resolved* by each platform's `StyleResolver`, and every
+ * key must be *accounted for* by each platform's `InertStyleDiagnostic`.
+ *
+ * Part one — inheritance completeness.
+ *
+ * `SectionStyle extends TrackStyle` in the spec, but Nitro flattens `extends`
+ * into independent structs on every platform — so nothing in any type system
+ * forces a platform's `StyleResolver` to read a newly added style key. A key
+ * the resolver forgets is silently dead: declared by consumers, decoded on the
+ * wire, never rendered. This test is the compile-time check the flattening
+ * took away:
+ *
+ * - every `SectionStyle` key must appear in each platform's
+ *   `sectionStyle(section, page)` merge;
+ * - every inherited `TrackStyle` key must appear in each platform's
+ *   `trackStyle(track, section)` merge;
+ * - `display` is positional (the deny-list): the track merge must resolve it
+ *   to nil/null and must not read it from any level.
+ */
+
+const ROOT = process.cwd()
+
+const RESOLVERS = [
+  {
+    file: 'ios/Browser/StyleResolver.swift',
+    sectionMarker: 'static func sectionStyle',
+    trackMarker: 'static func trackStyle',
+    positionalNil: 'display: nil'
+  },
+  {
+    file: 'android/src/main/java/com/audiobrowser/browser/StyleResolver.kt',
+    sectionMarker: 'fun sectionStyle',
+    trackMarker: 'fun trackStyle',
+    positionalNil: 'display = null'
+  }
+]
+
+/** Keys the spec deliberately excludes from item inheritance. */
+const POSITIONAL = ['display']
+
+function interfaceKeys(source: string, name: string): string[] {
+  const start = source.indexOf(`export interface ${name} `)
+  expect(
+    start,
+    `interface ${name} not found in browser-nodes.ts`
+  ).toBeGreaterThan(-1)
+  const end = source.indexOf('\n}', start)
+  const body = source.slice(start, end)
+  return [...body.matchAll(/^ {2}(\w+)\??:/gm)].flatMap((match) =>
+    match[1] === undefined ? [] : [match[1]]
+  )
+}
+
+/**
+ * The function's text from `marker` to the next function declaration (or end
+ * of file) — brace-agnostic, since Kotlin expression bodies have no braces.
+ */
+function functionBody(source: string, marker: string, file: string): string {
+  const start = source.indexOf(marker)
+  expect(start, `${marker} not found in ${file}`).toBeGreaterThan(-1)
+  const rest = source.slice(start + marker.length)
+  const next = rest.search(/\n\s*(?:static func|func|fun)\s/)
+  return marker + (next === -1 ? rest : rest.slice(0, next))
+}
+
+/** Comment-free view, so prose about a key doesn't count as reading it. */
+function stripComments(code: string): string {
+  return code
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .split('\n')
+    .map((line) => line.replace(/\/\/.*$/, ''))
+    .join('\n')
+}
+
+const nodes = readFileSync(
+  join(ROOT, 'src', 'types', 'browser-nodes.ts'),
+  'utf8'
+)
+const trackKeys = interfaceKeys(nodes, 'TrackStyle')
+const sectionKeys = [...trackKeys, ...interfaceKeys(nodes, 'SectionStyle')]
+const inheritedKeys = trackKeys.filter((key) => !POSITIONAL.includes(key))
+
+describe('style block shape', () => {
+  it('has the positional key and at least one inherited key', () => {
+    expect(trackKeys).toContain('display')
+    expect(inheritedKeys.length).toBeGreaterThan(0)
+  })
+})
+
+for (const resolver of RESOLVERS) {
+  describe(resolver.file, () => {
+    const source = readFileSync(join(ROOT, resolver.file), 'utf8')
+    const sectionBody = stripComments(
+      functionBody(source, resolver.sectionMarker, resolver.file)
+    )
+    const trackBody = stripComments(
+      functionBody(source, resolver.trackMarker, resolver.file)
+    )
+
+    // Containment of `holder?.key` for BOTH holders — `display =
+    // section?.display` with the page half dropped must fail — AND in
+    // precedence order: the narrower holder must be read first, or the
+    // scope-override/inheritance direction is inverted (`page ?? section`
+    // would pass a bare containment check).
+    it.each(sectionKeys)('sectionStyle merges %s (section ?? page)', (key) => {
+      const section = sectionBody.indexOf(`section?.${key}`)
+      const page = sectionBody.indexOf(`page?.${key}`)
+      expect(section, `section?.${key} not read`).toBeGreaterThan(-1)
+      expect(page, `page?.${key} not read`).toBeGreaterThan(-1)
+      expect(section, `section?.${key} must precede page?.${key}`).toBeLessThan(
+        page
+      )
+    })
+
+    it.each(inheritedKeys)(
+      'trackStyle inherits %s (track ?? section)',
+      (key) => {
+        const track = trackBody.indexOf(`track?.${key}`)
+        const section = trackBody.indexOf(`section?.${key}`)
+        expect(track, `track?.${key} not read`).toBeGreaterThan(-1)
+        expect(section, `section?.${key} not read`).toBeGreaterThan(-1)
+        expect(
+          track,
+          `track?.${key} must precede section?.${key}`
+        ).toBeLessThan(section)
+      }
+    )
+
+    it('trackStyle excludes the positional display (deny-list)', () => {
+      expect(trackBody).toContain(resolver.positionalNil)
+      // The nil assignment must be the ONLY mention: reading display from any
+      // level here would item-inherit a positional key.
+      const mentions = trackBody.match(/display/g) ?? []
+      expect(mentions).toHaveLength(1)
+    })
+  })
+}
+
+/**
+ * Part two — diagnostic completeness.
+ *
+ * The block model traded compile-time invalid-combination errors for
+ * inertness, and the dev-mode `InertStyleDiagnostic` is the recovery. It is
+ * exposed to the same flattening problem as the resolvers, one level up: a
+ * key added to the spec has no type-system tie to the diagnostic's rule set,
+ * so a property could ship whose inert combinations nobody is warned about.
+ *
+ * Each platform therefore dispositions the whole vocabulary — every key is a
+ * `Property` with an inertness rule, `alwaysRenderable`, or `positional` —
+ * and this test reads those three declarations and asserts set equality with
+ * the spec, both directions: a new key must be dispositioned, and a key
+ * deleted from the spec must not linger in the rule set.
+ */
+const DIAGNOSTICS = [
+  {
+    file: 'ios/Browser/InertStyleDiagnostic.swift',
+    // `case gridWrap`, up to the first member after the case list.
+    ruled: (source: string) =>
+      keysIn(
+        source,
+        /enum Property[\s\S]*?var isItemProperty/,
+        /^\s*case (\w+)$/gm
+      )
+  },
+  {
+    file: 'android/src/main/java/com/audiobrowser/browser/InertStyleDiagnostic.kt',
+    // `GRID_WRAP("gridWrap", …)`, up to the `;` that ends the entry list.
+    ruled: (source: string) =>
+      keysIn(source, /enum class Property[\s\S]*?;/, /\w+\("(\w+)"/g)
+  }
+]
+
+/** The capture group of every `pattern` match within the first `region`. */
+function keysIn(source: string, region: RegExp, pattern: RegExp): string[] {
+  const found = region.exec(source)
+  expect(found, `region ${region} not found`).not.toBeNull()
+  return [...found![0].matchAll(pattern)].flatMap((match) =>
+    match[1] === undefined ? [] : [match[1]]
+  )
+}
+
+for (const diagnostic of DIAGNOSTICS) {
+  describe(diagnostic.file, () => {
+    // Comment-free, so prose naming a key doesn't pass for dispositioning it.
+    const source = stripComments(
+      readFileSync(join(ROOT, diagnostic.file), 'utf8')
+    )
+    // The two lists are spelled `alwaysRenderable`/`positional` in Swift and
+    // SCREAMING_CASE in Kotlin; both hold bare string literals.
+    const listed = [
+      ...source.matchAll(
+        /(?:alwaysRenderable|ALWAYS_RENDERABLE|positional|POSITIONAL)\s*=[^\n]*/gi
+      )
+    ].flatMap((match) =>
+      [...match[0].matchAll(/"(\w+)"/g)].map((key) => key[1])
+    )
+
+    it('dispositions every key of the block, and only those', () => {
+      const dispositioned = [...diagnostic.ruled(source), ...listed]
+      expect(new Set(dispositioned)).toEqual(new Set(sectionKeys))
+    })
+  })
+}

package/src/test-utils/reactNativeStub.ts

@@ -0,0 +1,60 @@
+/**
+ * Stands in for `react-native` under vitest, via the alias in `vitest.config.ts`.
+ *
+ * Not a convenience: `react-native/index.js` is Flow-typed (`import typeof ...`)
+ * and Rollup cannot parse it, so any test that reaches a module importing from
+ * `'react-native'` fails to load at all. Jest consumers get this from
+ * `@react-native/jest-preset`; vitest has no equivalent.
+ *
+ * Keep it to the surface the library actually touches. Two symbols so far —
+ * `AppState` (usePolledProgress) and `Image.resolveAssetSource`. Anything a test
+ * needs to drive should get an explicit control here rather than a cast at the
+ * call site.
+ *
+ * @internal — never imported by production code, only aliased in by the runner.
+ */
+
+export type AppStateStatus = 'active' | 'background' | 'inactive'
+
+type ChangeListener = (status: AppStateStatus) => void
+
+const changeListeners = new Set<ChangeListener>()
+
+export const AppState = {
+  currentState: 'active' as AppStateStatus,
+
+  // `type` is widened to string so the guard stays live: real AppState also
+  // emits 'memoryWarning' and 'focus', and silently treating one of those as a
+  // 'change' subscription would be a confusing way to find out this stub is thin.
+  addEventListener(type: string, listener: ChangeListener) {
+    if (type !== 'change') throw new Error(`AppState stub: unhandled "${type}"`)
+    changeListeners.add(listener)
+    return { remove: () => changeListeners.delete(listener) }
+  }
+}
+
+/** Move the app to the foreground or background and notify subscribers. */
+export function setAppState(status: AppStateStatus): void {
+  AppState.currentState = status
+  // Deleting from a Set mid-iteration is safe, so a listener that removes itself
+  // during the callback needs no defensive copy.
+  for (const listener of changeListeners) listener(status)
+}
+
+/**
+ * Drop every subscription and return to the foreground. Call between tests —
+ * the stub is a module singleton, so state outlives an individual test.
+ */
+export function resetAppState(): void {
+  changeListeners.clear()
+  AppState.currentState = 'active'
+}
+
+/** Number of live `change` subscriptions, for asserting cleanup. */
+export function appStateListenerCount(): number {
+  return changeListeners.size
+}
+
+export const Image = {
+  resolveAssetSource: (source: unknown) => source
+}

package/src/types/browser-native.ts

@@ -9,12 +9,13 @@
 import type {
   ArtworkRequestConfig,
   BrowserSourceCallback,
-  ResolveAlbumUrlCallback,
+  ResolveAlbumPathCallback,
   FormatNavigationErrorCallback,
   HandleTrackLoadCallback,
   MediaRequestConfig,
   SearchSourceCallback,
-  TransformableRequestConfig
+  TransformableRequestConfig,
+  ViewMoreTitleCallback
 } from './browser'
 import type { ResolvedTrack } from './browser-nodes'
 
@@ -73,9 +74,12 @@ export interface NativeBrowserConfiguration {
   singleTrack?: boolean
   handleTrackLoad?: HandleTrackLoadCallback
   androidControllerOfflineError?: boolean
+  // Title of the "view more" row appended to a pathed section where the header
+  // can't be tapped (Android Auto). Absent = native's "View more" default.
+  viewMoreTitle?: ViewMoreTitleCallback
 
   // CarPlay options
   carPlayLoadingTitle?: string
-  resolveAlbumUrl?: ResolveAlbumUrlCallback
+  resolveAlbumPath?: ResolveAlbumPathCallback
   formatNavigationError?: FormatNavigationErrorCallback
 }