@glassly/engine 0.1.0-dev.0

package/src/facades/dev.ts

@@ -0,0 +1,213 @@
+/**
+ * dev facade — `engine.dev`: developer/debug surface over engine-owned state.
+ * Backend/cloud URL overrides read+write the engine settings store; the cloud
+ * URL setters reconnect the engine-owned cloud client onto the new endpoints;
+ *
+ * NOTE: the dev-time endpoint *resolution* (Metro-host auto-detect, env defaults)
+ * still lives host-side in `@/services/cloudClient` during the migration; this
+ * facade manages the explicit overrides + reconnect.
+ */
+import BluetoothSdk from "@glassly/bluetooth-sdk/internal"
+import {isGlassesReady} from "../services/GlassesReadiness"
+import {useCloudClientStatusStore} from "../stores/cloudClientStatus"
+import {useConnectionStore} from "../stores/connection"
+import {useCoreStore} from "../stores/core"
+import {useGlassesStore} from "../stores/glasses"
+import {useSettingsStore, SETTINGS} from "../stores/settings"
+import {useTranscriptionDebugStore} from "../stores/transcriptionDebug"
+import {cloudClientService} from "../services/CloudClientService"
+import {getConfigValues} from "../runtime/bootstrap"
+import {decideDevLaunchRoute} from "../utils/devMiniappLaunch"
+import {deriveDevPackageId, registerDevApp, DEV_APP_PACKAGE_NAME, type DevAppRecord} from "../services/AppRegistry"
+import {useAppStatusStore} from "../stores/apps"
+
+type CloudUrlOverrides = {core?: string; runtime?: string}
+
+/**
+ * Reconnect the cloud client onto the current cloud-URL overrides. Explicit
+ * partial overrides merge over the boot-resolved config (which carries the
+ * host's Metro/env URL resolution); both empty clears the live override.
+ */
+function applyCloudUrlReconnect(urls: CloudUrlOverrides = currentCloudUrlOverrides()): void {
+  const resolved = resolveCloudUrlReconnectTarget(urls)
+  if (resolved === undefined) {
+    cloudClientService.reconnect(null)
+  } else if (resolved) {
+    cloudClientService.reconnect(resolved)
+  } else {
+    console.warn("engine.dev.setCloudUrls: partial cloud override missing boot-resolved sibling endpoint")
+  }
+}
+
+function currentCloudUrlOverrides(): CloudUrlOverrides {
+  const s = useSettingsStore.getState()
+  return {
+    core: trimSetting(s.getSetting(SETTINGS.cloud_core_url.key)),
+    runtime: trimSetting(s.getSetting(SETTINGS.cloud_runtime_url.key)),
+  }
+}
+
+function resolveCloudUrlReconnectTarget(urls: CloudUrlOverrides): {core: string; runtime: string} | null | undefined {
+  const core = trimSetting(urls.core)
+  const runtime = trimSetting(urls.runtime)
+  if (!core && !runtime) return undefined
+
+  const config = getConfigValues()
+  const resolvedCore = core || config.coreUrl?.trim()
+  const resolvedRuntime = runtime || config.runtimeUrl?.trim()
+  return resolvedCore && resolvedRuntime ? {core: resolvedCore, runtime: resolvedRuntime} : null
+}
+
+function trimSetting(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined
+}
+
+function projectRuntimeStatus() {
+  const core = useCoreStore.getState()
+  const glasses = useGlassesStore.getState()
+  const connection = useConnectionStore.getState()
+  const cloudClient = useCloudClientStatusStore.getState()
+  const transcriptionDebug = useTranscriptionDebugStore.getState()
+  return {
+    searching: core.searching,
+    // Copy: the snapshot must not hand callers a mutable reference into the store.
+    micRanking: [...core.micRanking],
+    currentMic: core.currentMic,
+    systemMicUnavailable: core.systemMicUnavailable,
+    glassesConnected: glasses.connection.state === "connected",
+    glassesFullyBooted: isGlassesReady(glasses.connection),
+    bluetoothClassicConnected: glasses.bluetoothClassicConnected,
+    coreStatus: connection.status,
+    cloudClientStatus: cloudClient.status,
+    cloudClientAudioTransport: cloudClient.audioTransport,
+    transcriptionSubscribers: [...transcriptionDebug.transcriptionSubscribers],
+    translationSubscribers: [...transcriptionDebug.translationSubscribers],
+    recentTranscriptSources: {...transcriptionDebug.recentTranscriptSources},
+    cloudAudioSubscriptionWrite: {...transcriptionDebug.cloudAudioSubscriptionWrite},
+  }
+}
+
+export type DevRuntimeStatusSnapshot = ReturnType<typeof projectRuntimeStatus>
+
+export const dev = {
+  /** The cloud-v2 core/runtime URL overrides. */
+  cloudUrls: (): {core?: string; runtime?: string} => {
+    const s = useSettingsStore.getState()
+    return {core: s.getSetting(SETTINGS.cloud_core_url.key), runtime: s.getSetting(SETTINGS.cloud_runtime_url.key)}
+  },
+  /** Override the cloud-v2 URLs and reconnect the live client onto them. */
+  setCloudUrls: (urls: {core?: string; runtime?: string}) => {
+    const next = {...currentCloudUrlOverrides(), ...urls}
+    const resolved = resolveCloudUrlReconnectTarget(next)
+    if (resolved === null) {
+      console.warn("engine.dev.setCloudUrls: ignoring partial cloud override without a resolvable sibling endpoint")
+      return
+    }
+
+    const s = useSettingsStore.getState()
+    if (urls.core !== undefined) s.setSetting(SETTINGS.cloud_core_url.key, urls.core)
+    if (urls.runtime !== undefined) s.setSetting(SETTINGS.cloud_runtime_url.key, urls.runtime)
+    if (resolved === undefined) {
+      cloudClientService.reconnect(null)
+    } else {
+      cloudClientService.reconnect(resolved)
+    }
+  },
+
+  /** Tear down + rebuild the live cloud client (the dev "reconnect" button). */
+  reconnectCloud: (): void => applyCloudUrlReconnect(),
+
+  /** Current native (BLE-process) memory usage in MB — a dev/diagnostics gauge. */
+  getMemoryMB: (): number => BluetoothSdk.getMemoryMB(),
+  /**
+   * Phone-side bluetooth runtime snapshot (the core store read-model: scan/mic/
+   * search state) — the diagnostics/data-export surface. Shallow copy.
+   */
+  bluetoothStatus: (): Record<string, unknown> => {
+    const {setCoreInfo: _setCoreInfo, reset: _reset, ...state} = useCoreStore.getState()
+    return {...state}
+  },
+
+  /**
+   * Side-load a miniapp being served from a dev machine (the `glassly dev` / CLI
+   * flow) by its URL: probes `<url>/miniapp.json`, and on a reachable manifest
+   * registers it under its manifest package so it appears in `engine.miniapps`
+   * and can coexist with other dev miniapps. This is the OEM-host equivalent
+   * of the first-party
+   * developer-URL screen — the registration itself is engine-internal, so a
+   * host reaches it here rather than the internal registry. Rendering still
+   * flows through the normal display path once the miniapp is started.
+   */
+  loadDevMiniapp: async (
+    url: string,
+    name?: string,
+  ): Promise<{ok: true; packageName: string; name: string} | {ok: false; error: string}> => {
+    const devUrl = url.trim().replace(/\/+$/, "")
+    if (!devUrl) return {ok: false, error: "empty url"}
+    const result = await decideDevLaunchRoute("", devUrl)
+    if (result.decision !== "live") {
+      return {ok: false, error: "dev server unreachable, or no miniapp.json served there"}
+    }
+    const manifest = result.manifest
+    const appName = name ?? manifest.name ?? "Dev Miniapp"
+    const packageName = (manifest.packageName as string | undefined) ?? DEV_APP_PACKAGE_NAME
+    // Persist the host that answered — not the stale input IP — so home-tile
+    // relaunches skip a dead LAN address after mDNS/Metro failover.
+    const resolvedUrl = result.resolvedUrl || devUrl
+    // The `glassly-miniapp dev` server puts the hot-reload/log sidecar on the
+    // user port PLUS ONE — same convention as the first-party developer-URL
+    // screen's deriveDevPort.
+    let devPort: number | undefined
+    try {
+      const parsed = Number(new URL(resolvedUrl).port)
+      devPort = Number.isFinite(parsed) && parsed > 0 ? parsed + 1 : undefined
+    } catch {
+      devPort = undefined
+    }
+    // The record is stored under a namespaced dev id (deriveDevPackageId) so
+    // it survives release installs of the manifest package — stop/refresh and
+    // the returned packageName must use that id, which registerDevApp returns.
+    const devPackageId = deriveDevPackageId(packageName)
+    const existing = useAppStatusStore.getState().apps.find((app) => app.packageName === devPackageId)
+    if (existing?.running) await useAppStatusStore.getState().stop(devPackageId)
+    const record = await registerDevApp({
+      packageName,
+      name: appName,
+      iconUrl: manifest.icon ? new URL(manifest.icon, `${resolvedUrl}/`).toString() : `${resolvedUrl}/icon.png`,
+      // Persist the host that answered — not the stale input IP.
+      devUrl: resolvedUrl,
+      devPort,
+      type: manifest.type as DevAppRecord["type"],
+      permissions: manifest.permissions as DevAppRecord["permissions"],
+      hardwareRequirements: manifest.hardwareRequirements as DevAppRecord["hardwareRequirements"],
+      actions: manifest.actions as DevAppRecord["actions"],
+    })
+    await useAppStatusStore.getState().refresh()
+    return {ok: true, packageName: record.packageName, name: appName}
+  },
+
+  /** Current engine runtime status for engine-owned debug surfaces. */
+  runtimeStatus: (): DevRuntimeStatusSnapshot => projectRuntimeStatus(),
+
+  /** Subscribe to the projected engine runtime status; returns an unsubscribe. */
+  onRuntimeStatus: (cb: (status: DevRuntimeStatusSnapshot) => void): (() => void) => {
+    let last = JSON.stringify(projectRuntimeStatus())
+    const notify = () => {
+      const snap = projectRuntimeStatus()
+      const key = JSON.stringify(snap)
+      if (key === last) return
+      last = key
+      cb(snap)
+    }
+    const unsubscribers = [
+      useCoreStore.subscribe(notify),
+      useGlassesStore.subscribe(notify),
+      useConnectionStore.subscribe(notify),
+      useCloudClientStatusStore.subscribe(notify),
+      useTranscriptionDebugStore.subscribe(notify),
+    ]
+    return () => {
+      unsubscribers.forEach((unsubscribe) => unsubscribe())
+    }
+  },
+}

package/src/facades/display.ts

@@ -0,0 +1,17 @@
+/**
+ * display facade — `engine.display`: the host/OEM display surface. `mirror`
+ * exposes the mirrored-view read-model; `text`/`clear` are raw passthroughs to the
+ * glasses display for dev tools and escape-hatch use (normal rendering goes through
+ * the engine DisplayProcessor / layout system, not these).
+ */
+import BluetoothSdk from "@glassly/bluetooth-sdk/internal"
+import {displayMirror} from "./displayMirror"
+
+export const display = {
+  /** Mirrored-view read-model (current/onMirror/view/setView). */
+  mirror: displayMirror,
+  /** Write raw text to the glasses display at (x, y) with a font size. */
+  text: (...args: Parameters<typeof BluetoothSdk.displayText>) => BluetoothSdk.displayText(...args),
+  /** Clear the glasses display. */
+  clear: (): Promise<void> => BluetoothSdk.clearDisplay(),
+}

package/src/facades/displayMirror.ts

@@ -0,0 +1,33 @@
+/**
+ * glasses display mirror — the typed read facade over the (now engine-owned)
+ * display store, for a phone-side preview of the glasses screen
+ * (`engine.display.mirror`). The store is fed by the display paths
+ * (LocalDisplayManager + the cloud path) via `setDisplayEvent`; this facade is the
+ * read side: `current()` (snapshot) + `onMirror(cb)` (subscribe). The raw store is
+ * also exposed as `engine.displayStore` (the Glassly-app escape hatch).
+ */
+import {useDisplayStore} from "../stores/display"
+
+export type DisplayMirrorEvent = Record<string, unknown> & {view?: string; layout?: any}
+
+export const displayMirror = {
+  /** The display event currently shown on the previewed view (snapshot). */
+  current(): DisplayMirrorEvent {
+    // Copy: the snapshot must not hand callers a mutable reference into the store.
+    return {...useDisplayStore.getState().currentEvent}
+  },
+
+  /** Subscribe to changes of the previewed display event; returns an unsubscribe. */
+  onMirror(cb: (event: DisplayMirrorEvent) => void): () => void {
+    return useDisplayStore.subscribe((s) => s.currentEvent, cb)
+  },
+
+  /** Which view is previewed — the main screen or the dashboard. */
+  view(): string {
+    return useDisplayStore.getState().view
+  },
+  /** Switch the previewed view between `"main"` and `"dashboard"`. */
+  setView(view: "main" | "dashboard"): void {
+    useDisplayStore.getState().setView(view)
+  },
+}

package/src/facades/gallery.ts

@@ -0,0 +1,69 @@
+/**
+ * gallery facade — `engine.gallery`: the OEM-facing gallery-sync surface. Engine's
+ * gallerySyncService orchestrates the sync (hotspot → wifi → HTTP fetch → process →
+ * store); this facade exposes the projected status + the structured notices the host
+ * renders its own UI from, plus the sync/cancel actions. No host-injected UI — the host
+ * owns all alerts/navigation/i18n (it renders them off `onNotice`).
+ */
+import {
+  useGallerySyncStore,
+  selectSyncProgress,
+  selectIssyncing,
+  selectGlassesGalleryStatus,
+} from "../stores/gallerySync"
+import {gallerySyncService} from "../services/asg/gallerySyncService"
+import {onGalleryNotice, type GalleryNotice} from "../services/asg/galleryNotices"
+
+function projectStatus() {
+  const s = useGallerySyncStore.getState()
+  const progress = selectSyncProgress(s)
+  return {
+    ...progress,
+    processingFiles: Array.from(progress.processingFiles),
+    processedFiles: s.processedFiles,
+    isSyncing: selectIssyncing(s),
+    isStarting: s.syncStarting,
+    glassesGallery: selectGlassesGalleryStatus(s),
+    // Copy: the snapshot must not hand callers a mutable reference into the store
+    // (each queue item is copied too — callers must not mutate them in place).
+    queue: s.queue.map((item) => ({...item})),
+    queueLength: s.queue.length,
+    queueIndex: s.queueIndex,
+  }
+}
+
+export type GallerySyncStatus = ReturnType<typeof projectStatus>
+
+export const gallery = {
+  /** Snapshot of the current sync state + progress. */
+  status: (): GallerySyncStatus => projectStatus(),
+  /** Subscribe to sync-state changes; returns an unsubscribe. Deduped on the projected
+   * status (the gallerySync store mutates many unrelated fields during a sync), so the
+   * host only re-renders when the projection actually changes — matches the other
+   * read-model facades. */
+  onStatus: (cb: (status: GallerySyncStatus) => void): (() => void) => {
+    let last = JSON.stringify(projectStatus())
+    return useGallerySyncStore.subscribe(() => {
+      const status = projectStatus()
+      const serialized = JSON.stringify(status)
+      if (serialized === last) return
+      last = serialized
+      cb(status)
+    })
+  },
+  /** Subscribe to user-actionable notices (host renders alerts / settings deep-links). */
+  onNotice: (cb: (notice: GalleryNotice) => void): (() => void) => onGalleryNotice(cb),
+
+  /** Start a gallery sync (the host gates connectivity/permissions first). */
+  sync: (): Promise<void> => gallerySyncService.startSync(),
+  /** Cancel an in-progress sync. */
+  cancel: (): Promise<void> => gallerySyncService.cancelSync(),
+  /** Ask glasses to refresh their gallery summary counts. */
+  refreshStatus: (): Promise<void> => gallerySyncService.queryGlassesGalleryStatus(),
+  /** Remove local files from the current gallery queue after host-owned deletion UI completes. */
+  removeFilesFromQueue: (fileNames: string[]): void => useGallerySyncStore.getState().removeFilesFromQueue(fileNames),
+  /** Clear the current gallery sync queue after host-owned bulk deletion completes. */
+  clearQueue: (): void => useGallerySyncStore.getState().clearQueue(),
+  /** Clear the cached glasses gallery summary when product UI observes disconnect. */
+  clearGlassesGalleryStatus: (): void => useGallerySyncStore.getState().clearGlassesGalleryStatus(),
+}

package/src/facades/glasses.ts

@@ -0,0 +1,219 @@
+/**
+ * glasses facade — the core `engine.glasses.*` surface: connection actions (over
+ * the bluetooth-sdk passthrough), a curated status/info read-model (projected from
+ * the engine-owned glasses store), capabilities (from the model table), and the
+ * discrete input events. The `wifi` sub-facade is nested here.
+ *
+ * Read-models project the raw glasses store into the stable shape OEM UIs consume,
+ * so the device store's field layout doesn't leak into every screen.
+ */
+// Internal btsdk surface — connectSimulated/reconnect/controller live on the full
+// surface, not the public entry. Relative path (the alias doesn't resolve in engine's
+// standalone build); jest moduleNameMapper + tsconfig both resolve it.
+import BluetoothSdk from "@glassly/bluetooth-sdk/internal"
+import type {ButtonPressEvent, TouchEvent} from "@glassly/bluetooth-sdk/internal"
+import {useGlassesStore} from "../stores/glasses"
+import {useSettingsStore, SETTINGS} from "../stores/settings"
+import {hasDefaultDevice} from "../services/DeviceStoreHydration"
+import {projectPairingIdentity} from "../services/PairingIdentity"
+import {isGlassesConnected, isGlassesReady} from "../services/GlassesReadiness"
+import {pushAllBluetoothSettings} from "../services/GlassesSettingsSync"
+import {recordSupportProfileConnectionFailure} from "../services/SupportProfileSync"
+import {getModelCapabilities, type DeviceTypes} from "../types"
+import {glassesWifi} from "./glassesWifi"
+import {glassesSettings} from "./glassesSettings"
+
+function projectStatus() {
+  const s = useGlassesStore.getState()
+  return {
+    state: s.connection.state,
+    fullyBooted: isGlassesReady(s.connection),
+    battery: s.batteryLevel,
+    charging: s.charging,
+    case: {battery: s.caseBatteryLevel, charging: s.caseCharging, open: s.caseOpen, removed: s.caseRemoved},
+    signal: s.signalStrength,
+    micEnabled: s.micEnabled,
+    vadEnabled: s.voiceActivityDetectionEnabled,
+    btClassic: s.bluetoothClassicConnected,
+  }
+}
+
+function projectControllerStatus() {
+  const s = useGlassesStore.getState()
+  return {
+    connected: s.controllerConnected,
+    fullyBooted: s.controllerFullyBooted,
+    battery: s.controllerBatteryLevel,
+    signal: s.controllerSignalStrength,
+  }
+}
+
+function projectInfo() {
+  const s = useGlassesStore.getState()
+  return {
+    model: s.deviceModel,
+    style: s.style,
+    color: s.color,
+    bluetoothName: s.bluetoothName,
+    firmwareVersion: s.firmwareVersion,
+    mtkFirmware: s.mtkFirmwareVersion,
+    besFirmware: s.besFirmwareVersion,
+    appVersion: s.appVersion,
+    androidVersion: s.androidVersion,
+    serialNumber: s.serialNumber,
+    buildNumber: s.buildNumber,
+    btMac: s.bluetoothMacAddress,
+    wifiMac: s.wifiMacAddress,
+    leftMac: s.leftMacAddress,
+    rightMac: s.rightMacAddress,
+    // Copy: the snapshot must not hand callers a mutable reference into the store.
+    wifi: {...s.wifi},
+  }
+}
+
+export type GlassesStatusSnapshot = ReturnType<typeof projectStatus>
+export type ControllerStatusSnapshot = ReturnType<typeof projectControllerStatus>
+export type GlassesInfoSnapshot = ReturnType<typeof projectInfo>
+
+export const glasses = {
+  // --- connection (bluetooth-sdk passthrough) ---
+  /**
+   * Reconnect the default wearable. Seeds the phone's current device settings to
+   * native first, so they're primed before the connect handshake replays them to
+   * the glasses (this used to be a host-side step before `connectDefault`).
+   */
+  connectDefault: async (): Promise<void> => {
+    try {
+      await pushAllBluetoothSettings()
+      await BluetoothSdk.connectDefault()
+    } catch (error) {
+      recordSupportProfileConnectionFailure(error, "connect_default")
+      throw error
+    }
+  },
+  disconnect: (): Promise<void> => BluetoothSdk.disconnect(),
+  forget: (): Promise<void> => BluetoothSdk.forget(),
+  /** Connect to a specific (discovered) device. */
+  connect: async (...args: Parameters<typeof BluetoothSdk.connect>): Promise<void> => {
+    try {
+      await pushAllBluetoothSettings()
+      await BluetoothSdk.connect(...args)
+    } catch (error) {
+      recordSupportProfileConnectionFailure(error, "connect")
+      throw error
+    }
+  },
+  /** Connect the built-in simulated glasses (dev/testing). */
+  connectSimulated: (): Promise<void> => BluetoothSdk.connectSimulated(),
+  /** Set a device as the `connectDefault()` target. */
+  setDefault: (...args: Parameters<typeof BluetoothSdk.setDefaultDevice>) => BluetoothSdk.setDefaultDevice(...args),
+  /**
+   * Reconnect to the saved default glasses. Resolves `false` when there's nothing to
+   * reconnect to (no default paired) or the connect attempt fails (e.g. BLE powered
+   * off), `true` when already connected or after kicking off the connect. Never
+   * rejects — the boolean contract holds. The host gates connectivity/permissions
+   * (its UI) before calling.
+   */
+  reconnect: async (): Promise<boolean> => {
+    const defaultWearable = useSettingsStore.getState().getSetting(SETTINGS.default_wearable.key)
+    if (!defaultWearable) return false
+    if (isGlassesConnected(useGlassesStore.getState().connection)) return true
+    try {
+      await pushAllBluetoothSettings()
+      await BluetoothSdk.connectDefault()
+    } catch (error) {
+      recordSupportProfileConnectionFailure(error, "reconnect")
+      console.warn("engine.glasses.reconnect failed:", error)
+      return false
+    }
+    return true
+  },
+  /** True when no glasses has ever been paired NOR selected (the pairing-identity
+   * lifecycle is in its `none` state) — e.g. to route a first-run host into the
+   * pairing/onboarding flow. A pending selection is not "first" — the host should
+   * offer finish-pairing (see `engine.pairing.identity()`). */
+  isFirstPairing: (): boolean => projectPairingIdentity().kind === "none",
+  /**
+   * True when the SDK has an actual default DEVICE to reconnect to. Distinct from
+   * `default_wearable` (a model string that a pending or orphaned selection can
+   * hold without any paired device): connectDefault() throws without a device, so
+   * hosts should route to the pairing flow when this is false.
+   *
+   * Hydration-aware: awaits the device-store seed internally, so a cold-start
+   * read can't see a false "absent" for genuinely-paired users. Rejects if
+   * hydration failed — callers guarding destructive or routing decisions must
+   * fail open (treat as "has a device").
+   */
+  hasDefaultDevice: (): Promise<boolean> => hasDefaultDevice(),
+
+  // --- read-model (projected from the engine-owned glasses store) ---
+  status: (): GlassesStatusSnapshot => projectStatus(),
+  onStatus: (cb: (status: GlassesStatusSnapshot) => void): (() => void) => {
+    // Dedupe: the glasses store updates on many fields; only fire when the
+    // projected status snapshot actually changes.
+    let last = JSON.stringify(projectStatus())
+    return useGlassesStore.subscribe(() => {
+      const snap = projectStatus()
+      const key = JSON.stringify(snap)
+      if (key === last) return
+      last = key
+      cb(snap)
+    })
+  },
+  info: (): GlassesInfoSnapshot => projectInfo(),
+  onInfo: (cb: (info: GlassesInfoSnapshot) => void): (() => void) => {
+    let last = JSON.stringify(projectInfo())
+    return useGlassesStore.subscribe(() => {
+      const snap = projectInfo()
+      const key = JSON.stringify(snap)
+      if (key === last) return
+      last = key
+      cb(snap)
+    })
+  },
+  capabilities: () => getModelCapabilities(useGlassesStore.getState().deviceModel as DeviceTypes),
+  /** Ask the glasses to report fresh firmware/version info (updates the store). */
+  requestVersionInfo: () => BluetoothSdk.requestVersionInfo(),
+
+  // --- discrete input events (passthrough listeners) ---
+  onButtonPress: (cb: (event: ButtonPressEvent) => void): (() => void) => {
+    const sub = BluetoothSdk.addListener("button_press", cb)
+    return () => sub.remove()
+  },
+  onTouchGesture: (cb: (event: TouchEvent) => void): (() => void) => {
+    const sub = BluetoothSdk.addListener("touch_event", cb)
+    return () => sub.remove()
+  },
+
+  // --- ring controller (optional input device) ---
+  controller: {
+    connectDefault: (): Promise<void> => BluetoothSdk.connectDefaultController(),
+    disconnect: (): Promise<void> => BluetoothSdk.disconnectController(),
+    forget: (): Promise<void> => BluetoothSdk.forgetController(),
+    status: (): ControllerStatusSnapshot => projectControllerStatus(),
+    onStatus: (cb: (status: ControllerStatusSnapshot) => void): (() => void) => {
+      let last = JSON.stringify(projectControllerStatus())
+      return useGlassesStore.subscribe(() => {
+        const snap = projectControllerStatus()
+        const key = JSON.stringify(snap)
+        if (key === last) return
+        last = key
+        cb(snap)
+      })
+    },
+  },
+
+  // --- audio (glasses media-volume + own-app playback hint) ---
+  audio: {
+    /** Read the glasses' current media volume. */
+    getMediaVolume: () => BluetoothSdk.getGlassesMediaVolume(),
+    /** Set the glasses' media volume. */
+    setMediaVolume: (level: number) => BluetoothSdk.setGlassesMediaVolume(level),
+    /** Tell native whether THIS app is currently playing audio (for ducking). */
+    setOwnAppPlaying: (playing: boolean): Promise<void> => BluetoothSdk.setOwnAppAudioPlaying(playing),
+  },
+
+  // --- sub-facades ---
+  wifi: glassesWifi,
+  settings: glassesSettings,
+}

package/src/facades/glassesSettings.ts

@@ -0,0 +1,57 @@
+/**
+ * glasses.settings facade — `engine.glasses.settings`: the keyed DEVICE-settings
+ * surface (brightness, head-up angle, dashboard, camera/button, sensing, …). These
+ * are the settings the engine store auto-syncs to the glasses over the bluetooth-sdk
+ * (`BLUETOOTH_SETTING_KEYS`), so `set()` both persists and pushes to the device.
+ *
+ * Distinct from `engine.settings` (user/app prefs): this is scoped to the
+ * hardware-facing keys, minus the internal sync keys (auth/token) that aren't
+ * user-tunable device settings.
+ */
+import {useSettingsStore, SETTINGS, BLUETOOTH_SETTING_KEYS} from "../stores/settings"
+
+// Keys carried on BLUETOOTH_SETTING_KEYS for the device handshake that are NOT
+// user-tunable settings — auth, device/controller IDENTITY (set by pairing), and
+// internal RUNTIME flags. Kept out of the OEM-facing `available()` surface.
+const INTERNAL_KEYS = new Set<string>([
+  // auth
+  SETTINGS.core_token.key,
+  SETTINGS.auth_email.key,
+  // glasses + controller identity (managed by pairing, not the user)
+  SETTINGS.pending_wearable.key,
+  SETTINGS.default_wearable.key,
+  SETTINGS.device_name.key,
+  SETTINGS.device_address.key,
+  SETTINGS.project_name.key,
+  SETTINGS.pending_controller.key,
+  SETTINGS.default_controller.key,
+  SETTINGS.controller_device_name.key,
+  SETTINGS.controller_address.key,
+  // internal runtime flags
+  SETTINGS.local_stt_fallback_active.key,
+])
+const DEVICE_KEYS = BLUETOOTH_SETTING_KEYS.filter((k) => !INTERNAL_KEYS.has(k))
+
+// Copy: object/array-valued settings must not hand callers a mutable reference
+// into the store (mutations would bypass persistence + Bluetooth sync).
+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 glassesSettings = {
+  /** Read a device setting by key (object/array values are shallow copies). */
+  get: <T = unknown>(key: string): T | undefined =>
+    copySettingValue(useSettingsStore.getState().getSetting(key) as T | undefined),
+  /** Write a device setting — persists and auto-syncs to the connected glasses. */
+  set: <T = unknown>(key: string, value: T) => useSettingsStore.getState().setSetting(key, value),
+  /** Subscribe to changes for one device-setting 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],
+  /** The device-setting keys synced to the glasses (excludes internal sync keys). */
+  // Copy: callers must not be able to mutate the module-level key list.
+  available: (): string[] => [...DEVICE_KEYS],
+}

package/src/facades/glassesWifi.ts

@@ -0,0 +1,68 @@
+/**
+ * glasses.wifi facade — the first typed engine facade over the bluetooth-sdk
+ * passthrough, and the reference pattern the rest of the (A) host API copies.
+ *
+ * A facade wraps the raw `@glassly/bluetooth-sdk` surface into a small, typed,
+ * device-agnostic API (the `doX()` action shape here; `getX()`/`onX()` read-models
+ * come with domains that own their state). The host UI calls `engine.glasses.wifi.*`
+ * instead of importing bluetooth-sdk directly — that's the native-import boundary
+ * the engine is built around.
+ *
+ * `connect()` propagates bluetooth-sdk's coded errors unchanged so callers keep
+ * their existing error mapping. The `status()`/`onStatus()` read-model reads the
+ * glasses-state store engine now owns (wifi status is derived there from the
+ * device's connection info).
+ */
+import BluetoothSdk from "@glassly/bluetooth-sdk"
+import type {WifiSearchResult, WifiStatus} from "@glassly/bluetooth-sdk"
+import {useGlassesStore} from "../stores/glasses"
+
+export type {WifiSearchResult, WifiStatus}
+
+export const glassesWifi = {
+  /** Scan for nearby wifi networks. Request/response — resolves with the results. */
+  scan(): Promise<WifiSearchResult[]> {
+    return BluetoothSdk.requestWifiScan()
+  },
+
+  /**
+   * Subscribe to streamed scan results: the glasses report networks one by one
+   * while a scan runs, so callers can render them as they arrive instead of
+   * waiting for the final `scan()` result. Returns an unsubscribe.
+   */
+  onScanResult(cb: (networks: WifiSearchResult[]) => void): () => void {
+    const sub = BluetoothSdk.addListener("wifi_scan_result", (event) => {
+      cb(event.networks)
+    })
+    return () => sub.remove()
+  },
+
+  /**
+   * Send wifi credentials to the glasses. Resolves on success; rejects with the
+   * bluetooth-sdk coded error (`bluetooth_powered_off`, `request_timeout`, …) on
+   * failure, propagated unchanged for the caller to map.
+   */
+  async connect(ssid: string, password: string): Promise<void> {
+    await BluetoothSdk.sendWifiCredentials(ssid, password)
+  },
+
+  /** Forget a saved network on the glasses. */
+  async forget(ssid: string): Promise<void> {
+    await BluetoothSdk.forgetWifiNetwork(ssid)
+  },
+
+  /** The glasses' current wifi connection status (snapshot). */
+  status(): WifiStatus {
+    // Copy: the snapshot must not hand callers a mutable reference into the store.
+    return {...useGlassesStore.getState().wifi}
+  },
+
+  /** Subscribe to wifi-status changes (current, previous); returns an unsubscribe. */
+  onStatus(cb: (status: WifiStatus, previous: WifiStatus) => void): () => void {
+    // Copy: like status(), never publish the store's live wifi objects to listeners.
+    return useGlassesStore.subscribe(
+      (s) => s.wifi,
+      (wifi, previous) => cb({...wifi}, {...previous}),
+    )
+  },
+}