rn-system-bar 3.1.8 → 3.2.0

package/README.md

@@ -1,6 +1,6 @@
 # rn-system-bar v3
 
-> Control Android & iOS system bars, brightness, volume, orientation and screen flags from React Native.
+> Control Android & iOS system bars, brightness, volume, orientation, theme, and screen casting from React Native.
 
 Supports **React Native CLI · Expo Dev Client · TypeScript · New Architecture (TurboModules)**
 
@@ -14,13 +14,13 @@ npm install rn-system-bar
 yarn add rn-system-bar
 ```
 
-**iOS** (after install):
+**iOS** — run after install:
 
 ```bash
 cd ios && pod install
 ```
 
-**Android**: Auto-linked. No manual steps required.
+**Android** — auto-linked, no manual steps required.
 
 ---
 
@@ -32,12 +32,17 @@ React Native App
       ▼
 rn-system-bar  (TypeScript API + Platform guard)
       │
-      ├─ Android ──► SystemBarModule.kt ──► Android SDK APIs
-      │                                      ├ WindowInsetsController (API 30+)
-      │                                      ├ AudioManager
-      │                                      └ ActivityInfo
+      ├─ Android ──► SystemBarModule.kt
+      │               ├ WindowInsetsController (API 30+)
+      │               ├ AudioManager
+      │               ├ ActivityInfo
+      │               ├ DisplayManager        ← system screencast
+      │               └ MediaRouter           ← app-only cast
       │
-      └─ iOS ──────► SystemBarModule.swift ──► UIKit / AVFoundation
+      └─ iOS ──────► SystemBarModule.swift
+                      ├ UIKit / AVFoundation
+                      ├ UIScreen.screens      ← system screencast
+                      └ (AirPlay = system-managed, no public API)
 ```
 
 ---
@@ -46,263 +51,747 @@ rn-system-bar  (TypeScript API + Platform guard)
 
 ```
 rn-system-bar/
-├ package.json
 ├ index.ts
 ├ rn-system-bar.podspec
 │
 ├ src/
-│  ├ SystemBar.ts          ← JS/TS API (Platform-guarded)
-│  └ types.ts              ← All TypeScript types
+│  ├ SystemBar.ts       ← all imperative JS/TS APIs
+│  ├ types.ts           ← all TypeScript types
+│  ├ useSystemBar.ts    ← React hooks
+│  └ useTheme.ts        ← theme singleton + useTheme hook
 │
 ├ specs/
-│  └ NativeSystemBar.ts    ← TurboModule spec (New Architecture)
+│  └ NativeSystemBar.ts ← TurboModule spec (New Architecture)
 │
 ├ android/
-│  ├ build.gradle
 │  └ src/main/java/com/systembar/
-│     ├ SystemBarModule.kt ← Full Android native module
+│     ├ SystemBarModule.kt
 │     └ SystemBarPackage.kt
 │
 └ ios/
-   ├ SystemBarModule.swift  ← iOS native module
-   └ SystemBarModule.m      ← ObjC bridge header
+   ├ SystemBarModule.swift
+   └ SystemBarModule.m
 ```
 
 ---
 
-## 🚀 API Reference
+## 🚀 Quick Start
 
-### Navigation Bar — `Android only`
+```tsx
+import React, { useEffect } from "react";
+import { View, Button } from "react-native";
+import * as SystemBar from "rn-system-bar";
+import { useSystemBar, useTheme } from "rn-system-bar";
+
+export default function App() {
+  const { isDark } = useTheme();
+
+  useSystemBar({
+    navigationBarColor: isDark ? "#000000" : "#ffffff",
+    navigationBarButtonStyle: isDark ? "light" : "dark",
+    statusBarStyle: isDark ? "light" : "dark",
+    keepScreenOn: true,
+  });
 
-> All `NavigationBar` APIs are automatically guarded with `Platform.OS === "android"`.
-> Calling them on iOS prints a dev warning and is a no-op — no crash.
+  return (
+    <View>
+      <Button title="Immersive" onPress={() => SystemBar.immersiveMode(true)} />
+      <Button
+        title="Landscape"
+        onPress={() => SystemBar.setOrientation("landscape")}
+      />
+    </View>
+  );
+}
+```
+
+---
+
+## 🎨 Theme
+
+### `useTheme()`
+
+Reads the OS colour scheme and lets you override it manually. All `useTheme()` consumers across the app share one singleton — changing the mode in one place updates every subscriber instantly.
+
+```tsx
+import { useTheme } from "rn-system-bar";
+
+const { isDark, mode, setMode } = useTheme();
+
+// isDark  → true | false  (resolved, always concrete)
+// mode    → "system" | "dark" | "light"
+// setMode → (mode: ThemeMode) => void
+
+// Follow OS (default)
+setMode("system");
+
+// Force dark
+setMode("dark");
+
+// Force light
+setMode("light");
+```
+
+### `setGlobalThemeMode(mode)` — imperative, outside components
 
 ```ts
-import {
-  setNavigationBarColor,
-  setNavigationBarVisibility,
-  setNavigationBarButtonStyle,
-  setNavigationBarStyle,
-  setNavigationBarBehavior,
-} from "rn-system-bar";
+import { setGlobalThemeMode } from "rn-system-bar";
 
-setNavigationBarColor("#1a1a2e"); // hex color
-setNavigationBarVisibility("hidden"); // "visible" | "hidden"
-setNavigationBarButtonStyle("light"); // "light" | "dark"
-setNavigationBarStyle("dark"); // "auto" | "inverted" | "light" | "dark"
-setNavigationBarBehavior("overlay-swipe"); // "overlay-swipe" | "inset-swipe" | "inset-touch"
+// Call from anywhere — navigation handlers, async callbacks, etc.
+setGlobalThemeMode("dark");
+```
+
+### `useThemeSystemBar(config)` — theme + system bar in one hook
+
+Automatically re-applies the correct config whenever the theme changes (OS switch or manual `setMode`). Returns the full `ThemeState` so you can also read `isDark` / `mode` / `setMode`.
+
+```tsx
+import { useThemeSystemBar } from "rn-system-bar";
+
+const { isDark, mode, setMode } = useThemeSystemBar({
+  // Applied when dark
+  dark: {
+    navigationBarColor:       "#000000",
+    navigationBarButtonStyle: "light",
+    statusBarColor:           "#000000",
+    statusBarStyle:           "light",
+  },
+  // Applied when light
+  light: {
+    navigationBarColor:       "#ffffff",
+    navigationBarButtonStyle: "dark",
+    statusBarColor:           "#ffffff",
+    statusBarStyle:           "dark",
+  },
+  // Always applied on both themes (theme-specific values win)
+  base: {
+    keepScreenOn: true,
+    orientation:  "portrait",
+  },
+});
+
+// Manual toggle buttons
+<Button title="Dark"   onPress={() => setMode("dark")}   />
+<Button title="Light"  onPress={() => setMode("light")}  />
+<Button title="System" onPress={() => setMode("system")} />
 ```
 
 ---
 
-### Status Bar
+## 🔵 Navigation Bar — `Android only`
+
+> All navigation bar APIs are automatically guarded with `Platform.OS === "android"`.
+> Calling them on iOS prints a dev-only warning and is a no-op — no crash.
+
+### `setNavigationBarColor(color)`
+
+| Value           | Result                                                        |
+| --------------- | ------------------------------------------------------------- |
+| `"#rrggbb"`     | Solid colour                                                  |
+| `"transparent"` | Fully transparent — content draws edge-to-edge behind the bar |
+| `"translucent"` | Semi-transparent system scrim — frosted-glass effect          |
 
 ```ts
-import {
-  setStatusBarColor,
-  setStatusBarStyle,
-  setStatusBarVisibility,
-} from "rn-system-bar";
+import { setNavigationBarColor } from "rn-system-bar";
+
+setNavigationBarColor("#1a1a2e"); // solid hex
+setNavigationBarColor("transparent"); // edge-to-edge / glass
+setNavigationBarColor("translucent"); // frosted glass
+```
+
+### `setNavigationBarVisibility(mode)`
+
+```ts
+import { setNavigationBarVisibility } from "rn-system-bar";
+
+setNavigationBarVisibility("hidden"); // hide nav bar
+setNavigationBarVisibility("visible"); // show nav bar
+```
+
+### `setNavigationBarButtonStyle(style)`
+
+Controls the icon colour of the navigation bar buttons (back, home, recents).
+
+```ts
+import { setNavigationBarButtonStyle } from "rn-system-bar";
+
+setNavigationBarButtonStyle("light"); // white icons — use on dark backgrounds
+setNavigationBarButtonStyle("dark"); // dark icons  — use on light backgrounds
+```
+
+### `setNavigationBarStyle(style)`
+
+Higher-level wrapper that maps to button style — `"dark"` / `"auto"` → dark icons; `"light"` / `"inverted"` → light icons.
 
-setStatusBarColor("#000000"); // Android only (iOS ignores bg color)
-setStatusBarStyle("light"); // "light" | "dark"  — works on both platforms
-setStatusBarVisibility(false); // hide status bar
+```ts
+import { setNavigationBarStyle } from "rn-system-bar";
+
+setNavigationBarStyle("dark"); // dark icons
+setNavigationBarStyle("light"); // light icons
+setNavigationBarStyle("auto"); // follows system
+setNavigationBarStyle("inverted"); // opposite of system
+```
+
+### `setNavigationBarBehavior(behavior)`
+
+Controls how hidden bars re-appear after a swipe gesture.
+
+```ts
+import { setNavigationBarBehavior } from "rn-system-bar";
+
+setNavigationBarBehavior("overlay-swipe"); // bar appears temporarily on swipe (API 30+)
+setNavigationBarBehavior("inset-swipe"); // bar pushes content on swipe
+setNavigationBarBehavior("inset-touch"); // bar pushes content on touch
 ```
 
 ---
 
-### Brightness
+## 🔴 Status Bar
+
+### `setStatusBarColor(color)` — Android only
+
+| Value           | Result                                             |
+| --------------- | -------------------------------------------------- |
+| `"#rrggbb"`     | Solid colour                                       |
+| `"transparent"` | Fully transparent — content draws under status bar |
+| `"translucent"` | Semi-transparent system scrim                      |
 
 ```ts
-import { setBrightness, getBrightness } from "rn-system-bar";
+import { setStatusBarColor } from "rn-system-bar";
+
+setStatusBarColor("#000000"); // solid black
+setStatusBarColor("transparent"); // content visible behind status bar
+setStatusBarColor("translucent"); // frosted glass
+```
 
-setBrightness(0.8); // 0.0 – 1.0
+### `setStatusBarStyle(style)` — Android + iOS
 
-const level = await getBrightness(); // returns 0.0 – 1.0
+```ts
+import { setStatusBarStyle } from "rn-system-bar";
+
+setStatusBarStyle("light"); // white text/icons — use on dark backgrounds
+setStatusBarStyle("dark"); // dark text/icons  — use on light backgrounds
+```
+
+### `setStatusBarVisibility(visible)` — Android + iOS
+
+```ts
+import { setStatusBarVisibility } from "rn-system-bar";
+
+setStatusBarVisibility(false); // hide status bar (fullscreen)
+setStatusBarVisibility(true); // show status bar
 ```
 
 ---
 
-### Volume
+## ☀️ Brightness
+
+### `setBrightness(level)`
 
 ```ts
-import { setVolume, getVolume, setVolumeHUDVisible } from "rn-system-bar";
+import { setBrightness } from "rn-system-bar";
 
-setVolumeHUDVisible(false); // hide the system volume popup (Android)
-setVolume(0.5, "music"); // 0.0 – 1.0, stream: "music" | "ring" | "notification" | "alarm" | "system"
+setBrightness(1.0); // maximum brightness
+setBrightness(0.5); // 50%
+setBrightness(0.01); // minimum (0.0 is clamped to 0.01)
+```
+
+### `getBrightness()` → `Promise<number>`
+
+```ts
+import { getBrightness } from "rn-system-bar";
 
-const vol = await getVolume("music"); // returns 0.0 – 1.0
+const level = await getBrightness(); // 0.0 – 1.0
+console.log("Brightness:", level);
 ```
 
-> **iOS note**: `setVolume()` is a no-op on iOS (Apple restriction). `getVolume()` works.
+### `onBrightnessChange(callback)` → unsubscribe
+
+Fires on every brightness change. On Android, polls every 500 ms since `Settings.System` doesn't broadcast changes.
+
+```ts
+import { onBrightnessChange } from "rn-system-bar";
+
+const unsub = onBrightnessChange((brightness) => {
+  console.log("New brightness:", brightness); // 0.0 – 1.0
+});
+
+// Stop listening
+unsub();
+```
 
 ---
 
-### Screen
+## 🔊 Volume
+
+### `setVolume(level, stream?)`
+
+> **iOS note:** `setVolume()` is a no-op on iOS due to Apple restrictions. `getVolume()` works normally.
+
+```ts
+import { setVolume } from "rn-system-bar";
+
+setVolume(0.8); // 80% — defaults to "music" stream
+setVolume(0.5, "ring"); // 50% ring volume
+setVolume(1.0, "alarm"); // max alarm volume
+setVolume(0.3, "notification");
+setVolume(0.6, "system");
+```
+
+| Stream           | Description             |
+| ---------------- | ----------------------- |
+| `"music"`        | Media / music (default) |
+| `"ring"`         | Ringtone                |
+| `"notification"` | Notifications           |
+| `"alarm"`        | Alarms                  |
+| `"system"`       | UI sounds               |
+
+### `getVolume(stream?)` → `Promise<number>`
+
+```ts
+import { getVolume } from "rn-system-bar";
+
+const vol = await getVolume("music"); // 0.0 – 1.0
+```
+
+### `setVolumeHUDVisible(visible)` — Android only
+
+Show or hide the system volume popup when `setVolume` is called.
+
+```ts
+import { setVolumeHUDVisible } from "rn-system-bar";
+
+setVolumeHUDVisible(false); // silent volume change — no popup
+setVolumeHUDVisible(true); // show the popup (default behaviour)
+```
+
+### `onVolumeChange(callback)` → unsubscribe
+
+Fires when the volume changes via hardware buttons or another app.
 
 ```ts
-import { keepScreenOn, immersiveMode } from "rn-system-bar";
+import { onVolumeChange } from "rn-system-bar";
+
+const unsub = onVolumeChange((volume, stream) => {
+  console.log(`${stream} volume: ${volume}`); // e.g. "music volume: 0.7"
+});
+
+// Stop listening
+unsub();
+```
+
+---
+
+## 📺 Screen
+
+### `keepScreenOn(enable)` — Android + iOS
+
+Prevents the screen from sleeping while the app is in the foreground.
+
+```ts
+import { keepScreenOn } from "rn-system-bar";
 
 keepScreenOn(true); // prevent sleep
-immersiveMode(true); // hide status + nav bar (Android only)
+keepScreenOn(false); // allow sleep (default)
+```
+
+### `immersiveMode(enable)` — Android only
+
+Hides both status bar and navigation bar. Bars temporarily reappear on swipe.
+
+```ts
+import { immersiveMode } from "rn-system-bar";
+
+immersiveMode(true); // full immersive — both bars hidden
+immersiveMode(false); // restore both bars
+```
+
+### `setSecureScreen(enable)` — Android only
+
+Prevents the screen from being captured via screenshots or screen recording. Applies `FLAG_SECURE` to the window.
+
+```ts
+import { setSecureScreen } from "rn-system-bar";
+
+setSecureScreen(true); // block screenshots and screen recording
+setSecureScreen(false); // allow captures (default)
 ```
 
 ---
 
-### Orientation
+## 🔄 Orientation
+
+### `setOrientation(mode)` — Android + iOS
 
 ```ts
 import { setOrientation } from "rn-system-bar";
 
 setOrientation("portrait"); // lock portrait
-setOrientation("landscape"); // lock landscape
-setOrientation("landscape-left"); // specific side
-setOrientation("landscape-right");
-setOrientation("auto"); // unlock — sensor-driven
+setOrientation("landscape"); // lock landscape (either side)
+setOrientation("landscape-left"); // lock landscape — specific side
+setOrientation("landscape-right"); // lock landscape — specific side
+setOrientation("auto"); // unlock — follows device sensor
 ```
 
+> **Android note:** When the device's auto-rotate toggle is **ON**, `"portrait"` / `"landscape"` use sensor-based variants so the device can still rotate within the axis. When auto-rotate is **OFF**, orientation is hard-locked.
+
 ---
 
-## 📱 Full Example
+## 📡 System Screencast
+
+Detects OS-level external display state — HDMI, Miracast (Android), AirPlay mirror (iOS). This is the **system** casting state, not your app specifically.
+
+### `getSystemScreencastInfo()` → `Promise<SystemScreencastInfo>`
+
+```ts
+import { getSystemScreencastInfo } from "rn-system-bar";
+
+const info = await getSystemScreencastInfo();
+// {
+//   isCasting:   true,
+//   displayName: "Living Room TV",
+//   displays: [{ id: 1, name: "Living Room TV", isValid: true }]
+// }
+```
+
+### `onSystemScreencastChange(callback)` → unsubscribe
+
+```ts
+import { onSystemScreencastChange } from "rn-system-bar";
+
+const unsub = onSystemScreencastChange((info) => {
+  if (info.isCasting) {
+    console.log("Now casting to:", info.displayName);
+  } else {
+    console.log("Casting stopped");
+  }
+});
+
+// Stop listening
+unsub();
+```
+
+### `useSystemScreencast()` hook
 
 ```tsx
-import React, { useEffect } from "react";
-import { View, Button, Platform } from "react-native";
-import * as SystemBar from "rn-system-bar";
+import { useSystemScreencast } from "rn-system-bar";
 
-export default function App() {
-  useEffect(() => {
-    // Works on both platforms
-    SystemBar.setStatusBarStyle("light");
-    SystemBar.setBrightness(0.9);
-    SystemBar.keepScreenOn(true);
-
-    // Android-only (auto-guarded — safe to call without Platform check)
-    SystemBar.setNavigationBarColor("#000000");
-    SystemBar.setNavigationBarButtonStyle("light");
-    SystemBar.setNavigationBarBehavior("overlay-swipe");
-  }, []);
+const { isCasting, displayName, displays } = useSystemScreencast();
+
+return <Text>{isCasting ? `Casting to ${displayName}` : "Not casting"}</Text>;
+```
+
+---
+
+## 📲 App-Only Cast (Android)
+
+Cast **only this app's screen** to a nearby TV or Chromecast — the whole system is not mirrored. Uses Android `MediaRouter` internally, no Google Play Services required.
+
+> **iOS:** AirPlay is fully system-managed on iOS. Apple provides no public API for app-only casting. All `AppCast` functions are safe to call on iOS — they are no-ops that return idle state immediately.
+
+### State machine
+
+```
+idle → scanning → connecting → connected → disconnecting → idle
+                     ↕ error at any point
+```
+
+### `useAppCast()` hook — recommended
+
+The easiest way to manage casting. Handles initial state fetch, event subscription, and auto-stops the scan on unmount (battery-safe).
+
+```tsx
+import { useAppCast } from "rn-system-bar";
+
+export default function CastScreen() {
+  const {
+    state, // "idle" | "scanning" | "connecting" | "connected" | "disconnecting"
+    devices, // AppCastDevice[] — found nearby devices
+    connectedDevice, // AppCastDevice | null — currently active
+    error, // string | null — last error message
+    scan, // () => void — start discovery
+    stopScan, // () => void — stop discovery
+    connect, // (deviceId: string, pin?: string) => void
+    disconnect, // () => void
+  } = useAppCast();
 
   return (
     <View>
-      <Button
-        title="Immersive Mode"
-        onPress={() => SystemBar.immersiveMode(true)}
-      />
-      <Button
-        title="Landscape"
-        onPress={() => SystemBar.setOrientation("landscape")}
-      />
-      <Button
-        title="Get Brightness"
-        onPress={async () => {
-          const b = await SystemBar.getBrightness();
-          console.log("Brightness:", b);
-        }}
-      />
+      {state === "idle" && <Button title="Find TVs" onPress={scan} />}
+
+      {state === "scanning" && (
+        <>
+          <Text>Scanning…</Text>
+          <Button title="Stop" onPress={stopScan} />
+        </>
+      )}
+
+      {devices.map((device) => (
+        <View key={device.id}>
+          <Text>{device.name}</Text>
+          {device.description && <Text>{device.description}</Text>}
+          <Button
+            title={`Cast to ${device.name}`}
+            onPress={() => connect(device.id)}
+          />
+        </View>
+      ))}
+
+      {state === "connecting" && (
+        <Text>Connecting to {connectedDevice?.name}…</Text>
+      )}
+
+      {state === "connected" && (
+        <>
+          <Text>Casting to {connectedDevice?.name}</Text>
+          <Button title="Stop Casting" onPress={disconnect} />
+        </>
+      )}
+
+      {error && <Text style={{ color: "red" }}>Error: {error}</Text>}
     </View>
   );
 }
 ```
 
+### With pairing PIN
+
+```tsx
+const { devices, connect } = useAppCast();
+
+// If requiresPairing is true, pass the PIN as the second argument
+connect(device.id, "1234");
+```
+
+### Imperative API (without hook)
+
+```ts
+import {
+  startAppCastScan,
+  stopAppCastScan,
+  connectAppCast,
+  disconnectAppCast,
+  getAppCastInfo,
+  onAppCastChange,
+} from "rn-system-bar";
+
+// Subscribe first
+const unsub = onAppCastChange((info) => {
+  console.log("Cast state:", info.state);
+  console.log("Devices:", info.devices);
+  if (info.state === "connected") {
+    console.log("Casting to:", info.connectedDevice?.name);
+  }
+  if (info.error) console.warn("Error:", info.error);
+});
+
+// Start scan
+startAppCastScan();
+
+// Connect when a device appears
+connectAppCast("device_route_id_123");
+// With pairing PIN
+connectAppCast("device_route_id_123", "9876");
+
+// Stop casting
+disconnectAppCast();
+
+// Stop scanning
+stopAppCastScan();
+
+// Get current state without subscribing
+const info = await getAppCastInfo();
+
+// Clean up
+unsub();
+```
+
 ---
 
-## 🆕 New Architecture (TurboModules)
+## 🪝 `useSystemBar()` hook
 
-Add to your `react-native.config.js`:
+Apply multiple system bar settings declaratively in one call. Re-applies only when the config object actually changes (deep comparison via JSON).
 
-```js
-module.exports = {
-  dependencies: {
-    "rn-system-bar": {
-      platforms: {
-        android: {
-          packageImportPath: "import com.systembar.SystemBarPackage;",
-        },
-      },
-    },
-  },
-};
+```tsx
+import { useSystemBar } from "rn-system-bar";
+
+useSystemBar({
+  // Navigation bar (Android-only — safe to include on iOS)
+  navigationBarColor: "transparent",
+  navigationBarVisibility: "visible",
+  navigationBarButtonStyle: "light",
+  navigationBarStyle: "dark",
+  navigationBarBehavior: "overlay-swipe",
+
+  // Status bar
+  statusBarColor: "transparent", // Android only
+  statusBarStyle: "light",
+  statusBarVisible: true,
+
+  // Screen
+  keepScreenOn: true,
+  immersiveMode: false, // Android only
+  secureScreen: false, // Android only
+  brightness: 0.8,
+  orientation: "portrait",
+});
 ```
 
-The `specs/NativeSystemBar.ts` file is already configured for codegen via `codegenConfig` in `package.json`.
+All fields are optional. Only the ones you pass will be applied.
 
 ---
 
-## 🔖 Type Reference
+## 📱 Platform Support Matrix
+
+| Feature                       | Android |  iOS  |
+| ----------------------------- | :-----: | :---: |
+| `setNavigationBarColor`       |   ✅    |  ❌   |
+| `setNavigationBarVisibility`  |   ✅    |  ❌   |
+| `setNavigationBarButtonStyle` |   ✅    |  ❌   |
+| `setNavigationBarStyle`       |   ✅    |  ❌   |
+| `setNavigationBarBehavior`    |   ✅    |  ❌   |
+| `setStatusBarColor`           |   ✅    |  ❌   |
+| `setStatusBarStyle`           |   ✅    |  ✅   |
+| `setStatusBarVisibility`      |   ✅    |  ✅   |
+| `setBrightness`               |   ✅    |  ✅   |
+| `getBrightness`               |   ✅    |  ✅   |
+| `onBrightnessChange`          |   ✅    |  ✅   |
+| `setVolume`                   |   ✅    | ❌ \* |
+| `getVolume`                   |   ✅    |  ✅   |
+| `setVolumeHUDVisible`         |   ✅    |  ❌   |
+| `onVolumeChange`              |   ✅    |  ❌   |
+| `keepScreenOn`                |   ✅    |  ✅   |
+| `immersiveMode`               |   ✅    |  ❌   |
+| `setSecureScreen`             |   ✅    |  ❌   |
+| `setOrientation`              |   ✅    |  ✅   |
+| `getSystemScreencastInfo`     |   ✅    |  ✅   |
+| `onSystemScreencastChange`    |   ✅    |  ✅   |
+| `useSystemScreencast`         |   ✅    |  ✅   |
+| `startAppCastScan`            |   ✅    | ❌ †  |
+| `connectAppCast`              |   ✅    | ❌ †  |
+| `disconnectAppCast`           |   ✅    | ❌ †  |
+| `useAppCast`                  |   ✅    | ❌ †  |
+| `useTheme`                    |   ✅    |  ✅   |
+| `useThemeSystemBar`           |   ✅    |  ✅   |
+| `useSystemBar`                |   ✅    |  ✅   |
+
+> \* `setVolume` is a no-op on iOS — Apple does not allow apps to set system volume.
+> † App-only cast APIs are no-ops on iOS — AirPlay is system-managed with no public API.
+
+---
+
+## 📐 Full Type Reference
 
 ```ts
+// Theme
+type ThemeMode = "system" | "dark" | "light";
+
+interface ThemeState {
+  isDark: boolean;
+  mode: ThemeMode;
+  setMode: (mode: ThemeMode) => void;
+}
+
+// Navigation bar
+type NavigationBarColorValue = string | "transparent" | "translucent";
 type NavigationBarBehavior = "overlay-swipe" | "inset-swipe" | "inset-touch";
 type NavigationBarButtonStyle = "light" | "dark";
 type NavigationBarStyle = "auto" | "inverted" | "light" | "dark";
 type NavigationBarVisibility = "visible" | "hidden";
+
+// Status bar
+type StatusBarColorValue = string | "transparent" | "translucent";
 type StatusBarStyle = "light" | "dark";
+
+// Orientation
 type Orientation =
   | "portrait"
   | "landscape"
   | "landscape-left"
   | "landscape-right"
   | "auto";
+
+// Volume
 type VolumeStream = "music" | "ring" | "notification" | "alarm" | "system";
+
+// System screencast
+interface ScreencastDisplay {
+  id: number;
+  name: string;
+  isValid: boolean;
+}
+interface SystemScreencastInfo {
+  isCasting: boolean;
+  displayName: string | null;
+  displays: ScreencastDisplay[];
+}
+
+// App-only cast
+type AppCastState =
+  | "idle"
+  | "scanning"
+  | "connecting"
+  | "connected"
+  | "disconnecting";
+
+interface AppCastDevice {
+  id: string;
+  name: string;
+  description: string | null;
+  signalStrength: number | null; // 0–100 or null
+  requiresPairing: boolean;
+}
+
+interface AppCastInfo {
+  state: AppCastState;
+  devices: AppCastDevice[];
+  connectedDevice: AppCastDevice | null;
+  error: string | null;
+}
 ```
 
 ---
 
-## 📋 Platform Support Matrix
-
-| Feature                     | Android | iOS  |
-| --------------------------- | :-----: | :--: |
-| setNavigationBarColor       |   ✅    |  ❌  |
-| setNavigationBarVisibility  |   ✅    |  ❌  |
-| setNavigationBarButtonStyle |   ✅    |  ❌  |
-| setNavigationBarStyle       |   ✅    |  ❌  |
-| setNavigationBarBehavior    |   ✅    |  ❌  |
-| setStatusBarColor           |   ✅    |  ❌  |
-| setStatusBarStyle           |   ✅    |  ✅  |
-| setStatusBarVisibility      |   ✅    |  ✅  |
-| setBrightness               |   ✅    |  ✅  |
-| getBrightness               |   ✅    |  ✅  |
-| setVolume                   |   ✅    | ❌\* |
-| getVolume                   |   ✅    |  ✅  |
-| setVolumeHUDVisible         |   ✅    |  ❌  |
-| keepScreenOn                |   ✅    |  ✅  |
-| immersiveMode               |   ✅    |  ❌  |
-| setOrientation              |   ✅    |  ✅  |
-
-> \*iOS: `setVolume` is a no-op due to Apple restrictions.
-
-// useEffect(() => {
-// checkAuth();
-// }, []);
-
-// const checkAuth = async () => {
-// const token = await getAccessToken();
-
-// if (token) {
-// router.replace("/home");
-// } else {
-// router.replace("/login");
-// }
-// };
+## 🆕 New Architecture (TurboModules)
+
+Add to your `react-native.config.js`:
+
+```js
+module.exports = {
+  dependencies: {
+    "rn-system-bar": {
+      platforms: {
+        android: {
+          packageImportPath: "import com.systembar.SystemBarPackage;",
+        },
+      },
+    },
+  },
+};
+```
+
+The `specs/NativeSystemBar.ts` file is pre-configured for codegen.
+
+---
 
-# Use Sheet
+## 📋 Changelog
 
-<Button
-title="Open Sheet"
-variant="neutral"
-rounded={bw(80)}
-style={{ paddingVertical: hp(1) }}
-onPress={() => sheetRef.current?.open()}
-/>
+### v3.2 (current)
 
-<BottomSheet
-ref={sheetRef}
-style={{
-    snapPoints: [0.4, 0.7, 0.9],
-    borderRadius: ["15"],
-  }}
+- **New:** `setNavigationBarColor("transparent" | "translucent")` — edge-to-edge and frosted-glass nav bar
+- **New:** `setStatusBarColor("transparent" | "translucent")` — same for status bar
+- **New:** `useTheme()` — reactive OS dark/light mode with manual override (`"system"` | `"dark"` | `"light"`)
+- **New:** `setGlobalThemeMode()` — imperative theme setter, usable outside components
+- **New:** `useThemeSystemBar()` — auto-applies themed bar config on every theme change
+- **New:** `getSystemScreencastInfo()` / `onSystemScreencastChange()` / `useSystemScreencast()` — OS-level external display detection
+- **New:** `startAppCastScan()` / `connectAppCast()` / `disconnectAppCast()` / `useAppCast()` — in-app MediaRouter casting to TV/Chromecast (Android)
+- **Deprecated:** `getScreencastInfo()` → use `getSystemScreencastInfo()`
+- **Deprecated:** `onScreencastChange()` → use `onSystemScreencastChange()`
+- **Deprecated:** `useScreencast()` → use `useSystemScreencast()`
 
->
+### v3.1
 
-<Text>BottomSheet Open</Text>
-</BottomSheet>
+- Removed `expo-navigation-bar` dependency — all navigation bar APIs now go directly to native Kotlin/Swift
+- Added `onBrightnessChange()` realtime listener
+- Added `onVolumeChange()` realtime listener
+- Added `setSecureScreen()` for screenshot blocking

package/lib/src/SystemBar.js

@@ -17,9 +17,11 @@ const androidOnly = (name) => {
     }
     return true;
 };
-const checkNative = () => {
+const checkNative = (method) => {
     if (!Native)
         throw new Error("[rn-system-bar] Native module not found. Rebuild your project.");
+    if (method && typeof Native[method] !== "function")
+        throw new Error(`[rn-system-bar] Native.${method} not found. Rebuild your project.`);
 };
 // ═══════════════════════════════════════════════
 //  NAVIGATION BAR  (Android — 100% native)
@@ -207,7 +209,15 @@ exports.setOrientation = setOrientation;
  * Works on both Android (DisplayManager) and iOS (UIScreen.screens).
  */
 const getSystemScreencastInfo = () => {
-    checkNative();
+    if (!Native || typeof Native.getSystemScreencastInfo !== "function") {
+        if (__DEV__)
+            console.warn("[rn-system-bar] getSystemScreencastInfo not available on this build.");
+        return Promise.resolve({
+            isCasting: false,
+            displayName: null,
+            displays: [],
+        });
+    }
     return Native.getSystemScreencastInfo();
 };
 exports.getSystemScreencastInfo = getSystemScreencastInfo;

package/lib/src/useSystemBar.d.ts

@@ -1,4 +1,4 @@
-import type { AppCastInfo, NavigationBarBehavior, NavigationBarButtonStyle, NavigationBarColorValue, NavigationBarStyle, NavigationBarVisibility, Orientation, StatusBarColorValue, StatusBarStyle, SystemScreencastInfo, ThemeMode, ThemeState } from "./types";
+import type { AppCastInfo, NavigationBarBehavior, NavigationBarButtonStyle, NavigationBarColorValue, NavigationBarStyle, NavigationBarVisibility, Orientation, ScreencastInfo, StatusBarColorValue, StatusBarStyle, SystemScreencastInfo, ThemeMode, ThemeState } from "./types";
 export interface SystemBarConfig {
     navigationBarColor?: NavigationBarColorValue;
     navigationBarVisibility?: NavigationBarVisibility;
@@ -32,7 +32,7 @@ export { useTheme } from "./useTheme";
 export type { ThemeMode, ThemeState };
 export declare const useSystemScreencast: () => SystemScreencastInfo;
 /** @deprecated Renamed to useSystemScreencast() */
-export declare const useScreencast: () => SystemScreencastInfo;
+export declare const useScreencast: () => ScreencastInfo;
 export interface UseAppCastReturn extends AppCastInfo {
     /** Start scanning for nearby castable devices (TV, Chromecast, etc.). */
     scan: () => void;

package/lib/src/useSystemBar.js

@@ -134,7 +134,33 @@ const useSystemScreencast = () => {
 };
 exports.useSystemScreencast = useSystemScreencast;
 /** @deprecated Renamed to useSystemScreencast() */
-exports.useScreencast = exports.useSystemScreencast;
+// useSystemBar.ts — useScreencast
+const useScreencast = () => {
+    const [info, setInfo] = (0, react_1.useState)({
+        isCasting: false,
+        displayName: null,
+        displays: [],
+    });
+    (0, react_1.useEffect)(() => {
+        // Guard: if method doesn't exist on native module, bail silently
+        SystemBar.getScreencastInfo()
+            .then(setInfo)
+            .catch(() => {
+            if (__DEV__)
+                console.warn("[rn-system-bar] getSystemScreencastInfo not available. Rebuild native.");
+        });
+        let unsub;
+        try {
+            unsub = SystemBar.onScreencastChange(setInfo);
+        }
+        catch (_a) {
+            // native listener not available
+        }
+        return () => unsub === null || unsub === void 0 ? void 0 : unsub();
+    }, []);
+    return info;
+};
+exports.useScreencast = useScreencast;
 const useAppCast = () => {
     const [info, setInfo] = (0, react_1.useState)({
         state: "idle",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rn-system-bar",
-  "version": "3.1.8",
+  "version": "3.2.0",
   "description": "Control Android & iOS system bars, brightness, volume, orientation and screen flags from React Native.",
   "main": "lib/index.js",
   "react-native": "lib/index.js",

package/src/SystemBar.ts

@@ -15,7 +15,6 @@ import type {
   NavigationBarStyle,
   NavigationBarVisibility,
   Orientation,
-  ScreencastInfo,
   StatusBarColorValue,
   StatusBarStyle,
   SystemScreencastInfo,
@@ -35,11 +34,15 @@ const androidOnly = (name: string): boolean => {
   return true;
 };
 
-const checkNative = () => {
+const checkNative = (method?: string) => {
   if (!Native)
     throw new Error(
       "[rn-system-bar] Native module not found. Rebuild your project.",
     );
+  if (method && typeof Native[method] !== "function")
+    throw new Error(
+      `[rn-system-bar] Native.${method} not found. Rebuild your project.`,
+    );
 };
 
 // ═══════════════════════════════════════════════
@@ -246,7 +249,17 @@ export const setOrientation = (mode: Orientation): void => {
  * Works on both Android (DisplayManager) and iOS (UIScreen.screens).
  */
 export const getSystemScreencastInfo = (): Promise<SystemScreencastInfo> => {
-  checkNative();
+  if (!Native || typeof Native.getSystemScreencastInfo !== "function") {
+    if (__DEV__)
+      console.warn(
+        "[rn-system-bar] getSystemScreencastInfo not available on this build.",
+      );
+    return Promise.resolve({
+      isCasting: false,
+      displayName: null,
+      displays: [],
+    });
+  }
   return Native.getSystemScreencastInfo();
 };
 

package/src/useSystemBar.ts

@@ -12,6 +12,7 @@ import type {
   NavigationBarStyle,
   NavigationBarVisibility,
   Orientation,
+  ScreencastInfo,
   StatusBarColorValue,
   StatusBarStyle,
   SystemScreencastInfo,
@@ -183,7 +184,36 @@ export const useSystemScreencast = (): SystemScreencastInfo => {
 };
 
 /** @deprecated Renamed to useSystemScreencast() */
-export const useScreencast = useSystemScreencast;
+// useSystemBar.ts — useScreencast
+export const useScreencast = () => {
+  const [info, setInfo] = useState<ScreencastInfo>({
+    isCasting: false,
+    displayName: null,
+    displays: [],
+  });
+
+  useEffect(() => {
+    // Guard: if method doesn't exist on native module, bail silently
+    SystemBar.getScreencastInfo()
+      .then(setInfo)
+      .catch(() => {
+        if (__DEV__)
+          console.warn(
+            "[rn-system-bar] getSystemScreencastInfo not available. Rebuild native.",
+          );
+      });
+
+    let unsub: (() => void) | undefined;
+    try {
+      unsub = SystemBar.onScreencastChange(setInfo);
+    } catch {
+      // native listener not available
+    }
+    return () => unsub?.();
+  }, []);
+
+  return info;
+};
 
 // ─────────────────────────────────────────────
 //  UseAppCastReturn + useAppCast