@glassly/engine 0.3.7-beta.889 → 0.3.7-beta.896

package/src/services/AppStateBackup.ts

@@ -0,0 +1,283 @@
+/**
+ * App state backups (Settings > Profile > Backup): one JSON file carrying the
+ * system settings, every miniapp's SimpleStorage, the installed miniapp list
+ * with each app's home flags, and the memory timeline.
+ *
+ * It exists so a logout or reinstall doesn't mean signing back into every
+ * miniapp, which is why the file holds live credentials (miniapp tokens,
+ * provider API keys) as plain JSON. Pairing identity, cloud endpoints, and
+ * consent/login state stay out: they belong to the install and the account,
+ * not to the user's preferences.
+ *
+ * Storage keys are written without their user segment, so a backup restores
+ * into whatever namespace the phone has now (account or `local_`). Restore
+ * overwrites key by key and leaves keys the backup doesn't carry alone.
+ *
+ * Pure: the MMKV view, settings registry, and memory snapshot are passed in by
+ * appStateBackupFile.ts.
+ */
+
+import type {MemoryBackup} from "@glassly/miniapp"
+
+/** Key-value surface (MMKV in production, values already JSON-decoded). */
+export interface AppStateBackupBackend {
+  get(key: string): unknown | null
+  set(key: string, value: unknown): void
+  keys(): string[]
+}
+
+/** The fields of a SETTINGS descriptor that decide whether it is backed up. */
+export interface BackupSettingDescriptor {
+  key: string
+  persist: boolean
+  writable: boolean
+  nativeAuthoritative?: true
+  resetOnBuildEnvChange?: true
+  indexer?: (key: string) => string
+}
+
+export interface AppStateBackupMiniapp {
+  /** Set when the miniapp was installed at export. */
+  installed?: {version: string; source?: string}
+  /** SimpleStorage key → stored value. */
+  storage: Record<string, unknown>
+  /** Home flags by suffix: `hidden`, `always_on`, `widget_expand_<widgetId>`. */
+  prefs: Record<string, unknown>
+}
+
+export interface AppStateBackup {
+  format: "glassly-app-state"
+  version: 1
+  /** Epoch ms the backup was written. */
+  exportedAt: number
+  /** Stored setting values; indexed settings keep their `key:index` storage key. */
+  settings: Record<string, unknown>
+  miniapps: Record<string, AppStateBackupMiniapp>
+  memory: MemoryBackup | null
+}
+
+/** Thrown for a file that isn't an app state backup this build can read. */
+export class AppStateBackupError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = "AppStateBackupError"
+  }
+}
+
+const STORAGE_ROOT = "localstorage_"
+const PREF_SUFFIXES = ["hidden", "always_on"] as const
+const WIDGET_EXPAND_PREFIX = "widget_expand_"
+// Same rule as the miniapp.json schema; keeps a hand-edited file from writing keys no app reads.
+const PACKAGE_NAME_RE = /^[a-zA-Z][a-zA-Z0-9_]*(\.[a-zA-Z][a-zA-Z0-9_]*)+$/
+
+/**
+ * Persisted, writable settings that are still not the user's to carry between
+ * installs: account and consent state, the paired devices, and caches.
+ */
+const EXCLUDED_SETTINGS = new Set([
+  "auth_email",
+  "disable_cloud",
+  "ai_data_consent_version",
+  "ai_data_consent_agreed",
+  "login_skipped",
+  "has_paired_glasses",
+  "keyboard_name",
+  "cached_required_version",
+  "offline_camera_running",
+  "offline_translation_running",
+])
+
+export function isBackupSetting(setting: BackupSettingDescriptor): boolean {
+  return (
+    setting.persist &&
+    setting.writable &&
+    !setting.nativeAuthoritative &&
+    !setting.resetOnBuildEnvChange &&
+    !EXCLUDED_SETTINGS.has(setting.key)
+  )
+}
+
+export interface CollectAppStateInput {
+  backend: AppStateBackupBackend
+  userId: string
+  settings: BackupSettingDescriptor[]
+  installed: Array<{packageName: string; version: string; source?: string}>
+  memory: MemoryBackup | null
+  now: number
+}
+
+export function collectAppStateBackup(input: CollectAppStateInput): AppStateBackup {
+  const {backend, settings} = input
+  const keys = backend.keys()
+
+  const settingValues: Record<string, unknown> = {}
+  for (const setting of settings) {
+    if (!isBackupSetting(setting)) continue
+    if (setting.indexer) {
+      for (const key of keys) {
+        if (!key.startsWith(`${setting.key}:`)) continue
+        const value = backend.get(key)
+        if (value != null) settingValues[key] = value
+      }
+      continue
+    }
+    const value = backend.get(setting.key)
+    if (value != null) settingValues[setting.key] = value
+  }
+
+  const miniapps: Record<string, AppStateBackupMiniapp> = {}
+  const entry = (packageName: string) => (miniapps[packageName] ??= {storage: {}, prefs: {}})
+
+  for (const app of input.installed) {
+    const record = entry(app.packageName)
+    record.installed = app.source ? {version: app.version, source: app.source} : {version: app.version}
+    for (const suffix of PREF_SUFFIXES) {
+      const value = backend.get(`${app.packageName}_${suffix}`)
+      if (value != null) record.prefs[suffix] = value
+    }
+    const expandPrefix = `${app.packageName}_${WIDGET_EXPAND_PREFIX}`
+    for (const key of keys) {
+      if (!key.startsWith(expandPrefix)) continue
+      const value = backend.get(key)
+      if (value != null) record.prefs[key.slice(app.packageName.length + 1)] = value
+    }
+  }
+
+  // Longest first, so a package whose name extends another's still claims its own keys.
+  const known = input.installed.map((app) => app.packageName).sort((a, b) => b.length - a.length)
+  const prefix = `${STORAGE_ROOT}${input.userId}_`
+  for (const key of keys) {
+    if (!key.startsWith(prefix)) continue
+    const split = splitStorageKey(key.slice(prefix.length), known)
+    if (!split) continue
+    const value = backend.get(key)
+    if (value != null) entry(split.packageName).storage[split.key] = value
+  }
+
+  return {
+    format: "glassly-app-state",
+    version: 1,
+    exportedAt: input.now,
+    settings: settingValues,
+    miniapps,
+    memory: input.memory,
+  }
+}
+
+/** `{packageName}_{key}` → its parts. Package names may contain `_`, so known names win over the first `_`. */
+function splitStorageKey(rest: string, known: string[]): {packageName: string; key: string} | null {
+  const packageName = known.find((name) => rest.startsWith(`${name}_`)) ?? rest.slice(0, rest.indexOf("_"))
+  const key = rest.slice(packageName.length + 1)
+  if (!packageName || !key) return null
+  return {packageName, key}
+}
+
+export function parseAppStateBackup(data: unknown): AppStateBackup {
+  if (!isRecord(data) || data.format !== "glassly-app-state") {
+    throw new AppStateBackupError("Not a Glassly app state backup")
+  }
+  if (typeof data.version !== "number" || data.version > 1) {
+    throw new AppStateBackupError(`Unsupported app state backup version ${String(data.version)}`)
+  }
+
+  const settings = isRecord(data.settings) ? data.settings : {}
+  const miniapps: Record<string, AppStateBackupMiniapp> = {}
+  if (isRecord(data.miniapps)) {
+    for (const [packageName, raw] of Object.entries(data.miniapps)) {
+      if (!PACKAGE_NAME_RE.test(packageName) || !isRecord(raw)) continue
+      const record: AppStateBackupMiniapp = {
+        storage: isRecord(raw.storage) ? raw.storage : {},
+        prefs: isRecord(raw.prefs) ? raw.prefs : {},
+      }
+      if (isRecord(raw.installed) && typeof raw.installed.version === "string") {
+        record.installed = {version: raw.installed.version}
+        if (typeof raw.installed.source === "string") record.installed.source = raw.installed.source
+      }
+      miniapps[packageName] = record
+    }
+  }
+
+  let memory: MemoryBackup | null = null
+  if (data.memory != null) {
+    if (!isRecord(data.memory) || data.memory.format !== "glassly-memory") {
+      throw new AppStateBackupError("The backup's memory section is not a memory backup")
+    }
+    memory = data.memory as unknown as MemoryBackup
+  }
+
+  return {format: "glassly-app-state", version: 1, exportedAt: Number(data.exportedAt) || 0, settings, miniapps, memory}
+}
+
+/**
+ * The backup's settings this build will restore, split by how they're written:
+ * `plain` through the settings store, `indexed` (`key:index`) straight to storage.
+ * Keys this build doesn't know, or doesn't back up, are dropped.
+ */
+export function restorableSettings(
+  backup: AppStateBackup,
+  settings: BackupSettingDescriptor[],
+): {plain: Record<string, unknown>; indexed: Record<string, unknown>} {
+  const byKey = new Map(settings.map((setting) => [setting.key, setting]))
+  const plain: Record<string, unknown> = {}
+  const indexed: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(backup.settings)) {
+    if (value == null) continue
+    const colon = key.indexOf(":")
+    const setting = byKey.get(colon < 0 ? key : key.slice(0, colon))
+    if (!setting || !isBackupSetting(setting)) continue
+    if (colon < 0 && !setting.indexer) plain[key] = value
+    else if (colon > 0 && setting.indexer) indexed[key] = value
+  }
+  return {plain, indexed}
+}
+
+/** Miniapps the backup has storage for. */
+export function miniappsWithStorage(backup: AppStateBackup): string[] {
+  return Object.entries(backup.miniapps)
+    .filter(([, record]) => Object.entries(record.storage).some(([key, value]) => key && value != null))
+    .map(([packageName]) => packageName)
+}
+
+/** Write every miniapp's storage into `userId`'s namespace. Returns the packages that got keys. */
+export function restoreMiniappStorage(
+  backend: AppStateBackupBackend,
+  userId: string,
+  backup: AppStateBackup,
+): {packages: string[]; keys: number} {
+  const packages: string[] = []
+  let keys = 0
+  for (const [packageName, record] of Object.entries(backup.miniapps)) {
+    let wrote = 0
+    for (const [key, value] of Object.entries(record.storage)) {
+      if (!key || value == null) continue
+      backend.set(`${STORAGE_ROOT}${userId}_${packageName}_${key}`, value)
+      wrote++
+    }
+    if (wrote > 0) packages.push(packageName)
+    keys += wrote
+  }
+  return {packages, keys}
+}
+
+export interface MiniappPrefs {
+  hidden?: boolean
+  alwaysOn?: boolean
+  widgetExpand: Record<string, boolean>
+}
+
+/** A miniapp's home flags from the backup, with anything that isn't a boolean dropped. */
+export function miniappPrefs(record: AppStateBackupMiniapp): MiniappPrefs {
+  const prefs: MiniappPrefs = {widgetExpand: {}}
+  if (typeof record.prefs.hidden === "boolean") prefs.hidden = record.prefs.hidden
+  if (typeof record.prefs.always_on === "boolean") prefs.alwaysOn = record.prefs.always_on
+  for (const [key, value] of Object.entries(record.prefs)) {
+    if (!key.startsWith(WIDGET_EXPAND_PREFIX) || typeof value !== "boolean") continue
+    const widgetId = key.slice(WIDGET_EXPAND_PREFIX.length)
+    if (widgetId) prefs.widgetExpand[widgetId] = value
+  }
+  return prefs
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value != null && typeof value === "object" && !Array.isArray(value)
+}

package/src/services/LocalMiniappRuntime.ts

@@ -304,6 +304,20 @@ function withTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T | nul
   })
 }
 
+/** Bounds the cold-GPS wait for a one-shot poll; on a stall, any older fix beats an error. */
+const FRESH_LOCATION_TIMEOUT_MS = 8_000
+
+async function freshLocationOrStale(): Promise<Location.LocationObject> {
+  const fresh = await withTimeout(
+    Location.getCurrentPositionAsync({accuracy: Location.Accuracy.Low}),
+    FRESH_LOCATION_TIMEOUT_MS,
+  )
+  if (fresh) return fresh
+  const stale = await Location.getLastKnownPositionAsync()
+  if (stale) return stale
+  throw new Error("No location fix available")
+}
+
 const LOG_TAG = "LOCAL_MINIAPP"
 const DIAGNOSTIC_MAX_LIST_ITEMS = 100
 const DIAGNOSTIC_MAX_STRING_LENGTH = 512
@@ -3450,7 +3464,7 @@ class LocalMiniappRuntime {
       const locationStartedAt = Date.now()
       const cached = await Location.getLastKnownPositionAsync({maxAge: 60_000})
       console.log(`${LOG_TAG}: location poll cache hit=${cached !== null} elapsed=${Date.now() - locationStartedAt}ms`)
-      const location = cached ?? (await Location.getCurrentPositionAsync({accuracy: Location.Accuracy.Low}))
+      const location = cached ?? (await freshLocationOrStale())
       console.log(`${LOG_TAG}: location poll resolved elapsed=${Date.now() - locationStartedAt}ms`)
 
       this.sendResult(packageName, requestId, true, {
@@ -6071,13 +6085,16 @@ class LocalMiniappRuntime {
   private async startInteropApp(packageName: string): Promise<boolean> {
     const app = this.interopApps().find((a) => a.packageName === packageName)
     if (!app) return false
+    // session.miniapps.start comes from the glasses (the dashboard's Apps menu,
+    // an Assist voice command), unlike a headless action wake, which carries no source.
+    const launchSource = "glasses" as const
     // Running only for its widget: start() promotes it to a normal run, as opening it on the phone does.
-    if (app.widgetOnly) return useAppStatusStore.getState().start(app, {skipNavigation: true})
+    if (app.widgetOnly) return useAppStatusStore.getState().start(app, {skipNavigation: true, launchSource})
     if (app.local) {
-      await miniappLauncher.ensureConnected(packageName)
+      await miniappLauncher.ensureConnected(packageName, undefined, {launchSource})
       return true
     }
-    return useAppStatusStore.getState().start(app, {skipNavigation: true})
+    return useAppStatusStore.getState().start(app, {skipNavigation: true, launchSource})
   }
 
   private stopInteropApp(packageName: string): Promise<void> {

package/src/services/MiniappEngine.ts

@@ -29,42 +29,77 @@ export interface MiniappEngine {
 
 let engine: MiniappEngine | null = null
 
+/**
+ * Kill and re-spawn a miniapp's background JSContext from its installed bundle
+ * (dev: the dev server's fresh build). Resolves false when it isn't installed
+ * or the spawn failed.
+ */
+async function respawnBackground(router: JSRouter, uiRouter: UIRouter, packageName: string): Promise<boolean> {
+  // Re-resolve the freshly built bundle (dev: HTTP off the dev server;
+  // released: file:// snapshot) via the launcher's shared recipe. Carries
+  // the declared permissions + manifest across the respawn — omitting them
+  // would respawn the JSContext with no permissions, so SUBSCRIBE gates and
+  // per-call dispatch checks would start rejecting after a background
+  // hot-reload.
+  const resolved = await miniappLauncher.resolveBundle(packageName)
+  if (!resolved) {
+    console.warn(`JSRuntime: respawn-bg could not resolve bundle for ${packageName}`)
+    return false
+  }
+  // Force a respawn (kill + spawn) rather than launcher.ensureRunning,
+  // which is idempotent and would no-op an already-registered context.
+  await router.unregister(packageName)
+  const ok = await router.spawnAndRegister(packageName, resolved.bgSource, {
+    permissions: resolved.declaredPermissions,
+    installedManifest: resolved.installedManifest,
+  })
+  if (!ok) {
+    console.warn(`JSRuntime: respawn-bg failed for ${packageName}`)
+    return false
+  }
+  // The respawned JSContext is a fresh MiniappSession with ui.bound false.
+  // The mounted WebView won't re-fire glassly.ready() (it's latched), so
+  // re-announce it so RPC replies (glassly.request) reach the UI again
+  // instead of being dropped while unbound.
+  uiRouter.notifyReopen(packageName)
+  return true
+}
+
 function wireDevServerRespawnBackground(router: JSRouter, uiRouter: UIRouter): void {
   devServerBridge.onRespawnBackground(async (packageName) => {
     try {
-      // Re-resolve the freshly built bundle (dev: HTTP off the dev server;
-      // released: file:// snapshot) via the launcher's shared recipe. Carries
-      // the declared permissions + manifest across the respawn — omitting them
-      // would respawn the JSContext with no permissions, so SUBSCRIBE gates and
-      // per-call dispatch checks would start rejecting after a background
-      // hot-reload.
-      const resolved = await miniappLauncher.resolveBundle(packageName)
-      if (!resolved) {
-        console.warn(`JSRuntime: respawn-bg could not resolve bundle for ${packageName}`)
-        return
-      }
-      // Force a respawn (kill + spawn) rather than launcher.ensureRunning,
-      // which is idempotent and would no-op an already-registered context.
-      await router.unregister(packageName)
-      const ok = await router.spawnAndRegister(packageName, resolved.bgSource, {
-        permissions: resolved.declaredPermissions,
-        installedManifest: resolved.installedManifest,
-      })
-      if (!ok) {
-        console.warn(`JSRuntime: respawn-bg failed for ${packageName}`)
-        return
-      }
-      // The respawned JSContext is a fresh MiniappSession with ui.bound false.
-      // The mounted WebView won't re-fire glassly.ready() (it's latched), so
-      // re-announce it so RPC replies (glassly.request) reach the UI again
-      // instead of being dropped while unbound.
-      uiRouter.notifyReopen(packageName)
+      await respawnBackground(router, uiRouter, packageName)
     } catch (e) {
       console.warn(`JSRuntime: respawn-bg threw for ${packageName}:`, e)
     }
   })
 }
 
+/** Packages with a live background JSContext. */
+export function runningMiniappPackages(): string[] {
+  return engine?.router.registeredPackages() ?? []
+}
+
+/** Tear down a miniapp's background JSContext; a no-op when it isn't running. */
+export async function stopMiniapp(packageName: string): Promise<void> {
+  await engine?.router.unregister(packageName)
+}
+
+/**
+ * Start (or restart) a miniapp's background so it reads its storage afresh (an
+ * app state restore). Resolves false when the engine isn't up or the spawn failed.
+ */
+export async function respawnMiniapp(packageName: string): Promise<boolean> {
+  const current = engine
+  if (!current) return false
+  try {
+    return await respawnBackground(current.router, current.uiRouter, packageName)
+  } catch (e) {
+    console.warn(`JSRuntime: respawn threw for ${packageName}:`, e)
+    return false
+  }
+}
+
 /**
  * Construct (once) and return the JSRuntime engine singletons. Starts the router's
  * message pump on first call. Subsequent calls return the same instances.

package/src/services/NavigationService.ts

@@ -16,6 +16,7 @@ import CrustModule from "@glassly/crust"
 import {resolveMapboxAccessToken, resolveMapboxRenderToken, userMapboxApiKey} from "./MapboxTokenService"
 import {decodePolyline, parseDurationSeconds} from "./navigation/routesApiCodec"
 import {resolveStepRoads} from "./navigation/roadNameResolver"
+import {BgTimer} from "../utils/timers"
 
 const LOG_TAG = "NAV_SERVICE"
 
@@ -394,7 +395,7 @@ class NavigationService {
     sessionToken: string,
   ): Promise<{
     ok: boolean
-    suggestions?: Array<{placeId: string; mainText: string; secondaryText: string}>
+    suggestions?: Array<{placeId: string; mainText: string; secondaryText: string; distanceMeters?: number}>
     error?: string
   }> {
     return placeAutocompleteViaSearchBox(query, near, sessionToken)
@@ -506,6 +507,19 @@ export default navigationService
 const MAPBOX_DIRECTIONS_BASE = "https://api.mapbox.com/directions/v5/mapbox"
 const MAPBOX_GEOCODE_REVERSE = "https://api.mapbox.com/search/geocode/v6/reverse"
 const MAPBOX_SEARCHBOX_SUGGEST = "https://api.mapbox.com/search/searchbox/v1/suggest"
+
+/** Place search sits in front of a voice command; a stalled call must fail over, not hang. */
+const PLACE_SEARCH_TIMEOUT_MS = 6_000
+
+async function fetchWithTimeout(url: string, timeoutMs: number): Promise<Response> {
+  const controller = new AbortController()
+  const timer = BgTimer.setTimeout(() => controller.abort(), timeoutMs)
+  try {
+    return await fetch(url, {method: "GET", signal: controller.signal})
+  } finally {
+    BgTimer.clearTimeout(timer)
+  }
+}
 const MAPBOX_SEARCHBOX_RETRIEVE = "https://api.mapbox.com/search/searchbox/v1/retrieve"
 
 /**
@@ -818,7 +832,7 @@ async function placeAutocompleteViaSearchBox(
   sessionToken: string,
 ): Promise<{
   ok: boolean
-  suggestions?: Array<{placeId: string; mainText: string; secondaryText: string}>
+  suggestions?: Array<{placeId: string; mainText: string; secondaryText: string; distanceMeters?: number}>
   error?: string
 }> {
   if (!query.trim()) return {ok: true, suggestions: []}
@@ -837,11 +851,14 @@ async function placeAutocompleteViaSearchBox(
     types: "poi,address,place,street",
     limit: "10",
   })
-  // Mapbox wants lng,lat for proximity bias.
-  if (near) params.set("proximity", `${near.lng},${near.lat}`)
+  // Mapbox wants lng,lat for proximity bias; `origin` adds per-suggestion distance.
+  if (near) {
+    params.set("proximity", `${near.lng},${near.lat}`)
+    params.set("origin", `${near.lng},${near.lat}`)
+  }
 
   try {
-    const res = await fetch(`${MAPBOX_SEARCHBOX_SUGGEST}?${params.toString()}`, {method: "GET"})
+    const res = await fetchWithTimeout(`${MAPBOX_SEARCHBOX_SUGGEST}?${params.toString()}`, PLACE_SEARCH_TIMEOUT_MS)
     if (!res.ok) return {ok: false, error: `Search Box suggest ${res.status}`}
     const json = (await res.json()) as {
       suggestions?: Array<{
@@ -849,6 +866,7 @@ async function placeAutocompleteViaSearchBox(
         name?: string
         place_formatted?: string
         full_address?: string
+        distance?: number
       }>
     }
     const suggestions = (json.suggestions ?? [])
@@ -857,6 +875,7 @@ async function placeAutocompleteViaSearchBox(
         placeId: s.mapbox_id,
         mainText: s.name ?? "",
         secondaryText: s.place_formatted ?? s.full_address ?? "",
+        ...(typeof s.distance === "number" ? {distanceMeters: s.distance} : {}),
       }))
     return {ok: true, suggestions}
   } catch (err) {
@@ -890,9 +909,10 @@ async function placeDetailsViaSearchBox(
   }
   const params = new URLSearchParams({access_token: token, session_token: sessionToken})
   try {
-    const res = await fetch(`${MAPBOX_SEARCHBOX_RETRIEVE}/${encodeURIComponent(placeId)}?${params.toString()}`, {
-      method: "GET",
-    })
+    const res = await fetchWithTimeout(
+      `${MAPBOX_SEARCHBOX_RETRIEVE}/${encodeURIComponent(placeId)}?${params.toString()}`,
+      PLACE_SEARCH_TIMEOUT_MS,
+    )
     if (!res.ok) return {ok: false, error: `Search Box retrieve ${res.status}`}
     const json = (await res.json()) as {
       features?: Array<{