@mentra/engine 0.1.0-beta.0

package/src/stores/settings.ts

@@ -0,0 +1,1001 @@
+import {getTimeZone} from "react-native-localize"
+import {AsyncResult, result as Res, Result} from "typesafe-ts"
+import {create} from "zustand"
+import {subscribeWithSelector} from "zustand/middleware"
+
+import {storage} from "../utils/storage"
+import {getBluetoothSettingKeysForDevice} from "./bluetoothSettingKeys"
+import {useGlassesStore} from "./glasses"
+
+export {MENTRA_LIVE_SETTING_KEYS, getBluetoothSettingKeysForDevice} from "./bluetoothSettingKeys"
+
+export interface Setting {
+  key: string
+  defaultValue: () => any
+  writable: boolean
+  saveOnServer: boolean
+  // change the key to a different key based on the indexer
+  // NEVER do any network calls in the indexer (or performance will suffer greatly
+  indexer?: (key: string) => string
+  // optionally override the value of the setting when it's accessed
+  override?: () => any
+  // onWrite?: () => void
+  persist: boolean
+  // Pairing-identity keys are NATIVE-authoritative: the native layer writes
+  // them on pairing success (handleDeviceReady) / forget and echoes them down
+  // via save_setting; JS→native they travel only in the explicit SEEDS
+  // (hydration, pre-connect, post-demotion, abandon re-seed) — never the
+  // change-push and never the on-connect replay, whose mid-relay snapshot can
+  // overwrite a just-promoted identity. PAIRING_IDENTITY_KEYS is derived from
+  // this flag so the sync exclusions can't drift from the descriptors.
+  nativeAuthoritative?: true
+}
+
+export const SETTINGS: Record<string, Setting> = {
+  // feature flags / mantle settings:
+  dev_mode: {key: "dev_mode", defaultValue: () => __DEV__, writable: true, saveOnServer: true, persist: true}, // deprecated
+  debug_mode: {key: "debug_mode", defaultValue: () => __DEV__, writable: true, saveOnServer: true, persist: true},
+  super_mode: {key: "super_mode", defaultValue: () => false, writable: true, saveOnServer: true, persist: true},
+  appearance_menu_enabled: {
+    key: "appearance_menu_enabled",
+    defaultValue: () => false,
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  app_boot_extra_info: {
+    key: "app_boot_extra_info",
+    defaultValue: () => false,
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  miniapp_dev_mode: {
+    key: "miniapp_dev_mode",
+    defaultValue: () => false,
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  enable_squircles: {
+    key: "enable_squircles",
+    defaultValue: () => true,
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  android_blur: {
+    key: "android_blur",
+    defaultValue: () => {
+      return false
+    },
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  android_inner_shadow: {
+    key: "android_inner_shadow",
+    defaultValue: () => {
+      return false
+    },
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  ios_glass_effect: {
+    key: "ios_glass_effect",
+    defaultValue: () => true,
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  ios_app_switcher_bottom_swipe: {
+    key: "ios_app_switcher_bottom_swipe",
+    defaultValue: () => false,
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  debug_console: {
+    key: "debug_console",
+    defaultValue: () => false,
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  debug_navigation_history: {
+    key: "debug_navigation_history",
+    defaultValue: () => false,
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  debug_core_status_bar: {
+    key: "debug_core_status_bar",
+    defaultValue: () => false,
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  // Mentra Nex feature flags (off by default; toggled from Nex Developer Settings).
+  // When on, the Nex display skips ASCII-only text sanitization so CJK/Chinese
+  // captions render on glasses. Synced to the Bluetooth SDK via BLUETOOTH_SETTING_KEYS.
+  nex_chinese_captions: {
+    key: "nex_chinese_captions",
+    defaultValue: () => false,
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  // When on, LC3 audio received from Nex glasses is played back (Android only).
+  // Local-only dev toggle: defaults off and never synced to the cloud account
+  // (saveOnServer: false); persists locally so it survives app restarts.
+  // Key renamed from the legacy `nex_audio_playback` so stale server/local
+  // values (saved back when this was saveOnServer:true) can't re-enable it.
+  nex_lc3_audio_playback: {
+    key: "nex_lc3_audio_playback",
+    defaultValue: () => false,
+    writable: true,
+    saveOnServer: false,
+    persist: true,
+  },
+  china_deployment: {
+    key: "china_deployment",
+    defaultValue: () => (process.env.EXPO_PUBLIC_DEPLOYMENT_REGION === "china" ? true : false),
+    override: () => (process.env.EXPO_PUBLIC_DEPLOYMENT_REGION === "china" ? true : false),
+    writable: false,
+    saveOnServer: false,
+    persist: true,
+  },
+  // Cloud V2 endpoint OVERRIDES. Empty = no override; cloudClient's resolveUrl
+  // owns the full precedence (override -> env -> Metro-derived dev default).
+  // The value may be an explicit URL or the METRO_AUTO sentinel ("my dev
+  // laptop", resolved live from Metro so it survives network changes). Never
+  // bake an env var or a personal LAN IP into the default here: that makes the
+  // override branch always-truthy and strands devs on a stale address.
+  cloud_core_url: {
+    key: "cloud_core_url",
+    defaultValue: () => "",
+    writable: true,
+    saveOnServer: false,
+    persist: true,
+  },
+  cloud_runtime_url: {
+    key: "cloud_runtime_url",
+    defaultValue: () => "",
+    writable: true,
+    saveOnServer: false,
+    persist: true,
+  },
+  // Bookmarked Cloud V2 endpoint pairs. Each entry is {label, coreUrl,
+  // runtimeUrl} — core + runtime are saved together because they are always
+  // applied as a matched set (presets fill both; Save & Test verifies both).
+  saved_cloud_url_pairs: {
+    key: "saved_cloud_url_pairs",
+    defaultValue: () => [],
+    writable: true,
+    saveOnServer: false,
+    persist: true,
+  },
+  // Developer override for the ASG OTA manifest URL. null/empty = no override;
+  // the normal selection applies (legacy-glasses gate, EXPO_PUBLIC_ASG_OTA_VERSION_URL,
+  // glasses-reported URL, then production). See getAsgOtaVersionUrl.
+  ota_version_url: {
+    key: "ota_version_url",
+    defaultValue: () => null,
+    writable: true,
+    saveOnServer: false,
+    persist: true,
+  },
+  saved_ota_version_urls: {
+    key: "saved_ota_version_urls",
+    defaultValue: () => [],
+    writable: true,
+    saveOnServer: false,
+    persist: true,
+  },
+  reconnect_on_app_foreground: {
+    key: "reconnect_on_app_foreground",
+    defaultValue: () => true,
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  location_tier: {key: "location_tier", defaultValue: () => "", writable: true, saveOnServer: true, persist: true},
+  // Volatile bearer synced to Bluetooth for glasses-side Cloud V2 calls. The
+  // key name is kept for BLE compatibility, but the value must never be loaded
+  // from or saved to the legacy Cloud V1 settings store.
+  core_token: {key: "core_token", defaultValue: () => "", writable: true, saveOnServer: false, persist: false},
+  auth_email: {key: "auth_email", defaultValue: () => "", writable: true, saveOnServer: false, persist: true},
+  // Pairing identity is per-phone, not per-account: two phones on one account
+  // can be paired to different glasses, so none of these keys may sync to the
+  // server (saveOnServer: false — a stale server copy resurrecting a local
+  // pairing identity is exactly the desync this group's flags prevent).
+  //
+  // Two-phase identity: pending_wearable is the model the user last STARTED
+  // pairing (written at selection, rendered as a finish-pairing card);
+  // default_wearable + device_name + device_address are only promoted by the
+  // native layer when pairing actually succeeds (handleDeviceReady).
+  // pending_wearable persists so an abandoned selection still shows its
+  // finish-pairing card after an app restart.
+  pending_wearable: {
+    key: "pending_wearable",
+    defaultValue: () => "",
+    writable: true,
+    saveOnServer: false,
+    persist: true,
+    nativeAuthoritative: true,
+  },
+  default_wearable: {
+    key: "default_wearable",
+    defaultValue: () => "",
+    writable: true,
+    saveOnServer: false,
+    persist: true,
+    nativeAuthoritative: true,
+  },
+  device_name: {
+    key: "device_name",
+    defaultValue: () => "",
+    writable: true,
+    saveOnServer: false,
+    persist: true,
+    nativeAuthoritative: true,
+  },
+  device_address: {
+    key: "device_address",
+    defaultValue: () => "",
+    writable: true,
+    saveOnServer: false,
+    persist: true,
+    nativeAuthoritative: true,
+  },
+  default_controller: {
+    key: "default_controller",
+    defaultValue: () => "",
+    writable: true,
+    saveOnServer: false,
+    persist: true,
+    nativeAuthoritative: true,
+  },
+  pending_controller: {
+    key: "pending_controller",
+    defaultValue: () => "",
+    writable: true,
+    saveOnServer: false,
+    persist: true,
+    nativeAuthoritative: true,
+  },
+  controller_device_name: {
+    key: "controller_device_name",
+    defaultValue: () => "",
+    writable: true,
+    saveOnServer: false,
+    persist: true,
+    nativeAuthoritative: true,
+  },
+  controller_address: {
+    key: "controller_address",
+    defaultValue: () => "",
+    writable: true,
+    saveOnServer: false,
+    persist: true,
+    nativeAuthoritative: true,
+  },
+  // ui state:
+  home_background: {
+    key: "home_background",
+    defaultValue: () => "",
+    writable: true,
+    saveOnServer: false,
+    persist: true,
+  },
+  theme_preference: {
+    key: "theme_preference",
+    defaultValue: () => "light",
+    // Force light mode - i mode is not complete yet
+    // override: () => "light",
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  enable_phone_notifications: {
+    key: "enable_phone_notifications",
+    defaultValue: () => false,
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  settings_access_count: {
+    key: "settings_access_count",
+    defaultValue: () => 0,
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  show_advanced_settings: {
+    key: "show_advanced_settings",
+    defaultValue: () => false,
+    writable: true,
+    saveOnServer: false,
+    persist: true,
+  },
+  onboarding_completed: {
+    key: "onboarding_completed",
+    defaultValue: () => false,
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  onboarding_live_completed: {
+    key: "onboarding_live_completed",
+    defaultValue: () => false,
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  onboarding_os_completed: {
+    key: "onboarding_os_completed",
+    defaultValue: () => false,
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  has_ever_activated_app: {
+    key: "has_ever_activated_app",
+    defaultValue: () => false,
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+
+  // Bluetooth SDK settings:
+  sensing_enabled: {
+    key: "sensing_enabled",
+    defaultValue: () => true,
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  power_saving_mode: {
+    key: "power_saving_mode",
+    defaultValue: () => false,
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  voice_activity_detection_enabled: {
+    key: "voice_activity_detection_enabled",
+    defaultValue: () => true,
+    writable: true,
+    saveOnServer: false,
+    persist: false,
+  },
+  always_on_status_bar: {
+    key: "always_on_status_bar",
+    defaultValue: () => false,
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  // Legacy cloud/mobile setting name. Locally it maps to glasses-side Voice Activity Detection.
+  bypass_vad_for_debugging: {
+    key: "bypass_vad_for_debugging",
+    defaultValue: () => false,
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  bypass_audio_encoding_for_debugging: {
+    key: "bypass_audio_encoding_for_debugging",
+    defaultValue: () => false,
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  metric_system: {
+    key: "metric_system",
+    defaultValue: () => false,
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  twelve_hour_time: {
+    key: "twelve_hour_time",
+    defaultValue: () => true,
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  enforce_local_transcription: {
+    key: "enforce_local_transcription",
+    defaultValue: () => false,
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  // LC3 audio quality setting (frame size in bytes)
+  // 20 = 16kbps (low bandwidth), 40 = 32kbps (balanced), 60 = 48kbps (high quality)
+  lc3_frame_size: {
+    key: "lc3_frame_size",
+    defaultValue: () => 60,
+    writable: true,
+    saveOnServer: false,
+    persist: true,
+  },
+  preferred_mic: {
+    key: "preferred_mic",
+    defaultValue: () => "auto",
+    writable: true,
+    indexer: (key: string) => {
+      const glasses = useSettingsStore.getState().getSetting(SETTINGS.default_wearable.key)
+      if (glasses) {
+        return `${key}:${glasses}`
+      }
+      return key
+    },
+    saveOnServer: true,
+    persist: true,
+  },
+  screen_disabled: {
+    key: "screen_disabled",
+    defaultValue: () => false,
+    writable: true,
+    saveOnServer: false,
+    persist: true,
+  },
+  // glasses settings:
+  contextual_dashboard: {
+    key: "contextual_dashboard",
+    defaultValue: () => true,
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  use_native_dashboard: {
+    key: "use_native_dashboard",
+    defaultValue: () => true,
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  head_up_angle: {key: "head_up_angle", defaultValue: () => 45, writable: true, saveOnServer: true, persist: true},
+  brightness: {key: "brightness", defaultValue: () => 50, writable: true, saveOnServer: true, persist: true},
+  auto_brightness: {
+    key: "auto_brightness",
+    defaultValue: () => true,
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  dashboard_height: {
+    key: "dashboard_height",
+    defaultValue: () => 4,
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  dashboard_depth: {
+    key: "dashboard_depth",
+    defaultValue: () => 2,
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  menu_apps: {
+    key: "menu_apps",
+    defaultValue: () => null,
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  calendar_events: {
+    key: "calendar_events",
+    defaultValue: () => [],
+    writable: true,
+    saveOnServer: false,
+    persist: false,
+  },
+  // button settings
+  // Legacy persisted/cloud key; hardware behavior is now controlled by gallery_mode plus capture settings.
+  button_mode: {key: "button_mode", defaultValue: () => "photo", writable: true, saveOnServer: true, persist: true},
+  button_photo_size: {
+    key: "button_photo_size",
+    defaultValue: () => "max",
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  button_video_settings: {
+    key: "button_video_settings",
+    defaultValue: () => ({width: 1920, height: 1080, fps: 30}),
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  button_max_recording_time: {
+    key: "button_max_recording_time",
+    defaultValue: () => 10,
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  camera_fov: {
+    key: "camera_fov",
+    defaultValue: () => ({fov: 102, roi_position: 0}),
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  media_post_processing: {
+    key: "media_post_processing",
+    defaultValue: () => false,
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+
+  // time zone settings
+  time_zone: {
+    key: "time_zone",
+    defaultValue: () => "",
+    writable: true,
+    override: () => {
+      const override = useSettingsStore.getState().getSetting(SETTINGS.time_zone_override.key)
+      if (override) {
+        return override
+      }
+      return getTimeZone()
+    },
+    saveOnServer: true,
+    persist: true,
+  },
+  time_zone_override: {
+    key: "time_zone_override",
+    defaultValue: () => "",
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  // offline applets
+  offline_mode: {key: "offline_mode", defaultValue: () => false, writable: true, saveOnServer: true, persist: true},
+  // Runtime flag: coordinator flips this on when cloud STT has failed and fallback is active.
+  // Native GlassesStore watches it to gate PCM → Sherpa feeding. Not user-facing.
+  local_stt_fallback_active: {
+    key: "local_stt_fallback_active",
+    defaultValue: () => false,
+    writable: true,
+    saveOnServer: false,
+    persist: false,
+  },
+  gallery_mode: {key: "gallery_mode", defaultValue: () => true, writable: true, saveOnServer: true, persist: true},
+  gallery_sync_explained: {
+    key: "gallery_sync_explained",
+    defaultValue: () => false,
+    writable: true,
+    saveOnServer: false,
+    persist: true,
+  },
+  offline_camera_running: {
+    key: "offline_camera_running",
+    defaultValue: () => false,
+    writable: true,
+    saveOnServer: false,
+    persist: true,
+  },
+  // offline translation
+  offline_translation_running: {
+    key: "offline_translation_running",
+    defaultValue: () => false,
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  offline_translation_source: {
+    key: "offline_translation_source",
+    defaultValue: () => "en",
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  offline_translation_target: {
+    key: "offline_translation_target",
+    defaultValue: () => "es",
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  // button action settings
+  default_button_action_enabled: {
+    key: "default_button_action_enabled",
+    defaultValue: () => true,
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  default_button_action_app: {
+    key: "default_button_action_app",
+    defaultValue: () => "com.mentra.camera",
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  // notifications
+  notifications_enabled: {
+    key: "notifications_enabled",
+    defaultValue: () => true,
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  notifications_blocklist: {
+    key: "notifications_blocklist",
+    defaultValue: () => [],
+    writable: true,
+    saveOnServer: true,
+    persist: true,
+  },
+  // Cached required version from server - used to enforce updates even when offline
+  cached_required_version: {
+    key: "cached_required_version",
+    defaultValue: () => "",
+    writable: true,
+    saveOnServer: false,
+    persist: true,
+  },
+  // OTA update dismissal - stores the version code user dismissed (not persisted so resets on app restart)
+  dismissed_ota_version: {
+    key: "dismissed_ota_version",
+    defaultValue: () => "",
+    writable: true,
+    saveOnServer: false,
+    persist: false,
+  },
+  // Contact email for feedback (persisted for Apple private relay users)
+  contact_email: {
+    key: "contact_email",
+    defaultValue: () => "",
+    writable: true,
+    saveOnServer: false,
+    persist: true,
+  },
+} as const
+
+export const OFFLINE_APPLETS: string[] = ["com.mentra.livecaptions", "com.mentra.camera"]
+
+// These settings are automatically synced to the Bluetooth SDK.
+// Keep this list hardware-facing; app/UI/cloud-only preferences should stay in JS/Crust.
+export const BLUETOOTH_SETTING_KEYS: string[] = [
+  // Bluetooth settings:
+  SETTINGS.sensing_enabled.key,
+  SETTINGS.power_saving_mode.key,
+  SETTINGS.voice_activity_detection_enabled.key,
+  SETTINGS.lc3_frame_size.key,
+  SETTINGS.preferred_mic.key,
+  SETTINGS.screen_disabled.key,
+  SETTINGS.auth_email.key,
+  SETTINGS.core_token.key,
+  // glasses settings:
+  SETTINGS.contextual_dashboard.key,
+  SETTINGS.head_up_angle.key,
+  SETTINGS.brightness.key,
+  SETTINGS.auto_brightness.key,
+  SETTINGS.dashboard_height.key,
+  SETTINGS.dashboard_depth.key,
+  SETTINGS.menu_apps.key,
+  SETTINGS.calendar_events.key,
+  SETTINGS.use_native_dashboard.key,
+  SETTINGS.twelve_hour_time.key,
+  SETTINGS.metric_system.key,
+  // button:
+  SETTINGS.button_photo_size.key,
+  // Legacy MentraLive native code reads the object form when syncing video settings.
+  SETTINGS.button_video_settings.key,
+  SETTINGS.button_max_recording_time.key,
+  SETTINGS.camera_fov.key,
+  // device / pairing:
+  SETTINGS.pending_wearable.key,
+  SETTINGS.default_wearable.key,
+  SETTINGS.device_name.key,
+  SETTINGS.device_address.key,
+  SETTINGS.default_controller.key,
+  SETTINGS.pending_controller.key,
+  SETTINGS.controller_device_name.key,
+  SETTINGS.controller_address.key,
+  // offline applets:
+  SETTINGS.offline_mode.key,
+  // Runtime flag flipped by LocalSttFallbackCoordinator. Native reads it from
+  // GlassesStore to gate PCM → Sherpa feeding in handlePcm and to keep the
+  // mic on while local STT is the active engine.
+  SETTINGS.local_stt_fallback_active.key,
+  SETTINGS.gallery_mode.key,
+  // Mentra Nex feature flags:
+  SETTINGS.nex_chinese_captions.key,
+  SETTINGS.nex_lc3_audio_playback.key,
+]
+
+// Pairing identity is NATIVE-authoritative: the native layer writes it on
+// pairing success (handleDeviceReady) / forget and echoes it down via
+// save_setting; JS persists those echoes. JS→native, identity travels ONLY in
+// the explicit full seeds (device-store hydration, pre-connect push,
+// post-demotion re-push) — never in the change-push subscription. Relaying an
+// echoed identity change back up would make the sync bidirectional with loop
+// gain 1: two identity values in flight (e.g. a boot demotion crossing a
+// native promotion) then chase each other through push→apply→echo→push
+// forever, flapping the UI.
+//
+// Derived from the `nativeAuthoritative` descriptor flag (not maintained as a
+// parallel list) so the change-push exclusion in GlassesSettingsSync can't
+// drift from the setting declarations.
+export const PAIRING_IDENTITY_KEYS: string[] = Object.values(SETTINGS)
+  .filter((setting) => setting.nativeAuthoritative)
+  .map((setting) => setting.key)
+
+// const PER_GLASSES_SETTINGS_KEYS: string[] = [SETTINGS.preferred_mic.key]
+
+export interface SettingsState {
+  // Settings values
+  settings: Record<string, any>
+  // Loading states
+  isInitialized: boolean
+  // Actions
+  setSetting: (key: string, value: any, updateServer?: boolean) => AsyncResult<void, Error>
+  setManyLocally: (settings: Record<string, any>) => AsyncResult<void, Error>
+  getSetting: (key: string) => any
+  // loadSetting: (key: string) => AsyncResult<void, Error>
+  loadAllSettings: () => AsyncResult<void, Error>
+  // Utility methods
+  getBluetoothSettings: () => Record<string, any>
+  resetAllSettingsLocally: () => void
+}
+
+const getDefaultSettings = () =>
+  Object.keys(SETTINGS).reduce(
+    (acc, key) => {
+      acc[key] = SETTINGS[key].defaultValue()
+      return acc
+    },
+    {} as Record<string, any>,
+  )
+
+// Single-flight for loadAllSettings: the host fires it at module load and
+// engine.start()'s device-store hydration awaits it — without the memo the
+// second caller runs a duplicate full disk load while the first is still in
+// flight. Cleared on failure so a later call can retry.
+let loadAllSettingsInFlight: AsyncResult<void, Error> | null = null
+
+export const useSettingsStore = create<SettingsState>()(
+  subscribeWithSelector((set, get) => ({
+    settings: getDefaultSettings(),
+    isInitialized: false,
+    loadingKeys: new Set(),
+    setSetting: (key: string, value: any, _updateServer = true): AsyncResult<void, Error> => {
+      return Res.try_async(async () => {
+        const setting = SETTINGS[key]
+        const originalKey = key
+
+        if (!setting) {
+          throw new Error(`SETTINGS: SET: ${originalKey} is not a valid setting!`)
+        }
+
+        if (setting.indexer) {
+          key = setting.indexer(originalKey)
+        }
+
+        if (!setting.writable) {
+          throw new Error(`SETTINGS: ${originalKey} is not writable!`)
+        }
+
+        // Update store immediately for optimistic UI
+        console.log(`SETTINGS: SET: ${key} = ${value}`)
+        set((state) => ({
+          settings: {...state.settings, [key]: value},
+        }))
+
+        if (setting.persist) {
+          let res = await storage.save(key, value)
+          if (res.is_error()) {
+            throw new Error(`SETTINGS: couldn't save setting to storage: ${res.error}`)
+          }
+
+          // Cloud V1 per-change server sync removed with the V1 ripout (issue
+          // #3392). Settings are local-first until a V2 sync lands; the
+          // saveOnServer flags are retained as intent markers for that work.
+        }
+      })
+    },
+    getSetting: (key: string) => {
+      const state = get()
+      const originalKey = key
+      const setting = SETTINGS[originalKey]
+
+      if (!setting) {
+        console.error(`SETTINGS: GET: ${originalKey} is not a valid setting!`)
+        return undefined
+      }
+
+      if (setting.override) {
+        let override = setting.override()
+        if (override !== undefined) {
+          return override
+        }
+      }
+
+      if (setting.indexer) {
+        key = setting.indexer(originalKey)
+      }
+
+      // console.log(`GET SETTING: ${key} = ${state.settings[key]}`)
+
+      try {
+        const raw = state.settings[key] ?? SETTINGS[originalKey].defaultValue()
+        return raw
+      } catch (e) {
+        // for dynamically created settings, we need to create a new setting in SETTINGS:
+        console.log(`Failed to get setting, creating new setting:(${key}):`, e)
+        SETTINGS[key] = {key: key, defaultValue: () => undefined, writable: true, saveOnServer: false, persist: true}
+        return SETTINGS[key].defaultValue()
+      }
+    },
+    // batch update many settings from the server:
+    setManyLocally: (settings: Record<string, any>): AsyncResult<void, Error> => {
+      return Res.try_async(async () => {
+        const settingsToLoad: Record<string, any> = {}
+        // if a setting should not persist, don't load it:
+        for (const [key, value] of Object.entries(settings)) {
+          const stg: Setting | undefined = SETTINGS[key.toLowerCase()]
+          if (!stg) {
+            continue
+          }
+          if (!stg.persist) {
+            continue
+          }
+          settingsToLoad[key.toLowerCase()] = value
+        }
+        // console.log("SETTINGS: SET MANY LOCALLY: ", settingsToLoad)
+
+        set((state) => ({
+          settings: {...state.settings, ...settingsToLoad},
+        }))
+
+        // save to storage:
+        await Promise.all(Object.entries(settingsToLoad).map(([key, value]) => storage.save(key, value)))
+      })
+    },
+    // loads any preferences that have been changed from the default and saved to DISK!
+    loadAllSettings: (): AsyncResult<void, Error> => {
+      console.log("SETTINGS: loadAllSettings()")
+      if (loadAllSettingsInFlight) {
+        return loadAllSettingsInFlight
+      }
+      const inFlight = Res.try_async(async () => {
+        const state = get()
+        let loadedSettings: Record<string, any> = {}
+
+        if (state.isInitialized) {
+          return undefined
+        }
+
+        for (const setting of Object.values(SETTINGS)) {
+          // if the settings should not persist, don't load it:
+          if (!setting.persist) {
+            continue
+          }
+
+          // load all subkeys for an indexed setting:
+          if (setting?.indexer) {
+            console.log(`SETTINGS: LOAD: ${setting.key} with indexer!`)
+
+            let res: Result<Record<string, unknown>, Error> = storage.loadSubKeys(setting.key)
+            if (res.is_error()) {
+              console.log(`SETTINGS: LOAD: ${setting.key}`, res.error)
+              continue
+            }
+
+            let subKeys: Record<string, unknown> = res.value
+            console.log(`SETTINGS: LOAD: ${setting.key} subkeys are set!`, subKeys)
+            loadedSettings = {...loadedSettings, ...subKeys}
+            continue
+          }
+
+          let res = storage.load<any>(setting.key)
+          if (res.is_error()) {
+            console.log(`SETTINGS: LOAD: ${setting.key} is not set!`, res.error)
+            // this setting isn't set from the default, so we don't load anything
+            continue
+          }
+          // normal key:value pair:
+          let value = res.value
+          // res.value IS the stored value; logging value.value printed
+          // "undefined" for every loaded setting and disguised present
+          // values as missing. Redact token- and email-bearing keys: console
+          // logs are uploaded in bug-report artifacts (same keys
+          // diagnosticContext's SENSITIVE_SETTINGS_KEYS strips, minus an
+          // import that would cycle stores <-> utils).
+          const printable =
+            setting.key.includes("token") || setting.key.includes("email") ? "<redacted>" : JSON.stringify(value)
+          console.log(`SETTINGS: LOAD: ${setting.key} = ${printable}`)
+          loadedSettings[setting.key] = value
+        }
+
+        // console.log("##############################################")
+        // console.log(loadedSettings)
+        // console.log("##############################################")
+
+        set((state) => ({
+          isInitialized: true,
+          settings: {...state.settings, ...loadedSettings},
+        }))
+
+        // One-time migration: force android_blur=false for existing users.
+        // The setting's default is already false; this migration covers users
+        // who explicitly opted into Android blur effects before we discovered
+        // they're a major source of frame drops on cheap Android phones.
+        // The dimezisBlurViewSdk31Plus blur each costs ~5-10ms/frame; with
+        // multiple blurs on home (top fade + AppSwitcherButton x2) a low-end
+        // device misses the 16ms budget consistently. Users can turn it back
+        // on under Settings → Appearance once we've optimized further.
+        //
+        // The setSetting call also pushes to the server (saveOnServer: true)
+        // so the server-stored value flips too — otherwise the next sync
+        // from the user's server-stored prefs would re-enable blur.
+        // Best-effort: a server failure (offline, 5xx) shouldn't block boot;
+        // we still mark the migration done locally so we don't loop.
+        const MIGRATION_KEY = "migration:android_blur_default_false_v1"
+        const migrationDone = storage.load<boolean>(MIGRATION_KEY)
+        if (migrationDone.is_error() || !migrationDone.value) {
+          const current = get().getSetting(SETTINGS.android_blur.key)
+          if (current === true) {
+            const result = await get().setSetting(SETTINGS.android_blur.key, false, true)
+            if (result.is_error()) {
+              // Server push failed (offline / 5xx). Local storage was still
+              // updated, so the user immediately gets the new behavior. The
+              // server-side stale `true` will be overwritten the next time
+              // the user opens Appearance settings and the auto-sync runs.
+              console.log("SETTINGS: android_blur migration server-push failed:", result.error)
+            }
+          }
+          // Mark done unconditionally — even on server-push failure we don't
+          // want to retry the migration on every boot. The local value is
+          // already correct.
+          storage.save(MIGRATION_KEY, true)
+        }
+      })
+      loadAllSettingsInFlight = inFlight
+      void Promise.resolve(inFlight).then((result) => {
+        if (result.is_error()) {
+          loadAllSettingsInFlight = null
+        }
+      })
+      return inFlight
+    },
+    getBluetoothSettings: () => {
+      const state = get()
+      // Device-model-filtered key set (wire v2): Mentra Live (no display) gets
+      // the reduced MENTRA_LIVE_SETTING_KEYS; display glasses get the full set.
+      const deviceModel = useGlassesStore.getState().deviceModel || state.getSetting(SETTINGS.default_wearable.key)
+      const keys = getBluetoothSettingKeysForDevice(deviceModel, BLUETOOTH_SETTING_KEYS)
+      const bluetoothSettings: Record<string, any> = {}
+      for (const key of keys) {
+        const value = state.getSetting(key)
+        if (key === SETTINGS.core_token.key && (typeof value !== "string" || value.trim().length === 0)) {
+          continue
+        }
+        bluetoothSettings[key] = value
+      }
+      return bluetoothSettings
+    },
+    resetAllSettingsLocally: () => {
+      set((_state) => ({
+        settings: getDefaultSettings(),
+        isInitialized: true,
+      }))
+    },
+  })),
+)
+
+export const useSetting = <T = any>(key: string): [T, (value: T) => AsyncResult<void, Error>] => {
+  const value = useSettingsStore((state) => state.getSetting(key))
+  const setSetting = useSettingsStore((state) => state.setSetting)
+  return [value, (newValue: T) => setSetting(key, newValue)]
+}