rn-system-bar 3.1.7 → 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,12 +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.
 
 ---
 
@@ -31,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)
 ```
 
 ---
@@ -45,166 +51,705 @@ 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
+```
+
+---
+
+## 🚀 Quick Start
+
+```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,
+  });
+
+  return (
+    <View>
+      <Button title="Immersive" onPress={() => SystemBar.immersiveMode(true)} />
+      <Button
+        title="Landscape"
+        onPress={() => SystemBar.setOrientation("landscape")}
+      />
+    </View>
+  );
+}
 ```
 
 ---
 
-## 🚀 API Reference
+## 🎨 Theme
+
+### `useTheme()`
 
-### Navigation Bar — `Android only`
+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.
 
-> 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.
+```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";
 
-setStatusBarColor("#000000");   // Android only (iOS ignores bg color)
-setStatusBarStyle("light");     // "light" | "dark"  — works on both platforms
-setStatusBarVisibility(false);  // hide status 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.
+
+```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
+```
+
+---
+
+## 🔴 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 { setStatusBarColor } from "rn-system-bar";
+
+setStatusBarColor("#000000"); // solid black
+setStatusBarColor("transparent"); // content visible behind status bar
+setStatusBarColor("translucent"); // frosted glass
+```
+
+### `setStatusBarStyle(style)` — Android + iOS
+
+```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
 ```
 
 ---
 
-### Brightness
+## ☀️ Brightness
+
+### `setBrightness(level)`
 
 ```ts
-import { setBrightness, getBrightness } from "rn-system-bar";
+import { setBrightness } from "rn-system-bar";
+
+setBrightness(1.0); // maximum brightness
+setBrightness(0.5); // 50%
+setBrightness(0.01); // minimum (0.0 is clamped to 0.01)
+```
 
-setBrightness(0.8);                          // 0.0 – 1.0
+### `getBrightness()` → `Promise<number>`
 
-const level = await getBrightness();         // returns 0.0 – 1.0
+```ts
+import { getBrightness } from "rn-system-bar";
+
+const level = await getBrightness(); // 0.0 – 1.0
+console.log("Brightness:", level);
+```
+
+### `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();
 ```
 
 ---
 
-### Volume
+## 🔊 Volume
+
+### `setVolume(level, stream?)`
+
+> **iOS note:** `setVolume()` is a no-op on iOS due to Apple restrictions. `getVolume()` works normally.
 
 ```ts
-import { setVolume, getVolume, setVolumeHUDVisible } from "rn-system-bar";
+import { setVolume } 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"
+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
+```
 
-const vol = await getVolume("music");        // returns 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)
 ```
 
-> **iOS note**: `setVolume()` is a no-op on iOS (Apple restriction). `getVolume()` works.
+### `onVolumeChange(callback)` → unsubscribe
+
+Fires when the volume changes via hardware buttons or another app.
+
+```ts
+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
+## 📺 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
+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 { keepScreenOn, immersiveMode } from "rn-system-bar";
+import { setSecureScreen } from "rn-system-bar";
 
-keepScreenOn(true);                          // prevent sleep
-immersiveMode(true);                         // hide status + nav bar (Android only)
+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("portrait"); // lock portrait
+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() {
+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.
 
-  useEffect(() => {
-    // Works on both platforms
-    SystemBar.setStatusBarStyle("light");
-    SystemBar.setBrightness(0.9);
-    SystemBar.keepScreenOn(true);
+> **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.
 
-    // Android-only (auto-guarded — safe to call without Platform check)
-    SystemBar.setNavigationBarColor("#000000");
-    SystemBar.setNavigationBarButtonStyle("light");
-    SystemBar.setNavigationBarBehavior("overlay-swipe");
-  }, []);
+### 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();
+```
+
+---
+
+## 🪝 `useSystemBar()` hook
+
+Apply multiple system bar settings declaratively in one call. Re-applies only when the config object actually changes (deep comparison via JSON).
+
+```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",
+});
+```
+
+All fields are optional. Only the ones you pass will be applied.
+
+---
+
+## 📱 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;
+}
+```
+
 ---
 
 ## 🆕 New Architecture (TurboModules)
@@ -225,43 +770,28 @@ module.exports = {
 };
 ```
 
-The `specs/NativeSystemBar.ts` file is already configured for codegen via `codegenConfig` in `package.json`.
+The `specs/NativeSystemBar.ts` file is pre-configured for codegen.
 
 ---
 
-## 🔖 Type Reference
+## 📋 Changelog
 
-```ts
-type NavigationBarBehavior = "overlay-swipe" | "inset-swipe" | "inset-touch";
-type NavigationBarButtonStyle = "light" | "dark";
-type NavigationBarStyle = "auto" | "inverted" | "light" | "dark";
-type NavigationBarVisibility = "visible" | "hidden";
-type StatusBarStyle = "light" | "dark";
-type Orientation = "portrait" | "landscape" | "landscape-left" | "landscape-right" | "auto";
-type VolumeStream = "music" | "ring" | "notification" | "alarm" | "system";
-```
+### v3.2 (current)
 
----
+- **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
 
-## 📋 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.
+- 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