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

package/nitrogen/generated/shared/c++/{NotificationButton.hpp → RemoteButton.hpp}

@@ -1,5 +1,5 @@
 ///
-/// NotificationButton.hpp
+/// RemoteButton.hpp
 /// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
 /// https://github.com/mrousavy/nitro
 /// Copyright © Marc Rousavy @ Margelo
@@ -26,9 +26,9 @@
 namespace margelo::nitro::audiobrowser {
 
   /**
-   * An enum which can be represented as a JavaScript union (NotificationButton).
+   * An enum which can be represented as a JavaScript union (RemoteButton).
    */
-  enum class NotificationButton {
+  enum class RemoteButton {
     SKIP_TO_PREVIOUS      SWIFT_NAME(skipToPrevious) = 0,
     SKIP_TO_NEXT      SWIFT_NAME(skipToNext) = 1,
     JUMP_BACKWARD      SWIFT_NAME(jumpBackward) = 2,
@@ -40,30 +40,30 @@ namespace margelo::nitro::audiobrowser {
 
 namespace margelo::nitro {
 
-  // C++ NotificationButton <> JS NotificationButton (union)
+  // C++ RemoteButton <> JS RemoteButton (union)
   template <>
-  struct JSIConverter<margelo::nitro::audiobrowser::NotificationButton> final {
-    static inline margelo::nitro::audiobrowser::NotificationButton fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
+  struct JSIConverter<margelo::nitro::audiobrowser::RemoteButton> final {
+    static inline margelo::nitro::audiobrowser::RemoteButton fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
       std::string unionValue = JSIConverter<std::string>::fromJSI(runtime, arg);
       switch (hashString(unionValue.c_str(), unionValue.size())) {
-        case hashString("skip-to-previous"): return margelo::nitro::audiobrowser::NotificationButton::SKIP_TO_PREVIOUS;
-        case hashString("skip-to-next"): return margelo::nitro::audiobrowser::NotificationButton::SKIP_TO_NEXT;
-        case hashString("jump-backward"): return margelo::nitro::audiobrowser::NotificationButton::JUMP_BACKWARD;
-        case hashString("jump-forward"): return margelo::nitro::audiobrowser::NotificationButton::JUMP_FORWARD;
-        case hashString("favorite"): return margelo::nitro::audiobrowser::NotificationButton::FAVORITE;
+        case hashString("skip-to-previous"): return margelo::nitro::audiobrowser::RemoteButton::SKIP_TO_PREVIOUS;
+        case hashString("skip-to-next"): return margelo::nitro::audiobrowser::RemoteButton::SKIP_TO_NEXT;
+        case hashString("jump-backward"): return margelo::nitro::audiobrowser::RemoteButton::JUMP_BACKWARD;
+        case hashString("jump-forward"): return margelo::nitro::audiobrowser::RemoteButton::JUMP_FORWARD;
+        case hashString("favorite"): return margelo::nitro::audiobrowser::RemoteButton::FAVORITE;
         default: [[unlikely]]
-          throw std::invalid_argument("Cannot convert \"" + unionValue + "\" to enum NotificationButton - invalid value!");
+          throw std::invalid_argument("Cannot convert \"" + unionValue + "\" to enum RemoteButton - invalid value!");
       }
     }
-    static inline jsi::Value toJSI(jsi::Runtime& runtime, margelo::nitro::audiobrowser::NotificationButton arg) {
+    static inline jsi::Value toJSI(jsi::Runtime& runtime, margelo::nitro::audiobrowser::RemoteButton arg) {
       switch (arg) {
-        case margelo::nitro::audiobrowser::NotificationButton::SKIP_TO_PREVIOUS: return JSIConverter<std::string>::toJSI(runtime, "skip-to-previous");
-        case margelo::nitro::audiobrowser::NotificationButton::SKIP_TO_NEXT: return JSIConverter<std::string>::toJSI(runtime, "skip-to-next");
-        case margelo::nitro::audiobrowser::NotificationButton::JUMP_BACKWARD: return JSIConverter<std::string>::toJSI(runtime, "jump-backward");
-        case margelo::nitro::audiobrowser::NotificationButton::JUMP_FORWARD: return JSIConverter<std::string>::toJSI(runtime, "jump-forward");
-        case margelo::nitro::audiobrowser::NotificationButton::FAVORITE: return JSIConverter<std::string>::toJSI(runtime, "favorite");
+        case margelo::nitro::audiobrowser::RemoteButton::SKIP_TO_PREVIOUS: return JSIConverter<std::string>::toJSI(runtime, "skip-to-previous");
+        case margelo::nitro::audiobrowser::RemoteButton::SKIP_TO_NEXT: return JSIConverter<std::string>::toJSI(runtime, "skip-to-next");
+        case margelo::nitro::audiobrowser::RemoteButton::JUMP_BACKWARD: return JSIConverter<std::string>::toJSI(runtime, "jump-backward");
+        case margelo::nitro::audiobrowser::RemoteButton::JUMP_FORWARD: return JSIConverter<std::string>::toJSI(runtime, "jump-forward");
+        case margelo::nitro::audiobrowser::RemoteButton::FAVORITE: return JSIConverter<std::string>::toJSI(runtime, "favorite");
         default: [[unlikely]]
-          throw std::invalid_argument("Cannot convert NotificationButton to JS - invalid value: "
+          throw std::invalid_argument("Cannot convert RemoteButton to JS - invalid value: "
                                     + std::to_string(static_cast<int>(arg)) + "!");
       }
     }

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

@@ -0,0 +1,94 @@
+///
+/// RemoteButtonLayout.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+#pragma once
+
+#if __has_include(<NitroModules/JSIConverter.hpp>)
+#include <NitroModules/JSIConverter.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/NitroDefines.hpp>)
+#include <NitroModules/NitroDefines.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/JSIHelpers.hpp>)
+#include <NitroModules/JSIHelpers.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/PropNameIDCache.hpp>)
+#include <NitroModules/PropNameIDCache.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+
+// Forward declaration of `RemoteButton` to properly resolve imports.
+namespace margelo::nitro::audiobrowser { enum class RemoteButton; }
+
+#include "RemoteButton.hpp"
+#include <optional>
+#include <vector>
+
+namespace margelo::nitro::audiobrowser {
+
+  /**
+   * A struct which can be represented as a JavaScript object (RemoteButtonLayout).
+   */
+  struct RemoteButtonLayout final {
+  public:
+    std::optional<RemoteButton> back     SWIFT_PRIVATE;
+    std::optional<RemoteButton> forward     SWIFT_PRIVATE;
+    std::vector<RemoteButton> overflow     SWIFT_PRIVATE;
+
+  public:
+    RemoteButtonLayout() = default;
+    explicit RemoteButtonLayout(std::optional<RemoteButton> back, std::optional<RemoteButton> forward, std::vector<RemoteButton> overflow): back(back), forward(forward), overflow(overflow) {}
+
+  public:
+    friend bool operator==(const RemoteButtonLayout& lhs, const RemoteButtonLayout& rhs) = default;
+  };
+
+} // namespace margelo::nitro::audiobrowser
+
+namespace margelo::nitro {
+
+  // C++ RemoteButtonLayout <> JS RemoteButtonLayout (object)
+  template <>
+  struct JSIConverter<margelo::nitro::audiobrowser::RemoteButtonLayout> final {
+    static inline margelo::nitro::audiobrowser::RemoteButtonLayout fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
+      jsi::Object obj = arg.asObject(runtime);
+      return margelo::nitro::audiobrowser::RemoteButtonLayout(
+        JSIConverter<std::optional<margelo::nitro::audiobrowser::RemoteButton>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "back"))),
+        JSIConverter<std::optional<margelo::nitro::audiobrowser::RemoteButton>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "forward"))),
+        JSIConverter<std::vector<margelo::nitro::audiobrowser::RemoteButton>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "overflow")))
+      );
+    }
+    static inline jsi::Value toJSI(jsi::Runtime& runtime, const margelo::nitro::audiobrowser::RemoteButtonLayout& arg) {
+      jsi::Object obj(runtime);
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "back"), JSIConverter<std::optional<margelo::nitro::audiobrowser::RemoteButton>>::toJSI(runtime, arg.back));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "forward"), JSIConverter<std::optional<margelo::nitro::audiobrowser::RemoteButton>>::toJSI(runtime, arg.forward));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "overflow"), JSIConverter<std::vector<margelo::nitro::audiobrowser::RemoteButton>>::toJSI(runtime, arg.overflow));
+      return obj;
+    }
+    static inline bool canConvert(jsi::Runtime& runtime, const jsi::Value& value) {
+      if (!value.isObject()) {
+        return false;
+      }
+      jsi::Object obj = value.getObject(runtime);
+      if (!nitro::isPlainObject(runtime, obj)) {
+        return false;
+      }
+      if (!JSIConverter<std::optional<margelo::nitro::audiobrowser::RemoteButton>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "back")))) return false;
+      if (!JSIConverter<std::optional<margelo::nitro::audiobrowser::RemoteButton>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "forward")))) return false;
+      if (!JSIConverter<std::vector<margelo::nitro::audiobrowser::RemoteButton>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "overflow")))) return false;
+      return true;
+    }
+  };
+
+} // namespace margelo::nitro

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-audio-browser",
-  "version": "0.2.0-next.1",
+  "version": "0.2.0-next.11",
   "description": "react-native-audio-browser is a react native package built with Nitro",
   "keywords": [
     "react-native",
@@ -45,17 +45,20 @@
   },
   "scripts": {
     "android:format": "yarn workspace example-native android:format",
+    "android:format:check": "yarn workspace example-native android:format:check",
     "android:ide": "yarn workspace example-native android:ide",
     "android:logs": "react-native log-android",
     "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 && node codegen/strip-struct-equality.cjs && yarn build",
-    "prepare": "bob build",
+    "prepare": "bob build && yarn hooks:install",
+    "hooks:install": "git config core.hooksPath .githooks || exit 0",
     "example": "yarn workspace example-native",
-    "ci:format": "oxfmt --check src",
+    "ci:format": "oxfmt --check --ignore-path .gitignore --ignore-path .oxfmtignore .",
+    "ci:format:ios": "swiftformat --lint ios",
     "ci:lint": "oxlint --type-aware src",
-    "format": "oxfmt --write",
+    "format": "oxfmt --write --ignore-path .gitignore --ignore-path .oxfmtignore .",
     "ios:format": "swiftformat ios",
     "ios:ide": "yarn workspace example-native ios:ide",
     "ios:rebuild": "yarn workspace example-native ios:rebuild",
@@ -69,15 +72,20 @@
     "@react-native-community/cli": "15.0.0-alpha.2",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
     "@types/node": "^22",
     "@types/react": "19.1.1",
+    "@types/react-dom": "19.1.7",
     "conventional-changelog-conventionalcommits": "^9.3.0",
     "del-cli": "^5.1.0",
+    "happy-dom": "^20.11.2",
     "nitrogen": "0.35.0",
     "oxfmt": "^0.27.0",
     "oxlint": "^1.42.0",
     "oxlint-tsgolint": "^0.11.2",
     "react": "19.1.1",
+    "react-dom": "19.1.1",
     "react-native": "0.83.0",
     "react-native-builder-bob": "^0.37.0",
     "react-native-monorepo-config": "^0.3.1",

package/src/AudioBrowser.ts

@@ -1,4 +1,4 @@
+// `./native` is deliberately not re-exported — see public-surface.test.ts.
 export * from './features'
-export * from './native'
 export * from './types'
 export * from './utils/useDebug'

package/src/CLAUDE.md

@@ -0,0 +1,52 @@
+# TypeScript API
+
+The rules here are about the shape of the package's public surface. Both are
+enforced by tests, but the tests only tell you _after_ you've written it.
+
+## Everything you export is public
+
+`index.ts` → `AudioBrowser.ts` → `features/index.ts` is a chain of unfiltered
+`export *`. There is no allowlist to add a symbol to: a new `export` in any
+feature module joins the package's public surface the moment you write it.
+
+`@internal` does **not** make a value private. `stripInternal` honours it when
+building `lib/typescript` — what a consumer's TypeScript sees — but React Native
+resolves `"react-native": "src/index"`, so Metro bundles the _source_, where
+nothing was stripped. An `@internal` value is invisible to the type checker and
+fully reachable at runtime via `require()`.
+
+So an internal value needs a module the barrels don't re-export, imported
+directly by its callers — `features/player/validateOptions.ts` is the pattern.
+Types are exempt: they have no runtime representation, so `stripInternal` really
+does remove them, and `@internal` is enough.
+
+`native.ts` is the sharp case and stays out of the barrel permanently. It holds
+the raw Nitro object, whose `on*` properties are single callback slots that the
+emitters below already occupy — a consumer assigning one unsubscribes every hook
+in the library. Feature modules import it relatively; nothing else touches it.
+
+`public-surface.test.ts` walks the `export *` graph and fails on any reachable
+value that is `@internal`, `__`-prefixed, or `nativeBrowser`.
+
+## Events are emitters, not functions
+
+Every `on*` export is an object you subscribe to with `addListener(cb)`, which
+returns an unsubscribe function. Never export a bare `on*(cb)` subscribe
+function — that split is what made the whole remote-controls guide a compile
+error until it was unified.
+
+Two emitter classes, picked by what the event _is_:
+
+- `NativeUpdatedValue` — state with a current value (playback, options,
+  progress). Subscribes to native at module load so no update is missed, and
+  caches `lastValue` so hooks can read synchronously.
+- `LazyNativeEmitter` — discrete events with no current value (remote controls,
+  gate hits). Assigns the native callback on the first `addListener`, so an
+  event nobody listens to costs nothing.
+
+Both are created via `emitterize(cb => (nativeBrowser.onThing = cb))` and both
+return the instance. Neither class is exported from the package.
+
+`on*` observes; `handle*` overrides. `handleRemoteNext(cb)` is a plain setter
+that replaces the default behaviour and takes `undefined` to clear it, while
+`onRemoteNext` fires on every press regardless of who handled it.

package/src/features/battery.test.ts

@@ -0,0 +1,79 @@
+/** @vitest-environment happy-dom */
+
+import { renderHook, act, cleanup } from '@testing-library/react'
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import type { BatteryOptimizationStatus } from './battery'
+
+const native = vi.hoisted(() => ({
+  getBatteryWarningPending: vi.fn(() => false),
+  getBatteryOptimizationStatus: vi.fn<() => BatteryOptimizationStatus>(
+    () => 'unknown' as BatteryOptimizationStatus
+  ),
+  dismissBatteryWarning: vi.fn(),
+  openBatterySettings: vi.fn(),
+  onBatteryWarningPendingChanged: undefined as
+    | ((event: { pending: boolean }) => void)
+    | undefined,
+  onBatteryOptimizationStatusChanged: undefined as
+    | ((event: { status: BatteryOptimizationStatus }) => void)
+    | undefined
+}))
+
+vi.mock('../native', () => ({ nativeBrowser: native }))
+
+const { useBatteryWarning } = await import('./battery')
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  native.getBatteryWarningPending.mockReturnValue(false)
+  native.getBatteryOptimizationStatus.mockReturnValue(
+    'unknown' as BatteryOptimizationStatus
+  )
+})
+afterEach(cleanup)
+
+describe('useBatteryWarning', () => {
+  it('combines the two underlying values into one object', () => {
+    const { result } = renderHook(() => useBatteryWarning())
+    expect(result.current).toMatchObject({ pending: false, status: 'unknown' })
+  })
+
+  it('tracks each source independently', () => {
+    const { result } = renderHook(() => useBatteryWarning())
+
+    act(() => native.onBatteryWarningPendingChanged?.({ pending: true }))
+    expect(result.current).toMatchObject({ pending: true, status: 'unknown' })
+
+    act(() =>
+      native.onBatteryOptimizationStatusChanged?.({
+        status: 'restricted' as BatteryOptimizationStatus
+      })
+    )
+    expect(result.current).toMatchObject({
+      pending: true,
+      status: 'restricted'
+    })
+  })
+
+  it('exposes actions that reach native', () => {
+    const { result } = renderHook(() => useBatteryWarning())
+
+    result.current.dismiss()
+    expect(native.dismissBatteryWarning).toHaveBeenCalledOnce()
+
+    result.current.openSettings()
+    expect(native.openBatterySettings).toHaveBeenCalledOnce()
+  })
+
+  it('keeps the action identities stable across updates', () => {
+    const { result } = renderHook(() => useBatteryWarning())
+    const { dismiss, openSettings } = result.current
+
+    act(() => native.onBatteryWarningPendingChanged?.({ pending: true }))
+
+    // They are module-level functions, not closures — a consumer can safely put
+    // them in a dependency array.
+    expect(result.current.dismiss).toBe(dismiss)
+    expect(result.current.openSettings).toBe(openSettings)
+  })
+})

package/src/features/browser.ts

@@ -169,5 +169,5 @@ export function hasSearch(): boolean {
  * ```
  */
 export async function search(query: string): Promise<Track[]> {
-  return nativeBrowser.onSearch(query)
+  return nativeBrowser.search(query)
 }

package/src/features/carConnection.ts

@@ -19,7 +19,7 @@ export function isCarConnected(): boolean {
  * Subscribes to car connection changes (CarPlay on iOS, Android Auto /
  * Android Automotive on Android). Never fires on web.
  * @param callback - Called with the new connection state
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onCarConnectedChanged = NativeUpdatedValue.emitterize<boolean>(
   (cb) => (nativeBrowser.onCarConnectedChanged = cb)

package/src/features/equalizer.ts

@@ -46,7 +46,7 @@ export function setEqualizerLevels(levels: number[]): void {
 /**
  * Subscribes to equalizer settings changes (Android only).
  * @param callback - Called when equalizer settings change
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onEqualizerChanged =
   NativeUpdatedValue.emitterize<EqualizerSettings>(

package/src/features/errors.ts

@@ -134,7 +134,7 @@ export function getPlaybackError(): PlaybackError | undefined {
 /**
  * Subscribes to playback error events.
  * @param callback - Called when a playback error occurs
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onPlaybackError =
   NativeUpdatedValue.emitterize<PlaybackErrorEvent>(
@@ -165,7 +165,7 @@ export function getNavigationError(): NavigationError | undefined {
 /**
  * Subscribes to navigation error events.
  * @param callback - Called when a navigation error occurs
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onNavigationError =
   NativeUpdatedValue.emitterize<NavigationErrorEvent>(
@@ -198,7 +198,7 @@ export function getFormattedNavigationError():
 /**
  * Subscribes to formatted navigation error changes.
  * @param callback - Called when the formatted navigation error changes
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onFormattedNavigationError = NativeUpdatedValue.emitterize<
   FormattedNavigationError | undefined

package/src/features/favorites.ts

@@ -82,7 +82,7 @@ export interface FavoriteChangedEvent {
  * The native side has already updated the track's favorite state and UI.
  *
  * @param callback - Called with the track and its new favorite state
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  *
  * @example
  * ```ts

package/src/features/gate.ts

@@ -120,12 +120,20 @@ nativeBrowser.resolveGate = async (
  * some surfaces (CarPlay) any gate change pops pushed navigation back to root,
  * so a page the user had drilled into is reset to the tab root. Set the gate
  * before the car connects and it'll be there the moment it does.
+ *
+ * @platform ios android
+ * A no-op on web, which has no CarPlay or Android Auto surfaces for the gate to
+ * cover. Nothing is lost: the gate never covered in-app browse UI on any
+ * platform — that stays yours to gate.
  */
 export function setGate(gate: Gate, resolve?: GateResolver): void
 /**
  * Raises the gate with a resolver only (no default chrome).
  * The resolver must return a {@link Gate} or `true` for gated requests;
  * native uses the built-in fallback chrome when `true` and no default is set.
+ *
+ * @platform ios android
+ * A no-op on web — the resolver is never consulted there.
  */
 export function setGate(resolve: GateResolver): void
 export function setGate(a: Gate | GateResolver, b?: GateResolver): void {
@@ -140,6 +148,9 @@ export function setGate(a: Gate | GateResolver, b?: GateResolver): void {
 
 /**
  * Drops the gate — the real content comes back, and the current tab is kept.
+ *
+ * @platform ios android
+ * A no-op on web, where no gate was ever raised.
  */
 export function clearGate(): void {
   resolver = undefined
@@ -148,7 +159,11 @@ export function clearGate(): void {
 
 /**
  * Subscribes to gate events (fired when a request is gated).
- * @returns Cleanup function to unsubscribe.
+ *
+ * @platform ios android
+ * Never fires on web — there are no gated serves to report.
+ *
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onGate = LazyNativeEmitter.emitterize<GateEvent>(
   (cb) => (nativeBrowser.onGate = cb)