@glassly/engine 0.1.0-dev.0

package/src/services/PairingIdentity.ts

@@ -0,0 +1,154 @@
+/**
+ * PairingIdentity — the pairing-identity lifecycle, reified. The two-phase
+ * identity rules (see the pending/default group in stores/settings.ts) exist
+ * as a three-state machine over the identity settings keys:
+ *
+ *   none ──markPendingSelection()──▶ pending ──native promotion──▶ paired
+ *                                       ▲                            │
+ *                                       └───────boot demotion────────┘
+ *
+ * - `none`    — no model ever selected: hosts route to model selection.
+ * - `pending` — a model was CHOSEN (the one JS-owned identity write, made at
+ *               scan entry) but pairing never completed: hosts render
+ *               finish-pairing affordances.
+ * - `paired`  — the native layer promoted the identity at pairing success
+ *               (handleDeviceReady) and echoed it down via save_setting:
+ *               hosts render the device card / connect surfaces.
+ *
+ * Projection law, mirroring native currentDefaultDevice() on both platforms:
+ * `paired` requires default_wearable AND device_name; device_address is
+ * optional. Two read-time alignments with the demotion's own write rules:
+ * - The simulated device is its own identity (its name mirrors the model at
+ *   connectSimulated, and the boot demotion never touches it), so a simulated
+ *   default_wearable projects as `paired` even without a device_name echo.
+ * - A non-simulated default_wearable WITHOUT a device_name is the orphan
+ *   population `demoteOrphanedDefaultWearable` repairs into pending_wearable
+ *   at boot; the projection already reads it as `pending` (a fresher
+ *   pending_wearable wins, matching the demotion's latest-selection-wins
+ *   backfill).
+ *
+ * JS-initiated identity writes live here and only here — the scan screen
+ * (markPendingSelection), the device-event router (promotion retires the
+ * pending marker), and the boot demotion (demoteDefaultToPending) invoke
+ * these methods instead of writing the raw keys. The router's generic
+ * save_setting persistence is the inbound native→JS echo leg, not a
+ * JS-initiated write, and stays with the router.
+ */
+import {result as Res, type AsyncResult} from "typesafe-ts"
+
+import {useSettingsStore, SETTINGS} from "../stores/settings"
+import {DeviceTypes} from "../types"
+
+export type IdentitySnapshot =
+  | {kind: "none"}
+  | {kind: "pending"; model: string}
+  | {kind: "paired"; model: string; name: string; address?: string}
+
+// Identity keys hold model/name strings; anything else (legacy null, a stray
+// non-string) reads as absent, matching native currentDefaultDevice()'s
+// blank checks.
+function readIdentityString(key: string): string {
+  const value = useSettingsStore.getState().getSetting(key)
+  return typeof value === "string" ? value : ""
+}
+
+/** Project the identity settings keys into the lifecycle snapshot. */
+export function projectPairingIdentity(): IdentitySnapshot {
+  const model = readIdentityString(SETTINGS.default_wearable.key)
+  const name = readIdentityString(SETTINGS.device_name.key)
+
+  if (model && name) {
+    const address = readIdentityString(SETTINGS.device_address.key)
+    return address ? {kind: "paired", model, name, address} : {kind: "paired", model, name}
+  }
+  if (model && model.includes(DeviceTypes.SIMULATED)) {
+    return {kind: "paired", model, name: model}
+  }
+  const pending = readIdentityString(SETTINGS.pending_wearable.key)
+  if (pending) return {kind: "pending", model: pending}
+  if (model) return {kind: "pending", model}
+  return {kind: "none"}
+}
+
+/**
+ * Subscribe to identity changes, deduped on the projected snapshot (same
+ * style as glasses.onStatus): the settings store updates on many keys; the
+ * callback fires only when the identity snapshot actually changes.
+ */
+export function subscribePairingIdentity(cb: (identity: IdentitySnapshot) => void): () => void {
+  let last = JSON.stringify(projectPairingIdentity())
+  return useSettingsStore.subscribe(() => {
+    const snap = projectPairingIdentity()
+    const key = JSON.stringify(snap)
+    if (key === last) return
+    last = key
+    cb(snap)
+  })
+}
+
+/**
+ * Selection: mark the model the user chose as the PENDING wearable (written
+ * at scan entry). Promotion to `paired` only ever happens natively at pairing
+ * success. The marker persists so an abandoned selection still renders its
+ * finish-pairing card after an app restart.
+ */
+export function markPendingSelection(model: string): AsyncResult<void, Error> {
+  // Guard the public write-path: an empty/whitespace model would persist a
+  // pending identity that renders a blank finish-pairing card.
+  const trimmed = typeof model === "string" ? model.trim() : ""
+  if (!trimmed) {
+    console.warn(`PairingIdentity: ignoring pending selection with empty model (got ${JSON.stringify(model)})`)
+    return Res.try_async(async () => {})
+  }
+  console.log(`PairingIdentity: pending selection -> "${trimmed}"`)
+  const result = useSettingsStore.getState().setSetting(SETTINGS.pending_wearable.key, trimmed)
+  // setSetting resolves to a Result (never rejects); a persist failure would
+  // silently drop the finish-pairing affordance on restart — surface it.
+  void Promise.resolve(result).then((r) => {
+    if (r.is_error()) console.warn("PairingIdentity: pending selection failed to persist:", r.error)
+  })
+  return result
+}
+
+/**
+ * Promotion retires the selection: when the native layer promotes the default
+ * wearable at pairing success and its save_setting echo lands, the pending
+ * marker has served its purpose. Invoked by DeviceEventRouter for every echo;
+ * a no-op for other keys, empty promotions, and an already-clear marker.
+ */
+export async function retirePendingSelectionOnPromotion(echoedKey: string, echoedValue: unknown): Promise<void> {
+  if (echoedKey !== SETTINGS.default_wearable.key || !echoedValue) return
+  const settings = useSettingsStore.getState()
+  const pending = settings.getSetting(SETTINGS.pending_wearable.key)
+  if (pending) {
+    console.log(`PairingIdentity: promotion "${String(echoedValue)}" retires pending "${pending}"`)
+    await settings.setSetting(SETTINGS.pending_wearable.key, "")
+  }
+}
+
+/**
+ * Demotion: turn an orphaned default identity back into a pending selection.
+ * The guards (hydration, the native default-device read, link-layer state)
+ * live with the boot repair in demoteOrphanedDefaultWearable — this is only
+ * the identity write set: backfill the pending marker unless a fresher
+ * selection already holds it (the user's LATEST selection wins), then clear
+ * the promoted identity triplet.
+ */
+export async function demoteDefaultToPending(model: string): Promise<void> {
+  const settings = useSettingsStore.getState()
+  // readIdentityString, not raw getSetting: a truthy non-string legacy value
+  // must read as absent here too, or the orphaned model is never backfilled
+  // while the projection reads the same junk as no pending at all.
+  const fresher = readIdentityString(SETTINGS.pending_wearable.key)
+  console.log(
+    fresher
+      ? `PairingIdentity: demote "${model}" — fresher pending "${fresher}" kept`
+      : `PairingIdentity: demote "${model}" -> pending`,
+  )
+  if (!fresher) {
+    await settings.setSetting(SETTINGS.pending_wearable.key, model)
+  }
+  await settings.setSetting(SETTINGS.default_wearable.key, "")
+  await settings.setSetting(SETTINGS.device_name.key, "")
+  await settings.setSetting(SETTINGS.device_address.key, "")
+}

package/src/services/PhoneCalendarHelpers.ts

@@ -0,0 +1,212 @@
+import {MiniappErrorCode, type CalendarEvent} from "@glassly/miniapp"
+
+const DEFAULT_LIMIT = 50
+const MAX_LIMIT = 100
+const MAX_RANGE_MS = 31 * 24 * 60 * 60 * 1000
+
+export interface CalendarListRequest {
+  startsAt?: unknown
+  endsAt?: unknown
+  limit?: unknown
+}
+
+export class PhoneCalendarError extends Error {
+  constructor(
+    public readonly code: MiniappErrorCode,
+    message: string,
+  ) {
+    super(message)
+    this.name = "PhoneCalendarError"
+  }
+}
+
+export interface ValidatedCalendarListRequest {
+  startsAt: Date
+  endsAt: Date
+  limit: number
+}
+
+export interface RawCalendarEvent {
+  id?: string
+  calendarId?: string
+  title?: string | null
+  startDate: string | Date
+  endDate: string | Date
+  timeZone?: string | null
+  allDay?: boolean
+  location?: string | null
+  notes?: string | null
+  url?: string | null
+}
+
+export function validateCalendarListRequest(request: CalendarListRequest): ValidatedCalendarListRequest {
+  const startsAt = parseDate(request.startsAt, "startsAt")
+  const endsAt = parseDate(request.endsAt, "endsAt")
+  if (endsAt.getTime() <= startsAt.getTime()) {
+    throw new PhoneCalendarError(MiniappErrorCode.INVALID_ARGUMENT, "endsAt must be after startsAt")
+  }
+  if (endsAt.getTime() - startsAt.getTime() > MAX_RANGE_MS) {
+    throw new PhoneCalendarError(MiniappErrorCode.INVALID_ARGUMENT, "Calendar query range may not exceed 31 days")
+  }
+
+  const limit = request.limit === undefined ? DEFAULT_LIMIT : request.limit
+  if (typeof limit !== "number" || !Number.isInteger(limit) || limit < 1 || limit > MAX_LIMIT) {
+    throw new PhoneCalendarError(
+      MiniappErrorCode.INVALID_ARGUMENT,
+      `limit must be an integer between 1 and ${MAX_LIMIT}`,
+    )
+  }
+  return {startsAt, endsAt, limit}
+}
+
+function parseDate(value: unknown, field: string): Date {
+  if (typeof value !== "string") {
+    throw new PhoneCalendarError(MiniappErrorCode.INVALID_ARGUMENT, `${field} must be an ISO 8601 string`)
+  }
+  const date = new Date(value)
+  if (Number.isNaN(date.getTime())) {
+    throw new PhoneCalendarError(MiniappErrorCode.INVALID_ARGUMENT, `${field} must be a valid ISO 8601 string`)
+  }
+  return date
+}
+
+export function extractHttpsLinks(...values: Array<string | null | undefined>): string[] {
+  const links = new Set<string>()
+  for (const value of values) {
+    for (const match of value?.match(/https:\/\/[^\s<>"']+/gi) ?? []) {
+      let link = match
+      while (".,;:!?)]}".includes(link[link.length - 1] ?? "")) link = link.slice(0, -1)
+      if (link) links.add(link)
+    }
+  }
+  return [...links]
+}
+
+interface CalendarDateParts {
+  year: number
+  month: number
+  day: number
+  hour: number
+  minute: number
+  second: number
+}
+
+function localDateParts(date: Date): CalendarDateParts {
+  return {
+    year: date.getFullYear(),
+    month: date.getMonth() + 1,
+    day: date.getDate(),
+    hour: date.getHours(),
+    minute: date.getMinutes(),
+    second: date.getSeconds(),
+  }
+}
+
+function datePartsInTimeZone(date: Date, timeZone: string): CalendarDateParts | undefined {
+  try {
+    const parts = new Intl.DateTimeFormat("en-US", {
+      timeZone,
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+      hour: "2-digit",
+      minute: "2-digit",
+      second: "2-digit",
+      hourCycle: "h23",
+    }).formatToParts(date)
+    const value = (type: Intl.DateTimeFormatPartTypes) => Number(parts.find((part) => part.type === type)?.value)
+    return {
+      year: value("year"),
+      month: value("month"),
+      day: value("day"),
+      hour: value("hour"),
+      minute: value("minute"),
+      second: value("second"),
+    }
+  } catch {
+    return undefined
+  }
+}
+
+function timeZoneOffsetMinutes(date: Date, timeZone: string): number | undefined {
+  const parts = datePartsInTimeZone(date, timeZone)
+  if (!parts) return undefined
+  const representedAsUtc = Date.UTC(
+    parts.year,
+    parts.month - 1,
+    parts.day,
+    parts.hour,
+    parts.minute,
+    parts.second,
+    date.getUTCMilliseconds(),
+  )
+  return Math.round((representedAsUtc - date.getTime()) / 60_000)
+}
+
+function pad(value: number, length = 2): string {
+  return String(value).padStart(length, "0")
+}
+
+function formatOffset(offsetMinutes: number): string {
+  if (offsetMinutes === 0) return "Z"
+  const sign = offsetMinutes < 0 ? "-" : "+"
+  const absolute = Math.abs(offsetMinutes)
+  return `${sign}${pad(Math.floor(absolute / 60))}:${pad(absolute % 60)}`
+}
+
+function formatAllDayDate(value: string | Date, timeZone?: string | null): string {
+  const dateOnly = typeof value === "string" ? /^(\d{4})-(\d{2})-(\d{2})$/.exec(value) : null
+  if (dateOnly) {
+    const [, year, month, day] = dateOnly
+    const localMidnight = new Date(Number(year), Number(month) - 1, Number(day))
+    let offsetMinutes = -localMidnight.getTimezoneOffset()
+    if (timeZone) {
+      // Resolve the offset at midnight in the event timezone. Repeating once
+      // accounts for the initial UTC guess landing across a DST boundary.
+      const wallTime = Date.UTC(Number(year), Number(month) - 1, Number(day))
+      let instant = new Date(wallTime)
+      for (let attempt = 0; attempt < 2; attempt += 1) {
+        const offset = timeZoneOffsetMinutes(instant, timeZone)
+        if (offset === undefined) break
+        offsetMinutes = offset
+        instant = new Date(wallTime - offset * 60_000)
+      }
+    }
+    return `${year}-${month}-${day}T00:00:00.000${formatOffset(offsetMinutes)}`
+  }
+
+  const date = new Date(value)
+  const zonedParts = timeZone ? datePartsInTimeZone(date, timeZone) : undefined
+  const parts = zonedParts ?? localDateParts(date)
+  const offsetMinutes =
+    timeZone && zonedParts
+      ? (timeZoneOffsetMinutes(date, timeZone) ?? -date.getTimezoneOffset())
+      : -date.getTimezoneOffset()
+  return `${pad(parts.year, 4)}-${pad(parts.month)}-${pad(parts.day)}T${pad(parts.hour)}:${pad(parts.minute)}:${pad(parts.second)}.${pad(date.getUTCMilliseconds(), 3)}${formatOffset(offsetMinutes)}`
+}
+
+export function normalizeCalendarEvent(event: RawCalendarEvent): CalendarEvent {
+  const startsAt = event.allDay
+    ? formatAllDayDate(event.startDate, event.timeZone)
+    : new Date(event.startDate).toISOString()
+  const endsAt = event.allDay ? formatAllDayDate(event.endDate, event.timeZone) : new Date(event.endDate).toISOString()
+  const calendarId = event.calendarId ?? ""
+  const eventId = event.id ?? ""
+  return {
+    id: `${calendarId}:${eventId}:${startsAt}`,
+    calendarId,
+    title: event.title ?? "",
+    startsAt,
+    endsAt,
+    ...(event.timeZone ? {timezone: event.timeZone} : {}),
+    allDay: !!event.allDay,
+    ...(event.location ? {location: event.location} : {}),
+    ...(event.notes ? {notes: event.notes} : {}),
+    ...(event.url ? {url: event.url} : {}),
+    links: extractHttpsLinks(event.url, event.location, event.notes),
+  }
+}
+
+export function calendarEventOverlapsWindow(event: CalendarEvent, startsAt: Date, endsAt: Date): boolean {
+  return Date.parse(event.endsAt) > startsAt.getTime() && Date.parse(event.startsAt) < endsAt.getTime()
+}

package/src/services/PhoneCalendarService.ts

@@ -0,0 +1,61 @@
+import * as Calendar from "expo-calendar"
+import {Platform} from "react-native"
+import {check, PERMISSIONS, RESULTS} from "react-native-permissions"
+
+import {MiniappErrorCode, type CalendarListResult} from "@glassly/miniapp"
+
+import {
+  calendarEventOverlapsWindow,
+  type CalendarListRequest,
+  normalizeCalendarEvent,
+  PhoneCalendarError,
+  validateCalendarListRequest,
+} from "./PhoneCalendarHelpers"
+
+export {PhoneCalendarError} from "./PhoneCalendarHelpers"
+
+type CalendarPermissionStatus = Awaited<
+  ReturnType<typeof Calendar.getCalendarPermissionsAsync>
+>["status"]
+
+/**
+ * expo-calendar reports anything below EventKit full access as not granted,
+ * so distinguish the states the user can actually fix. "Reopen the miniapp"
+ * is only true while the permission is undetermined — once iOS has resolved
+ * it (denied or write-only/limited), only Settings can change it.
+ */
+async function calendarPermissionMessage(status: CalendarPermissionStatus): Promise<string> {
+  if (status === "undetermined") {
+    return "Calendar permission has not been granted yet. Reopen the miniapp and allow calendar access."
+  }
+  if (Platform.OS === "ios") {
+    const writeOnly = await check(PERMISSIONS.IOS.CALENDARS_WRITE_ONLY).catch(() => null)
+    if (writeOnly === RESULTS.GRANTED || writeOnly === RESULTS.LIMITED) {
+      return 'Calendar access is limited to write-only. Enable "Full Access" for Glassly in Settings › Privacy & Security › Calendars.'
+    }
+    return "Calendar access is denied. Enable it for Glassly in Settings › Privacy & Security › Calendars."
+  }
+  return "Calendar access is denied. Enable the Calendar permission for Glassly in your phone's app settings."
+}
+
+export async function listPhoneCalendarEvents(request: CalendarListRequest): Promise<CalendarListResult> {
+  const {startsAt, endsAt, limit} = validateCalendarListRequest(request)
+  const permission = await Calendar.getCalendarPermissions()
+  if (permission.status !== "granted") {
+    throw new PhoneCalendarError(MiniappErrorCode.PERMISSION_DENIED, await calendarPermissionMessage(permission.status))
+  }
+
+  const calendars = await Calendar.getCalendars(Calendar.EntityTypes.EVENT)
+  if (calendars.length === 0) return {events: [], truncated: false}
+
+  const rawEvents = await Calendar.listEvents(calendars, startsAt, endsAt)
+  const events = rawEvents
+    .map(normalizeCalendarEvent)
+    .filter((event) => calendarEventOverlapsWindow(event, startsAt, endsAt))
+    .sort((a, b) => Date.parse(a.startsAt) - Date.parse(b.startsAt) || Date.parse(a.endsAt) - Date.parse(b.endsAt))
+
+  return {
+    events: events.slice(0, limit),
+    truncated: events.length > limit,
+  }
+}

package/src/services/PhoneCameraFovCoordinator.ts

@@ -0,0 +1,210 @@
+import BluetoothSdk, {type CameraFovRequest, type CameraFovResult} from "@glassly/bluetooth-sdk/internal"
+
+export const CAMERA_FOV_OVERRIDE_TTL_MS = 300_000
+export const CAMERA_FOV_OVERRIDE_REFRESH_MS = 120_000
+// Legacy ASG clients restart the camera HAL for an FOV update but cannot acknowledge
+// when it is usable again. The ASG cooldown is 5s; retain a small settling margin so
+// miniapps cannot submit a photo against the stale camera service.
+const LEGACY_CAMERA_RESTART_SETTLE_MS = 7_000
+
+interface OverrideEntry {
+  leaseId: string
+  fov: number
+  roiPosition: "center" | "bottom" | "top"
+  order: number
+}
+
+let leaseCounter = 0
+
+function mintLeaseId(): string {
+  leaseCounter = (leaseCounter + 1) & 0xffff
+  return `fov-${leaseCounter.toString(16).padStart(4, "0")}`
+}
+
+function isLegacyFovCompatibilityError(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error)
+  return /timed out waiting for glasses response|not available|unknown method/i.test(message)
+}
+
+/**
+ * Serializes miniapp-owned FOV/ROI overrides. The last live owner wins; releasing it applies the
+ * previous owner or asks ASG to restore its persistent base. ASG refreshes are no-restart TTL
+ * extensions for crash safety.
+ */
+export class PhoneCameraFovCoordinator {
+  private readonly overrides = new Map<string, OverrideEntry>()
+  private effectiveLeaseId: string | undefined
+  private sequence = 0
+  private queue: Promise<unknown> = Promise.resolve()
+  private refreshTimer: ReturnType<typeof setTimeout> | undefined
+  private legacyMode = false
+
+  constructor(private readonly legacyRestartSettleMs = LEGACY_CAMERA_RESTART_SETTLE_MS) {}
+
+  /** Report-safe FOV ownership snapshot for incident diagnostics. */
+  getDiagnosticSnapshot(): Record<string, unknown> {
+    return {
+      owners: [...this.overrides.entries()]
+        .sort(([, a], [, b]) => b.order - a.order)
+        .map(([packageName, entry]) => ({
+          packageName,
+          effective: entry.leaseId === this.effectiveLeaseId,
+          fov: entry.fov,
+          roiPosition: entry.roiPosition,
+        })),
+      legacyMode: this.legacyMode,
+    }
+  }
+
+  setOverride(packageName: string, request: CameraFovRequest): Promise<CameraFovResult> {
+    return this.enqueue(async () => {
+      const previous = this.overrides.get(packageName)
+      const leaseId = previous?.leaseId ?? mintLeaseId()
+      const order = ++this.sequence
+      try {
+        if (this.legacyMode) return this.setLegacyOverride(packageName, request, leaseId, order)
+        const result = await BluetoothSdk.setCameraFovOverride({
+          ...request,
+          leaseId,
+          ttlMs: CAMERA_FOV_OVERRIDE_TTL_MS,
+        })
+        this.overrides.set(packageName, {
+          leaseId,
+          fov: result.fov,
+          roiPosition: result.roiPosition,
+          order,
+        })
+        this.effectiveLeaseId = leaseId
+        this.scheduleRefresh()
+        return result
+      } catch (error) {
+        if (!isLegacyFovCompatibilityError(error)) throw error
+        console.warn("[PhoneCameraFovCoordinator] override unavailable; using legacy FOV command", error)
+        const result = await this.setLegacyOverride(packageName, request, leaseId, order)
+        // Only cache compatibility mode after the fallback itself succeeds. A
+        // disconnect or missing native bridge must not permanently downgrade
+        // future requests on a healthy/newer glasses connection.
+        this.legacyMode = true
+        return result
+      }
+    })
+  }
+
+  releaseForApp(packageName: string): Promise<void> {
+    return this.enqueue(async () => {
+      const removed = this.overrides.get(packageName)
+      if (!removed) return
+      if (removed.leaseId !== this.effectiveLeaseId) {
+        this.overrides.delete(packageName)
+        return
+      }
+
+      const next = [...this.overrides.entries()]
+        .filter(([candidatePackage]) => candidatePackage !== packageName)
+        .map(([, entry]) => entry)
+        .sort((a, b) => b.order - a.order)[0]
+      if (this.legacyMode) {
+        if (next) {
+          await this.applyLegacyFov({fov: next.fov, roiPosition: next.roiPosition})
+          this.overrides.delete(packageName)
+          this.effectiveLeaseId = next.leaseId
+        } else {
+          // Legacy commands are one-way and have no lease-release protocol.
+          // Ask native to replay its unchanged persistent base setting, then
+          // probe the modern override path again for the next ownership cycle.
+          await BluetoothSdk.restoreLegacyCameraFov()
+          await this.waitForLegacyCameraRestart()
+          this.overrides.delete(packageName)
+          this.clearRefresh()
+          this.effectiveLeaseId = undefined
+          this.legacyMode = false
+        }
+        return
+      }
+      if (next) {
+        await BluetoothSdk.setCameraFovOverride({
+          leaseId: next.leaseId,
+          fov: next.fov,
+          roiPosition: next.roiPosition,
+          ttlMs: CAMERA_FOV_OVERRIDE_TTL_MS,
+        })
+        // Commit phone-side ownership only after ASG accepted the replacement. On failure the
+        // closing app remains effective here, allowing unregister/reconnect cleanup to retry.
+        this.overrides.delete(packageName)
+        this.effectiveLeaseId = next.leaseId
+        this.scheduleRefresh()
+      } else {
+        await BluetoothSdk.releaseCameraFovOverride(removed.leaseId)
+        this.overrides.delete(packageName)
+        this.clearRefresh()
+        this.effectiveLeaseId = undefined
+      }
+    })
+  }
+
+  private scheduleRefresh(): void {
+    if (this.legacyMode) return
+    this.clearRefresh()
+    const leaseId = this.effectiveLeaseId
+    if (!leaseId) return
+    this.refreshTimer = setTimeout(() => {
+      void this.enqueue(async () => {
+        if (this.effectiveLeaseId !== leaseId) return
+        const entry = [...this.overrides.values()].find((candidate) => candidate.leaseId === leaseId)
+        if (!entry) return
+        await BluetoothSdk.setCameraFovOverride({
+          leaseId,
+          fov: entry.fov,
+          roiPosition: entry.roiPosition,
+          ttlMs: CAMERA_FOV_OVERRIDE_TTL_MS,
+        })
+        this.scheduleRefresh()
+      }).catch((error) => console.warn("[PhoneCameraFovCoordinator] failed to refresh override", error))
+    }, CAMERA_FOV_OVERRIDE_REFRESH_MS)
+  }
+
+  private clearRefresh(): void {
+    if (this.refreshTimer) clearTimeout(this.refreshTimer)
+    this.refreshTimer = undefined
+  }
+
+  private async setLegacyOverride(
+    packageName: string,
+    request: CameraFovRequest,
+    leaseId: string,
+    order: number,
+  ): Promise<CameraFovResult> {
+    const result = await this.applyLegacyFov(request)
+    this.overrides.set(packageName, {
+      leaseId,
+      fov: result.fov,
+      roiPosition: result.roiPosition,
+      order,
+    })
+    this.effectiveLeaseId = leaseId
+    this.clearRefresh()
+    return result
+  }
+
+  private async applyLegacyFov(request: CameraFovRequest): Promise<CameraFovResult> {
+    const result = await BluetoothSdk.setLegacyCameraFov(request)
+    await this.waitForLegacyCameraRestart()
+    return result
+  }
+
+  private waitForLegacyCameraRestart(): Promise<void> {
+    if (this.legacyRestartSettleMs <= 0) return Promise.resolve()
+    return new Promise<void>((resolve) => setTimeout(resolve, this.legacyRestartSettleMs))
+  }
+
+  private enqueue<T>(operation: () => Promise<T>): Promise<T> {
+    const result = this.queue.then(operation, operation)
+    this.queue = result.then(
+      () => undefined,
+      () => undefined,
+    )
+    return result
+  }
+}
+
+export const phoneCameraFovCoordinator = new PhoneCameraFovCoordinator()