@pickleball/expo-sdk 0.2.0 → 1.0.0

package/src/native-runtime.ts

@@ -1,94 +1,86 @@
-import type { EngineDependencies, SdkNetwork, SdkRuntime, SdkStorage, TelemetrySink } from "./engine";
-import { LiveKitRoomAdapter, type NativeLiveKitBindings } from "./livekit-room-adapter";
+import type {
+  EngineDependencies,
+  SdkNetwork,
+  SdkRuntime,
+  SdkStorage,
+  SessionCommandChannel,
+  TelemetrySink,
+} from "./engine";
+import type {
+  SessionCommandPollResult,
+  SessionCommandRecord,
+} from "./contracts";
 import { RtmpRoomAdapter, type NativeRtmpBindings } from "./rtmp-room-adapter";
 import { UnsupportedRuntimeError } from "./errors";
 
 declare const require: (name: string) => any;
 
-let globalsRegistered = false;
-
-export function createNativeLiveKitBindings(): NativeLiveKitBindings {
-  const reactNativeLiveKit = require("@livekit/react-native");
-  const liveKit = require("livekit-client");
-  return {
-    registerGlobals() {
-      if (!globalsRegistered) {
-        reactNativeLiveKit.registerGlobals();
-        globalsRegistered = true;
-      }
-    },
-    createRoom: () => new liveKit.Room({ adaptiveStream: false, dynacast: false }),
-    createLocalTracks: liveKit.createLocalTracks,
-    startAudioSession: () => reactNativeLiveKit.AudioSession.startAudioSession(),
-    stopAudioSession: () => reactNativeLiveKit.AudioSession.stopAudioSession(),
-    isLandscape() {
-      const { width, height } = require("react-native").Dimensions.get("window");
-      return width > height;
-    },
-    async listCameras() {
-      const { mediaDevices } = require("@livekit/react-native-webrtc");
-      const devices: Array<{
-        kind?: string;
-        deviceId?: string;
-        label?: string;
-        facing?: string;
-      }> = await mediaDevices.enumerateDevices();
-      return devices
-        .filter((device) => device.kind === "videoinput" && device.deviceId)
-        .map((device) => ({
-          deviceId: String(device.deviceId),
-          label: String(device.label ?? ""),
-          facing:
-            device.facing === "front" || device.facing === "environment"
-              ? device.facing
-              : ("unknown" as const),
-        }));
-    },
-    cameraSource: liveKit.Track.Source.Camera,
-    events: {
-      reconnecting: liveKit.RoomEvent.Reconnecting,
-      reconnected: liveKit.RoomEvent.Reconnected,
-      disconnected: liveKit.RoomEvent.Disconnected,
-      mediaDevicesError: liveKit.RoomEvent.MediaDevicesError,
-      dataReceived: liveKit.RoomEvent.DataReceived,
-    },
-  };
-}
-
-export function createDefaultRuntime(): SdkRuntime {
-  const { NativeModules, Platform } = require("react-native");
+/**
+ * Runtime cho app RTMP-only (KHÔNG có LiveKit/WebRTC): assert bằng module
+ * @pickleball/rtmp-native, xin quyền bằng API quyền thuần (Android) hoặc hàm
+ * native `requestPermissions` (iOS, rtmp-native ≥ 0.2; thiếu thì AVFoundation
+ * hỏi lúc mở camera). Chuyển từ apps/device-streamer (createRtmpOnlyRuntime).
+ * Không dùng getUserMedia: máy MediaTek chỉ cho một camera mở cùng lúc.
+ */
+export function createRtmpRuntime(): SdkRuntime {
+  const { Platform, PermissionsAndroid } = require("react-native");
   return {
     assertSupported() {
-      if (
-        (Platform.OS !== "ios" && Platform.OS !== "android") ||
-        !NativeModules.LivekitReactNativeModule
-      ) {
+      if (Platform.OS !== "ios" && Platform.OS !== "android") {
         throw new UnsupportedRuntimeError();
       }
+      try {
+        require("@pickleball/rtmp-native");
+      } catch {
+        throw new UnsupportedRuntimeError(
+          "@pickleball/rtmp-native is required: install it and rebuild the Development Build",
+        );
+      }
     },
     async requestPermissions() {
+      if (Platform.OS === "android") {
+        try {
+          const granted = await PermissionsAndroid.requestMultiple([
+            PermissionsAndroid.PERMISSIONS.CAMERA,
+            PermissionsAndroid.PERMISSIONS.RECORD_AUDIO,
+          ]);
+          return (
+            granted[PermissionsAndroid.PERMISSIONS.CAMERA] ===
+              PermissionsAndroid.RESULTS.GRANTED &&
+            granted[PermissionsAndroid.PERMISSIONS.RECORD_AUDIO] ===
+              PermissionsAndroid.RESULTS.GRANTED
+          );
+        } catch {
+          return false;
+        }
+      }
       try {
-        const { mediaDevices } = require("@livekit/react-native-webrtc");
-        const stream = await mediaDevices.getUserMedia({ audio: true, video: true });
-        for (const track of stream.getTracks()) track.stop();
-        return true;
+        const native = require("@pickleball/rtmp-native").default;
+        if (typeof native?.requestPermissions === "function") {
+          return (await native.requestPermissions()) !== false;
+        }
       } catch {
-        return false;
+        // Binary cũ chưa có hàm → AVFoundation tự hỏi lúc prepare.
       }
+      return true;
     },
-    activateKeepAwake() {
-      return require("expo-keep-awake").activateKeepAwakeAsync(
-        "@pickleball/expo-sdk",
-      );
-    },
-    deactivateKeepAwake() {
-      return require("expo-keep-awake").deactivateKeepAwake(
-        "@pickleball/expo-sdk",
-      );
+    activateKeepAwake: () =>
+      Promise.resolve(
+        require("expo-keep-awake").activateKeepAwakeAsync("@pickleball/expo-sdk"),
+      ).catch(() => undefined),
+    // deactivate trả promise và REJECT khi activity đã chết (sau crash/reload) —
+    // không catch là thêm một "Uncaught (in promise)" gây nhiễu log.
+    deactivateKeepAwake: () => {
+      void Promise.resolve(
+        require("expo-keep-awake").deactivateKeepAwake("@pickleball/expo-sdk"),
+      ).catch(() => undefined);
     },
   };
 }
 
+/** Runtime mặc định của SDK 1.0 = RTMP (LiveKit đã gỡ khỏi SDK — ADR-0002). */
+export const createDefaultRuntime = createRtmpRuntime;
+
 export function createDefaultStorage(): SdkStorage {
   // Cài localStorage của expo-sqlite ở LẦN DÙNG ĐẦU, không phải lúc gọi factory:
   // app thường tạo storage ở module scope (root layout), và static-render web
@@ -174,19 +166,122 @@ export function createDefaultTelemetry(
   };
 }
 
+/** roomFactory mặc định của SDK 1.0 = RTMP (fps/camera mặc định của native). */
 export function createDefaultRoomFactory(): EngineDependencies["roomFactory"] {
-  return () => new LiveKitRoomAdapter(createNativeLiveKitBindings());
+  return createRtmpRoomFactory();
 }
 
 /**
- * Bindings cho mode device-rtmp. `require` động giống LiveKit ở trên: app nào
- * không cài @pickleball/rtmp-native thì chỉ lỗi khi thật sự chọn mode này,
- * không gãy lúc import SDK.
+ * Kênh poll lệnh cho phiên device-rtmp. URL suy từ telemetry endpoint
+ * (.../telemetry → .../commands) — cùng origin, cùng Bearer token, nên không
+ * cần thêm bất kỳ trường mới nào đi qua proxy của đối tác.
+ */
+export function createDefaultCommandChannel(
+  fetchImplementation = globalThis.fetch,
+  timeoutMs = 10_000,
+): SessionCommandChannel {
+  const controllers = new Set<AbortController>();
+  return {
+    async poll(credentials, after): Promise<SessionCommandPollResult> {
+      const endpoint = credentials.endpoint.replace(/\/telemetry$/, "/commands");
+      const controller = new AbortController();
+      controllers.add(controller);
+      const timeout = setTimeout(() => controller.abort(), timeoutMs);
+      try {
+        const response = await fetchImplementation(endpoint, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${credentials.token}`,
+          },
+          body: JSON.stringify({ after }),
+          signal: controller.signal,
+          redirect: "error",
+        });
+        if (!response.ok) {
+          if (typeof response.text === "function") await response.text();
+          throw Object.assign(new Error("Command poll rejected"), {
+            status: response.status,
+          });
+        }
+        const envelope = (await response.json()) as { data?: unknown };
+        return parseCommandPollResult(envelope?.data);
+      } finally {
+        clearTimeout(timeout);
+        controllers.delete(controller);
+      }
+    },
+    dispose() {
+      for (const controller of controllers) controller.abort();
+      controllers.clear();
+    },
+  };
+}
+
+function parseCommandPollResult(value: unknown): SessionCommandPollResult {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Command poll returned an invalid payload");
+  }
+  const record = value as Record<string, unknown>;
+  const status = record.status;
+  if (status !== "scheduled" && status !== "live" && status !== "ended") {
+    throw new Error("Command poll returned an invalid status");
+  }
+  const commands: SessionCommandRecord[] = [];
+  if (Array.isArray(record.commands)) {
+    for (const item of record.commands) {
+      if (item === null || typeof item !== "object") continue;
+      const command = item as Record<string, unknown>;
+      if (
+        typeof command.id !== "string" ||
+        (command.action !== "start" &&
+          command.action !== "stop" &&
+          command.action !== "end") ||
+        typeof command.issuedAt !== "number" ||
+        !Number.isFinite(command.issuedAt)
+      ) {
+        continue;
+      }
+      commands.push({
+        id: command.id,
+        action: command.action,
+        issuedAt: command.issuedAt,
+      });
+    }
+  }
+  return { commands, status };
+}
+
+/**
+ * Bindings native RTMP. `require` động: app chưa cài @pickleball/rtmp-native
+ * chỉ lỗi khi thật sự mở camera (UnsupportedRuntimeError rõ ràng), không gãy
+ * lúc import SDK — static-render web của expo-router vẫn nạp được module.
  */
 export function createNativeRtmpBindings(): NativeRtmpBindings {
   const native = require("@pickleball/rtmp-native").default;
+  const { Platform, PermissionsAndroid } = require("react-native");
   return {
     prepare: (options) => native.prepare(options),
+    // Android: xin quyền THUẦN, không mở camera như getUserMedia của WebRTC.
+    // Máy MediaTek (Xiaomi tanzanite) chỉ cho một camera mở cùng lúc — camera
+    // WebRTC chưa nhả (~400ms) là HaishinKit dính "Too many users (-87)" và
+    // preview đen. iOS không có giới hạn đó nên để engine fallback getUserMedia.
+    ...(Platform.OS === "android"
+      ? {
+          async requestPermissions() {
+            const granted = await PermissionsAndroid.requestMultiple([
+              PermissionsAndroid.PERMISSIONS.CAMERA,
+              PermissionsAndroid.PERMISSIONS.RECORD_AUDIO,
+            ]);
+            return (
+              granted[PermissionsAndroid.PERMISSIONS.CAMERA] ===
+                PermissionsAndroid.RESULTS.GRANTED &&
+              granted[PermissionsAndroid.PERMISSIONS.RECORD_AUDIO] ===
+                PermissionsAndroid.RESULTS.GRANTED
+            );
+          },
+        }
+      : {}),
     isLandscape() {
       const { width, height } = require("react-native").Dimensions.get("window");
       return width > height;
@@ -201,12 +296,22 @@ export function createNativeRtmpBindings(): NativeRtmpBindings {
     setVideoBitrate: (bps) => native.setVideoBitrate(bps),
     dispose: () => native.dispose(),
     addStatusListener: (listener) => native.addListener("onStatusChanged", listener),
+    addBandwidthListener: (listener) => native.addListener("onBandwidth", listener),
   };
 }
 
 /** roomFactory cho mode device-rtmp (thiết bị đẩy RTMP, không dùng LiveKit). */
-export function createRtmpRoomFactory(): EngineDependencies["roomFactory"] {
-  return () => new RtmpRoomAdapter(createNativeRtmpBindings());
+export function createRtmpRoomFactory(options?: {
+  /**
+   * fps capture + encode (24 tiết kiệm băng thông, 30 mặc định của native).
+   * 60 chỉ nên truyền khi `getCameraCapabilities().supportedFrameRates` có nó —
+   * native bỏ qua trong im lặng nếu ống kính đang gắn không chạy được.
+   */
+  frameRate?: 24 | 30 | 60;
+  /** Camera mở sẵn lúc prepare — thiếu = camera sau mặc định của native. */
+  cameraId?: string;
+}): EngineDependencies["roomFactory"] {
+  return () => new RtmpRoomAdapter(createNativeRtmpBindings(), options);
 }
 
 /**
@@ -264,6 +369,21 @@ export function createDefaultDeviceMetrics(): NonNullable<
       /* expo-device chưa được cài */
     }
 
+    // Nhiệt máy + nhiệt pin: chỉ có đường native (không package Expo nào đọc
+    // được). Guard require như các nguồn khác — app không cài rtmp-native thì
+    // bỏ qua hai trường này thay vì gãy cả collector.
+    try {
+      const native = require("@pickleball/rtmp-native").default;
+      const health = await native.getDeviceHealth();
+      if (typeof health?.thermal === "number") metrics.thermal = health.thermal;
+      if (typeof health?.batteryTempC === "number") {
+        // Làm tròn 1 số lẻ: pin báo theo 1/10 °C, giữ nguyên là đủ chính xác.
+        metrics.batteryTempC = Math.round(health.batteryTempC * 10) / 10;
+      }
+    } catch (error) {
+      notes.push(`device health: ${String(error)}`);
+    }
+
     try {
       const NetInfo = require("@react-native-community/netinfo").default;
       const status = await NetInfo.fetch();
@@ -277,6 +397,42 @@ export function createDefaultDeviceMetrics(): NonNullable<
                 ).toUpperCase()
               : status.type;
       }
+      // Chi tiết mạng cho việc truy vết sự cố tại sân: máy còn bám router của
+      // giải hay đã rớt sang 4G, sóng yếu tới mức nào.
+      //
+      // CỐ Ý không đọc `details.ssid`/`bssid`: hai field đó bị khoá sau quyền
+      // VỊ TRÍ (Android cần ACCESS_FINE_LOCATION + bật GPS; iOS cần entitlement
+      // Access WiFi Information). Xin quyền vị trí cho mỗi máy đặt ở sân chỉ để
+      // hiện tên WiFi là cái giá quá đắt — IP nội bộ dưới đây phân biệt được
+      // router mà không cần quyền nào.
+      const details = status?.details as
+        | {
+            ipAddress?: unknown;
+            strength?: unknown;
+            linkSpeed?: unknown;
+            frequency?: unknown;
+          }
+        | undefined;
+      if (typeof details?.ipAddress === "string" && details.ipAddress) {
+        metrics.localIp = details.ipAddress;
+      }
+      // strength: 0-100 (%). CHỈ Android — iOS không mở cường độ sóng cho app.
+      if (typeof details?.strength === "number" && Number.isFinite(details.strength)) {
+        metrics.signalPct = Math.round(details.strength);
+      }
+      if (typeof details?.linkSpeed === "number" && Number.isFinite(details.linkSpeed)) {
+        metrics.linkMbps = Math.round(details.linkSpeed);
+      }
+      // Tần số kênh (Android) — phân biệt 2.4/5 GHz không cần quyền vị trí.
+      // Chỉ đi vào telemetry PHIÊN (dataJson tự do); heartbeat thiết bị lọc
+      // theo METRIC_FIELDS nên không đụng validator server.
+      if (
+        typeof details?.frequency === "number" &&
+        Number.isFinite(details.frequency) &&
+        details.frequency > 0
+      ) {
+        metrics.freqMhz = Math.round(details.frequency);
+      }
     } catch {
       /* netinfo không khả dụng */
     }

package/src/plugin.ts

@@ -4,12 +4,19 @@ import {
   withAndroidManifest,
   withDangerousMod,
   withInfoPlist,
-  withPlugins,
   type ConfigPlugin,
 } from "expo/config-plugins";
 import { readdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { PICKLEBALL_EXPO_SDK_VERSION } from "./version";
+
+/**
+ * Version của SCHEMA plugin — tách khỏi version package có chủ ý. Giá trị này
+ * được inline vào dist/plugin.cjs, mà @expo/fingerprint băm file đó làm
+ * runtimeVersion của app fleet: gắn theo version package là MỖI lần bump SDK
+ * (kể cả patch JS-only) đổi fingerprint và toàn bộ máy ngoài sân mất OTA. Chỉ
+ * nâng khi plugin đổi hành vi native (permission, mod).
+ */
+export const PLUGIN_SCHEMA_VERSION = "1";
 
 export interface PickleballLivePluginProps {
   cameraPermission?: string;
@@ -24,11 +31,17 @@ export interface PickleballLivePluginProps {
    * - voice: false → hiện chưa gate gì trong plugin (mic thuộc livestream);
    *   nhận trước để tương thích về sau. Muốn loại hẳn native khỏi binary, thêm
    *   expo.autolinking.exclude trong package.json của app (xem README).
+   * - livekit: KHÔNG còn tác dụng từ 1.0 (SDK RTMP-only, không compose plugin
+   *   LiveKit nữa). Vẫn nhận để app.config cũ của fleet không phải sửa — sửa
+   *   là đổi fingerprint OTA.
    */
   modules?: {
     remote?: boolean;
     voice?: boolean;
+    /** @deprecated bị bỏ qua từ 1.0 */
+    livekit?: boolean;
   };
+  /** @deprecated bị bỏ qua từ 1.0 (SDK không còn LiveKit). */
   liveKit?: {
     android?: { audioType?: string; enableScreenShareService?: boolean };
     ios?: { enableMultitaskingCameraAccess?: boolean };
@@ -38,6 +51,9 @@ export interface PickleballLivePluginProps {
 const CORE_ANDROID_PERMISSIONS = [
   "android.permission.ACCESS_NETWORK_STATE",
   "android.permission.CAMERA",
+  "android.permission.FOREGROUND_SERVICE",
+  "android.permission.FOREGROUND_SERVICE_CAMERA",
+  "android.permission.FOREGROUND_SERVICE_MICROPHONE",
   "android.permission.INTERNET",
   "android.permission.MODIFY_AUDIO_SETTINGS",
   "android.permission.RECORD_AUDIO",
@@ -98,9 +114,6 @@ const withPickleballLive: ConfigPlugin<PickleballLivePluginProps | undefined> =
     ? [...CORE_ANDROID_PERMISSIONS, ...REMOTE_ANDROID_PERMISSIONS]
     : [...CORE_ANDROID_PERMISSIONS];
 
-  config = withPlugins(config, [
-    ["@livekit/react-native-expo-plugin", props?.liveKit],
-  ]);
   config.ios = { ...config.ios, bitcode: false };
   config = withInfoPlist(config, (mod) => {
     mod.modResults.NSCameraUsageDescription = cameraPermission;
@@ -162,5 +175,5 @@ const withPickleballLive: ConfigPlugin<PickleballLivePluginProps | undefined> =
 export default createRunOncePlugin(
   withPickleballLive,
   "@pickleball/expo-sdk",
-  PICKLEBALL_EXPO_SDK_VERSION,
+  PLUGIN_SCHEMA_VERSION,
 );

package/src/provider.tsx

@@ -1,4 +1,4 @@
-import React, { useEffect, useRef, useSyncExternalStore, type ReactNode } from "react";
+import React, { useEffect, useMemo, useRef, useSyncExternalStore, type ReactNode } from "react";
 import { AppState } from "react-native";
 import type { BootstrapInput, LivestreamSessionProvider, StartLivestreamInput, EndReason } from "./contracts";
 import { ExpoSdkConfigurationError, type PickleballExpoError } from "./errors";
@@ -10,9 +10,12 @@ import {
   type SdkNetwork,
   type SdkRuntime,
   type SdkStorage,
+  type SessionCommandChannel,
+  type SessionCommandSubscription,
   type TelemetrySink,
 } from "./engine";
 import {
+  createDefaultCommandChannel,
   createDefaultDeviceMetrics,
   createDefaultNetwork,
   createDefaultRoomFactory,
@@ -64,10 +67,33 @@ export interface PickleballLiveProviderProps {
   children?: ReactNode;
   sessionProvider: LivestreamSessionProvider;
   bootstrapInput: BootstrapInput;
+  /**
+   * Phiên phải SỐNG TIẾP khi app biến mất giữa chừng (sụp nguồn, bị vuốt tắt,
+   * component remount), để lần mở sau nhận lại đúng phiên cũ — giữ nguyên link
+   * xem và VOD liền một mạch.
+   *
+   * Mặc định false = hành vi cũ: mở app lại là dọn sạch phiên cũ. App gác sân bật
+   * cờ này khi máy đang được gán sân; máy không gán sân vẫn dọn như cũ để không
+   * để lại phiên treo trong các ca ngoài giải.
+   *
+   * Nhận boolean HOẶC hàm (được phép async). App nên truyền HÀM ĐỌC THẲNG ĐĨA:
+   * engine hỏi cờ này đúng lúc khởi động, thường TRƯỚC khi state React kịp
+   * restore — truyền boolean suy từ state là dính race keep=false oan (đã dính
+   * thật 18/08/2026, sinh phiên chờ thứ hai đè phiên live cũ).
+   */
+  keepSessionOnRestart?: boolean | (() => boolean | Promise<boolean>);
   runtime?: SdkRuntime;
   storage?: SdkStorage;
   network?: SdkNetwork;
   telemetry?: TelemetrySink;
+  /** Kênh poll lệnh cho mode device-rtmp — mặc định suy từ telemetry endpoint. */
+  commandChannel?: SessionCommandChannel;
+  /**
+   * Kênh nhận lệnh qua websocket (first-party nối thẳng Convex). Có thì lệnh về
+   * tức thì và poll tụt về nhịp reconcile chậm — cắt phần lớn function call của
+   * đường poll. Thiếu (máy đối tác qua proxy) thì chỉ dùng poll HTTP như cũ.
+   */
+  commandSubscription?: SessionCommandSubscription;
   roomFactory?: () => RoomAdapter;
   deviceMetrics?: EngineDependencies["deviceMetrics"];
   theme?: Partial<LivestreamTheme>;
@@ -121,6 +147,31 @@ const LivestreamContext = React.createContext<LivestreamContextValue | null>(nul
 
 export function PickleballLiveProvider(props: PickleballLiveProviderProps) {
   const engineRef = useRef<LivestreamEngine | null>(null);
+  const keepSessionRef = useRef(props.keepSessionOnRestart);
+  keepSessionRef.current = props.keepSessionOnRestart;
+  // dispose() phải quyết NGAY (sync) có giữ phiên hay không, còn prop dạng hàm
+  // thì async — resolve sẵn vào ref này. Khi prop là hàm mà chưa có kết quả,
+  // nghiêng về GIỮ: dọn oan là mất phiên vĩnh viễn (link đổi, VOD tách đôi),
+  // giữ oan thì lưới server (1 giờ live / 30 phút standby) dọn hộ.
+  const resolvedKeepRef = useRef(typeof props.keepSessionOnRestart === "function");
+  useEffect(() => {
+    const value = props.keepSessionOnRestart;
+    if (typeof value !== "function") {
+      resolvedKeepRef.current = value === true;
+      return;
+    }
+    resolvedKeepRef.current = true;
+    let cancelled = false;
+    void Promise.resolve()
+      .then(() => value())
+      .then((keep) => {
+        if (!cancelled) resolvedKeepRef.current = keep === true;
+      })
+      .catch(() => undefined);
+    return () => {
+      cancelled = true;
+    };
+  }, [props.keepSessionOnRestart]);
   const hostRef = useRef<LivestreamHostContextValue | null>(null);
   const effectGenerationRef = useRef(0);
   if (!engineRef.current) {
@@ -132,8 +183,19 @@ export function PickleballLiveProvider(props: PickleballLiveProviderProps) {
       storage: props.storage ?? createDefaultStorage(),
       network: props.network ?? createDefaultNetwork(),
       telemetry: props.telemetry ?? createDefaultTelemetry(),
+      commandChannel: props.commandChannel ?? createDefaultCommandChannel(),
+      ...(props.commandSubscription
+        ? { commandSubscription: props.commandSubscription }
+        : {}),
       deviceMetrics,
       roomFactory: props.roomFactory ?? createDefaultRoomFactory(),
+      // Đọc qua ref để engine luôn thấy giá trị MỚI NHẤT: engine chỉ dựng một lần
+      // (engineRef), còn prop thì đổi theo việc máy được gán/gỡ sân. Prop dạng
+      // hàm được gọi xuyên qua (engine tự await) — đường cho app đọc thẳng đĩa.
+      keepSessionOnRestart: () => {
+        const value = keepSessionRef.current;
+        return typeof value === "function" ? value() : value === true;
+      },
     };
     engineRef.current = new LivestreamEngine(dependencies);
     hostRef.current = {
@@ -161,7 +223,7 @@ export function PickleballLiveProvider(props: PickleballLiveProviderProps) {
       subscription.remove();
       queueMicrotask(() => {
         if (effectGenerationRef.current === effectGeneration) {
-          void engine.dispose();
+          void engine.dispose({ keepSession: resolvedKeepRef.current });
         }
       });
     };
@@ -171,22 +233,36 @@ export function PickleballLiveProvider(props: PickleballLiveProviderProps) {
     if (snapshot.error) props.onError?.(snapshot.error);
   }, [props.onError, snapshot.error]);
 
-  const value: LivestreamContextValue = {
-    ...snapshot,
-    locale: props.locale ?? "vi",
-    theme: { ...defaultLivestreamTheme, ...props.theme },
-    prepare: () => engine.prepare(),
-    start: (input, options) => engine.start(input, options),
-    startPublishing: () => engine.startPublishing(),
-    stopPublishing: () => engine.stopPublishing(),
-    stop: (reason) => engine.stop(reason),
-    retry: () => engine.retry(),
-    switchCamera: () => engine.switchCamera(),
-    setMicrophoneEnabled: (enabled) => engine.setMicrophoneEnabled(enabled),
-    setCaptureOrientation: (orientation) =>
-      engine.setCaptureOrientation(orientation),
-    selectCamera: (deviceId) => engine.selectCamera(deviceId),
-  };
+  // Hành động ổn định theo engine (không dựng lại mỗi render): các effect phía
+  // trên (AutoResume, useStandbySession, app đối tác) đặt chúng vào dependency
+  // — dựng lại mỗi render là effect huỷ/chạy lại theo nhịp render, timer thử
+  // lại không bao giờ kịp nổ.
+  const actions = useMemo(
+    () => ({
+      prepare: () => engine.prepare(),
+      start: (input: StartLivestreamInput, options?: { autoPublish?: boolean }) =>
+        engine.start(input, options),
+      startPublishing: () => engine.startPublishing(),
+      stopPublishing: () => engine.stopPublishing(),
+      stop: (reason?: EndReason) => engine.stop(reason),
+      retry: () => engine.retry(),
+      switchCamera: () => engine.switchCamera(),
+      setMicrophoneEnabled: (enabled: boolean) => engine.setMicrophoneEnabled(enabled),
+      setCaptureOrientation: (orientation: "portrait" | "landscape") =>
+        engine.setCaptureOrientation(orientation),
+      selectCamera: (deviceId: string) => engine.selectCamera(deviceId),
+    }),
+    [engine],
+  );
+  const locale = props.locale ?? "vi";
+  const theme = useMemo(
+    () => ({ ...defaultLivestreamTheme, ...props.theme }),
+    [props.theme],
+  );
+  const value = useMemo<LivestreamContextValue>(
+    () => ({ ...snapshot, locale, theme, ...actions }),
+    [snapshot, locale, theme, actions],
+  );
   return (
     <LivestreamHostContext.Provider value={hostRef.current}>
       <LivestreamContext.Provider value={value}>

package/src/realtime/index.ts

@@ -0,0 +1,56 @@
+/**
+ * Kênh lệnh realtime qua websocket Convex cho app dùng camera grant.
+ *
+ * Grant có `convexUrl` (origin .convex.cloud) → truyền
+ * `commandSubscription={createGrantCommandSubscription(() => grant?.convexUrl)}`
+ * vào PickleballLiveProvider: lệnh start/stop/end về tức thì và poll HTTP tụt
+ * về nhịp đối chiếu 30s (thay vì 2s/4s — ~3.600 call/giờ/máy).
+ *
+ * Subpath riêng vì kéo theo `convex`; root entry giữ gọn. `./device-agent` vẫn
+ * re-export cùng hàm cho app fleet.
+ */
+import type { SdkTelemetryCredentials, SessionCommandRecord } from "../contracts";
+import {
+  createConvexCommandSubscription,
+  createConvexDeviceRealtime,
+  type ConvexDeviceRealtime,
+} from "../device-agent/convex-command-subscription";
+import type { SessionCommandSubscription } from "../engine";
+
+export { createConvexCommandSubscription, createConvexDeviceRealtime, type ConvexDeviceRealtime };
+
+/**
+ * Subscription cho app dùng camera grant: URL Convex nằm TRONG grant
+ * (`grant.convexUrl`) nên chỉ biết sau khi start — đọc URL lúc engine subscribe
+ * (ngay sau khi vào phiên), dựng MỘT client mỗi origin và tái dùng qua các
+ * phiên. Không có URL (deployment không lộ origin chuẩn) → không subscribe,
+ * engine giữ poll HTTP như cũ.
+ *
+ * Dùng với createCameraGrantProvider: `() => provider.getActiveGrant()?.convexUrl`.
+ */
+export function createGrantCommandSubscription(
+  getConvexUrl: () => string | null | undefined,
+): SessionCommandSubscription {
+  const clients = new Map<string, ConvexDeviceRealtime>();
+  return {
+    subscribe(
+      credentials: SdkTelemetryCredentials,
+      sessionId: string,
+      onCommands: (commands: SessionCommandRecord[]) => void,
+      onError?: (error: Error) => void,
+    ) {
+      const url = getConvexUrl();
+      if (!url) return () => undefined;
+      let realtime = clients.get(url);
+      if (!realtime) {
+        realtime = createConvexDeviceRealtime(url);
+        clients.set(url, realtime);
+      }
+      return realtime.commandSubscription.subscribe(credentials, sessionId, onCommands, onError);
+    },
+    dispose() {
+      for (const realtime of clients.values()) realtime.dispose();
+      clients.clear();
+    },
+  };
+}