@pickleball/expo-sdk 0.1.1 → 0.2.0

package/src/device-agent/component.tsx

@@ -0,0 +1,49 @@
+import { useEffect, useRef } from "react";
+import { useLivestreamHost } from "../provider";
+import {
+  DeviceAgent,
+  type DeviceAgentDeviceInfo,
+  type DeviceAgentTransport,
+  type DeviceControlChannel,
+  type RemoteStartConfig,
+} from "./agent";
+
+/**
+ * Bật device-agent: đăng ký thiết bị + heartbeat presence khi app mở, nhận
+ * lệnh start/stop livestream từ dashboard qua kênh điều khiển on-demand.
+ * Render bên trong PickleballLiveProvider (thường là child đầu tiên).
+ * Tách khỏi provider để app không dùng tính năng này không bundle convex.
+ */
+export interface PickleballDeviceAgentProps {
+  transport: DeviceAgentTransport;
+  remoteStart: RemoteStartConfig;
+  deviceInfo?: DeviceAgentDeviceInfo;
+  onRemoteSessionStarted?: (sessionId: string) => void;
+  createControlChannel?: (convexUrl: string) => DeviceControlChannel;
+}
+
+export function PickleballDeviceAgent(props: PickleballDeviceAgentProps) {
+  const host = useLivestreamHost();
+
+  // Giữ tham chiếu mới nhất để agent (tạo 1 lần) luôn gọi callback hiện hành
+  const propsRef = useRef(props);
+  propsRef.current = props;
+
+  useEffect(() => {
+    const agent = new DeviceAgent({
+      engine: host.engine,
+      bootstrapInput: host.bootstrapInput,
+      deviceMetrics: host.deviceMetrics,
+      transport: propsRef.current.transport,
+      remoteStart: propsRef.current.remoteStart,
+      deviceInfo: propsRef.current.deviceInfo,
+      createControlChannel: propsRef.current.createControlChannel,
+      onRemoteSessionStarted: (sessionId) =>
+        propsRef.current.onRemoteSessionStarted?.(sessionId),
+    });
+    agent.start();
+    return () => agent.stop();
+  }, [host]);
+
+  return null;
+}

package/src/device-agent/convex-control-channel.ts

@@ -0,0 +1,82 @@
+import { ConvexClient } from "convex/browser";
+import { anyApi } from "convex/server";
+import type { DeviceCommand, DeviceControlChannel } from "./agent";
+
+/**
+ * Kênh điều khiển realtime mặc định: Convex websocket subscribe các function
+ * deviceControl (auth bằng connect-token nhận qua heartbeat — thiết bị không
+ * có account, pattern pairingCode). Chỉ mở khi dashboard yêu cầu "Kết nối",
+ * đóng ngay khi kênh kết thúc → không giữ websocket lúc idle.
+ */
+export function createConvexControlChannel(convexUrl: string): DeviceControlChannel {
+  const client = new ConvexClient(convexUrl);
+  const deviceControl = anyApi.deviceControl;
+
+  function toCommands(value: unknown): DeviceCommand[] {
+    if (!Array.isArray(value)) return [];
+    const commands: DeviceCommand[] = [];
+    for (const item of value) {
+      if (item === null || typeof item !== "object") continue;
+      const record = item as Record<string, unknown>;
+      if (
+        typeof record.id !== "string" ||
+        (record.type !== "start_livestream" && record.type !== "stop_livestream") ||
+        typeof record.expiresAt !== "number"
+      ) {
+        continue;
+      }
+      const payload =
+        record.payload !== null &&
+        typeof record.payload === "object" &&
+        !Array.isArray(record.payload)
+          ? (record.payload as Record<string, unknown>)
+          : {};
+      commands.push({
+        id: record.id,
+        type: record.type,
+        payload: {
+          ...(typeof payload.title === "string" ? { title: payload.title } : {}),
+          ...(payload.visibility === "public" || payload.visibility === "private"
+            ? { visibility: payload.visibility }
+            : {}),
+        },
+        expiresAt: record.expiresAt,
+      });
+    }
+    return commands;
+  }
+
+  return {
+    async attach(controlSessionId, token) {
+      await client.mutation(deviceControl.deviceAttach, { controlSessionId, token });
+    },
+    onCommands(controlSessionId, token, callback) {
+      return client.onUpdate(
+        deviceControl.pendingCommands,
+        { controlSessionId, token },
+        (value) => callback(toCommands(value)),
+      );
+    },
+    onState(controlSessionId, token, callback) {
+      return client.onUpdate(
+        deviceControl.controlSessionState,
+        { controlSessionId, token },
+        (value) => {
+          const status =
+            value !== null &&
+            typeof value === "object" &&
+            typeof (value as Record<string, unknown>).status === "string"
+              ? ((value as Record<string, unknown>).status as string)
+              : "ended";
+          callback({ status });
+        },
+      );
+    },
+    async ack(input) {
+      await client.mutation(deviceControl.ackCommand, { ...input });
+    },
+    close() {
+      void client.close();
+    },
+  };
+}

package/src/device-agent/http-transport.ts

@@ -0,0 +1,143 @@
+import type { BootstrapInput } from "../contracts";
+import type {
+  DeviceAgentDeviceInfo,
+  DeviceAgentTransport,
+  DeviceControlSessionGrant,
+  DeviceHeartbeatBody,
+} from "./agent";
+import {
+  ExpoSdkConfigurationError,
+  ExpoSdkTimeoutError,
+  InvalidResponseError,
+  NetworkUnavailableError,
+  PickleballExpoError,
+  errorFromCode,
+} from "../errors";
+
+type Fetch = typeof globalThis.fetch;
+type HeadersInput = Record<string, string>;
+
+export interface HttpDeviceAgentTransportOptions {
+  /** Base URL của proxy đối tác (cùng proxy với session provider). */
+  baseUrl: string;
+  fetch?: Fetch;
+  headers?: HeadersInput | (() => HeadersInput | Promise<HeadersInput>);
+  timeoutMs?: number;
+  paths?: Partial<{ register: string; heartbeat: string }>;
+}
+
+const defaultPaths = {
+  register: "/devices/register",
+  heartbeat: "/devices/heartbeat",
+};
+
+/** Transport HTTP cho DeviceAgent — mirror createHttpSessionProvider. */
+export function createHttpDeviceAgentTransport(
+  options: HttpDeviceAgentTransportOptions,
+): DeviceAgentTransport {
+  const baseUrl = options.baseUrl.replace(/\/+$/, "");
+  if (baseUrl === "") {
+    throw new ExpoSdkConfigurationError("baseUrl must be a non-empty string");
+  }
+  const fetchImplementation = options.fetch ?? globalThis.fetch;
+  if (typeof fetchImplementation !== "function") {
+    throw new ExpoSdkConfigurationError("A Fetch API implementation is required");
+  }
+  const paths = { ...defaultPaths, ...options.paths };
+
+  async function post(path: string, body: unknown): Promise<unknown> {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? 10_000);
+    try {
+      const extraHeaders =
+        typeof options.headers === "function"
+          ? await options.headers()
+          : (options.headers ?? {});
+      const response = await fetchImplementation(
+        `${baseUrl}/${path.replace(/^\/+/, "")}`,
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json", ...extraHeaders },
+          body: JSON.stringify(body),
+          signal: controller.signal,
+          redirect: "error",
+        },
+      );
+      const envelope = await response.json().catch(() => {
+        throw new InvalidResponseError();
+      });
+      if (!response.ok) throw parseProxyError(envelope);
+      if (!isRecord(envelope) || !("data" in envelope)) {
+        throw new InvalidResponseError();
+      }
+      return envelope.data;
+    } catch (error) {
+      if (controller.signal.aborted) throw new ExpoSdkTimeoutError();
+      if (error instanceof PickleballExpoError) throw error;
+      if (error instanceof TypeError) {
+        throw new NetworkUnavailableError(undefined, { cause: error });
+      }
+      throw error;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+  return {
+    async register(input: BootstrapInput & DeviceAgentDeviceInfo) {
+      const data = await post(paths.register, input);
+      if (
+        !isRecord(data) ||
+        typeof data.deviceId !== "string" ||
+        typeof data.heartbeatIntervalMs !== "number" ||
+        !Number.isFinite(data.heartbeatIntervalMs)
+      ) {
+        throw new InvalidResponseError();
+      }
+      return {
+        deviceId: data.deviceId,
+        heartbeatIntervalMs: data.heartbeatIntervalMs,
+      };
+    },
+    async heartbeat(input: BootstrapInput & DeviceHeartbeatBody) {
+      const data = await post(paths.heartbeat, input);
+      if (!isRecord(data)) throw new InvalidResponseError();
+      const grant = data.controlSession;
+      if (grant === null || grant === undefined) return { controlSession: null };
+      if (
+        !isRecord(grant) ||
+        typeof grant.id !== "string" ||
+        typeof grant.token !== "string" ||
+        typeof grant.convexUrl !== "string" ||
+        grant.convexUrl === ""
+      ) {
+        throw new InvalidResponseError();
+      }
+      return {
+        controlSession: {
+          id: grant.id,
+          token: grant.token,
+          convexUrl: grant.convexUrl,
+        } satisfies DeviceControlSessionGrant,
+      };
+    },
+  };
+}
+
+function parseProxyError(envelope: unknown) {
+  if (
+    isRecord(envelope) &&
+    isRecord(envelope.error) &&
+    typeof envelope.error.code === "string"
+  ) {
+    return errorFromCode(
+      envelope.error.code,
+      typeof envelope.error.message === "string" ? envelope.error.message : undefined,
+    );
+  }
+  return new InvalidResponseError();
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/device-agent/index.ts

@@ -0,0 +1,4 @@
+export * from "./agent";
+export * from "./http-transport";
+export { createConvexControlChannel } from "./convex-control-channel";
+export { PickleballDeviceAgent, type PickleballDeviceAgentProps } from "./component";

package/src/engine.ts

@@ -18,6 +18,7 @@ import {
   SdkDisabledError,
   SessionConflictError,
   UnsupportedSdkError,
+  isSessionGoneError,
   normalizeError,
 } from "./errors";
 import { isSdkRemoteConfig, isSdkVersionSupported } from "./contracts";
@@ -240,7 +241,11 @@ export class LivestreamEngine {
       sessionId: null,
       previewTrack: null,
       isMicrophoneEnabled: true,
-      isCameraFront: true,
+      // Camera SAU mặc định: thiết bị quay sân luôn dùng camera sau, bắt người
+      // dùng bấm đổi mỗi buổi là thừa. Phải khớp với mặc định của MỌI adapter
+      // (LiveKitRoomAdapter.isFront, module RTMP cameraPosition) — lệch một chỗ
+      // là nhãn UI và hình thực tế ngược nhau vĩnh viễn.
+      isCameraFront: false,
       captureOrientation: null,
       deviceMetrics: null,
       cameras: [],
@@ -747,10 +752,21 @@ export class LivestreamEngine {
       );
     }
     if (!this.dependencies.network.isOnline()) return;
-    await this.dependencies.sessionProvider.end({
-      sessionId: pending.sessionId,
-      reason: pending.pendingEnd ?? "error",
-    });
+    try {
+      await this.dependencies.sessionProvider.end({
+        sessionId: pending.sessionId,
+        reason: pending.pendingEnd ?? "error",
+      });
+    } catch (error) {
+      // CHỈ 404 mới xoá dấu: phiên đã biến mất hẳn (bị watchdog dọn, thuộc
+      // deployment khác, ID sai) nên thử lại bao nhiêu lần cũng vô ích, mà giữ
+      // dấu thì thiết bị bị khoá VĨNH VIỄN với thông báo "Đang có phiên phát
+      // khác" — box hết pin giữa trận là dính, chỉ gỡ được bằng cài lại app.
+      //
+      // Mất mạng hay 5xx thì KHÔNG xoá: phiên cũ có thể vẫn đang chạy thật, xoá
+      // dấu sẽ dẫn tới hai phiên live song song.
+      if (!isSessionGoneError(error)) throw error;
+    }
     await this.dependencies.storage.removeItem(PENDING_END_KEY);
     this.pendingReplayError = undefined;
   }

package/src/errors.ts

@@ -126,3 +126,19 @@ export function normalizeError(error: unknown): PickleballExpoError {
   }
   return new UnknownSdkError();
 }
+
+/**
+ * Phiên đã biến mất hẳn phía server (HTTP 404): bị watchdog dọn, thuộc
+ * deployment khác, hoặc ID không hợp lệ. Khác hẳn lỗi mạng/5xx — thử lại không
+ * bao giờ cứu được, nên caller phải bỏ dấu khôi phục thay vì chặn vĩnh viễn.
+ *
+ * Mã HTTP được gắn vào lỗi ở http-session-provider vì envelope trả về chỉ có
+ * code "UNKNOWN", không phân biệt được 404 với 5xx.
+ */
+export function isSessionGoneError(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    (error as { httpStatus?: unknown }).httpStatus === 404
+  );
+}

package/src/http-session-provider.ts

@@ -80,7 +80,7 @@ export function createHttpSessionProvider(
       const envelope = await response.json().catch(() => {
         throw new InvalidResponseError();
       });
-      if (!response.ok) throw parseProxyError(envelope);
+      if (!response.ok) throw parseProxyError(envelope, response.status);
       if (!isRecord(envelope) || !("data" in envelope)) {
         throw new InvalidResponseError();
       }
@@ -168,22 +168,25 @@ function joinUrl(base: string, path: string) {
   return `${base}/${path.replace(/^\/+/, "")}`;
 }
 
-function parseProxyError(envelope: unknown) {
-  if (
+function parseProxyError(envelope: unknown, httpStatus: number) {
+  const error =
     isRecord(envelope) &&
     isRecord(envelope.error) &&
     typeof envelope.error.code === "string"
-  ) {
-    return errorFromCode(
-      envelope.error.code,
-      typeof envelope.error.message === "string"
-        ? envelope.error.message
-        : undefined,
-    );
-  }
-  return new InvalidResponseError();
+      ? errorFromCode(
+          envelope.error.code,
+          typeof envelope.error.message === "string"
+            ? envelope.error.message
+            : undefined,
+        )
+      : new InvalidResponseError();
+  // Mã lỗi trong envelope không phân biệt được "phiên đã biến mất" (404) với
+  // "server đang trục trặc" (5xx) — cả hai đều là UNKNOWN. Giữ lại mã HTTP để
+  // engine quyết được: 404 thì xoá dấu pending-end, 5xx thì giữ và thử lại.
+  return Object.assign(error, { httpStatus });
 }
 
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -219,7 +222,10 @@ function isSessionGrant(value: unknown): value is SdkSessionGrant {
     typeof value.sessionId === "string" &&
     value.sessionId.length > 0 &&
     typeof value.serverUrl === "string" &&
-    /^wss:\/\//.test(value.serverUrl) &&
+    // wss:// cho mode LiveKit, rtmp(s):// cho mode device-rtmp. Trước đây chỉ
+    // chấp nhận wss:// nên grant RTMP bị coi là "phản hồi máy chủ không hợp lệ".
+    // Vẫn chặn ws:// trần để không rơi xuống WebSocket không mã hoá.
+    /^(wss|rtmps?):\/\//.test(value.serverUrl) &&
     typeof value.participantToken === "string" &&
     value.participantToken.length > 0 &&
     (value.playbackUrl === null || typeof value.playbackUrl === "string") &&

package/src/index.ts

@@ -1,16 +1,40 @@
+/**
+ * Entry gọn cho tích hợp livestream cơ bản. Các tính năng khác nằm ở subpath:
+ *   @pickleball/expo-sdk/match         — scoreboard + persistence
+ *   @pickleball/expo-sdk/match/voice   — đọc điểm bằng loa
+ *   @pickleball/expo-sdk/match/remote  — remote BLE/HID
+ *   @pickleball/expo-sdk/device-agent  — điều khiển từ dashboard
+ *   @pickleball/expo-sdk/advanced      — engine internals, DI, mock/test
+ * Metro không tree-shake nên chỉ import subpath nào app thật sự dùng.
+ */
 export * from "./contracts";
-export * from "./match/contracts";
-export * from "./match/engine";
-export { replayMatchEvents, undoLastMatchEvent } from "./match/replay";
-export * from "./match/persistence";
-export * from "./match/provider";
-export * from "./match/remote";
-export * from "./match/voice";
 export * from "./errors";
-export * from "./engine";
-export * from "./http-session-provider";
-export * from "./livekit-room-adapter";
-export * from "./native-runtime";
-export * from "./provider";
-export * from "./livestream-screen";
-export * from "./version";
+export {
+  PickleballLiveProvider,
+  useLivestream,
+  defaultLivestreamTheme,
+  type PickleballLiveProviderProps,
+  type LivestreamContextValue,
+  type LivestreamTheme,
+} from "./provider";
+export { LivestreamScreen, type LivestreamScreenProps } from "./livestream-screen";
+export {
+  createHttpSessionProvider,
+  type HttpSessionProviderOptions,
+  type HttpSessionProviderPaths,
+} from "./http-session-provider";
+// Partner dùng để persist token/cấu hình (expo-sqlite localStorage)
+export { createDefaultStorage } from "./native-runtime";
+// Type-only: xuất hiện trong LivestreamContextValue/ProviderProps
+export type {
+  CameraDeviceInfo,
+  CaptureOrientation,
+  DeviceMetricsSample,
+  LivestreamSnapshot,
+  RoomAdapter,
+  SdkNetwork,
+  SdkRuntime,
+  SdkStorage,
+  TelemetrySink,
+} from "./engine";
+export { PICKLEBALL_EXPO_SDK_VERSION } from "./version";

package/src/livekit-room-adapter.ts

@@ -93,7 +93,8 @@ export class LiveKitRoomAdapter implements RoomAdapter {
   private videoTrack?: LocalTrackLike;
   private audioTrack?: LocalTrackLike;
   private preview?: LocalPreviewReference;
-  private isFront = true;
+  // Khớp engine (isCameraFront: false) — xem ghi chú ở engine.ts.
+  private isFront = false;
   private orientationOverride: "portrait" | "landscape" | null = null;
   private deviceOverride: string | null = null;
   private published = false;
@@ -147,6 +148,15 @@ export class LiveKitRoomAdapter implements RoomAdapter {
 
   async connect(input: RoomConnection) {
     this.ensureNotDisposed();
+    // Chặn lệch mode (đối xứng với guard trong RtmpRoomAdapter): nếu app trên
+    // server đã chuyển sang device-rtmp thì grant trả rtmp:// — LiveKit không
+    // hiểu URL đó và sẽ hỏng câm lặng nếu không báo ở đây.
+    if (!/^wss?:\/\//i.test(input.serverUrl)) {
+      throw new Error(
+        `Mode LiveKit cần endpoint wss:// nhưng phiên trả về "${input.serverUrl}". ` +
+          "App trên server đang đặt deliveryMode khác — đổi mode trong app cho khớp.",
+      );
+    }
     if (!this.preview) throw new Error("Preview must be prepared before connecting");
     if (this.room.state !== "disconnected") await this.disconnect(false);
     await this.ensurePreparedTracks();
@@ -175,7 +185,7 @@ export class LiveKitRoomAdapter implements RoomAdapter {
     if (enabled) {
       const publication = await this.room.localParticipant.publishTrack(
         this.videoTrack,
-        { simulcast: false, source: this.bindings.cameraSource },
+        this.videoPublishOptions(),
       );
       await this.room.localParticipant.publishTrack(this.audioTrack);
       this.preview.trackRef = {
@@ -210,6 +220,33 @@ export class LiveKitRoomAdapter implements RoomAdapter {
     return { width: long, height: short, frameRate: 30 };
   }
 
+  /**
+   * 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() {
+    return {
+      source: this.bindings.cameraSource,
+      simulcast: false,
+      videoCodec: "h264",
+      degradationPreference: "maintain-framerate",
+      videoEncoding: {
+        maxBitrate: this.quality === 1080 ? 4_500_000 : 2_500_000,
+        maxFramerate: 30,
+      },
+    };
+  }
+
   async setCaptureOrientation(orientation: "portrait" | "landscape") {
     this.ensureNotDisposed();
     // Chỉ ghi nhận lựa chọn (phục vụ hint UI/telemetry); capture format không

package/src/livestream-screen.tsx

@@ -8,6 +8,7 @@ import {
   type ViewStyle,
 } from "react-native";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
+import { sessionShortCode } from "@pickleball/shared";
 import type { LivestreamState, StartLivestreamInput } from "./contracts";
 import type { ExpoSdkErrorCode } from "./errors";
 import type { LocalPreviewReference } from "./livekit-room-adapter";
@@ -447,6 +448,16 @@ export function LivestreamScreen(props: LivestreamScreenProps) {
                 {formatElapsed(state.elapsedMs)}
               </Text>
             ) : null}
+            {/* Mã ngắn trùng với mã trên dashboard — 8 sân chạy cùng lúc thì
+                cần thứ đối chiếu được, tiêu đề không đủ phân biệt. */}
+            {state.sessionId ? (
+              <Text
+                selectable
+                style={[{ color: theme.textSecondary, fontSize: 12, letterSpacing: 1 }, bodyFont]}
+              >
+                {sessionShortCode(state.sessionId)}
+              </Text>
+            ) : null}
             {inLive && state.deviceMetrics ? (
               <Text
                 selectable
@@ -953,17 +964,28 @@ function AspectBox({
 }
 
 function DefaultPreview({ state }: { state: RenderState }) {
-  const preview = state.previewTrack as LocalPreviewReference | null;
+  const preview = state.previewTrack as
+    | LocalPreviewReference
+    | { kind?: string }
+    | null;
   if (!preview) return <View style={{ flex: 1, backgroundColor: state.theme.background }} />;
+  // Mode device-rtmp: khung hình đi thẳng trong native, JS không có track nào để
+  // bind. Render view native của HaishinKit; thiếu nhánh này thì màn TỐI ĐEN dù
+  // camera đã mở và đang encode bình thường.
+  if ((preview as { kind?: string }).kind === "rtmp") {
+    const rtmp = require("@pickleball/rtmp-native");
+    return <rtmp.PickleballRtmpPreviewView style={{ flex: 1 }} />;
+  }
   const liveKit = require("@livekit/react-native");
+  const liveKitPreview = preview as LocalPreviewReference;
   // restartTrack thay mediaStreamTrack bên trong cùng một track object nên
   // React không thấy prop đổi; remount view theo camera đang chọn để render
   // đúng stream mới sau khi lật camera / chọn ống kính.
   const remountKey = `${state.selectedCameraId ?? "auto"}:${state.isCameraFront ? "front" : "back"}`;
-  return preview.trackRef ? (
-    <liveKit.VideoTrack key={remountKey} trackRef={preview.trackRef} mirror={state.isCameraFront} objectFit="cover" style={{ flex: 1 }} />
+  return liveKitPreview.trackRef ? (
+    <liveKit.VideoTrack key={remountKey} trackRef={liveKitPreview.trackRef} mirror={state.isCameraFront} objectFit="cover" style={{ flex: 1 }} />
   ) : (
-    <liveKit.VideoView key={remountKey} videoTrack={preview.videoTrack} mirror={state.isCameraFront} objectFit="cover" style={{ flex: 1 }} />
+    <liveKit.VideoView key={remountKey} videoTrack={liveKitPreview.videoTrack} mirror={state.isCameraFront} objectFit="cover" style={{ flex: 1 }} />
   );
 }
 

package/src/match/index.ts

@@ -0,0 +1,29 @@
+/**
+ * Entry cho tính năng trận đấu: scoreboard engine, persistence SQLite và
+ * PickleballMatchProvider. Voice/remote có subpath riêng
+ * (@pickleball/expo-sdk/match/voice, /match/remote) — ở đây chỉ re-export
+ * type-only các kiểu xuất hiện trong props của provider.
+ */
+export * from "./contracts";
+export * from "./engine";
+export { replayMatchEvents, undoLastMatchEvent } from "./replay";
+export * from "./persistence";
+export * from "./provider";
+export type {
+  MatchVoiceService,
+  VoiceAudioMode,
+  VoiceRouteState,
+  VoiceTtsOptions,
+} from "./voice/types";
+export type {
+  RemoteActionMapping,
+  RemoteBinding,
+  RemoteHidGestureMapping,
+  RemoteHidVolumeEvent,
+  RemoteInputMode,
+  RemoteMappedAction,
+  RemoteNativeState,
+  RemoteScanAdvertisement,
+  RemoteService,
+  RemoteState,
+} from "./remote/types";

package/src/match/provider.tsx

@@ -523,7 +523,9 @@ export function PickleballMatchProvider({
         ? awardRallyToSide("right", "remote")
         : mapped === "undo"
           ? undo("remote")
-          : null;
+          : mapped === "announce"
+            ? replayAnnouncement()
+            : null;
     if (action) void action.catch(() => undefined);
   };
 
@@ -536,7 +538,7 @@ export function PickleballMatchProvider({
       hidGestureRecognizerRef.current ??= new HidVolumeGestureRecognizer({
         ...hidGestureMapping,
         onGesture: (gesture) => {
-          handleRemoteMappedActionRef.current(hidGestureMapping[gesture]);
+          handleRemoteMappedActionRef.current(hidGestureMapping[gesture] ?? "none");
         },
       });
       hidGestureRecognizerRef.current.push(event);

package/src/match/remote/hid-gesture.ts

@@ -16,7 +16,7 @@ export class HidVolumeGestureRecognizer {
   constructor(private readonly options: HidVolumeGestureRecognizerOptions) {}
 
   push(event: RemoteHidVolumeEvent) {
-    if (event.direction !== this.options.direction) return;
+    if (this.options.direction !== "any" && event.direction !== this.options.direction) return;
     if (
       this.lastTimestamp !== null &&
       event.timestamp - this.lastTimestamp > this.options.settleMs
@@ -43,7 +43,15 @@ export class HidVolumeGestureRecognizer {
   private finishBurst() {
     this.clearTimer();
     if (!this.resolved && this.count > 0) {
-      this.options.onGesture(this.count === 1 ? "single" : "double");
+      this.options.onGesture(
+        this.count === 1
+          ? "single"
+          : this.count === 2
+            ? "double"
+            : this.count === 3
+              ? "triple"
+              : "quadruple",
+      );
     }
     this.reset();
   }