@pickleball/expo-sdk 0.1.1

package/src/match/remote/deduplicator.ts

@@ -0,0 +1,54 @@
+export interface RemoteDeduplicationKey {
+  readonly packetId?: number;
+  readonly fingerprint: string;
+}
+
+export interface BTHomeRemoteDeduplicatorOptions {
+  readonly fingerprintWindowMs?: number;
+}
+
+interface DeviceDeduplicationState {
+  packetId?: number;
+  fingerprint?: string;
+  fingerprintSeenAt?: number;
+}
+
+export class BTHomeRemoteDeduplicator {
+  private readonly devices = new Map<string, DeviceDeduplicationState>();
+  private readonly fingerprintWindowMs: number;
+
+  constructor(options: BTHomeRemoteDeduplicatorOptions = {}) {
+    this.fingerprintWindowMs = options.fingerprintWindowMs ?? 300;
+  }
+
+  get trackedDeviceCount(): number {
+    return this.devices.size;
+  }
+
+  accept(deviceId: string, key: RemoteDeduplicationKey, now = Date.now()): boolean {
+    const previous = this.devices.get(deviceId);
+    if (key.packetId !== undefined) {
+      if (previous?.packetId === key.packetId) return false;
+      this.devices.set(deviceId, { packetId: key.packetId });
+      return true;
+    }
+    if (
+      previous?.fingerprint === key.fingerprint &&
+      previous.fingerprintSeenAt !== undefined &&
+      now - previous.fingerprintSeenAt <= this.fingerprintWindowMs
+    ) {
+      return false;
+    }
+    this.devices.set(deviceId, { fingerprint: key.fingerprint, fingerprintSeenAt: now });
+    return true;
+  }
+
+  forget(deviceId: string): void {
+    this.devices.delete(deviceId);
+  }
+
+  clear(): void {
+    this.devices.clear();
+  }
+}
+

package/src/match/remote/encoding.ts

@@ -0,0 +1,12 @@
+export function decodeBase64Bytes(value: string): Uint8Array {
+  if (typeof globalThis.atob !== "function") {
+    throw new Error("Base64 decoding is unavailable in this runtime");
+  }
+  const binary = globalThis.atob(value);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index += 1) {
+    bytes[index] = binary.charCodeAt(index);
+  }
+  return bytes;
+}
+

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

@@ -0,0 +1,61 @@
+import type { RemoteHidGesture, RemoteHidGestureMapping, RemoteHidVolumeEvent } from "./types";
+
+export interface HidVolumeGestureRecognizerOptions extends Pick<
+  RemoteHidGestureMapping,
+  "direction" | "settleMs" | "holdEventCount"
+> {
+  readonly onGesture: (gesture: RemoteHidGesture) => void;
+}
+
+export class HidVolumeGestureRecognizer {
+  private count = 0;
+  private resolved = false;
+  private lastTimestamp: number | null = null;
+  private timer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(private readonly options: HidVolumeGestureRecognizerOptions) {}
+
+  push(event: RemoteHidVolumeEvent) {
+    if (event.direction !== this.options.direction) return;
+    if (
+      this.lastTimestamp !== null &&
+      event.timestamp - this.lastTimestamp > this.options.settleMs
+    ) {
+      this.finishBurst();
+    }
+    this.lastTimestamp = event.timestamp;
+    this.clearTimer();
+    if (!this.resolved) {
+      this.count += 1;
+      if (event.longPress || this.count >= this.options.holdEventCount) {
+        this.resolved = true;
+        this.options.onGesture("hold");
+      }
+    }
+    this.timer = setTimeout(() => this.finishBurst(), this.options.settleMs);
+  }
+
+  dispose() {
+    this.clearTimer();
+    this.reset();
+  }
+
+  private finishBurst() {
+    this.clearTimer();
+    if (!this.resolved && this.count > 0) {
+      this.options.onGesture(this.count === 1 ? "single" : "double");
+    }
+    this.reset();
+  }
+
+  private clearTimer() {
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = null;
+  }
+
+  private reset() {
+    this.count = 0;
+    this.resolved = false;
+    this.lastTimestamp = null;
+  }
+}

package/src/match/remote/index.ts

@@ -0,0 +1,5 @@
+export * from "./types";
+export * from "./parser";
+export * from "./deduplicator";
+export * from "./encoding";
+export * from "./hid-gesture";

package/src/match/remote/native-service.ts

@@ -0,0 +1,62 @@
+import { RemoteError, type RemoteHidVolumeEvent, type RemoteNativeState, type RemoteScanAdvertisement, type RemoteService } from "./types";
+
+interface NativeSubscription { remove(): void }
+interface RemoteNativeModule {
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  destroy(): Promise<void>;
+  addListener(name: "onAdvertisement", listener: (event: RemoteScanAdvertisement) => void): NativeSubscription;
+  addListener(name: "onStateChanged", listener: (event: RemoteNativeState) => void): NativeSubscription;
+  addListener(name: "onHidVolume", listener: (event: RemoteHidVolumeEvent) => void): NativeSubscription;
+  startHidCapture(options?: { consume?: boolean }): Promise<void>;
+  stopHidCapture(): Promise<void>;
+}
+
+declare const require: (name: string) => any;
+
+function loadNative(): RemoteNativeModule {
+  const imported = require("@pickleball/remote-native");
+  return (imported.default ?? imported) as RemoteNativeModule;
+}
+
+export function createDefaultRemoteService(): RemoteService {
+  let native: RemoteNativeModule | null = null;
+  let disposed = false;
+  const getNative = () => {
+    if (disposed) throw new RemoteError("native_unavailable", "Remote scanner is disposed");
+    try {
+      native ??= loadNative();
+      return native;
+    } catch (cause) {
+      throw new RemoteError(
+        "native_unavailable",
+        "BTHome scanning requires an iOS or Android build with @pickleball/remote-native",
+        { cause },
+      );
+    }
+  };
+  return {
+    start: () => getNative().start(),
+    async stop() { await native?.stop(); },
+    async dispose() {
+      if (disposed) return;
+      disposed = true;
+      await native?.destroy();
+      native = null;
+    },
+    subscribeAdvertisement(listener) {
+      const subscription = getNative().addListener("onAdvertisement", listener);
+      return () => subscription.remove();
+    },
+    subscribeState(listener) {
+      const subscription = getNative().addListener("onStateChanged", listener);
+      return () => subscription.remove();
+    },
+    startHidCapture: (options) => getNative().startHidCapture(options),
+    async stopHidCapture() { await native?.stopHidCapture(); },
+    subscribeHidVolume(listener) {
+      const subscription = getNative().addListener("onHidVolume", listener);
+      return () => subscription.remove();
+    },
+  };
+}

package/src/match/remote/parser.ts

@@ -0,0 +1,134 @@
+import { BTHOME_SERVICE_UUID, type RemoteButtonAction } from "./types";
+
+export type BTHomeRemoteParseErrorCode =
+  | "wrong_uuid"
+  | "unsupported_version"
+  | "encrypted"
+  | "truncated"
+  | "unknown_object"
+  | "invalid_button_event"
+  | "no_button";
+
+export class BTHomeRemoteParseError extends Error {
+  readonly name = "BTHomeRemoteParseError";
+  constructor(readonly code: BTHomeRemoteParseErrorCode, message: string) {
+    super(message);
+  }
+}
+
+export interface BTHomeAdvertisementInput {
+  readonly deviceId: string;
+  readonly serviceUuid: string;
+  /** FCD2 service data only. The first byte must be BTHome device-info, not UUID bytes. */
+  readonly serviceData: Uint8Array;
+}
+
+export interface ParsedBTHomeRemoteAdvertisement {
+  readonly deviceId: string;
+  readonly version: 2;
+  readonly encrypted: false;
+  readonly triggerBased: boolean;
+  readonly packetId?: number;
+  readonly button: {
+    readonly action: RemoteButtonAction;
+    readonly objectIndex: number;
+    readonly rawEvent: number;
+  };
+  readonly fingerprint: string;
+}
+
+/*
+ * Fixed BTHome v2 object lengths. Keeping the registry explicit is important:
+ * unknown object values are never searched for a coincidental 0x3a byte.
+ * It covers the environmental, binary-sensor, event, count and distance
+ * objects commonly emitted by BTHome remotes and sensors.
+ */
+const OBJECT_LENGTHS: Readonly<Record<number, number>> = Object.freeze({
+  0x00: 1, 0x01: 1, 0x02: 2, 0x03: 2, 0x04: 3, 0x05: 3,
+  0x06: 2, 0x07: 2, 0x08: 2, 0x09: 1, 0x0a: 3, 0x0b: 3,
+  0x0c: 2, 0x0d: 2, 0x0e: 2, 0x0f: 1, 0x10: 1, 0x11: 1,
+  0x12: 2, 0x13: 2, 0x14: 2, 0x15: 1, 0x16: 1, 0x17: 1,
+  0x18: 1, 0x19: 1, 0x1a: 1, 0x1b: 1, 0x1c: 1, 0x1d: 1,
+  0x1e: 1, 0x1f: 1, 0x20: 1, 0x21: 1, 0x22: 1, 0x23: 1,
+  0x24: 1, 0x25: 1, 0x26: 1, 0x27: 1, 0x28: 1, 0x29: 1,
+  0x2a: 1, 0x2b: 1, 0x2c: 1, 0x2d: 1, 0x2e: 1, 0x2f: 1,
+  0x3a: 1, 0x3c: 2, 0x3d: 2, 0x3e: 4, 0x3f: 2, 0x40: 1,
+  0x41: 1, 0x42: 1, 0x43: 1, 0x44: 2, 0x45: 2, 0x46: 4,
+  0x47: 4, 0x48: 4, 0x49: 2, 0x4a: 2, 0x4b: 2, 0x4c: 4,
+  0x4d: 4, 0x4e: 4, 0x4f: 4,
+});
+
+function isBTHomeUuid(uuid: string): boolean {
+  const normalized = uuid.toLowerCase().replaceAll("-", "");
+  return normalized === "fcd2" || normalized === "0000fcd200001000800000805f9b34fb";
+}
+
+function fingerprint(bytes: Uint8Array): string {
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+function mapButtonEvent(value: number): RemoteButtonAction | null | undefined {
+  if (value === 0x01) return "single";
+  if (value === 0x02) return "double";
+  if (value === 0x04 || value === 0x80) return "long";
+  if (value === 0x00 || value === 0x03 || value === 0x05 || value === 0x06) return null;
+  return undefined;
+}
+
+export function parseBTHomeV2Advertisement(
+  input: BTHomeAdvertisementInput,
+): ParsedBTHomeRemoteAdvertisement {
+  if (!isBTHomeUuid(input.serviceUuid)) {
+    throw new BTHomeRemoteParseError("wrong_uuid", `Expected ${BTHOME_SERVICE_UUID} service data`);
+  }
+  if (input.serviceData.length < 1) {
+    throw new BTHomeRemoteParseError("truncated", "BTHome device-info byte is missing");
+  }
+  const info = input.serviceData[0]!;
+  const version = (info >> 5) & 0x07;
+  if (version !== 2) {
+    throw new BTHomeRemoteParseError("unsupported_version", `Unsupported BTHome version ${version}`);
+  }
+  if ((info & 0x01) !== 0) {
+    throw new BTHomeRemoteParseError("encrypted", "Encrypted BTHome advertisements are unsupported");
+  }
+
+  let offset = 1;
+  let objectIndex = 0;
+  let packetId: number | undefined;
+  let button: ParsedBTHomeRemoteAdvertisement["button"] | undefined;
+  while (offset < input.serviceData.length) {
+    const objectId = input.serviceData[offset++]!;
+    const length = OBJECT_LENGTHS[objectId];
+    if (length === undefined) {
+      throw new BTHomeRemoteParseError("unknown_object", `Unknown BTHome object 0x${objectId.toString(16)}`);
+    }
+    if (offset + length > input.serviceData.length) {
+      throw new BTHomeRemoteParseError("truncated", `BTHome object 0x${objectId.toString(16)} is truncated`);
+    }
+    if (objectId === 0x00 && packetId === undefined) packetId = input.serviceData[offset];
+    if (objectId === 0x3a && !button) {
+      const rawEvent = input.serviceData[offset]!;
+      const action = mapButtonEvent(rawEvent);
+      if (action === undefined) {
+        throw new BTHomeRemoteParseError("invalid_button_event", `Reserved button event 0x${rawEvent.toString(16)}`);
+      }
+      if (action) button = { action, objectIndex, rawEvent };
+    }
+    offset += length;
+    objectIndex += 1;
+  }
+  if (!button) {
+    throw new BTHomeRemoteParseError("no_button", "No actionable BTHome button event was found");
+  }
+  return {
+    deviceId: input.deviceId,
+    version: 2,
+    encrypted: false,
+    triggerBased: (info & 0x04) !== 0,
+    packetId,
+    button,
+    fingerprint: fingerprint(input.serviceData),
+  };
+}
+

package/src/match/remote/types.ts

@@ -0,0 +1,116 @@
+export const BTHOME_SERVICE_UUID = "FCD2" as const;
+
+export type RemoteButtonAction = "single" | "double" | "long";
+export type RemoteInputMode = "bthome" | "hidVolume" | "both";
+export type RemoteMappedAction = "left" | "right" | "undo" | "none";
+export interface RemoteActionMapping {
+  readonly volumeUp: RemoteMappedAction;
+  readonly volumeDown: RemoteMappedAction;
+  readonly longPress: RemoteMappedAction;
+}
+export const DEFAULT_REMOTE_ACTION_MAPPING: RemoteActionMapping = {
+  volumeUp: "left", volumeDown: "right", longPress: "undo",
+};
+export interface RemoteHidVolumeEvent {
+  readonly source: "hidVolume";
+  readonly direction: "volumeUp" | "volumeDown";
+  readonly repeat: boolean;
+  readonly longPress: boolean;
+  readonly timestamp: number;
+}
+
+export type RemoteHidGesture = "single" | "double" | "hold";
+
+export interface RemoteHidGestureMapping {
+  /** Raw HID direction emitted by the calibrated remote button. */
+  readonly direction: RemoteHidVolumeEvent["direction"];
+  /** Quiet window used to close one physical gesture burst. */
+  readonly settleMs: number;
+  /** Repeated volume changes required to classify a hold before the burst ends. */
+  readonly holdEventCount: number;
+  readonly single: RemoteMappedAction;
+  readonly double: RemoteMappedAction;
+  readonly hold: RemoteMappedAction;
+}
+
+export interface RemoteBinding {
+  /** Stable identifier supplied by CoreBluetooth or BluetoothLeScanner. */
+  readonly deviceId: string;
+  readonly label?: string;
+}
+
+export type RemotePermissionStatus =
+  | "unknown"
+  | "granted"
+  | "denied"
+  | "restricted"
+  | "unavailable";
+
+export type RemoteStatus =
+  | "unavailable"
+  | "poweredOff"
+  | "idle"
+  | "scanning"
+  | "bound"
+  | "outOfRange";
+
+export interface RemoteCandidate {
+  readonly deviceId: string;
+  readonly label?: string;
+  readonly rssi: number;
+  readonly lastSeenAt: number;
+}
+
+export interface RemoteState {
+  readonly status: RemoteStatus;
+  readonly permission: RemotePermissionStatus;
+  readonly binding: RemoteBinding | null;
+  readonly candidate: RemoteCandidate | null;
+  readonly lastSeenAt: number | null;
+  readonly error: RemoteError | null;
+  readonly hidCaptureArmed: boolean;
+  readonly lastInputSource: "bthome" | "hidVolume" | null;
+  readonly lastHidEvent: RemoteHidVolumeEvent | null;
+}
+
+export type RemoteErrorCode =
+  | "permission_denied"
+  | "permission_restricted"
+  | "bluetooth_unavailable"
+  | "bluetooth_powered_off"
+  | "scan_failed"
+  | "native_unavailable";
+
+export class RemoteError extends Error {
+  readonly name = "RemoteError";
+
+  constructor(readonly code: RemoteErrorCode, message: string, options?: { cause?: unknown }) {
+    super(message, options);
+  }
+}
+
+export interface RemoteScanAdvertisement {
+  readonly deviceId: string;
+  readonly name?: string;
+  readonly rssi: number;
+  readonly serviceUuid: string;
+  /** Base64 encoded FCD2 service-data payload, beginning with the device-info byte. */
+  readonly serviceData: string;
+  readonly timestamp: number;
+}
+
+export type RemoteNativeState =
+  | { readonly status: "permission"; readonly permission: RemotePermissionStatus }
+  | { readonly status: "poweredOff" | "unavailable" | "scanning" | "idle" }
+  | { readonly status: "error"; readonly code: string; readonly message: string };
+
+export interface RemoteService {
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  dispose(): Promise<void>;
+  subscribeAdvertisement(listener: (event: RemoteScanAdvertisement) => void): () => void;
+  subscribeState(listener: (event: RemoteNativeState) => void): () => void;
+  startHidCapture(options?: { consume?: boolean }): Promise<void>;
+  stopHidCapture(): Promise<void>;
+  subscribeHidVolume(listener: (event: RemoteHidVolumeEvent) => void): () => void;
+}

package/src/match/replay.ts

@@ -0,0 +1,102 @@
+import type {
+  MatchEvent,
+  MatchEventUndoneEvent,
+  MatchInputSource,
+  MatchSnapshot,
+} from "./contracts";
+import { applyMatchEvent, createMatch } from "./engine";
+import { cloneSnapshot, valuesEqual } from "./state";
+import { assertRuntimeMatchEvent } from "./validation";
+
+interface EffectiveEvent {
+  event: Exclude<MatchEvent, MatchEventUndoneEvent>;
+  before: MatchSnapshot;
+}
+
+interface ReplayTrace {
+  snapshot: MatchSnapshot;
+  effectiveEvents: EffectiveEvent[];
+  processedEvents: number;
+  undoValidations: number;
+}
+
+function replayTrace(events: readonly unknown[]): ReplayTrace {
+  const [rawCreated, ...remaining] = events;
+  assertRuntimeMatchEvent(rawCreated);
+  if (rawCreated.type !== "matchCreated" || rawCreated.sequence !== 0) {
+    throw new TypeError("A match event log must begin with its creation event");
+  }
+  const created = rawCreated;
+  if (created.id !== `${created.snapshot.id}:0`) {
+    throw new TypeError("Creation event id does not match its snapshot");
+  }
+  const expected = createMatch(
+    {
+      id: created.snapshot.id,
+      format: created.snapshot.format,
+      scoringMode: created.snapshot.scoringMode,
+      targetScore: created.snapshot.targetScore,
+      initialServingTeam: created.snapshot.initialServingTeam,
+      teams: created.snapshot.teams,
+    },
+    created.source,
+  ).snapshot;
+  if (!valuesEqual(expected, created.snapshot)) {
+    throw new TypeError("Creation snapshot is not a valid initial match state");
+  }
+  let snapshot = cloneSnapshot(created.snapshot);
+  const effectiveEvents: EffectiveEvent[] = [];
+  let processedEvents = 1;
+  let undoValidations = 0;
+
+  for (const rawEvent of remaining) {
+    assertRuntimeMatchEvent(rawEvent);
+    const event = rawEvent;
+    if (event.type === "matchEventUndone") {
+      const target = effectiveEvents.at(-1);
+      if (!target || target.event.id !== event.targetEventId) {
+        throw new TypeError("Undo does not target the latest effective match event");
+      }
+      if (!valuesEqual(target.before, event.restoredSnapshot)) {
+        throw new TypeError("Undo snapshot does not match its event lineage");
+      }
+      effectiveEvents.pop();
+      undoValidations += 1;
+    } else {
+      effectiveEvents.push({ event, before: cloneSnapshot(snapshot) });
+    }
+    snapshot = applyMatchEvent(snapshot, event);
+    processedEvents += 1;
+  }
+
+  return { snapshot, effectiveEvents, processedEvents, undoValidations };
+}
+
+export function replayMatchEvents(events: readonly unknown[]): MatchSnapshot {
+  return replayTrace(events).snapshot;
+}
+
+/** Internal deterministic complexity signal used by reducer regression tests. */
+export function replayMatchEventsWithStats(events: readonly unknown[]) {
+  const { snapshot, processedEvents, undoValidations } = replayTrace(events);
+  return { snapshot, processedEvents, undoValidations };
+}
+
+export function undoLastMatchEvent(
+  events: readonly MatchEvent[],
+  source: MatchInputSource = "local",
+): MatchEventUndoneEvent | null {
+  const trace = replayTrace(events);
+  const target = trace.effectiveEvents.at(-1);
+  if (!target) return null;
+  const sequence = trace.snapshot.sequence + 1;
+  return {
+    type: "matchEventUndone",
+    schemaVersion: 1,
+    id: `${trace.snapshot.id}:${sequence}`,
+    sequence,
+    source,
+    targetEventId: target.event.id,
+    restoredSnapshot: cloneSnapshot(target.before),
+  };
+}

package/src/match/state.ts

@@ -0,0 +1,72 @@
+import type {
+  GameSnapshot,
+  MatchPlayer,
+  MatchSnapshot,
+  MatchTeam,
+} from "./contracts";
+
+function clonePlayer(player: MatchPlayer): MatchPlayer {
+  return { id: player.id, name: player.name };
+}
+
+export function cloneTeam(team: MatchTeam): MatchTeam {
+  return {
+    id: team.id,
+    ...(team.name === undefined ? {} : { name: team.name }),
+    ...(team.initialServerId === undefined
+      ? {}
+      : { initialServerId: team.initialServerId }),
+    players: team.players.map(clonePlayer),
+  };
+}
+
+function cloneGame(game: GameSnapshot): GameSnapshot {
+  return { ...game, score: { ...game.score } };
+}
+
+export function cloneSnapshot(snapshot: MatchSnapshot): MatchSnapshot {
+  return {
+    ...snapshot,
+    teams: { A: cloneTeam(snapshot.teams.A), B: cloneTeam(snapshot.teams.B) },
+    designatedServerByTeam: { ...snapshot.designatedServerByTeam },
+    courtSides: { ...snapshot.courtSides },
+    playerCourts: { ...snapshot.playerCourts },
+    games: snapshot.games.map(cloneGame),
+    gamesWon: { ...snapshot.gamesWon },
+    serve: { ...snapshot.serve },
+    pendingCourtSwitch: snapshot.pendingCourtSwitch
+      ? { ...snapshot.pendingCourtSwitch }
+      : null,
+  };
+}
+
+export function valuesEqual(left: unknown, right: unknown): boolean {
+  if (left === right) return true;
+  if (Array.isArray(left) || Array.isArray(right)) {
+    return (
+      Array.isArray(left) &&
+      Array.isArray(right) &&
+      left.length === right.length &&
+      left.every((value, index) => valuesEqual(value, right[index]))
+    );
+  }
+  if (
+    typeof left !== "object" ||
+    left === null ||
+    typeof right !== "object" ||
+    right === null
+  ) {
+    return false;
+  }
+  const leftRecord = left as Record<string, unknown>;
+  const rightRecord = right as Record<string, unknown>;
+  const leftKeys = Object.keys(leftRecord).sort();
+  const rightKeys = Object.keys(rightRecord).sort();
+  return (
+    leftKeys.length === rightKeys.length &&
+    leftKeys.every(
+      (key, index) =>
+        key === rightKeys[index] && valuesEqual(leftRecord[key], rightRecord[key]),
+    )
+  );
+}