react-native-audio-browser 0.2.0-next.11 → 0.2.0-next.12

package/src/features/queue/queue.ts

@@ -1,7 +1,8 @@
 import type { Track } from '../../types'
 import { nativeBrowser } from '../../native'
 import { NativeUpdatedValue } from '../../utils/NativeUpdatedValue'
-import { useNativeUpdatedValue } from '../../utils/useNativeUpdatedValue'
+import { useNativeValueRefreshedBy } from '../../utils/useNativeValueRefreshedBy'
+import { onFavoriteChanged } from '../favorites'
 
 // MARK: - Types
 
@@ -165,7 +166,9 @@ export const onQueueEnded =
 
 /**
  * Subscribes to queue change events.
- * Called when tracks are added, removed, reordered, or when track metadata changes.
+ * Called when tracks are added, removed, or reordered. An in-place mutation of
+ * a queued track's metadata (a favorite toggle) emits `onFavoriteChanged`
+ * instead; {@link useQueue} subscribes to both.
  * @param callback - Called with the updated queue
  * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
@@ -175,10 +178,14 @@ export const onQueueChanged = NativeUpdatedValue.emitterize<Track[]>(
 
 // MARK: - Hooks
 
+// Module-level so the hook's subscription identity is stable across renders.
+const queueInvalidators = [onQueueChanged, onFavoriteChanged]
+
 /**
- * Hook that returns the current queue and updates when it changes.
+ * Hook that returns the current queue, updating on queue changes AND on
+ * in-place mutations of queued tracks (favorite toggles).
  * @returns The current queue
  */
 export function useQueue(): Track[] {
-  return useNativeUpdatedValue(getQueue, onQueueChanged)
+  return useNativeValueRefreshedBy(getQueue, queueInvalidators)
 }

package/src/nitro-stub-drift.test.ts

@@ -234,4 +234,44 @@ describe('NitroTypeStubs mirror the generated Nitro types', () => {
         drift.join('\n')
     ).toEqual([])
   })
+
+  it('declares struct members in the generated initializer order', () => {
+    // Name/type parity is not enough: the stub struct's memberwise init must
+    // accept the same ARGUMENT ORDER as the generated labelled init, or shared
+    // sources compile under `swift test` and fail in the app build with
+    // "argument 'x' must precede argument 'y'" (nitrogen flattens `extends`
+    // own-properties-first, which is easy to get backwards — SectionStyle did).
+    // A stub may omit members; the ones it declares must be a subsequence of
+    // the generated order.
+    const misordered: string[] = []
+
+    for (const [name, stub] of stubs) {
+      if (name in NOT_GENERATED || stub.kind !== 'struct') continue
+      const real = parseGenerated(name)
+      if (real == null || real.kind !== 'struct') continue
+
+      const realOrder = [...real.members.keys()]
+      const stubOrder = [...stub.members.keys()].filter((member) =>
+        real.members.has(member)
+      )
+      let cursor = -1
+      for (const member of stubOrder) {
+        const index = realOrder.indexOf(member)
+        if (index < cursor) {
+          misordered.push(
+            `${name}: stub declares [${stubOrder.join(', ')}], ` +
+              `generated init order is [${realOrder.join(', ')}]`
+          )
+          break
+        }
+        cursor = index
+      }
+    }
+
+    expect(
+      misordered,
+      `Stub struct members are out of order relative to the generated init:\n` +
+        misordered.join('\n')
+    ).toEqual([])
+  })
 })

package/src/public-surface.test.ts

@@ -104,4 +104,44 @@ describe('public surface', () => {
   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

@@ -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,139 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+/**
+ * Inheritance-completeness guard for the style declaration block (ADR 0011).
+ *
+ * `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)
+    })
+  })
+}

package/src/types/browser-native.ts

@@ -9,7 +9,7 @@
 import type {
   ArtworkRequestConfig,
   BrowserSourceCallback,
-  ResolveAlbumUrlCallback,
+  ResolveAlbumPathCallback,
   FormatNavigationErrorCallback,
   HandleTrackLoadCallback,
   MediaRequestConfig,
@@ -76,6 +76,6 @@ export interface NativeBrowserConfiguration {
 
   // CarPlay options
   carPlayLoadingTitle?: string
-  resolveAlbumUrl?: ResolveAlbumUrlCallback
+  resolveAlbumPath?: ResolveAlbumPathCallback
   formatNavigationError?: FormatNavigationErrorCallback
 }