@pickleball/expo-sdk 0.2.0 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # @pickleball/expo-sdk
 
+## 1.0.0
+
+### Major Changes
+
+- 04e5c5d: **1.0.0 — RTMP-only + camera grant (ADR-0002).** Điện thoại của user đối tác lên
+  sóng qua đúng pipeline device-rtmp của thiết bị Picklive; LiveKit gỡ hẳn khỏi SDK.
+
+  BREAKING
+  - Gỡ LiveKit: không còn `LiveKitRoomAdapter`, `createNativeLiveKitBindings`,
+    `LivestreamScreen` (thay bằng `PickleballCameraScreen` ở `./ui`), peer
+    `@livekit/react-native`, `@livekit/react-native-webrtc`, `livekit-client` và
+    dependency `@livekit/react-native-expo-plugin`. `createDefaultRuntime` /
+    `createDefaultRoomFactory` giờ là RTMP.
+  - `@pickleball/rtmp-native` `>=0.2.0` là peer BẮT BUỘC (không còn optional).
+  - Grant `serverUrl` phải là `rtmp(s)://` — `createHttpSessionProvider` /
+    `isSessionGrant` từ chối `wss://` (INVALID_RESPONSE).
+  - Config plugin không compose plugin LiveKit nữa; prop `modules.livekit` và
+    `liveKit` vẫn được nhận nhưng bị bỏ qua. Plugin dùng `PLUGIN_SCHEMA_VERSION`
+    ("1") thay cho version package trong `createRunOncePlugin` — bump SDK không
+    còn đổi fingerprint OTA của app.
+  - `withLocalVideoQuality` generic: trả đúng kiểu provider truyền vào (giữ
+    `resume`/`getActiveGrant`).
+
+  MỚI (từ 0.3 additive, gộp vào 1.0)
+  - `createCameraGrantProvider` / `useCameraGrant`: grant từ backend đối tác →
+    Bearer thẳng `/api/v2/camera/sessions/{id}/*`; tự publish khi start không
+    standby; nhận lại phiên sau khi app bị kill (`hasResumableSession`,
+    `clearStoredSession`); Bearer hết hạn không bao giờ khoá máy.
+  - Resume hạng nhất: `withResume`, `createHttpResumeFetcher`,
+    `PickleballAutoResume`, `PickleballAutoPrepare`, `useStandbySession`
+    (+ `resumeSessionId`), `resume-policy`.
+  - `./ui`: `PickleballCameraScreen` (casual/court, copy vi/en, lỗi bản địa hoá),
+    `CameraControlsSheet` (độ phân giải, fps theo capability, chống chớp, camera
+    mặc định, zoom/EV/khoá/đèn pin, đo uplink) + primitives/helpers/hooks.
+  - `./realtime`: `createGrantCommandSubscription`, `createConvexCommandSubscription`.
+  - `createRtmpRuntime`, `createRtmpRoomFactory` ở root; camera-settings store;
+    camera-controls (`typeof`-guard); `runUplinkCheck`/`VIDEO_BITRATE_BPS`.
+  - Engine: poll lệnh 409 → dừng tại chỗ; không xoay token mỗi giây ở phút cuối;
+    hành động của `useLivestream` ổn định qua re-render.
+  - `SdkError.reason` (409: superseded|ended|expired) và `retryAfterMs` (429).
+
 ## 0.2.0
 
 ### Minor Changes (BREAKING — modular subpath split)

package/README.md

@@ -1,144 +1,198 @@
 # `@pickleball/expo-sdk`
 
-Foreground livestreaming for Expo iOS and Android, with a headless state-machine API and a ready-made recording screen. Every successful session uses server-side recording.
+Livestream a pickleball match from the phone camera, straight into Pickleball
+Live's RTMP pipeline (hardware H.264 → RTMP → HLS/VOD on R2), with a headless
+state machine, React hooks, a ready-made camera screen, and an Expo config
+plugin. **1.0 is RTMP-only**: LiveKit/WebRTC is gone, the only native
+dependency is `@pickleball/rtmp-native`.
 
-## Modules (v0.2 — subpath split)
+## How a partner app goes live (camera grant)
 
-The root entry is the lean livestream core. Every other feature lives on its own
-subpath — **Metro does not tree-shake, so only import the subpaths your app
-actually uses**:
+```
+Partner app (this SDK)          Partner backend (holds the API key)         Pickleball Live
+──────────────────────          ───────────────────────────────────         ───────────────
+user taps "Go live" ──────────► POST /api/v1/live-sessions
+                                  {cameraGrant:true, matchRef, title,
+                                   quality?, courtRef?}  ── x-api-key ────► creates the session
+◄──── CameraGrant (verbatim) ─── ◄──── {session, cameraGrant} ─────────────
+SDK: Bearer grant.telemetry.token ──────────────────────────────────────► /api/v2/camera/sessions/{id}/
+                                                                            publish|unpublish|refresh|end|
+                                                                            telemetry|commands
+SDK: RTMP (grant.serverUrl + stream key) ───────────────────────────────► MediaMTX → HLS → R2 → VOD
+                                ◄──── webhooks session.live / session.ended / recording.ready (matchRef)
+```
+
+The app never holds an API key and never configures a Pickleball URL: every
+endpoint is derived from the grant. The partner backend has exactly one job —
+issue grants (`@pickleball/server-sdk` `liveSessions.createCameraSession`).
+
+## Modules (Metro does not tree-shake — import only what you use)
 
 | Import | Contents | Extra runtime deps |
 |---|---|---|
-| `@pickleball/expo-sdk` | `PickleballLiveProvider`, `useLivestream`, `LivestreamScreen`, `createHttpSessionProvider`, `createDefaultStorage`, contracts, errors | LiveKit (core) |
-| `@pickleball/expo-sdk/match` | Match scoreboard: `PickleballMatchProvider`, `usePickleballMatch`, scoring engine, SQLite persistence | `expo-sqlite` |
+| `@pickleball/expo-sdk` | `PickleballLiveProvider`, `useLivestream`, `createCameraGrantProvider`, resume (`PickleballAutoResume`, `useStandbySession`, `withResume`), camera settings/controls, `runUplinkCheck`, `createRtmpRuntime`, contracts, errors | `@pickleball/rtmp-native` (peer) |
+| `@pickleball/expo-sdk/ui` | `PickleballCameraScreen`, `CameraControlsSheet`, primitives, `statusPillFor`, copy vi/en | `react-native-safe-area-context` |
+| `@pickleball/expo-sdk/realtime` | `createGrantCommandSubscription` — commands over a Convex websocket instead of 2 s polling | `convex` |
+| `@pickleball/expo-sdk/match` | Match scoreboard: `PickleballMatchProvider`, `usePickleballMatch`, SQLite persistence | `expo-sqlite` |
 | `@pickleball/expo-sdk/match/voice` | Offline score announcer (VI/EN) + TTS | `@pickleball/voice-native`, `expo-audio` |
 | `@pickleball/expo-sdk/match/remote` | BLE/HID court remote input | `@pickleball/remote-native`, Bluetooth permissions |
-| `@pickleball/expo-sdk/device-agent` | Device registry + dashboard remote control (`PickleballDeviceAgent`) | `convex` (bundled only via this subpath) |
-| `@pickleball/expo-sdk/advanced` | `LivestreamEngine`, DI interfaces (`RoomAdapter`, `TelemetrySink`…), default runtime factories, `LiveKitRoomAdapter` — for mocks/tests/custom wiring | — |
+| `@pickleball/expo-sdk/device-agent` | Device registry + dashboard remote control (Pickleball's own fleet app) | `convex` |
+| `@pickleball/expo-sdk/advanced` | `LivestreamEngine`, DI interfaces, `RtmpRoomAdapter`, grant validators — for mocks/tests/custom wiring | — |
 
-Migration from 0.1: symbols that used to come from the root barrel now import
-from the matching subpath above; the provider's `deviceAgent` prop was replaced
-by mounting `<PickleballDeviceAgent/>` (from `/device-agent`) inside the
-provider.
+## Install
 
-## Native requirements
-
-This package requires an Expo Development Build. Expo Go and web are intentionally unsupported because LiveKit needs native WebRTC modules. Supported Expo SDK range: `>=56 <58`.
+```bash
+npx expo install @pickleball/expo-sdk @pickleball/rtmp-native \
+  @react-native-community/netinfo expo-file-system expo-keep-awake expo-sqlite \
+  react-native-safe-area-context
+```
 
-Install the peer dependencies with the versions compatible with your Expo SDK, then add the config plugin and rebuild the native app:
+Add the config plugin and rebuild the native app (Expo Development Build / EAS —
+Expo Go and web cannot run the camera module):
 
 ```json
 {
   "expo": {
     "plugins": [
-      [
-        "@pickleball/expo-sdk",
-        {
-          "cameraPermission": "Allow this app to livestream matches.",
-          "microphonePermission": "Allow this app to capture match audio."
-        }
-      ]
+      ["@pickleball/expo-sdk", {
+        "cameraPermission": "Allow this app to livestream matches.",
+        "microphonePermission": "Allow this app to capture match audio.",
+        "modules": { "remote": false }
+      }]
     ]
   }
 }
 ```
 
-The plugin composes the official LiveKit Expo plugin and declares the WebRTC
-permissions required by LiveKit through Expo CNG; do not edit native projects
-manually. The permission set follows the native requirements documented by the
-MIT-licensed LiveKit React Native/WebRTC projects; this package does not bundle
-the community `@config-plugins/react-native-webrtc` plugin.
-
-### Slimming the native footprint
-
-If the app never uses the BLE/HID court remote, disable its native config so
-the build drops the Bluetooth permissions, the iOS Bluetooth purpose string,
-and the MainActivity key-event patch:
-
-```json
-["@pickleball/expo-sdk", { "modules": { "remote": false } }]
-```
-
-`modules.voice` is accepted for forward compatibility (microphone/audio
-permissions belong to livestreaming, so it currently gates nothing).
+`modules.remote: false` drops the Bluetooth permissions and the MainActivity
+key-event patch when the app does not use the court remote. `modules.livekit`
+and `liveKit` from 0.x are still accepted and ignored. To keep the voice/remote
+native modules out of the binary entirely, add them to `expo.autolinking.exclude`
+in the app's `package.json`.
 
-To strip the unused native modules from the binary entirely, exclude them from
-autolinking in the **app's** `package.json` — safe only if the app never
-activates voice playback or remote scanning at runtime:
-
-```json
-{
-  "expo": {
-    "autolinking": {
-      "exclude": ["@pickleball/voice-native", "@pickleball/remote-native"]
-    }
-  }
-}
-```
-
-## Usage
+## Quick start (casual: the user goes live from the phone)
 
 ```tsx
 import {
-  LivestreamScreen,
   PickleballLiveProvider,
-  createHttpSessionProvider,
+  PickleballAutoResume,
+  createCameraGrantProvider,
+  createCameraSettingsStore,
+  createRtmpRuntime,
+  cameraSettingsKey,
+  rtmpRoomFactoryFor,
+  useCameraSettings,
+  useLivestream,
+  withLocalVideoQuality,
 } from "@pickleball/expo-sdk";
-
-const sessionProvider = createHttpSessionProvider({
-  baseUrl: "https://partner.example.com/mobile/live",
-  headers: async () => ({ Authorization: `Bearer ${await getUserToken()}` }),
+import { PickleballCameraScreen } from "@pickleball/expo-sdk/ui";
+import { createGrantCommandSubscription } from "@pickleball/expo-sdk/realtime";
+
+const settings = createCameraSettingsStore();          // resolution/fps/camera, persisted
+const grants = createCameraGrantProvider({
+  // Your backend: authenticates the user, calls Pickleball REST v1 with the
+  // API key, and returns the CameraGrant verbatim.
+  requestGrant: async (input) => {
+    const res = await fetch(`${API}/matches`, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${await userToken()}`, "Content-Type": "application/json" },
+      body: JSON.stringify({ title: input.title, quality: input.quality }),
+    });
+    return (await res.json()).data.grant;
+  },
 });
+const sessionProvider = withLocalVideoQuality(grants, () => settings.get().resolution);
 
-export function MatchLive() {
+export function LiveRoot({ children }) {
+  const config = useCameraSettings(settings);
   return (
     <PickleballLiveProvider
+      key={cameraSettingsKey(config)}                    // remount → re-prepare on resolution/fps change
       sessionProvider={sessionProvider}
-      bootstrapInput={{
-        sdkVersion: "0.1.0",
-        platform: "ios",
-        bundleId: "com.example.app",
-        installationId: "your-existing-installation-id",
-      }}
+      bootstrapInput={identity}                          // sdkVersion, platform, bundleId, installationId
+      runtime={createRtmpRuntime()}
+      roomFactory={rtmpRoomFactoryFor(config)}
+      keepSessionOnRestart={() => grants.hasResumableSession()}
+      commandSubscription={createGrantCommandSubscription(() => grants.getActiveGrant()?.convexUrl)}
+      locale="vi"
     >
-      <LivestreamScreen
-        input={{
-          externalSessionId: "match-123",
-          title: "Court 1",
-          consentVersion: "2026-01",
-        }}
-      />
+      <PickleballAutoResume provider={grants} resumeInput={{ consentVersion: "2026-09" }} />
+      {children}
     </PickleballLiveProvider>
   );
 }
-```
-
-`createHttpSessionProvider` talks only to the partner-owned proxy routes `/bootstrap`, `/sessions`, `/sessions/:id/refresh`, and `/sessions/:id/end`. It has no API-key option. Keep the Pickleball API key in the backend.
-Production proxy URLs must use HTTPS; plain HTTP is accepted only for loopback development URLs such as `http://localhost:3000`.
-
-Tokens stay in memory. The only persisted value is a bounded `{sessionId, pendingEnd}` record used to finish a session after connectivity returns. Remote policy can change data and flags, but native changes require a semver release and a rebuilt app.
 
-For custom UI, use `useLivestream()` and its `prepare`, `start`, `stop`, `retry`, `switchCamera`, and `setMicrophoneEnabled` actions. `LivestreamScreen` supports Vietnamese/English copy, theme tokens, and preview/header/controls/error render overrides.
+export function CameraRoute({ matchId, title }) {
+  const live = useLivestream();
+  return (
+    <PickleballCameraScreen
+      settings={settings}
+      title={title}
+      onGoLive={() =>
+        live.start(
+          { externalSessionId: `match-${matchId}`, title, consentVersion: "2026-09", quality: settings.get().resolution },
+          { autoPublish: true },
+        )
+      }
+    />
+  );
+}
+```
 
-## Optional: dashboard remote control
+What happens: `start()` asks your backend for a grant, publishes on the server
+(`/publish`), connects RTMP and goes live. The screen shows the status pill,
+lens row, a two-step Stop, a "•••" sheet with resolution/fps/camera/zoom/EV/
+locks/torch/upload-speed check, and dims itself after 30 s live to save heat.
 
-Opt in to device registry + remote start/stop from the operator dashboard by
-mounting `PickleballDeviceAgent` inside the provider (this is the only place
-that pulls the `convex` client into the bundle):
+### Court mode (the phone replaces a fixed court camera)
 
 ```tsx
-import {
-  PickleballDeviceAgent,
-  createHttpDeviceAgentTransport,
-} from "@pickleball/expo-sdk/device-agent";
-
-<PickleballLiveProvider sessionProvider={sessionProvider} bootstrapInput={identity}>
-  <PickleballDeviceAgent
-    transport={createHttpDeviceAgentTransport({ baseUrl: proxyUrl, headers })}
-    remoteStart={{ consentVersion: "2026-01", defaultTitle: "Court 1" }}
-    onRemoteSessionStarted={(sessionId) => router.push("/livestream")}
-  />
-  {children}
-</PickleballLiveProvider>
+const { armed } = useStandbySession({
+  input: { externalSessionId: `court-${courtRef}-${n}`, title: `${courtRef} — chờ trận`,
+           consentVersion: "2026-09", metadata: { courtRef } },
+  resumeSessionId: hintFromYourBackend ?? null,
+});
+<PickleballCameraScreen mode="court" settings={settings} courtLabel={courtRef} />
 ```
+
+Your backend forwards `courtRef` when it creates the session; the phone waits in
+standby (12 h preset) and the referee's `POST /api/v1/courts/{courtRef}/match-start`
+flips it live through the command channel; `match-end` ends it. Only one camera
+can hold a court — a fleet device already assigned there returns
+`COURT_HAS_DEVICE`.
+
+### Resume after the app is killed
+
+The provider stores `{sessionId, base, Bearer}` in the app sandbox (expo-sqlite
+localStorage by default — pass `storage` to use `expo-secure-store`). On the next
+launch `PickleballAutoResume` refreshes the grant and re-joins the same session
+(same watch link, one VOD); a session the server no longer holds is abandoned
+cleanly. Call `grants.clearStoredSession()` on logout and end the session from
+your backend.
+
+## Behaviour to know
+
+- `standby` is free: no recording until `/publish`. Casual sessions end after
+  15 min of standby, 90 s in background, 3 h max; court-bound sessions get
+  12 h / 5 min / 6 h.
+- A re-issued grant (your backend calls `/camera-grant` again) supersedes the
+  previous one: the old phone gets `409` with `reason: "superseded"` on its next
+  poll and stops at once. One grant = one phone.
+- Errors surface as `PickleballExpoError` with `code` (`PERMISSION_DENIED`,
+  `NETWORK_UNAVAILABLE`, `TOKEN_EXPIRED`, `SESSION_CONFLICT`, …), `httpStatus`,
+  and for `SESSION_CONFLICT` a `reason` (`superseded | ended | expired`).
+- Tokens live only in the grant; the SDK never sees an API key. Keep the key
+  in your backend.
+
+## Migration 0.2 → 1.0
+
+| 0.2 | 1.0 |
+|---|---|
+| `LivestreamScreen` (root) | `PickleballCameraScreen` from `@pickleball/expo-sdk/ui` |
+| `createHttpSessionProvider` + partner proxy (6 routes, authz gateway) | `createCameraGrantProvider` + one backend endpoint that returns a grant |
+| `createDefaultRuntime` (LiveKit) | `createRtmpRuntime` (`createDefaultRuntime` is now an alias) |
+| `createRtmpRoomFactory` from `/advanced` | root export |
+| LiveKit peers + `modules.livekit` | removed; `@pickleball/rtmp-native >=0.2.0` required |
+
+`createHttpSessionProvider` still exists for first-party namespaces, but only
+accepts `rtmp(s)://` grants.

package/dist/advanced-DcbHBCGb.d.ts

@@ -0,0 +1,300 @@
+import { R as RoomAdapter, a1 as RoomConnection, e as CameraDeviceInfo, g as CaptureOrientation, a2 as RoomEvent, r as SdkBootstrap, C as CameraGrant, b as SdkSessionGrant, y as SdkSessionRefresh, z as SdkTelemetryCredentials, a3 as EngineDependencies, w as SdkNetwork, x as SdkRuntime, a as SdkStorage, T as TelemetrySink, a0 as LivestreamEngine, B as BootstrapInput, m as LivestreamSnapshot, c as StartLivestreamInput, i as EndReason, L as LivestreamSessionProvider, H as SessionCommandChannel, S as SessionCommandSubscription, o as PickleballExpoError } from './engine-BSvSdCSE.js';
+import React, { ReactNode } from 'react';
+
+/**
+ * Trạng thái từ tầng RTMP native (trùng NativeRtmpStatus của @pickleball/rtmp-native).
+ */
+type RtmpStatus = {
+    readonly status: "idle" | "connecting" | "connected" | "publishing";
+} | {
+    readonly status: "disconnected";
+    readonly reason?: string;
+} | {
+    readonly status: "error";
+    readonly code: string;
+    readonly message: string;
+};
+/** Phản hồi băng thông từ native (trùng NativeRtmpBandwidth của rtmp-native). */
+interface RtmpBandwidth {
+    /** false = encoder đang đẩy nhanh hơn đường truyền chịu được. */
+    readonly sufficient: boolean;
+    readonly videoBitrate: number;
+}
+/**
+ * Dấu hiệu để UI biết render nguồn nào. LiveKit trả về một track object; RTMP
+ * không có "track" ở JS (khung hình đi thẳng trong native), nên trả marker này
+ * — nếu trả undefined thì UI tưởng chưa có preview và vẽ màn TỐI ĐEN.
+ */
+interface RtmpPreviewMarker {
+    readonly kind: "rtmp";
+}
+/** Bề mặt native mà adapter cần — tiêm vào để test được không cần thiết bị thật. */
+interface NativeRtmpBindings {
+    prepare(options: {
+        quality: 720 | 1080;
+        landscape: boolean;
+        /** fps mong muốn (24 tiết kiệm băng thông, 30 mặc định) — thiếu = native tự chọn. */
+        frameRate?: 24 | 30 | 60;
+        /**
+         * Camera mở ngay từ đầu. Thiếu = native dùng camera sau mặc định. Đặt ở đây
+         * thay vì gọi selectCamera sau prepare để không phải mở camera hai lần.
+         */
+        cameraId?: string;
+    }): Promise<void>;
+    /**
+     * Xin quyền camera/mic bằng API quyền thuần (PermissionsAndroid, ...).
+     * Không có thì engine rơi về getUserMedia của WebRTC — thứ mở camera thật
+     * và đụng HaishinKit trên máy Android chỉ cho một camera mở cùng lúc.
+     */
+    requestPermissions?(): Promise<boolean>;
+    /** Hướng cầm máy hiện tại — cùng nguồn mà LiveKitRoomAdapter dùng. */
+    isLandscape?(): boolean;
+    connect(options: {
+        url: string;
+        videoBitrate: number;
+        publish: boolean;
+    }): Promise<void>;
+    setPublishing(enabled: boolean): Promise<void>;
+    disconnect(): Promise<void>;
+    switchCamera(): Promise<void>;
+    listCameras(): Array<{
+        deviceId: string;
+        label: string;
+        facing: string;
+    }>;
+    selectCamera(deviceId: string, facing: string): Promise<void>;
+    setMicrophoneEnabled(enabled: boolean): Promise<void>;
+    setVideoBitrate(bitsPerSecond: number): Promise<void>;
+    dispose(): Promise<void>;
+    addStatusListener(listener: (event: RtmpStatus) => void): {
+        remove(): void;
+    };
+    /** Optional: bản native cũ chưa phát onBandwidth thì adapter bỏ qua thích ứng. */
+    addBandwidthListener?(listener: (event: RtmpBandwidth) => void): {
+        remove(): void;
+    };
+}
+/**
+ * Adapter cho mode deliveryMode="device-rtmp".
+ *
+ * Thiết bị mã hoá H.264 bằng phần cứng MỘT lần rồi đẩy thẳng RTMP; server chỉ
+ * remux sang HLS. Không có phòng LiveKit, không egress → $0 transcode.
+ *
+ * Khác LiveKitRoomAdapter ở một điểm quan trọng: RTMP **không có kênh dữ liệu**,
+ * nên adapter này không bao giờ phát RoomEvent "command". Lệnh điều khiển từ
+ * dashboard đi đường khác (deviceControl trên Convex) — xem device-agent.
+ */
+declare class RtmpRoomAdapter implements RoomAdapter {
+    private readonly bindings;
+    private readonly options;
+    /**
+     * RTMP không tự hồi: native chỉ phát hiện đứt (watchdog iOS / onDisconnect
+     * Android) và báo "disconnected" — không tự quay số lại. Engine thấy cờ này
+     * là chạy vòng redial backoff. Thiếu cờ: phiên ngồi chờ "reconnected" không
+     * bao giờ tới rồi chết network_timeout sau 30s (prod 17/08/2026).
+     */
+    readonly needsManualReconnect = true;
+    private readonly listeners;
+    private nativeSubscription?;
+    private bandwidthSubscription?;
+    private quality;
+    private connected;
+    private prepared;
+    /** Khung người dùng chọn trên UI (9:16/16:9) — ưu tiên hơn hướng cầm máy. */
+    private captureOrientation?;
+    private bitrateState?;
+    /**
+     * Chỉ tồn tại khi bindings hỗ trợ — engine kiểm tra truthiness để quyết định
+     * fallback về runtime.requestPermissions() (getUserMedia), nên KHÔNG được
+     * khai báo method luôn-có rồi tự fallback bên trong.
+     */
+    readonly requestPermissions?: () => Promise<boolean>;
+    constructor(bindings: NativeRtmpBindings, options?: {
+        frameRate?: 24 | 30 | 60;
+        cameraId?: string;
+    });
+    /**
+     * Phần tuỳ chọn của prepare(). Giữ dạng spread có điều kiện: truyền
+     * `frameRate: undefined` xuống Expo Record là ghi đè mặc định của native
+     * bằng null chứ không phải "bỏ qua trường".
+     */
+    private prepareOverrides;
+    preparePreview(quality: 720 | 1080): Promise<RtmpPreviewMarker>;
+    connect(input: RoomConnection): Promise<void>;
+    setPublishing(enabled: boolean): Promise<void>;
+    disconnect(_stopTracks?: boolean): Promise<void>;
+    switchCamera(): Promise<void>;
+    /** Ống kính vật lý (0.5x siêu rộng · 1x · tele) — không có thì UI kẹt ở mặc định. */
+    listCameras(): Promise<CameraDeviceInfo[]>;
+    selectCamera(deviceId: string, facing: CameraDeviceInfo["facing"]): Promise<void>;
+    setMicrophoneEnabled(enabled: boolean): Promise<void>;
+    /** Hạ chất lượng khi mạng yếu — thay cho BWE mà WebRTC cho sẵn. */
+    setVideoBitrate(bitsPerSecond: number): Promise<void>;
+    setCaptureOrientation(orientation: CaptureOrientation): Promise<void>;
+    subscribe(listener: (event: RoomEvent) => void): () => void;
+    dispose(): Promise<void>;
+    private handleBandwidth;
+    private emit;
+}
+
+/**
+ * Validator + helper HTTP dùng chung cho hai session provider:
+ * - createHttpSessionProvider (proxy đối tác / first-party device-app)
+ * - createCameraGrantProvider (điện thoại đối tác, grant từ backend đối tác)
+ *
+ * Tách ra để hai provider không chép luật "grant thế nào là hợp lệ" ra hai nơi
+ * rồi lệch nhau; engine chỉ tin `isSdkRemoteConfig`, còn hình dạng grant là
+ * việc của lớp này.
+ */
+type Fetch = typeof globalThis.fetch;
+declare function isBootstrap(value: unknown): value is SdkBootstrap;
+declare function isTelemetryCredentials(value: unknown): value is SdkTelemetryCredentials;
+/**
+ * Grant phiên. SDK 1.0 là RTMP-only: `serverUrl` phải là rtmp(s):// (ingest).
+ * Grant LiveKit (wss://) của mô hình cũ bị từ chối ngay ở đây — lỗi
+ * INVALID_RESPONSE rõ ràng thay vì HaishinKit ném lúc connect.
+ */
+declare function isSessionGrant(value: unknown): value is SdkSessionGrant;
+/**
+ * Camera grant (điện thoại đối tác): superset của SdkSessionGrant, BẮT BUỘC là
+ * RTMP và mang `status` để đường nhận lại biết phiên cũ đang phát hay đang chờ.
+ */
+declare function isCameraGrant(value: unknown): value is CameraGrant;
+declare function isSessionRefresh(value: unknown): value is SdkSessionRefresh;
+/**
+ * Gốc API của phiên suy từ endpoint telemetry trong grant: `…/sessions/{id}/telemetry`
+ * → `…/sessions/{id}`. Đây là cách duy nhất SDK biết namespace (sdk / camera /
+ * device-app) mà không cần app cấu hình URL PickLive nào.
+ */
+declare function sessionApiBaseFromTelemetryEndpoint(endpoint: string): string;
+
+/**
+ * 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.
+ */
+declare function createRtmpRuntime(): SdkRuntime;
+/** Runtime mặc định của SDK 1.0 = RTMP (LiveKit đã gỡ khỏi SDK — ADR-0002). */
+declare const createDefaultRuntime: typeof createRtmpRuntime;
+declare function createDefaultStorage(): SdkStorage;
+declare function createDefaultNetwork(): SdkNetwork;
+declare function createDefaultTelemetry(fetchImplementation?: typeof fetch, timeoutMs?: number): TelemetrySink;
+/** roomFactory mặc định của SDK 1.0 = RTMP (fps/camera mặc định của native). */
+declare function createDefaultRoomFactory(): EngineDependencies["roomFactory"];
+/**
+ * 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.
+ */
+declare function createNativeRtmpBindings(): NativeRtmpBindings;
+/** roomFactory cho mode device-rtmp (thiết bị đẩy RTMP, không dùng LiveKit). */
+declare 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"];
+/**
+ * Thu chỉ số thiết bị cho heartbeat. Mỗi nguồn là optional — thiếu package
+ * (expo-battery/expo-device/expo-file-system) thì bỏ qua trường đó thay vì lỗi.
+ */
+declare function createDefaultDeviceMetrics(): NonNullable<EngineDependencies["deviceMetrics"]>;
+
+interface LivestreamTheme {
+    background: string;
+    foreground: string;
+    accent: string;
+    danger: string;
+    /** Chữ phụ mờ nhất (labels, chú thích). */
+    muted: string;
+    overlay: string;
+    radius: number;
+    /** Token FintechX — đồng bộ với dashboard web. */
+    surface: string;
+    elevated: string;
+    hairline: string;
+    /** Màu chữ đặt trên nền accent. */
+    ink: string;
+    textSecondary: string;
+    radiusSm: number;
+    fontFamily?: string;
+    fontFamilyBold?: string;
+    displayFontFamily?: string;
+}
+/** FintechX design tokens — trùng bộ token trong apps/web/globals.css. */
+declare const defaultLivestreamTheme: LivestreamTheme;
+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>;
+    locale?: "vi" | "en";
+    onError?: (error: PickleballExpoError) => void;
+}
+/**
+ * Context nội bộ cho các module opt-in (VD PickleballDeviceAgent) cần truy cập
+ * engine trực tiếp — export qua "./advanced", không thuộc API tích hợp cơ bản.
+ */
+interface LivestreamHostContextValue {
+    engine: LivestreamEngine;
+    bootstrapInput: BootstrapInput;
+    deviceMetrics: NonNullable<EngineDependencies["deviceMetrics"]>;
+}
+declare function useLivestreamHost(): LivestreamHostContextValue;
+interface LivestreamContextValue extends LivestreamSnapshot {
+    locale: "vi" | "en";
+    theme: LivestreamTheme;
+    prepare(): Promise<void>;
+    start(input: StartLivestreamInput, options?: {
+        autoPublish?: boolean;
+    }): Promise<void>;
+    /** Bắt đầu phát khi đang standby. */
+    startPublishing(): Promise<void>;
+    /** Tạm dừng phát về standby (không kết thúc phiên). */
+    stopPublishing(): Promise<void>;
+    stop(reason?: EndReason): Promise<void>;
+    retry(): Promise<void>;
+    switchCamera(): Promise<void>;
+    setMicrophoneEnabled(enabled: boolean): Promise<void>;
+    setCaptureOrientation(orientation: "portrait" | "landscape"): Promise<void>;
+    selectCamera(deviceId: string): Promise<void>;
+}
+declare function PickleballLiveProvider(props: PickleballLiveProviderProps): React.JSX.Element;
+declare function useLivestream(): LivestreamContextValue;
+
+export { type Fetch as F, type LivestreamContextValue as L, type NativeRtmpBindings as N, PickleballLiveProvider as P, RtmpRoomAdapter as R, type LivestreamTheme as a, type PickleballLiveProviderProps as b, createDefaultStorage as c, createRtmpRoomFactory as d, createRtmpRuntime as e, defaultLivestreamTheme as f, type LivestreamHostContextValue as g, type RtmpStatus as h, createDefaultDeviceMetrics as i, createDefaultNetwork as j, createDefaultRoomFactory as k, createDefaultRuntime as l, createDefaultTelemetry as m, createNativeRtmpBindings as n, isBootstrap as o, isCameraGrant as p, isSessionGrant as q, isSessionRefresh as r, isTelemetryCredentials as s, sessionApiBaseFromTelemetryEndpoint as t, useLivestream as u, useLivestreamHost as v };