@pickleball/expo-sdk 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @pickleball/expo-sdk
 
+## 0.2.0
+
+### Minor Changes (BREAKING — modular subpath split)
+
+- Root entry (`@pickleball/expo-sdk`) is now the lean livestream core only:
+  `PickleballLiveProvider`, `useLivestream`, `LivestreamScreen`,
+  `createHttpSessionProvider`, `createDefaultStorage`, contracts, errors, version.
+- Feature clusters moved to subpaths (Metro does not tree-shake — import only
+  what the app uses): `@pickleball/expo-sdk/match`, `/match/voice`,
+  `/match/remote`, `/device-agent`, `/advanced` (engine internals, DI, mocks).
+- `PickleballLiveProvider` no longer accepts the `deviceAgent` prop. Mount
+  `<PickleballDeviceAgent/>` (from `/device-agent`) inside the provider instead —
+  this keeps `convex` out of the bundle for apps that never use remote control.
+- Config plugin: new `modules: { remote?: boolean; voice?: boolean }` props.
+  `modules.remote: false` drops the Bluetooth permissions/purpose string and the
+  MainActivity HID patch. To strip the native modules from the binary entirely,
+  exclude `@pickleball/voice-native` / `@pickleball/remote-native` via
+  `expo.autolinking.exclude` (see README).
+- Removed unused `expo-speech` dependency.
+
+Migration 0.1 → 0.2: imports of match/voice/remote/device-agent/engine symbols
+move from the root barrel to the matching subpath; `deviceAgent` prop becomes
+`<PickleballDeviceAgent/>`.
+
 ## 0.1.1
 
 ### Patch Changes

package/README.md

@@ -2,6 +2,26 @@
 
 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.
 
+## Modules (v0.2 — subpath split)
+
+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**:
+
+| 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/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 | — |
+
+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.
+
 ## 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`.
@@ -30,6 +50,33 @@ 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).
+
+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
 
 ```tsx
@@ -73,3 +120,25 @@ Production proxy URLs must use HTTPS; plain HTTP is accepted only for loopback d
 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.
+
+## Optional: dashboard remote control
+
+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):
+
+```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>
+```

package/dist/advanced-BXDrDl1h.d.ts

@@ -0,0 +1,316 @@
+import { j as RoomAdapter, C as CameraDeviceInfo, V as RoomConnection, W as RoomEvent, a as CaptureOrientation, X as EngineDependencies, p as SdkNetwork, r as SdkRuntime, u as SdkStorage, T as TelemetrySink, Q as LivestreamEngine, B as BootstrapInput, g as LivestreamSnapshot, S as StartLivestreamInput, c as EndReason, L as LivestreamSessionProvider, i as PickleballExpoError } from './engine-CCSSqPbZ.js';
+import React, { ReactNode } from 'react';
+
+interface LocalTrackLike {
+    kind: string;
+    stop(): void;
+    mute?(): Promise<unknown>;
+    unmute?(): Promise<unknown>;
+    /** livekit-client LocalVideoTrack restart; deterministic facing switch. */
+    restartTrack?(options: {
+        facingMode?: "user" | "environment";
+        deviceId?: string;
+        resolution?: {
+            width: number;
+            height: number;
+            frameRate: number;
+        };
+    }): Promise<unknown>;
+    mediaStreamTrack?: {
+        readyState?: string;
+        /**
+         * react-native-webrtc: đổi thiết bị/facing TẠI CHỖ trên cùng track native
+         * (mediaStreamTrackApplyConstraints) — preview và sender giữ nguyên.
+         */
+        applyConstraints?(constraints: {
+            facingMode?: "user" | "environment";
+            deviceId?: string;
+            width?: number;
+            height?: number;
+            frameRate?: number;
+        }): Promise<void>;
+        /** react-native-webrtc native camera flip; blind front/back toggle. */
+        _switchCamera?(): void;
+    };
+}
+interface RoomLike {
+    state: string;
+    localParticipant: {
+        publishTrack(track: LocalTrackLike, options?: unknown): Promise<unknown>;
+        unpublishTrack?(track: LocalTrackLike, stopOnUnpublish?: boolean): Promise<unknown> | unknown;
+    };
+    connect(serverUrl: string, token: string, options?: unknown): Promise<void>;
+    disconnect(stopTracks?: boolean): Promise<void>;
+    on(event: string, listener: (...args: unknown[]) => void): unknown;
+    off(event: string, listener: (...args: unknown[]) => void): unknown;
+}
+interface NativeLiveKitBindings {
+    registerGlobals(): void;
+    createRoom(): RoomLike;
+    createLocalTracks(options: {
+        audio: true;
+        video: {
+            facingMode?: "user" | "environment";
+            deviceId?: string;
+            resolution: {
+                width: number;
+                height: number;
+                frameRate: number;
+            };
+        };
+    }): Promise<LocalTrackLike[]>;
+    startAudioSession(): Promise<void> | void;
+    stopAudioSession(): Promise<void> | void;
+    /** Current window orientation; capture dimensions follow it. */
+    isLandscape?(): boolean;
+    /** Physical/virtual cameras reported by the platform. */
+    listCameras?(): Promise<CameraDeviceInfo[]>;
+    cameraSource?: unknown;
+    events: {
+        reconnecting: string;
+        reconnected: string;
+        disconnected: string;
+        mediaDevicesError: string;
+        /** LiveKit RoomEvent.DataReceived — nhận lệnh điều khiển từ dashboard. */
+        dataReceived?: string;
+    };
+}
+interface LocalPreviewReference {
+    videoTrack: unknown;
+    trackRef?: {
+        participant: RoomLike["localParticipant"];
+        publication: unknown;
+        source?: unknown;
+    };
+}
+declare class LiveKitRoomAdapter implements RoomAdapter {
+    private readonly bindings;
+    private readonly room;
+    private readonly listeners;
+    private tracks;
+    private videoTrack?;
+    private audioTrack?;
+    private preview?;
+    private isFront;
+    private orientationOverride;
+    private deviceOverride;
+    private published;
+    private disposed;
+    private quality;
+    private readonly nativeListeners;
+    constructor(bindings: NativeLiveKitBindings);
+    preparePreview(quality: 720 | 1080): Promise<LocalPreviewReference | undefined>;
+    connect(input: RoomConnection): Promise<void>;
+    /** Bật/tắt publish track khi đã trong phòng — standby ↔ live. */
+    setPublishing(enabled: boolean): Promise<void>;
+    disconnect(stopTracks?: boolean): Promise<void>;
+    private captureResolution;
+    /**
+     * Tùy chọn publish video. Mặc định của livekit-client (VP8, không encoding,
+     * không degradation preference) khiến uplink yếu bóp bitrate xuống ~600kbps
+     * mà VẪN giữ 1080 @ ~10fps → khối bể nát, tệ hơn 720p sạch.
+     *
+     * - videoCodec H.264: HW-encode trên Android, hiệu quả hơn VP8 ở bitrate thấp,
+     *   trùng preset egress (H264_*) nên bỏ được 1 lần transcode phía egress.
+     * - simulcast tắt: viewer chỉ xem HLS do egress xuất; egress subscribe đúng
+     *   1 lớp đã publish, nên simulcast chỉ thêm tải/bất ổn encoder (H.264 simulcast
+     *   kém tin cậy trên Android) mà không lợi gì cho người xem ở kiến trúc này.
+     * - maintain-framerate: pickleball chuyển động nhanh; khi uplink không gánh nổi
+     *   mức đích thì HẠ ĐỘ PHÂN GIẢI (giữ nét-trên-điểm-ảnh) thay vì đóng băng fps.
+     * - maxBitrate: trần theo mức chất lượng; BWE vẫn tự hạ dưới trần khi mạng yếu.
+     */
+    private videoPublishOptions;
+    setCaptureOrientation(orientation: "portrait" | "landscape"): Promise<void>;
+    /**
+     * livekit-client restart() chỉ giữ deviceId/facingMode khi gọi getUserMedia
+     * (vứt width/height/frameRate) nên track mới rơi về format mặc định
+     * 640x480. Native applyConstraints thì ngược lại: chỉ xử lý
+     * width/height/frameRate. Sau mỗi restartTrack phải nắn lại format trên
+     * track mới bằng applyConstraints.
+     */
+    private reapplyCaptureFormat;
+    switchCamera(): Promise<void>;
+    listCameras(): Promise<CameraDeviceInfo[]>;
+    selectCamera(deviceId: string, facing: CameraDeviceInfo["facing"]): Promise<void>;
+    setMicrophoneEnabled(enabled: boolean): Promise<void>;
+    subscribe(listener: (event: RoomEvent) => void): () => boolean;
+    dispose(): Promise<void>;
+    private releaseTracks;
+    private ensurePreparedTracks;
+    private emit;
+    private ensureNotDisposed;
+}
+
+/**
+ * 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;
+};
+/**
+ * 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;
+    }): Promise<void>;
+    /** 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;
+    };
+}
+/**
+ * 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 listeners;
+    private nativeSubscription?;
+    private quality;
+    private connected;
+    constructor(bindings: NativeRtmpBindings);
+    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 emit;
+}
+
+declare function createNativeLiveKitBindings(): NativeLiveKitBindings;
+declare function createDefaultRuntime(): SdkRuntime;
+declare function createDefaultStorage(): SdkStorage;
+declare function createDefaultNetwork(): SdkNetwork;
+declare function createDefaultTelemetry(fetchImplementation?: typeof fetch, timeoutMs?: number): TelemetrySink;
+declare function createDefaultRoomFactory(): EngineDependencies["roomFactory"];
+/**
+ * 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.
+ */
+declare function createNativeRtmpBindings(): NativeRtmpBindings;
+/** roomFactory cho mode device-rtmp (thiết bị đẩy RTMP, không dùng LiveKit). */
+declare function createRtmpRoomFactory(): 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;
+    runtime?: SdkRuntime;
+    storage?: SdkStorage;
+    network?: SdkNetwork;
+    telemetry?: TelemetrySink;
+    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 LivestreamContextValue as L, type NativeLiveKitBindings as N, PickleballLiveProvider as P, RtmpRoomAdapter as R, type LivestreamTheme as a, type PickleballLiveProviderProps as b, createDefaultStorage as c, defaultLivestreamTheme as d, LiveKitRoomAdapter as e, type LivestreamHostContextValue as f, type LocalPreviewReference as g, type NativeRtmpBindings as h, type RtmpStatus as i, createDefaultDeviceMetrics as j, createDefaultNetwork as k, createDefaultRoomFactory as l, createDefaultRuntime as m, createDefaultTelemetry as n, createNativeLiveKitBindings as o, createNativeRtmpBindings as p, createRtmpRoomFactory as q, useLivestreamHost as r, useLivestream as u };