@glassly/engine 0.1.0-dev.0

package/src/facades/permissions.ts

@@ -0,0 +1,165 @@
+/**
+ * permissions facade — `engine.permissions`: the raw OS-permission ops the runtime
+ * needs, mapped from feature keys to react-native-permissions. This is the LEAN
+ * surface (check/request/openSettings/requirementsForMiniapp) — the host keeps its
+ * own UI helpers (rationale dialogs, denied-warnings) on top; engine stays free of
+ * i18n/theme/AlertUtils.
+ */
+import {Platform, Linking, PermissionsAndroid, type Permission as AndroidPermission} from "react-native"
+import {check, request, PERMISSIONS, RESULTS, type Permission} from "react-native-permissions"
+
+import appRegistry from "../services/AppRegistry"
+import type {AppletPermission} from "../types"
+
+/** OEM-facing feature keys (mapped to OS permissions per platform). */
+export const PermissionFeatures = {
+  MICROPHONE: "microphone",
+  CAMERA: "camera",
+  CALENDAR: "calendar",
+  LOCATION: "location",
+  LOCAL_WIFI: "local_wifi",
+  BACKGROUND_LOCATION: "background_location",
+  BLUETOOTH: "bluetooth",
+  PHONE_STATE: "phone_state",
+  POST_NOTIFICATIONS: "post_notifications",
+} as const
+
+const ANDROID = PermissionsAndroid.PERMISSIONS
+const apiLevel = typeof Platform.Version === "number" ? Platform.Version : parseInt(String(Platform.Version), 10)
+const requiresSeparateAndroidBackgroundLocation = apiLevel >= 29
+
+export function localWifiPermissionForAndroid(
+  androidApiLevel: number,
+  androidPermissions: typeof PermissionsAndroid.PERMISSIONS = ANDROID,
+): AndroidPermission {
+  return androidApiLevel >= 33 ? androidPermissions.NEARBY_WIFI_DEVICES : androidPermissions.ACCESS_FINE_LOCATION
+}
+
+async function areAndroidPermissionsGranted(perms: AndroidPermission[]): Promise<boolean> {
+  for (const p of perms) {
+    if (!(await PermissionsAndroid.check(p))) return false
+  }
+  return true
+}
+
+async function requestAndroidPermissions(perms: AndroidPermission[]): Promise<boolean> {
+  const results = await PermissionsAndroid.requestMultiple(perms)
+  return perms.every((p) => results[p] === PermissionsAndroid.RESULTS.GRANTED)
+}
+
+async function checkAndroidBackgroundLocation(): Promise<boolean> {
+  const hasForegroundLocation = await areAndroidPermissionsGranted([ANDROID.ACCESS_FINE_LOCATION])
+  if (!hasForegroundLocation || !requiresSeparateAndroidBackgroundLocation) return hasForegroundLocation
+
+  return PermissionsAndroid.check(ANDROID.ACCESS_BACKGROUND_LOCATION)
+}
+
+async function requestAndroidBackgroundLocation(): Promise<boolean> {
+  const hasForegroundLocation = await requestAndroidPermissions([ANDROID.ACCESS_FINE_LOCATION])
+  if (!hasForegroundLocation || !requiresSeparateAndroidBackgroundLocation) return hasForegroundLocation
+
+  if (await PermissionsAndroid.check(ANDROID.ACCESS_BACKGROUND_LOCATION)) return true
+
+  const result = await PermissionsAndroid.request(ANDROID.ACCESS_BACKGROUND_LOCATION)
+  return result === PermissionsAndroid.RESULTS.GRANTED
+}
+
+function iosPerms(feature: string): Permission[] {
+  switch (feature) {
+    case PermissionFeatures.MICROPHONE:
+      return [PERMISSIONS.IOS.MICROPHONE]
+    case PermissionFeatures.CAMERA:
+      return [PERMISSIONS.IOS.CAMERA]
+    case PermissionFeatures.CALENDAR:
+      return [PERMISSIONS.IOS.CALENDARS]
+    case PermissionFeatures.LOCATION:
+      return [PERMISSIONS.IOS.LOCATION_WHEN_IN_USE]
+    case PermissionFeatures.LOCAL_WIFI:
+      return []
+    case PermissionFeatures.BACKGROUND_LOCATION:
+      // iOS won't grant ALWAYS without WHEN_IN_USE first — request both (matches
+      // the host PermissionsUtils mapping), else a cold request can't escalate.
+      return [PERMISSIONS.IOS.LOCATION_WHEN_IN_USE, PERMISSIONS.IOS.LOCATION_ALWAYS]
+    case PermissionFeatures.BLUETOOTH:
+      return [PERMISSIONS.IOS.BLUETOOTH]
+    default:
+      return []
+  }
+}
+
+function androidPerms(feature: string): AndroidPermission[] {
+  switch (feature) {
+    case PermissionFeatures.MICROPHONE:
+      return [ANDROID.RECORD_AUDIO]
+    case PermissionFeatures.CAMERA:
+      return [ANDROID.CAMERA]
+    case PermissionFeatures.CALENDAR:
+      // Expo Calendar requires both grants on Android, including for read APIs.
+      // The miniapp-facing calendar API remains read-only.
+      return [ANDROID.READ_CALENDAR, ANDROID.WRITE_CALENDAR]
+    case PermissionFeatures.LOCATION:
+    case PermissionFeatures.BACKGROUND_LOCATION:
+      return [ANDROID.ACCESS_FINE_LOCATION]
+    case PermissionFeatures.LOCAL_WIFI:
+      return [localWifiPermissionForAndroid(apiLevel)]
+    case PermissionFeatures.PHONE_STATE:
+      return [ANDROID.READ_PHONE_STATE]
+    case PermissionFeatures.BLUETOOTH:
+      return apiLevel >= 31 ? [ANDROID.BLUETOOTH_SCAN, ANDROID.BLUETOOTH_CONNECT, ANDROID.BLUETOOTH_ADVERTISE] : []
+    case PermissionFeatures.POST_NOTIFICATIONS:
+      return apiLevel >= 33 ? [ANDROID.POST_NOTIFICATIONS] : []
+    default:
+      return []
+  }
+}
+
+export const permissions = {
+  /** Is the given feature's OS permission currently granted? */
+  async check(feature: string): Promise<boolean> {
+    if (Platform.OS === "android") {
+      if (feature === PermissionFeatures.BACKGROUND_LOCATION) return checkAndroidBackgroundLocation()
+
+      const perms = androidPerms(feature)
+      if (perms.length === 0) return true // nothing to ask on this OS/version
+      // Every permission in the group must be granted (e.g. bluetooth =
+      // scan+connect+advertise, calendar = read+write) — matches the iOS branch.
+      return areAndroidPermissionsGranted(perms)
+    }
+    const perms = iosPerms(feature)
+    if (perms.length === 0) return true
+    for (const p of perms) {
+      const status = await check(p)
+      if (status !== RESULTS.GRANTED && status !== RESULTS.LIMITED) return false
+    }
+    return true
+  },
+
+  /** Request the given feature's OS permission. Resolves to whether it's granted. */
+  async request(feature: string): Promise<boolean> {
+    if (Platform.OS === "android") {
+      if (feature === PermissionFeatures.BACKGROUND_LOCATION) return requestAndroidBackgroundLocation()
+
+      const perms = androidPerms(feature)
+      if (perms.length === 0) return true
+      // Granted only when EVERY permission in the group was granted.
+      return requestAndroidPermissions(perms)
+    }
+    const perms = iosPerms(feature)
+    if (perms.length === 0) return true
+    let granted = true
+    for (const p of perms) {
+      const result = await request(p)
+      if (result !== RESULTS.GRANTED && result !== RESULTS.LIMITED) granted = false
+    }
+    return granted
+  },
+
+  /** Open the OS settings app (so the user can grant a blocked permission). */
+  openSettings: (): Promise<void> => Linking.openSettings(),
+
+  /** The permissions a given installed miniapp declares it needs. */
+  async requirementsForMiniapp(packageName: string): Promise<AppletPermission[]> {
+    const apps = await appRegistry.getInstalledMiniapps()
+    return apps.find((a) => a.packageName === packageName)?.permissions ?? []
+  },
+}

package/src/facades/phoneNotifications.ts

@@ -0,0 +1,41 @@
+/**
+ * phoneNotifications facade — `engine.phoneNotifications`: forward phone
+ * notifications to the glasses, with a per-app blocklist. Android-only (the
+ * NotificationListenerService); the getters return sensible defaults on iOS.
+ *
+ * The per-app blocklist is an engine setting (auto-synced to the native
+ * listener); the installed-apps list + listener permission are CrustModule.
+ * Capture itself is controlled only by Android notification access and the
+ * hidden operational kill switch.
+ */
+import {Platform} from "react-native"
+import CrustModule from "@glassly/crust"
+import {useSettingsStore, SETTINGS} from "../stores/settings"
+
+export const phoneNotifications = {
+  /** The phone's installed apps (package, name, icon). (empty on iOS) */
+  installedApps: (): Promise<Array<{packageName: string; appName: string; icon: string | null}>> => {
+    if (Platform.OS !== "android") return Promise.resolve([])
+    return CrustModule.getInstalledApps()
+  },
+
+  /** The per-app blocklist (package names whose notifications are NOT forwarded). */
+  blocklist: (): string[] => {
+    const b = useSettingsStore.getState().getSetting(SETTINGS.notifications_blocklist.key)
+    return Array.isArray(b) ? b : []
+  },
+  /** Replace the per-app blocklist. */
+  setBlocklist: (packageNames: string[]) =>
+    useSettingsStore.getState().setSetting(SETTINGS.notifications_blocklist.key, packageNames),
+
+  /** Does the app have the Android notification-listener permission? (false on iOS) */
+  hasListenerPermission: (): Promise<boolean> => {
+    if (Platform.OS !== "android") return Promise.resolve(false)
+    return CrustModule.hasNotificationListenerPermission()
+  },
+  /** Open the OS settings to grant the notification-listener permission. (no-op on iOS) */
+  requestListenerPermission: () => {
+    if (Platform.OS !== "android") return
+    return CrustModule.openNotificationListenerSettings()
+  },
+}

package/src/facades/providerKeys.ts

@@ -0,0 +1,31 @@
+/**
+ * providerKeys facade — `engine.providerKeys.{anthropic,gemini,elevenlabs}`:
+ * validate-before-save probes for the user-supplied AI/voice provider keys
+ * (Settings > API Keys). Same per-provider shape as `engine.maps.mapbox` /
+ * `engine.speech.sonioxDirect` so the Keys screen treats providers uniformly.
+ */
+import {
+  validateAnthropicApiKey,
+  validateElevenLabsApiKey,
+  validateGeminiApiKey,
+  validateOpenAiApiKey,
+} from "../services/ProviderKeyValidation"
+
+export const providerKeys = {
+  anthropic: {
+    /** Probe a key against the Anthropic API without saving it. */
+    validateKey: (...args: Parameters<typeof validateAnthropicApiKey>) => validateAnthropicApiKey(...args),
+  },
+  gemini: {
+    /** Probe a key against the Gemini API without saving it. */
+    validateKey: (...args: Parameters<typeof validateGeminiApiKey>) => validateGeminiApiKey(...args),
+  },
+  openai: {
+    /** Probe a key against the OpenAI API without saving it. */
+    validateKey: (...args: Parameters<typeof validateOpenAiApiKey>) => validateOpenAiApiKey(...args),
+  },
+  elevenlabs: {
+    /** Probe a key against the ElevenLabs API without saving it. */
+    validateKey: (...args: Parameters<typeof validateElevenLabsApiKey>) => validateElevenLabsApiKey(...args),
+  },
+}

package/src/facades/reports.ts

@@ -0,0 +1,180 @@
+/**
+ * reports facade — `engine.reports`: user/system report submission over the
+ * Cloud V2 core client.
+ *
+ * Host/OEM code owns UI and wording. Engine owns Glassly mechanics: context
+ * collection, recent phone logs, Cloud V2 calls, local automatic throttling,
+ * screenshots, and notifying connected glasses.
+ */
+import BluetoothSdk from "@glassly/bluetooth-sdk/internal"
+import type {ReportAttachmentInput, ReportContext, ReportStatus, SubmitReportInput} from "@glassly/cloud-client"
+import {useGlassesStore} from "../stores/glasses"
+import {isGlassesConnected} from "../services/GlassesReadiness"
+import {cloudClientService} from "../services/CloudClientService"
+import {collectDiagnosticContext} from "../utils/diagnosticContext"
+import {logBuffer} from "../utils/devLogging"
+
+export type {
+  ReportAttachmentInput,
+  ReportContext,
+  ReportDetails,
+  ReportStatus,
+  ReportTrigger,
+} from "@glassly/cloud-client"
+
+export type EngineSubmitReportInput =
+  | (Omit<Extract<SubmitReportInput, {kind: "bug"}>, "context"> & {
+      context?: Partial<ReportContext>
+      screenshots?: ReportAttachmentInput[]
+    })
+  | (Omit<Extract<SubmitReportInput, {kind: "feedback"}>, "context"> & {
+      context?: Partial<ReportContext>
+    })
+
+export type EngineSubmitAutomaticReportInput = Omit<Extract<SubmitReportInput, {kind: "automatic"}>, "context"> & {
+  context?: Partial<ReportContext>
+  screenshots?: ReportAttachmentInput[]
+  throttleKey?: string
+  throttleWindowMs?: number
+}
+
+type InternalSubmitReportInput = EngineSubmitReportInput | EngineSubmitAutomaticReportInput
+
+export type ReportSubmitResult =
+  | {status: "submitted"; reportId: string; reportStatus: ReportStatus}
+  | {status: "skipped"; reason: "throttled_within_window"}
+  | {status: "failed"; error: string}
+
+const DEFAULT_AUTOMATIC_REPORT_THROTTLE_MS = 90_000
+const automaticReportThrottleRegistry = new Map<string, number>()
+
+function automaticThrottleShouldSkip(key: string, nowMs: number, windowMs: number): boolean {
+  const previous = automaticReportThrottleRegistry.get(key)
+  if (previous !== undefined && nowMs - previous < windowMs) {
+    return true
+  }
+  pruneAutomaticThrottleRegistry(nowMs, windowMs)
+  return false
+}
+
+function markAutomaticThrottleSuccess(key: string, nowMs: number, windowMs: number): void {
+  automaticReportThrottleRegistry.set(key, nowMs)
+  pruneAutomaticThrottleRegistry(nowMs, windowMs)
+}
+
+function pruneAutomaticThrottleRegistry(nowMs: number, windowMs: number): void {
+  for (const [entryKey, entryTime] of automaticReportThrottleRegistry) {
+    if (nowMs - entryTime > windowMs * 3) {
+      automaticReportThrottleRegistry.delete(entryKey)
+    }
+  }
+}
+
+function notifyGlasses(reportId: string, apiBaseUrl?: string | null): void {
+  if (!isGlassesConnected(useGlassesStore.getState().connection)) return
+  void (async () => {
+    try {
+      await cloudClientService.syncCoreTokenToBluetooth()
+      await BluetoothSdk.sendIncidentId(reportId, apiBaseUrl ?? cloudClientService.getCoreUrl())
+    } catch (error) {
+      console.warn("reports.submit: notify glasses failed:", error instanceof Error ? error.message : error)
+    }
+  })()
+}
+
+async function submitReportInternal(input: InternalSubmitReportInput): Promise<ReportSubmitResult> {
+  const throttle =
+    input.kind === "automatic" && input.throttleKey
+      ? {
+          key: input.throttleKey,
+          windowMs: input.throttleWindowMs ?? DEFAULT_AUTOMATIC_REPORT_THROTTLE_MS,
+        }
+      : null
+
+  if (input.kind === "automatic" && input.throttleKey) {
+    const shouldSkip = automaticThrottleShouldSkip(
+      input.throttleKey,
+      Date.now(),
+      throttle?.windowMs ?? DEFAULT_AUTOMATIC_REPORT_THROTTLE_MS,
+    )
+    if (shouldSkip) return {status: "skipped", reason: "throttled_within_window"}
+  }
+
+  const context = await collectDiagnosticContext(input.context)
+  let reportId: string
+  let reportStatus: ReportStatus
+  let artifactsComplete = true
+  try {
+    const res =
+      input.kind === "feedback"
+        ? await cloudClientService.core.reports.submit({
+            kind: "feedback",
+            feedback: input.feedback,
+            context,
+          })
+        : input.kind === "bug"
+          ? await cloudClientService.core.reports.submit({
+              kind: "bug",
+              trigger: input.trigger,
+              report: input.report,
+              context,
+            })
+          : await cloudClientService.core.reports.submit({
+              kind: "automatic",
+              trigger: input.trigger,
+              report: input.report,
+              context,
+            })
+    reportId = res.reportId
+    reportStatus = res.status
+  } catch (error) {
+    return {status: "failed", error: error instanceof Error ? error.message : String(error)}
+  }
+
+  if (input.kind !== "feedback") {
+    const logs = logBuffer.getRecentLogs()
+    if (logs.length > 0) {
+      try {
+        await cloudClientService.core.reports.addLogs(reportId, "phone", logs)
+      } catch (error) {
+        artifactsComplete = false
+        console.warn("reports.submit: add phone logs failed:", error instanceof Error ? error.message : error)
+      }
+    }
+
+    notifyGlasses(reportId, cloudClientService.getCoreUrl())
+
+    if (input.screenshots && input.screenshots.length > 0) {
+      try {
+        await cloudClientService.core.reports.addScreenshots(reportId, input.screenshots)
+      } catch (error) {
+        artifactsComplete = false
+        console.warn("reports.submit: add screenshots failed:", error instanceof Error ? error.message : error)
+      }
+    }
+
+    try {
+      const completed = await cloudClientService.core.reports.complete(reportId)
+      reportStatus = completed.status
+    } catch (error) {
+      artifactsComplete = false
+      console.warn("reports.submit: complete report failed:", error instanceof Error ? error.message : error)
+    }
+  }
+
+  if (throttle && artifactsComplete) {
+    markAutomaticThrottleSuccess(throttle.key, Date.now(), throttle.windowMs)
+  }
+
+  return {status: "submitted", reportId, reportStatus}
+}
+
+export const reports = {
+  submit(input: EngineSubmitReportInput): Promise<ReportSubmitResult> {
+    return submitReportInternal(input)
+  },
+}
+
+export function submitAutomaticReport(input: EngineSubmitAutomaticReportInput): Promise<ReportSubmitResult> {
+  return submitReportInternal(input)
+}

package/src/facades/session.ts

@@ -0,0 +1,54 @@
+/**
+ * session facade — `engine.session`: the cloud-v2 live-session surface engine
+ * now owns (keystone #5). Exposes the connection status read-model (status +
+ * audio transport, projected from the engine-owned cloud-status store) and the
+ * liveness flag.
+ *
+ */
+import {cloudClientService} from "../services/CloudClientService"
+import {useCloudClientStatusStore} from "../stores/cloudClientStatus"
+import {useConnectionStore} from "../stores/connection"
+import type {WebSocketStatus} from "../stores/connection"
+import type {CloudClientStatusSnapshot} from "../runtime/config"
+
+function project(): CloudClientStatusSnapshot {
+  const s = useCloudClientStatusStore.getState()
+  return {status: s.status, audioTransport: s.audioTransport}
+}
+
+export const session = {
+  /** Current cloud live-session status (connection state + audio transport). */
+  status: (): CloudClientStatusSnapshot => project(),
+  /** Subscribe to cloud session-status changes; returns an unsubscribe. */
+  onStatus: (cb: (status: CloudClientStatusSnapshot) => void): (() => void) => {
+    // Dedupe: fire only when the projected {status, audioTransport} changes.
+    let last = JSON.stringify(project())
+    return useCloudClientStatusStore.subscribe(() => {
+      const snap = project()
+      const key = JSON.stringify(snap)
+      if (key === last) return
+      last = key
+      cb(snap)
+    })
+  },
+  /** Whether the live-session handshake has completed. */
+  isConnected: (): boolean => cloudClientService.isConnected(),
+
+  /**
+   * Legacy Cloud-V1 websocket status. The socket's writer (the host
+   * WebSocketManager) was deleted in the Cloud V1 ripout, so this now always
+   * reports the store's initial DISCONNECTED; the host connection banners
+   * render `status()` (the cloud-v2 runtime) instead. Kept, with the backing
+   * connection store, for the engine-side legacy-surface removal (issue #3392).
+   */
+  legacyWebsocketStatus: (): WebSocketStatus => useConnectionStore.getState().status,
+  /** Subscribe to legacy websocket status changes; fires only when it changes. Returns an unsubscribe. */
+  onLegacyWebsocketStatus: (cb: (status: WebSocketStatus) => void): (() => void) => {
+    let last = useConnectionStore.getState().status
+    return useConnectionStore.subscribe((state) => {
+      if (state.status === last) return
+      last = state.status
+      cb(state.status)
+    })
+  },
+}

package/src/facades/settings.ts

@@ -0,0 +1,57 @@
+/**
+ * settings facade — `engine.settings`: the typed keyed user-settings surface over
+ * the engine-owned settings store. This is the (A) OEM contract; the raw store at
+ * `engine.stores.settings` is the Glassly-app escape hatch.
+ *
+ * Keys + their schema live in `SETTINGS` (theme, devMode, metric/twelveHourTime,
+ * notifications, onboarding flags, …); `descriptor(key)`/`keys()` expose them.
+ */
+import {useSettingsStore, SETTINGS} from "../stores/settings"
+
+// Copy: object/array-valued settings must not hand callers a mutable reference
+// into the store (mutations would silently corrupt store state, bypassing set()).
+function copySettingValue<T>(value: T): T {
+  if (Array.isArray(value)) return [...value] as T
+  if (value && typeof value === "object") return {...(value as object)} as T
+  return value
+}
+
+export const settings = {
+  /** Read a setting by key (the current value, or its default; object/array values
+   * are shallow copies). */
+  get: <T = unknown>(key: string): T | undefined =>
+    copySettingValue(useSettingsStore.getState().getSetting(key) as T | undefined),
+  /**
+   * Write a setting. `syncToServer` (default true) also pushes the change to the
+   * backend; pass false for device-local-only writes.
+   */
+  set: <T = unknown>(key: string, value: T, syncToServer = true) =>
+    useSettingsStore.getState().setSetting(key, value, syncToServer),
+  /** Subscribe to changes for one key; returns an unsubscribe. */
+  onChanged: <T = unknown>(key: string, cb: (value: T | undefined) => void): (() => void) =>
+    useSettingsStore.subscribe((s) => s.getSetting(key) as T | undefined, cb),
+  /** The schema descriptor for a key (type, default, options…), or undefined. */
+  descriptor: (key: string) => SETTINGS[key],
+  /** All known setting keys. */
+  keys: (): string[] => Object.keys(SETTINGS),
+  /**
+   * Reset every setting to its default on THIS device only (no server sync) —
+   * the logout path. Server-side settings are untouched.
+   */
+  resetAllLocal: (): void => useSettingsStore.getState().resetAllSettingsLocally(),
+  /**
+   * Hydrate the settings store from device storage — the host-boot step (fire
+   * once at app start, before UI reads settings). Single-flighted internally.
+   */
+  loadAll: () => useSettingsStore.getState().loadAllSettings(),
+  /**
+   * Every EXPLICITLY-SET setting (shallow copy; keys never written are absent —
+   * use get() for default-resolved reads). The data-export surface.
+   */
+  getAll: (): Record<string, unknown> => ({...useSettingsStore.getState().settings}),
+  /**
+   * Bulk device-local write without server sync — seeding the store from a
+   * backend settings payload.
+   */
+  setManyLocal: (values: Record<string, unknown>) => useSettingsStore.getState().setManyLocally(values),
+}

package/src/facades/speakers.ts

@@ -0,0 +1,152 @@
+/**
+ * speakers facade — `engine.speakers`: the device owner's voice profile for
+ * on-device voice recognition (Settings > Voice Recognition).
+ *
+ * Owner-only surface: the user enrolls their OWN voice once (`enrollSelf`);
+ * transcripts are then labeled user / other / unknown. The profile store
+ * keeps its generic multi-profile shape underneath, but this facade only
+ * exposes the self profile.
+ *
+ * Enrollment is a guided recording through whichever mic is currently active
+ * (native holds the mic open for the session). Raw audio never reaches JS —
+ * native returns chunk embeddings, which land in the profile store here; the
+ * store push back to native happens via SpeakerIdSync.
+ */
+import BluetoothSdk from "@glassly/bluetooth-sdk/internal"
+import type {SpeakerEnrollProgressEvent, SpeakerEnrollResultEvent} from "@glassly/bluetooth-sdk/internal"
+
+import speakerIdModelManager, {type SpeakerIdModelProgress} from "../services/SpeakerIdModelManager"
+import type {SpeakerProfile} from "../services/SpeakerProfileStore"
+import {speakerProfileStore} from "../services/speakerProfileStoreInstance"
+
+const DEFAULT_TARGET_SPEECH_SECONDS = 20
+
+/**
+ * Display name of the self profile. Shown on the memory timeline (which
+ * renders `resolvedSpeakerName`); miniapps never see it (PII strip).
+ */
+const SELF_PROFILE_NAME = "You"
+
+export type EnrollOutcome =
+  | {ok: true; profile: SpeakerProfile}
+  | {ok: false; reason: "inconsistent" | "too_short" | "model_unavailable" | "unsupported" | "cancelled" | string}
+
+let activeEnrollment: {cancel: () => void} | null = null
+
+/**
+ * Run one enrollment session to completion. Resolves when native reports the
+ * result; on success the embeddings are stored (new profile, or appended to
+ * `improveProfileId` for "Improve recognition").
+ */
+async function runEnrollment(input: {
+  name?: string
+  improveProfileId?: string
+  targetSpeechSeconds?: number
+}): Promise<EnrollOutcome> {
+  if (activeEnrollment) return {ok: false, reason: "already_enrolling"}
+
+  return new Promise<EnrollOutcome>((resolve) => {
+    let settled = false
+    const settle = (outcome: EnrollOutcome) => {
+      if (settled) return
+      settled = true
+      sub.remove()
+      activeEnrollment = null
+      console.log(
+        outcome.ok
+          ? `SpeakerID: enrollment stored — profile "${outcome.profile.name}" (${outcome.profile.samples.length} samples)`
+          : `SpeakerID: enrollment not stored — ${outcome.reason}`,
+      )
+      resolve(outcome)
+    }
+
+    const sub = BluetoothSdk.addListener("speaker_enroll_result", (event: SpeakerEnrollResultEvent) => {
+      void (async () => {
+        if (!event.ok) {
+          settle({ok: false, reason: event.reason ?? "failed"})
+          return
+        }
+        const embeddings = event.embeddings ?? []
+        const source = event.source === "glasses" ? "glasses" : "phone"
+        try {
+          if (input.improveProfileId) {
+            const profile = await speakerProfileStore.addSamples(input.improveProfileId, embeddings, source)
+            if (profile) settle({ok: true, profile})
+            else settle({ok: false, reason: "profile_not_found"})
+          } else {
+            const profile = await speakerProfileStore.add(input.name ?? "", embeddings, source)
+            settle({ok: true, profile})
+          }
+        } catch (err) {
+          settle({ok: false, reason: err instanceof Error ? err.message : "store_failed"})
+        }
+      })()
+    })
+
+    activeEnrollment = {
+      cancel: () => {
+        void BluetoothSdk.cancelSpeakerEnrollment().catch(() => {})
+        settle({ok: false, reason: "cancelled"})
+      },
+    }
+
+    void BluetoothSdk.startSpeakerEnrollment({
+      targetSpeechSeconds: input.targetSpeechSeconds ?? DEFAULT_TARGET_SPEECH_SECONDS,
+    }).catch((err) => {
+      settle({ok: false, reason: err instanceof Error ? err.message : "start_failed"})
+    })
+  })
+}
+
+export const speakers = {
+  /** The owner's enrolled voice profile, or null before enrollment. */
+  getSelf: async (): Promise<SpeakerProfile | null> => {
+    const profiles = await speakerProfileStore.list()
+    return profiles[0] ?? null
+  },
+  /** Subscribe to profile-store mutations. */
+  onChanged: (listener: () => void): (() => void) => speakerProfileStore.onChanged(listener),
+  /**
+   * Enroll (or re-enroll) the owner's voice via guided recording on the
+   * active mic. Replaces any existing self profile on success.
+   */
+  enrollSelf: async (opts?: {targetSpeechSeconds?: number}): Promise<EnrollOutcome> => {
+    const outcome = await runEnrollment({name: SELF_PROFILE_NAME, targetSpeechSeconds: opts?.targetSpeechSeconds})
+    if (outcome.ok) {
+      // Drop any previous self profile — one owner voice at a time. Done
+      // after the new profile is stored so a failed session can't delete.
+      const stale = (await speakerProfileStore.list()).filter((p) => p.id !== outcome.profile.id)
+      for (const profile of stale) await speakerProfileStore.remove(profile.id)
+    }
+    return outcome
+  },
+  /** "Improve recognition": record more samples onto the self profile. */
+  improveSelf: async (opts?: {targetSpeechSeconds?: number}): Promise<EnrollOutcome> => {
+    const self = await speakers.getSelf()
+    if (!self) return {ok: false, reason: "not_enrolled"}
+    return runEnrollment({improveProfileId: self.id, targetSpeechSeconds: opts?.targetSpeechSeconds})
+  },
+  /** Delete the self profile (also drops it from native via store-change push). */
+  removeSelf: async (): Promise<boolean> => {
+    const self = await speakers.getSelf()
+    if (!self) return false
+    return speakerProfileStore.remove(self.id)
+  },
+  /** Cancel the in-flight enrollment session, if any. */
+  cancelEnrollment: (): void => {
+    activeEnrollment?.cancel()
+  },
+  /** Live recording meter + progress ring during enrollment. */
+  onEnrollProgress: (listener: (progress: SpeakerEnrollProgressEvent) => void): (() => void) => {
+    const sub = BluetoothSdk.addListener("speaker_enroll_progress", listener)
+    return () => sub.remove()
+  },
+  /** Embedding-model delivery (one-time ~28 MB download). */
+  model: {
+    isAvailable: (): Promise<boolean> => speakerIdModelManager.isModelAvailable(),
+    sizeBytes: (): number => speakerIdModelManager.sizeBytes,
+    download: (onProgress?: (p: SpeakerIdModelProgress) => void): Promise<void> =>
+      speakerIdModelManager.downloadModel(onProgress),
+    cancelDownload: (): Promise<void> => speakerIdModelManager.cancelDownload(),
+  },
+}