@pickleball/expo-sdk 0.1.1

package/src/match/provider.tsx

@@ -0,0 +1,728 @@
+import React, {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
+import type {
+  CourtSide,
+  MatchCorrection,
+  MatchCreateInput,
+  MatchEvent,
+  MatchInputSource,
+  MatchSnapshot,
+} from "./contracts";
+import {
+  awardRally,
+  confirmCourtSwitch as makeCourtSwitchConfirmation,
+  correctMatch,
+  endMatch as makeEndMatch,
+} from "./engine";
+import { createDefaultMatchEventStore } from "./persistence/default-store";
+import type { MatchSummary, PersistedMatch } from "./persistence/types";
+import { BTHomeRemoteDeduplicator } from "./remote/deduplicator";
+import { decodeBase64Bytes } from "./remote/encoding";
+import { HidVolumeGestureRecognizer } from "./remote/hid-gesture";
+import { createDefaultRemoteService } from "./remote/native-service";
+import { parseBTHomeV2Advertisement } from "./remote/parser";
+import {
+  RemoteError,
+  type RemoteBinding,
+  DEFAULT_REMOTE_ACTION_MAPPING,
+  type RemoteActionMapping,
+  type RemoteHidVolumeEvent,
+  type RemoteHidGestureMapping,
+  type RemoteInputMode,
+  type RemoteMappedAction,
+  type RemoteNativeState,
+  type RemoteScanAdvertisement,
+  type RemoteService,
+  type RemoteState,
+} from "./remote/types";
+import { undoLastMatchEvent } from "./replay";
+import { createDefaultMatchVoiceService } from "./voice/service";
+import type {
+  MatchVoiceService,
+  VoiceAudioMode,
+  VoiceRouteState,
+  VoiceTtsOptions,
+} from "./voice/types";
+
+export interface PickleballMatchStore {
+  initialize(): Promise<void>;
+  createMatch(input: MatchCreateInput, source?: MatchInputSource): Promise<PersistedMatch>;
+  appendEvent(currentSnapshot: MatchSnapshot, event: MatchEvent): Promise<PersistedMatch>;
+  resumeMatch(matchId: string): Promise<PersistedMatch | null>;
+  resumeActiveMatch(): Promise<PersistedMatch | null>;
+  listMatches(): Promise<readonly MatchSummary[]>;
+  archiveMatch(matchId: string): Promise<void>;
+  getRemoteBinding?(): Promise<RemoteBinding | null>;
+  setRemoteBinding?(binding: RemoteBinding | null): Promise<void>;
+}
+
+export class NoActiveMatchError extends Error {
+  readonly name = "NoActiveMatchError";
+  readonly code = "NO_ACTIVE_MATCH";
+
+  constructor() {
+    super("No pickleball match is loaded");
+  }
+}
+
+/**
+ * State-changing actions reject with NoActiveMatchError when no match is loaded.
+ * Commands the engine deems ineligible are ignored and resolve the current snapshot.
+ */
+export interface PickleballMatchContextValue {
+  readonly snapshot: MatchSnapshot | null;
+  readonly events: readonly MatchEvent[];
+  readonly loading: boolean;
+  readonly error: Error | null;
+  readonly voiceError: Error | null;
+  readonly audioState: VoiceRouteState;
+  readonly remoteState: RemoteState;
+  createMatch(input: MatchCreateInput, source?: MatchInputSource): Promise<MatchSnapshot>;
+  resumeMatch(matchId?: string): Promise<MatchSnapshot | null>;
+  awardRallyToSide(side: CourtSide, source?: MatchInputSource): Promise<MatchSnapshot>;
+  undo(source?: MatchInputSource): Promise<MatchSnapshot>;
+  correctState(
+    correction: MatchCorrection,
+    source?: MatchInputSource,
+  ): Promise<MatchSnapshot>;
+  confirmCourtSwitch(source?: MatchInputSource): Promise<MatchSnapshot>;
+  endMatch(reason: string, source?: MatchInputSource): Promise<MatchSnapshot>;
+  testSpeaker(): Promise<void>;
+  replayAnnouncement(): Promise<void>;
+  setVoiceAudioMode(mode: VoiceAudioMode): Promise<void>;
+  bindRemote(binding: RemoteBinding): Promise<void>;
+  unbindRemote(): Promise<void>;
+  startRemoteScan(): Promise<void>;
+  stopRemoteScan(): Promise<void>;
+  startHidCapture(): Promise<void>;
+  stopHidCapture(): Promise<void>;
+}
+
+export interface PickleballMatchProviderProps {
+  readonly children?: ReactNode;
+  /** Fixed for this provider instance. Remount to use a different local store. */
+  readonly store?: PickleballMatchStore;
+  /** Fixed for this provider instance. Remount to use a different factory. */
+  readonly storeFactory?: () => Promise<PickleballMatchStore>;
+  /** Resumes the active local match on mount. Disable for hosts that resume explicitly. */
+  readonly autoResume?: boolean;
+  readonly onError?: (error: Error) => void | Promise<void>;
+  /** Fixed for this provider instance. Primarily useful for custom storage and tests. */
+  readonly voiceService?: MatchVoiceService;
+  /** Initial audio session mode. Defaults to live so mounting never disables capture. */
+  readonly voiceAudioMode?: VoiceAudioMode;
+  /** Cloud TTS endpoint for announcements. Without it only bundled WAVs play. Fixed for this provider instance. */
+  readonly voiceTts?: VoiceTtsOptions;
+  /** Fixed for this provider instance. Primarily useful for tests and custom native bridges. */
+  readonly remoteService?: RemoteService;
+  /** Foreground silence before a bound remote becomes outOfRange. */
+  readonly remoteOutOfRangeTimeoutMs?: number;
+  readonly remoteInputMode?: RemoteInputMode;
+  readonly remoteActionMapping?: Partial<RemoteActionMapping>;
+  /** Optional single/double/hold recognizer for one calibrated HID volume button. */
+  readonly hidGestureMapping?: RemoteHidGestureMapping;
+  readonly consumeHidVolumeKeys?: boolean;
+}
+
+const INITIAL_REMOTE_STATE: RemoteState = {
+  status: "idle",
+  permission: "unknown",
+  binding: null,
+  candidate: null,
+  lastSeenAt: null,
+  error: null,
+  hidCaptureArmed: false,
+  lastInputSource: null,
+  lastHidEvent: null,
+};
+
+const MatchContext = React.createContext<PickleballMatchContextValue | null>(null);
+
+export function PickleballMatchProvider({
+  children,
+  store,
+  storeFactory,
+  autoResume = true,
+  onError,
+  voiceService,
+  voiceAudioMode = "live",
+  voiceTts,
+  remoteService,
+  remoteOutOfRangeTimeoutMs = 5_000,
+  remoteInputMode = "bthome",
+  remoteActionMapping,
+  hidGestureMapping,
+  consumeHidVolumeKeys = true,
+}: PickleballMatchProviderProps) {
+  const [snapshot, setSnapshot] = useState<MatchSnapshot | null>(null);
+  const [events, setEvents] = useState<readonly MatchEvent[]>([]);
+  const [loading, setLoading] = useState(autoResume);
+  const [error, setError] = useState<Error | null>(null);
+  const [voiceError, setVoiceError] = useState<Error | null>(null);
+  const [audioState, setAudioState] = useState<VoiceRouteState>(
+    voiceService?.audioState ?? {
+      route: "system",
+      interrupted: false,
+      disconnectedReason: null,
+    },
+  );
+  const [remoteState, setRemoteState] = useState<RemoteState>(INITIAL_REMOTE_STATE);
+  const snapshotRef = useRef<MatchSnapshot | null>(null);
+  const eventsRef = useRef<readonly MatchEvent[]>([]);
+  const queueRef = useRef<Promise<void>>(Promise.resolve());
+  const mountedRef = useRef(true);
+  const didAutoResumeRef = useRef(false);
+  const autoResumeOnMountRef = useRef(autoResume);
+  const onErrorRef = useRef(onError);
+  onErrorRef.current = onError;
+  const storeConfigurationRef = useRef({ store, storeFactory });
+  const storePromiseRef = useRef<Promise<PickleballMatchStore> | null>(null);
+  const voiceServiceRef = useRef<MatchVoiceService | null>(voiceService ?? null);
+  const voiceEffectGenerationRef = useRef(0);
+  const remoteServiceRef = useRef<RemoteService | null>(remoteService ?? null);
+  const remoteBindingRef = useRef<RemoteBinding | null>(null);
+  const remoteScanActiveRef = useRef(false);
+  const remoteLifecycleQueueRef = useRef<Promise<void>>(Promise.resolve());
+  const remoteUnsubscribersRef = useRef<readonly (() => void)[]>([]);
+  const remoteDedupeRef = useRef(new BTHomeRemoteDeduplicator());
+  const remoteRangeTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const handleRemoteAdvertisementRef = useRef<(event: RemoteScanAdvertisement) => void>(() => undefined);
+  const handleRemoteNativeStateRef = useRef<(event: RemoteNativeState) => void>(() => undefined);
+  const handleHidVolumeRef = useRef<(event: RemoteHidVolumeEvent) => void>(() => undefined);
+  const handleRemoteMappedActionRef = useRef<(action: RemoteMappedAction) => void>(() => undefined);
+  const hidGestureRecognizerRef = useRef<HidVolumeGestureRecognizer | null>(null);
+  const resolvedRemoteMapping = useMemo(
+    () => ({ ...DEFAULT_REMOTE_ACTION_MAPPING, ...remoteActionMapping }),
+    [remoteActionMapping],
+  );
+
+  const reportVoiceError = useCallback((caught: unknown) => {
+    const operationError =
+      caught instanceof Error ? caught : new Error("Unknown voice operation failure");
+    if (mountedRef.current) setVoiceError(operationError);
+  }, []);
+
+  const voiceTtsRef = useRef(voiceTts);
+  const requireVoiceService = useCallback(() => {
+    voiceServiceRef.current ??= createDefaultMatchVoiceService({
+      audioMode: voiceAudioMode,
+      tts: voiceTtsRef.current,
+    });
+    return voiceServiceRef.current;
+  }, [voiceAudioMode]);
+
+  const requireRemoteService = useCallback(() => {
+    remoteServiceRef.current ??= createDefaultRemoteService();
+    return remoteServiceRef.current;
+  }, []);
+
+  const getStore = useCallback(() => {
+    if (!storePromiseRef.current) {
+      const configuration = storeConfigurationRef.current;
+      const pending = Promise.resolve().then(async () => {
+        const persistence = configuration.store
+          ? configuration.store
+          : configuration.storeFactory
+            ? await configuration.storeFactory()
+            : await createDefaultMatchEventStore();
+        await persistence.initialize();
+        return persistence;
+      });
+      storePromiseRef.current = pending;
+      void pending.catch(() => {
+        if (storePromiseRef.current === pending) storePromiseRef.current = null;
+      });
+    }
+    return storePromiseRef.current;
+  }, []);
+
+  const publish = useCallback((match: PersistedMatch | null) => {
+    snapshotRef.current = match?.snapshot ?? null;
+    eventsRef.current = match?.events ?? [];
+    if (mountedRef.current) {
+      setSnapshot(snapshotRef.current);
+      setEvents(eventsRef.current);
+    }
+  }, []);
+
+  const enqueue = useCallback(<T,>(work: () => Promise<T>): Promise<T> => {
+    const run = async () => {
+      if (mountedRef.current) {
+        setLoading(true);
+        setError(null);
+      }
+      try {
+        return await work();
+      } catch (caught) {
+        const operationError =
+          caught instanceof Error ? caught : new Error("Unknown match operation failure");
+        if (mountedRef.current) setError(operationError);
+        try {
+          const observerResult = onErrorRef.current?.(operationError);
+          if (observerResult) void Promise.resolve(observerResult).catch(() => undefined);
+        } catch {
+          // Observers cannot replace the operation failure seen by the caller.
+        }
+        throw operationError;
+      } finally {
+        if (mountedRef.current) setLoading(false);
+      }
+    };
+    const result = queueRef.current.then(run, run);
+    queueRef.current = result.then(
+      () => undefined,
+      () => undefined,
+    );
+    return result;
+  }, []);
+
+  const requireSnapshot = useCallback(() => {
+    if (!snapshotRef.current) throw new NoActiveMatchError();
+    return snapshotRef.current;
+  }, []);
+
+  const commit = useCallback(
+    (makeEvent: (current: MatchSnapshot) => MatchEvent | null) =>
+      enqueue(async () => {
+        const current = requireSnapshot();
+        const event = makeEvent(current);
+        if (!event) return current;
+        const persistence = await getStore();
+        const committed = await persistence.appendEvent(current, event);
+        publish(committed);
+        if (event.type === "rallyAwarded" || event.type === "courtSwitchConfirmed") {
+          try {
+            requireVoiceService().announce(current, committed.snapshot, event);
+          } catch (voiceFailure) {
+            reportVoiceError(voiceFailure);
+          }
+        }
+        return committed.snapshot;
+      }),
+    [enqueue, getStore, publish, reportVoiceError, requireSnapshot, requireVoiceService],
+  );
+
+  const createMatchAction = useCallback(
+    (input: MatchCreateInput, source: MatchInputSource = "local") =>
+      enqueue(async () => {
+        const persistence = await getStore();
+        const created = await persistence.createMatch(input, source);
+        publish(created);
+        return created.snapshot;
+      }),
+    [enqueue, getStore, publish],
+  );
+
+  const resumeMatchAction = useCallback(
+    (matchId?: string) =>
+      enqueue(async () => {
+        const persistence = await getStore();
+        const resumed = matchId
+          ? await persistence.resumeMatch(matchId)
+          : await persistence.resumeActiveMatch();
+        publish(resumed);
+        return resumed?.snapshot ?? null;
+      }),
+    [enqueue, getStore, publish],
+  );
+
+  const awardRallyToSide = useCallback(
+    (side: CourtSide, source: MatchInputSource = "local") =>
+      commit((current) => awardRally(current, side, source)),
+    [commit],
+  );
+
+  const undo = useCallback(
+    (source: MatchInputSource = "local") =>
+      commit(() => undoLastMatchEvent(eventsRef.current, source)),
+    [commit],
+  );
+
+  const correctState = useCallback(
+    (correction: MatchCorrection, source: MatchInputSource = "local") =>
+      commit((current) => correctMatch(current, correction, source)),
+    [commit],
+  );
+
+  const confirmCourtSwitch = useCallback(
+    (source: MatchInputSource = "local") =>
+      commit((current) => makeCourtSwitchConfirmation(current, source)),
+    [commit],
+  );
+
+  const endMatch = useCallback(
+    (reason: string, source: MatchInputSource = "local") =>
+      commit((current) => makeEndMatch(current, reason, source)),
+    [commit],
+  );
+
+  const runVoiceAction = useCallback(
+    async (action: (service: MatchVoiceService) => Promise<void>) => {
+      try {
+        setVoiceError(null);
+        await action(requireVoiceService());
+      } catch (caught) {
+        reportVoiceError(caught);
+        throw caught;
+      }
+    },
+    [reportVoiceError, requireVoiceService],
+  );
+
+  const testSpeaker = useCallback(
+    () => runVoiceAction((service) => service.testSpeaker()),
+    [runVoiceAction],
+  );
+  const replayAnnouncement = useCallback(
+    () => runVoiceAction((service) => service.replayAnnouncement()),
+    [runVoiceAction],
+  );
+  const setVoiceAudioMode = useCallback(
+    (mode: VoiceAudioMode) =>
+      runVoiceAction(async (service) => {
+        if (!service.configureAudioMode) {
+          throw new Error("The injected voice service cannot change audio mode");
+        }
+        await service.configureAudioMode(mode);
+      }),
+    [runVoiceAction],
+  );
+
+  const publishRemote = useCallback((update: (current: RemoteState) => RemoteState) => {
+    if (mountedRef.current) setRemoteState(update);
+  }, []);
+
+  const clearRemoteRangeTimer = useCallback(() => {
+    if (remoteRangeTimerRef.current) clearTimeout(remoteRangeTimerRef.current);
+    remoteRangeTimerRef.current = null;
+  }, []);
+
+  const armRemoteRangeTimer = useCallback(() => {
+    clearRemoteRangeTimer();
+    remoteRangeTimerRef.current = setTimeout(() => {
+      if (!remoteScanActiveRef.current || !remoteBindingRef.current) return;
+      publishRemote((current) => ({ ...current, status: "outOfRange" }));
+    }, remoteOutOfRangeTimeoutMs);
+  }, [clearRemoteRangeTimer, publishRemote, remoteOutOfRangeTimeoutMs]);
+
+  const bindRemote = useCallback(async (binding: RemoteBinding) => {
+    if (binding.deviceId.trim().length === 0) throw new Error("Remote identifier cannot be empty");
+    const persistence = await getStore();
+    if (!persistence.setRemoteBinding) throw new Error("Remote binding persistence is unavailable");
+    await persistence.setRemoteBinding(binding);
+    remoteBindingRef.current = binding;
+    remoteDedupeRef.current.clear();
+    publishRemote((current) => ({
+      ...current,
+      binding,
+      candidate: null,
+      status: remoteScanActiveRef.current ? "bound" : "idle",
+      error: null,
+    }));
+  }, [getStore, publishRemote]);
+
+  const unbindRemote = useCallback(async () => {
+    const persistence = await getStore();
+    if (!persistence.setRemoteBinding) throw new Error("Remote binding persistence is unavailable");
+    await persistence.setRemoteBinding(null);
+    remoteBindingRef.current = null;
+    remoteDedupeRef.current.clear();
+    clearRemoteRangeTimer();
+    publishRemote((current) => ({
+      ...current,
+      binding: null,
+      candidate: null,
+      lastSeenAt: null,
+      status: remoteScanActiveRef.current ? "scanning" : "idle",
+      error: null,
+    }));
+  }, [clearRemoteRangeTimer, getStore, publishRemote]);
+
+  const ensureRemoteSubscriptions = useCallback((service: RemoteService) => {
+    if (remoteUnsubscribersRef.current.length > 0) return;
+    remoteUnsubscribersRef.current = [
+      service.subscribeAdvertisement((event) => handleRemoteAdvertisementRef.current(event)),
+      service.subscribeState((event) => handleRemoteNativeStateRef.current(event)),
+      service.subscribeHidVolume((event) => handleHidVolumeRef.current(event)),
+    ];
+  }, []);
+
+  const startRemoteScan = useCallback(() => {
+    const run = remoteLifecycleQueueRef.current.then(async () => {
+      if (remoteScanActiveRef.current) return;
+      const persistence = await getStore();
+      const binding = persistence.getRemoteBinding
+        ? await persistence.getRemoteBinding()
+        : remoteBindingRef.current;
+      remoteBindingRef.current = binding;
+      const service = requireRemoteService();
+      ensureRemoteSubscriptions(service);
+      remoteScanActiveRef.current = true;
+      publishRemote((current) => ({
+        ...current,
+        binding,
+        status: binding ? "bound" : "scanning",
+        error: null,
+      }));
+      try {
+        await service.start();
+      } catch (caught) {
+        remoteScanActiveRef.current = false;
+        const failure = caught instanceof RemoteError
+          ? caught
+          : new RemoteError("scan_failed", "Unable to start BTHome scanning", { cause: caught });
+        publishRemote((current) => ({ ...current, status: "idle", error: failure }));
+        throw failure;
+      }
+    });
+    remoteLifecycleQueueRef.current = run.catch(() => undefined);
+    return run;
+  }, [ensureRemoteSubscriptions, getStore, publishRemote, requireRemoteService]);
+
+  const stopRemoteScan = useCallback(() => {
+    const run = remoteLifecycleQueueRef.current.then(async () => {
+      remoteScanActiveRef.current = false;
+      clearRemoteRangeTimer();
+      remoteDedupeRef.current.clear();
+      await remoteServiceRef.current?.stop();
+      for (const unsubscribe of remoteUnsubscribersRef.current) unsubscribe();
+      remoteUnsubscribersRef.current = [];
+      publishRemote((current) => ({ ...current, status: "idle", candidate: null }));
+    });
+    remoteLifecycleQueueRef.current = run.catch(() => undefined);
+    return run;
+  }, [clearRemoteRangeTimer, publishRemote]);
+
+  const startHidCapture = useCallback(async () => {
+    if (remoteInputMode === "bthome") throw new Error("HID volume input is disabled by remoteInputMode");
+    hidGestureRecognizerRef.current?.dispose();
+    hidGestureRecognizerRef.current = null;
+    const service = requireRemoteService();
+    ensureRemoteSubscriptions(service);
+    await service.startHidCapture({ consume: consumeHidVolumeKeys });
+    publishRemote((current) => ({ ...current, hidCaptureArmed: true, error: null }));
+  }, [consumeHidVolumeKeys, ensureRemoteSubscriptions, publishRemote, remoteInputMode, requireRemoteService]);
+
+  const stopHidCapture = useCallback(async () => {
+    hidGestureRecognizerRef.current?.dispose();
+    hidGestureRecognizerRef.current = null;
+    await remoteServiceRef.current?.stopHidCapture();
+    publishRemote((current) => ({ ...current, hidCaptureArmed: false }));
+  }, [publishRemote]);
+
+  handleRemoteMappedActionRef.current = (mapped) => {
+    const action = mapped === "left"
+      ? awardRallyToSide("left", "remote")
+      : mapped === "right"
+        ? awardRallyToSide("right", "remote")
+        : mapped === "undo"
+          ? undo("remote")
+          : null;
+    if (action) void action.catch(() => undefined);
+  };
+
+  handleHidVolumeRef.current = (event) => {
+    if (!mountedRef.current) return;
+    publishRemote((current) => ({
+      ...current, lastInputSource: "hidVolume", lastHidEvent: event,
+    }));
+    if (hidGestureMapping) {
+      hidGestureRecognizerRef.current ??= new HidVolumeGestureRecognizer({
+        ...hidGestureMapping,
+        onGesture: (gesture) => {
+          handleRemoteMappedActionRef.current(hidGestureMapping[gesture]);
+        },
+      });
+      hidGestureRecognizerRef.current.push(event);
+      return;
+    }
+    const mapped = event.longPress
+      ? resolvedRemoteMapping.longPress
+      : resolvedRemoteMapping[event.direction];
+    handleRemoteMappedActionRef.current(mapped);
+  };
+
+  handleRemoteNativeStateRef.current = (nativeState) => {
+    if (!remoteScanActiveRef.current) return;
+    if (nativeState.status === "permission") {
+      const error = nativeState.permission === "denied"
+        ? new RemoteError("permission_denied", "Bluetooth scan permission was denied")
+        : nativeState.permission === "restricted"
+          ? new RemoteError("permission_restricted", "Bluetooth access is restricted")
+          : null;
+      publishRemote((current) => ({ ...current, permission: nativeState.permission, error }));
+      return;
+    }
+    if (nativeState.status === "poweredOff" || nativeState.status === "unavailable") {
+      const error = nativeState.status === "poweredOff"
+        ? new RemoteError("bluetooth_powered_off", "Bluetooth is powered off")
+        : new RemoteError("bluetooth_unavailable", "Bluetooth LE is unavailable");
+      publishRemote((current) => ({ ...current, status: nativeState.status, error }));
+      return;
+    }
+    if (nativeState.status === "error") {
+      publishRemote((current) => ({
+        ...current,
+        error: new RemoteError("scan_failed", nativeState.message),
+      }));
+    }
+  };
+
+  handleRemoteAdvertisementRef.current = (advertisement) => {
+    if (!remoteScanActiveRef.current) return;
+    let parsed;
+    try {
+      parsed = parseBTHomeV2Advertisement({
+        deviceId: advertisement.deviceId,
+        serviceUuid: advertisement.serviceUuid,
+        serviceData: decodeBase64Bytes(advertisement.serviceData),
+      });
+    } catch {
+      return;
+    }
+    const binding = remoteBindingRef.current;
+    if (!binding) {
+      publishRemote((current) => ({
+        ...current,
+        candidate: {
+          deviceId: advertisement.deviceId,
+          ...(advertisement.name ? { label: advertisement.name } : {}),
+          rssi: advertisement.rssi,
+          lastSeenAt: advertisement.timestamp,
+        },
+      }));
+      return;
+    }
+    if (binding.deviceId !== advertisement.deviceId) return;
+    if (!remoteDedupeRef.current.accept(advertisement.deviceId, parsed, advertisement.timestamp)) return;
+    armRemoteRangeTimer();
+    publishRemote((current) => ({
+      ...current,
+      status: "bound",
+      lastSeenAt: advertisement.timestamp,
+      lastInputSource: "bthome",
+      error: null,
+    }));
+    const action = parsed.button.action === "single"
+      ? awardRallyToSide("left", "remote")
+      : parsed.button.action === "double"
+        ? awardRallyToSide("right", "remote")
+        : undo("remote");
+    void action.catch(() => undefined);
+  };
+
+  useEffect(() => {
+    mountedRef.current = true;
+    if (!didAutoResumeRef.current && autoResumeOnMountRef.current) {
+      didAutoResumeRef.current = true;
+      void resumeMatchAction().catch(() => undefined);
+    }
+    return () => {
+      mountedRef.current = false;
+      remoteScanActiveRef.current = false;
+      hidGestureRecognizerRef.current?.dispose();
+      hidGestureRecognizerRef.current = null;
+      clearRemoteRangeTimer();
+      for (const unsubscribe of remoteUnsubscribersRef.current) unsubscribe();
+      remoteUnsubscribersRef.current = [];
+      const service = remoteServiceRef.current;
+      if (service) {
+        void Promise.resolve().then(async () => {
+          await service.stop();
+          await service.stopHidCapture();
+          await service.dispose();
+        }).catch(() => undefined);
+      }
+    };
+  }, [clearRemoteRangeTimer, resumeMatchAction]);
+
+  useEffect(() => {
+    const effectGeneration = ++voiceEffectGenerationRef.current;
+    const service = requireVoiceService();
+    const refresh = () => {
+      if (!mountedRef.current) return;
+      setAudioState(service.audioState);
+      if (service.lastError) setVoiceError(service.lastError);
+    };
+    const unsubscribe = service.subscribe(refresh);
+    refresh();
+    void service.initialize().then(refresh).catch(reportVoiceError);
+    return () => {
+      unsubscribe();
+      if (!voiceService) {
+        void Promise.resolve().then(async () => {
+          if (voiceEffectGenerationRef.current === effectGeneration) await service.dispose();
+        }).catch(() => undefined);
+      }
+    };
+  }, [reportVoiceError, requireVoiceService, voiceService]);
+
+  const value = useMemo<PickleballMatchContextValue>(
+    () => ({
+      snapshot,
+      events,
+      loading,
+      error,
+      voiceError,
+      audioState,
+      remoteState,
+      createMatch: createMatchAction,
+      resumeMatch: resumeMatchAction,
+      awardRallyToSide,
+      undo,
+      correctState,
+      confirmCourtSwitch,
+      endMatch,
+      testSpeaker,
+      replayAnnouncement,
+      setVoiceAudioMode,
+      bindRemote,
+      unbindRemote,
+      startRemoteScan,
+      stopRemoteScan,
+      startHidCapture,
+      stopHidCapture,
+    }),
+    [
+      snapshot,
+      events,
+      loading,
+      error,
+      voiceError,
+      audioState,
+      remoteState,
+      createMatchAction,
+      resumeMatchAction,
+      awardRallyToSide,
+      undo,
+      correctState,
+      confirmCourtSwitch,
+      endMatch,
+      testSpeaker,
+      replayAnnouncement,
+      setVoiceAudioMode,
+      bindRemote,
+      unbindRemote,
+      startRemoteScan,
+      stopRemoteScan,
+      startHidCapture,
+      stopHidCapture,
+    ],
+  );
+
+  return <MatchContext.Provider value={value}>{children}</MatchContext.Provider>;
+}
+
+export function usePickleballMatch(): PickleballMatchContextValue {
+  const value = React.use(MatchContext);
+  if (!value) {
+    throw new Error("usePickleballMatch must be used inside PickleballMatchProvider");
+  }
+  return value;
+}