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

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

@@ -0,0 +1,80 @@
+///
+/// GridTile.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/NitroHash.hpp>)
+#include <NitroModules/NitroHash.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#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
+
+namespace margelo::nitro::audiobrowser {
+
+  /**
+   * An enum which can be represented as a JavaScript union (GridTile).
+   */
+  enum class GridTile {
+    PLAIN      SWIFT_NAME(plain) = 0,
+    CARD      SWIFT_NAME(card) = 1,
+    CONDENSED      SWIFT_NAME(condensed) = 2,
+  } CLOSED_ENUM;
+
+} // namespace margelo::nitro::audiobrowser
+
+namespace margelo::nitro {
+
+  // C++ GridTile <> JS GridTile (union)
+  template <>
+  struct JSIConverter<margelo::nitro::audiobrowser::GridTile> final {
+    static inline margelo::nitro::audiobrowser::GridTile 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("plain"): return margelo::nitro::audiobrowser::GridTile::PLAIN;
+        case hashString("card"): return margelo::nitro::audiobrowser::GridTile::CARD;
+        case hashString("condensed"): return margelo::nitro::audiobrowser::GridTile::CONDENSED;
+        default: [[unlikely]]
+          throw std::invalid_argument("Cannot convert \"" + unionValue + "\" to enum GridTile - invalid value!");
+      }
+    }
+    static inline jsi::Value toJSI(jsi::Runtime& runtime, margelo::nitro::audiobrowser::GridTile arg) {
+      switch (arg) {
+        case margelo::nitro::audiobrowser::GridTile::PLAIN: return JSIConverter<std::string>::toJSI(runtime, "plain");
+        case margelo::nitro::audiobrowser::GridTile::CARD: return JSIConverter<std::string>::toJSI(runtime, "card");
+        case margelo::nitro::audiobrowser::GridTile::CONDENSED: return JSIConverter<std::string>::toJSI(runtime, "condensed");
+        default: [[unlikely]]
+          throw std::invalid_argument("Cannot convert GridTile to JS - invalid value: "
+                                    + std::to_string(static_cast<int>(arg)) + "!");
+      }
+    }
+    static inline bool canConvert(jsi::Runtime& runtime, const jsi::Value& value) {
+      if (!value.isString()) {
+        return false;
+      }
+      std::string unionValue = JSIConverter<std::string>::fromJSI(runtime, value);
+      switch (hashString(unionValue.c_str(), unionValue.size())) {
+        case hashString("plain"):
+        case hashString("card"):
+        case hashString("condensed"):
+          return true;
+        default:
+          return false;
+      }
+    }
+  };
+
+} // namespace margelo::nitro

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

@@ -0,0 +1,76 @@
+///
+/// ImageShape.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/NitroHash.hpp>)
+#include <NitroModules/NitroHash.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#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
+
+namespace margelo::nitro::audiobrowser {
+
+  /**
+   * An enum which can be represented as a JavaScript union (ImageShape).
+   */
+  enum class ImageShape {
+    CIRCULAR      SWIFT_NAME(circular) = 0,
+    ROUNDED_RECTANGLE      SWIFT_NAME(roundedRectangle) = 1,
+  } CLOSED_ENUM;
+
+} // namespace margelo::nitro::audiobrowser
+
+namespace margelo::nitro {
+
+  // C++ ImageShape <> JS ImageShape (union)
+  template <>
+  struct JSIConverter<margelo::nitro::audiobrowser::ImageShape> final {
+    static inline margelo::nitro::audiobrowser::ImageShape 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("circular"): return margelo::nitro::audiobrowser::ImageShape::CIRCULAR;
+        case hashString("rounded-rectangle"): return margelo::nitro::audiobrowser::ImageShape::ROUNDED_RECTANGLE;
+        default: [[unlikely]]
+          throw std::invalid_argument("Cannot convert \"" + unionValue + "\" to enum ImageShape - invalid value!");
+      }
+    }
+    static inline jsi::Value toJSI(jsi::Runtime& runtime, margelo::nitro::audiobrowser::ImageShape arg) {
+      switch (arg) {
+        case margelo::nitro::audiobrowser::ImageShape::CIRCULAR: return JSIConverter<std::string>::toJSI(runtime, "circular");
+        case margelo::nitro::audiobrowser::ImageShape::ROUNDED_RECTANGLE: return JSIConverter<std::string>::toJSI(runtime, "rounded-rectangle");
+        default: [[unlikely]]
+          throw std::invalid_argument("Cannot convert ImageShape to JS - invalid value: "
+                                    + std::to_string(static_cast<int>(arg)) + "!");
+      }
+    }
+    static inline bool canConvert(jsi::Runtime& runtime, const jsi::Value& value) {
+      if (!value.isString()) {
+        return false;
+      }
+      std::string unionValue = JSIConverter<std::string>::fromJSI(runtime, value);
+      switch (hashString(unionValue.c_str(), unionValue.size())) {
+        case hashString("circular"):
+        case hashString("rounded-rectangle"):
+          return true;
+        default:
+          return false;
+      }
+    }
+  };
+
+} // namespace margelo::nitro

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

@@ -28,14 +28,24 @@
 #error NitroModules cannot be found! Are you sure you installed NitroModules properly?
 #endif
 
+// Forward declaration of `GridTile` to properly resolve imports.
+namespace margelo::nitro::audiobrowser { enum class GridTile; }
 // Forward declaration of `StyleDisplay` to properly resolve imports.
 namespace margelo::nitro::audiobrowser { enum class StyleDisplay; }
 // Forward declaration of `ArtworkRendering` to properly resolve imports.
 namespace margelo::nitro::audiobrowser { enum class ArtworkRendering; }
+// Forward declaration of `ImageShape` to properly resolve imports.
+namespace margelo::nitro::audiobrowser { enum class ImageShape; }
+// Forward declaration of `CardImage` to properly resolve imports.
+namespace margelo::nitro::audiobrowser { enum class CardImage; }
 
 #include <optional>
+#include "GridTile.hpp"
 #include "StyleDisplay.hpp"
 #include "ArtworkRendering.hpp"
+#include "ImageShape.hpp"
+#include <string>
+#include "CardImage.hpp"
 
 namespace margelo::nitro::audiobrowser {
 
@@ -45,12 +55,17 @@ namespace margelo::nitro::audiobrowser {
   struct SectionStyle final {
   public:
     std::optional<bool> gridWrap     SWIFT_PRIVATE;
+    std::optional<GridTile> gridTile     SWIFT_PRIVATE;
     std::optional<StyleDisplay> display     SWIFT_PRIVATE;
     std::optional<ArtworkRendering> artworkRendering     SWIFT_PRIVATE;
+    std::optional<ImageShape> imageShape     SWIFT_PRIVATE;
+    std::optional<std::string> accessorySymbol     SWIFT_PRIVATE;
+    std::optional<std::string> cardTint     SWIFT_PRIVATE;
+    std::optional<CardImage> cardImage     SWIFT_PRIVATE;
 
   public:
     SectionStyle() = default;
-    explicit SectionStyle(std::optional<bool> gridWrap, std::optional<StyleDisplay> display, std::optional<ArtworkRendering> artworkRendering): gridWrap(gridWrap), display(display), artworkRendering(artworkRendering) {}
+    explicit SectionStyle(std::optional<bool> gridWrap, std::optional<GridTile> gridTile, std::optional<StyleDisplay> display, std::optional<ArtworkRendering> artworkRendering, std::optional<ImageShape> imageShape, std::optional<std::string> accessorySymbol, std::optional<std::string> cardTint, std::optional<CardImage> cardImage): gridWrap(gridWrap), gridTile(gridTile), display(display), artworkRendering(artworkRendering), imageShape(imageShape), accessorySymbol(accessorySymbol), cardTint(cardTint), cardImage(cardImage) {}
 
   public:
     friend bool operator==(const SectionStyle& lhs, const SectionStyle& rhs) = default;
@@ -67,15 +82,25 @@ namespace margelo::nitro {
       jsi::Object obj = arg.asObject(runtime);
       return margelo::nitro::audiobrowser::SectionStyle(
         JSIConverter<std::optional<bool>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "gridWrap"))),
+        JSIConverter<std::optional<margelo::nitro::audiobrowser::GridTile>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "gridTile"))),
         JSIConverter<std::optional<margelo::nitro::audiobrowser::StyleDisplay>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "display"))),
-        JSIConverter<std::optional<margelo::nitro::audiobrowser::ArtworkRendering>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "artworkRendering")))
+        JSIConverter<std::optional<margelo::nitro::audiobrowser::ArtworkRendering>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "artworkRendering"))),
+        JSIConverter<std::optional<margelo::nitro::audiobrowser::ImageShape>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "imageShape"))),
+        JSIConverter<std::optional<std::string>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "accessorySymbol"))),
+        JSIConverter<std::optional<std::string>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "cardTint"))),
+        JSIConverter<std::optional<margelo::nitro::audiobrowser::CardImage>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "cardImage")))
       );
     }
     static inline jsi::Value toJSI(jsi::Runtime& runtime, const margelo::nitro::audiobrowser::SectionStyle& arg) {
       jsi::Object obj(runtime);
       obj.setProperty(runtime, PropNameIDCache::get(runtime, "gridWrap"), JSIConverter<std::optional<bool>>::toJSI(runtime, arg.gridWrap));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "gridTile"), JSIConverter<std::optional<margelo::nitro::audiobrowser::GridTile>>::toJSI(runtime, arg.gridTile));
       obj.setProperty(runtime, PropNameIDCache::get(runtime, "display"), JSIConverter<std::optional<margelo::nitro::audiobrowser::StyleDisplay>>::toJSI(runtime, arg.display));
       obj.setProperty(runtime, PropNameIDCache::get(runtime, "artworkRendering"), JSIConverter<std::optional<margelo::nitro::audiobrowser::ArtworkRendering>>::toJSI(runtime, arg.artworkRendering));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "imageShape"), JSIConverter<std::optional<margelo::nitro::audiobrowser::ImageShape>>::toJSI(runtime, arg.imageShape));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "accessorySymbol"), JSIConverter<std::optional<std::string>>::toJSI(runtime, arg.accessorySymbol));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "cardTint"), JSIConverter<std::optional<std::string>>::toJSI(runtime, arg.cardTint));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "cardImage"), JSIConverter<std::optional<margelo::nitro::audiobrowser::CardImage>>::toJSI(runtime, arg.cardImage));
       return obj;
     }
     static inline bool canConvert(jsi::Runtime& runtime, const jsi::Value& value) {
@@ -87,8 +112,13 @@ namespace margelo::nitro {
         return false;
       }
       if (!JSIConverter<std::optional<bool>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "gridWrap")))) return false;
+      if (!JSIConverter<std::optional<margelo::nitro::audiobrowser::GridTile>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "gridTile")))) return false;
       if (!JSIConverter<std::optional<margelo::nitro::audiobrowser::StyleDisplay>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "display")))) return false;
       if (!JSIConverter<std::optional<margelo::nitro::audiobrowser::ArtworkRendering>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "artworkRendering")))) return false;
+      if (!JSIConverter<std::optional<margelo::nitro::audiobrowser::ImageShape>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "imageShape")))) return false;
+      if (!JSIConverter<std::optional<std::string>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "accessorySymbol")))) return false;
+      if (!JSIConverter<std::optional<std::string>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "cardTint")))) return false;
+      if (!JSIConverter<std::optional<margelo::nitro::audiobrowser::CardImage>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "cardImage")))) return false;
       return true;
     }
   };

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

@@ -32,10 +32,17 @@
 namespace margelo::nitro::audiobrowser { enum class StyleDisplay; }
 // Forward declaration of `ArtworkRendering` to properly resolve imports.
 namespace margelo::nitro::audiobrowser { enum class ArtworkRendering; }
+// Forward declaration of `ImageShape` to properly resolve imports.
+namespace margelo::nitro::audiobrowser { enum class ImageShape; }
+// Forward declaration of `CardImage` to properly resolve imports.
+namespace margelo::nitro::audiobrowser { enum class CardImage; }
 
 #include "StyleDisplay.hpp"
 #include <optional>
 #include "ArtworkRendering.hpp"
+#include "ImageShape.hpp"
+#include <string>
+#include "CardImage.hpp"
 
 namespace margelo::nitro::audiobrowser {
 
@@ -46,10 +53,14 @@ namespace margelo::nitro::audiobrowser {
   public:
     std::optional<StyleDisplay> display     SWIFT_PRIVATE;
     std::optional<ArtworkRendering> artworkRendering     SWIFT_PRIVATE;
+    std::optional<ImageShape> imageShape     SWIFT_PRIVATE;
+    std::optional<std::string> accessorySymbol     SWIFT_PRIVATE;
+    std::optional<std::string> cardTint     SWIFT_PRIVATE;
+    std::optional<CardImage> cardImage     SWIFT_PRIVATE;
 
   public:
     TrackStyle() = default;
-    explicit TrackStyle(std::optional<StyleDisplay> display, std::optional<ArtworkRendering> artworkRendering): display(display), artworkRendering(artworkRendering) {}
+    explicit TrackStyle(std::optional<StyleDisplay> display, std::optional<ArtworkRendering> artworkRendering, std::optional<ImageShape> imageShape, std::optional<std::string> accessorySymbol, std::optional<std::string> cardTint, std::optional<CardImage> cardImage): display(display), artworkRendering(artworkRendering), imageShape(imageShape), accessorySymbol(accessorySymbol), cardTint(cardTint), cardImage(cardImage) {}
 
   public:
     friend bool operator==(const TrackStyle& lhs, const TrackStyle& rhs) = default;
@@ -66,13 +77,21 @@ namespace margelo::nitro {
       jsi::Object obj = arg.asObject(runtime);
       return margelo::nitro::audiobrowser::TrackStyle(
         JSIConverter<std::optional<margelo::nitro::audiobrowser::StyleDisplay>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "display"))),
-        JSIConverter<std::optional<margelo::nitro::audiobrowser::ArtworkRendering>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "artworkRendering")))
+        JSIConverter<std::optional<margelo::nitro::audiobrowser::ArtworkRendering>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "artworkRendering"))),
+        JSIConverter<std::optional<margelo::nitro::audiobrowser::ImageShape>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "imageShape"))),
+        JSIConverter<std::optional<std::string>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "accessorySymbol"))),
+        JSIConverter<std::optional<std::string>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "cardTint"))),
+        JSIConverter<std::optional<margelo::nitro::audiobrowser::CardImage>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "cardImage")))
       );
     }
     static inline jsi::Value toJSI(jsi::Runtime& runtime, const margelo::nitro::audiobrowser::TrackStyle& arg) {
       jsi::Object obj(runtime);
       obj.setProperty(runtime, PropNameIDCache::get(runtime, "display"), JSIConverter<std::optional<margelo::nitro::audiobrowser::StyleDisplay>>::toJSI(runtime, arg.display));
       obj.setProperty(runtime, PropNameIDCache::get(runtime, "artworkRendering"), JSIConverter<std::optional<margelo::nitro::audiobrowser::ArtworkRendering>>::toJSI(runtime, arg.artworkRendering));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "imageShape"), JSIConverter<std::optional<margelo::nitro::audiobrowser::ImageShape>>::toJSI(runtime, arg.imageShape));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "accessorySymbol"), JSIConverter<std::optional<std::string>>::toJSI(runtime, arg.accessorySymbol));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "cardTint"), JSIConverter<std::optional<std::string>>::toJSI(runtime, arg.cardTint));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "cardImage"), JSIConverter<std::optional<margelo::nitro::audiobrowser::CardImage>>::toJSI(runtime, arg.cardImage));
       return obj;
     }
     static inline bool canConvert(jsi::Runtime& runtime, const jsi::Value& value) {
@@ -85,6 +104,10 @@ namespace margelo::nitro {
       }
       if (!JSIConverter<std::optional<margelo::nitro::audiobrowser::StyleDisplay>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "display")))) return false;
       if (!JSIConverter<std::optional<margelo::nitro::audiobrowser::ArtworkRendering>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "artworkRendering")))) return false;
+      if (!JSIConverter<std::optional<margelo::nitro::audiobrowser::ImageShape>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "imageShape")))) return false;
+      if (!JSIConverter<std::optional<std::string>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "accessorySymbol")))) return false;
+      if (!JSIConverter<std::optional<std::string>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "cardTint")))) return false;
+      if (!JSIConverter<std::optional<margelo::nitro::audiobrowser::CardImage>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "cardImage")))) return false;
       return true;
     }
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-audio-browser",
-  "version": "0.2.0-next.12",
+  "version": "0.2.0-next.13",
   "description": "react-native-audio-browser is a react native package built with Nitro",
   "keywords": [
     "react-native",
@@ -31,6 +31,7 @@
     "ios/**/*.mm",
     "ios/**/*.cpp",
     "ios/**/*.swift",
+    "website/guide",
     "*.podspec",
     "README.md"
   ],
@@ -46,23 +47,27 @@
   "scripts": {
     "android:format": "yarn workspace example-native android:format",
     "android:format:check": "yarn workspace example-native android:format:check",
+    "android:gradle-stop": "yarn workspace example-native android:gradle-stop",
     "android:ide": "yarn workspace example-native android:ide",
     "android:logs": "react-native log-android",
     "android:test": "yarn workspace example-native android:test",
+    "android:types": "yarn workspace example-native android:types",
     "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 && yarn hooks:install",
     "hooks:install": "git config core.hooksPath .githooks || exit 0",
     "example": "yarn workspace example-native",
+    "ci:android": "yarn android:format:check && yarn android:types && yarn android:test",
     "ci:format": "oxfmt --check --ignore-path .gitignore --ignore-path .oxfmtignore .",
     "ci:format:ios": "swiftformat --lint ios",
+    "ci:ios": "yarn ci:format:ios && yarn ios:test",
     "ci:lint": "oxlint --type-aware src",
     "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",
-    "ios:test": "swift test",
+    "ios:test": "swift test --disable-sandbox",
     "lint": "oxlint --fix",
     "release": "semantic-release",
     "test": "vitest run",

package/src/features/playback/progress.ts

@@ -118,7 +118,8 @@ export function usePolledProgress(updateInterval = 1000): Progress {
     }
 
     const stop = () => {
-      clearTimeout(timer)
+      // Guarded: React Native types clearTimeout(handle: number) — no undefined.
+      if (timer !== undefined) clearTimeout(timer)
       timer = undefined
       unsubscribeState?.()
       unsubscribeState = undefined

package/src/features/playback/rate.ts

@@ -14,8 +14,15 @@ export function getRate(): number {
 
 /**
  * Sets the playback rate.
+ *
+ * The rate is a speed multiplier, not a transport control — it is independent
+ * of play/pause, and setting it while paused never starts playback. Use
+ * {@link play} / {@link pause} for that.
+ *
  * @param rate - The playback rate to change to, where 0.5 would be half speed,
- * 1 would be regular speed, 2 would be double speed etc.
+ * 1 would be regular speed, 2 would be double speed etc. Must be greater than
+ * zero; platforms disagree on what a non-positive rate does (iOS ignores it,
+ * Android throws, web stalls the element), so treat it as unsupported.
  */
 export function setRate(rate: number): void {
   nativeBrowser.setRate(rate)

package/src/style-resolution.test.ts

@@ -3,7 +3,12 @@ import { join } from 'node:path'
 import { describe, expect, it } from 'vitest'
 
 /**
- * Inheritance-completeness guard for the style declaration block (ADR 0011).
+ * 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
@@ -137,3 +142,69 @@ for (const resolver of RESOLVERS) {
     })
   })
 }
+
+/**
+ * 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/types/browser-nodes.ts

@@ -25,6 +25,50 @@ export type StyleDisplay = 'list' | 'grid'
  */
 export type ArtworkRendering = 'original' | 'stencil'
 
+/**
+ * The shape a grid tile's artwork is cropped to.
+ *
+ * - `'rounded-rectangle'` (default) — the standard tile crop.
+ * - `'circular'` — the standard presentation for *people* (artists, hosts,
+ *   DJs). Shape encodes the kind of item, so mixed grids legitimately
+ *   render circular artists next to rounded albums.
+ *
+ * Named after Apple's `imageShape` parameter (a platform passthrough), and
+ * deliberately without a grid prefix: every tile presentation that takes a
+ * shape reads the same property.
+ */
+export type ImageShape = 'circular' | 'rounded-rectangle'
+
+/**
+ * The kind of tile a grid renders.
+ *
+ * - `'plain'` (default) — artwork tiles with a title.
+ * - `'card'` — a larger card with title/subtitle and a
+ *   {@link TrackStyle.cardTint} color; its image mode is
+ *   {@link TrackStyle.cardImage}. Cards have no shape.
+ * - `'condensed'` — a denser cell carrying title + subtitle; takes
+ *   {@link TrackStyle.imageShape} and {@link TrackStyle.accessorySymbol}
+ *   like a plain tile.
+ *
+ * Element families are mutually exclusive within a container, so this is
+ * a container property — hence the enum, and the `grid` prefix.
+ */
+export type GridTile = 'plain' | 'card' | 'condensed'
+
+/**
+ * How a card tile uses its image.
+ *
+ * - `'normal'` (default) — image above the labels;
+ *   {@link TrackStyle.cardTint} colors a gradient behind the labels.
+ * - `'background'` — the image fills the card full-height with the labels
+ *   overlaid; `cardTint` becomes the color behind them. Selects the larger
+ *   artwork target size.
+ *
+ * An enum rather than a boolean: it names the card's image mode and
+ * leaves room for future modes.
+ */
+export type CardImage = 'normal' | 'background'
+
 /**
  * The style declaration block a {@link Track} may carry: *inherited item
  * properties* (resolved `track ?? section ?? page ?? default`, per
@@ -82,6 +126,58 @@ export interface TrackStyle {
    * @platform carplay
    */
   artworkRendering?: ArtworkRendering
+
+  /**
+   * Inherited (`track ?? section ?? page`): the shape a grid tile's
+   * artwork is cropped to — `'circular'` for people, the default
+   * `'rounded-rectangle'` for everything else. Shape follows the item
+   * wherever it travels: a circular artist stays circular in whatever
+   * grid renders it next. Inert where the presentation has no shape
+   * (list rows, pre-26 CarPlay, Android Auto).
+   *
+   * @default 'rounded-rectangle'
+   *
+   * @platform carplay
+   */
+  imageShape?: ImageShape
+
+  /**
+   * Inherited (`track ?? section ?? page`): an SF Symbol name drawn as
+   * the item's accessory wherever the current presentation supports one —
+   * the trailing edge of a list row, leading the title on an iOS 26 grid
+   * tile (placement is the platform's choice per surface). A resolved
+   * symbol replaces the derived accessory (the disclosure chevron a
+   * browsable row gets); `'none'` clears an inherited value, restoring
+   * the derived behavior — inheritance has no other escape, and no SF
+   * Symbol is named `none`, so the sentinel is collision-free. Inert off
+   * CarPlay.
+   *
+   * @platform carplay
+   */
+  accessorySymbol?: string
+
+  /**
+   * Inherited (`track ?? section ?? page`): the card treatment's tint
+   * color (hex, e.g. `'#1e3a8a'`) — a gradient behind the labels, or the
+   * color behind them when {@link TrackStyle.cardImage} is
+   * `'background'`. Card-prefixed: inert unless the container renders
+   * `gridTile: 'card'`.
+   *
+   * @platform carplay
+   */
+  cardTint?: string
+
+  /**
+   * Inherited (`track ?? section ?? page`): how a card tile uses its
+   * image — see {@link CardImage}. Uniform via the section value,
+   * mixable per card. Inert unless the container renders
+   * `gridTile: 'card'`.
+   *
+   * @default 'normal'
+   *
+   * @platform carplay
+   */
+  cardImage?: CardImage
 }
 
 /**
@@ -113,6 +209,20 @@ export interface SectionStyle extends TrackStyle {
    * @see https://developer.apple.com/documentation/carplay/cplistimagerowitem
    */
   gridWrap?: boolean
+
+  /**
+   * The kind of tile this container's grid renders — see
+   * {@link GridTile}. A container property (element families are
+   * container-homogeneous), resolved by scope override
+   * (`section ?? page`), never per item. Inert unless
+   * {@link TrackStyle.display} is `'grid'`, and on CarPlay before
+   * iOS 26 (where the treatment drops and the layout survives).
+   *
+   * @default 'plain'
+   *
+   * @platform carplay
+   */
+  gridTile?: GridTile
 }
 
 /**
@@ -200,8 +310,8 @@ export interface Section {
   /**
    * Navigation target for the section header / "view all" surface. A
    * tile section's header tap (CarPlay) and appended "view all" link
-   * (Android Auto) navigate here. Absent = a pure preview; the header is
-   * not tappable.
+   * (Android Auto) navigate here. Absent = a self-contained section:
+   * the header is a plain label, not a link.
    */
   path?: string
   /** The section's tracks. */

package/src/web/TrackPlayer/QueueManager.test.ts

@@ -160,6 +160,35 @@ describe('QueueManager', () => {
       expect(q.nextIndex()).toBeUndefined()
     })
 
+    // Filling a queue that had no current track: the order is shuffled with
+    // nothing to lead it, so the track that becomes current can land anywhere —
+    // last included, which reads as end-of-queue from the very first track.
+    it('leads the order with the start track when setTracks fills an empty queue', () => {
+      const fresh = new QueueManager()
+      fresh.setShuffleEnabled(true) // shuffle already on, queue still empty
+      fresh.setTracks(tracks(4))
+      fresh.currentIndex = 2 // the start index
+
+      // identity order [0,1,2,3] re-pinned on 2 → [2,1,0,3]
+      expect(fresh.previousIndex()).toBeUndefined()
+      expect(fresh.nextIndex()).toBe(1)
+    })
+
+    it('leads the order with the start track when insert fills an empty queue', () => {
+      const fresh = new QueueManager()
+      fresh.setShuffleEnabled(true)
+      const random = vi.spyOn(Math, 'random').mockReturnValue(0.999)
+      try {
+        fresh.insert(tracks(4)) // slotted in at the order's end → [0,1,2,3]
+      } finally {
+        random.mockRestore()
+      }
+      fresh.currentIndex = 3 // would sit LAST in the order without the re-pin
+
+      expect(fresh.nextIndex()).toBe(1)
+      expect(fresh.previousIndex()).toBeUndefined()
+    })
+
     it('keeps every track at its shuffle position across a move', () => {
       q.currentIndex = 1
       q.move(1, 3) // tracks [s0,s2,s3,s1]; order remapped to [0,3,1,2]