@glassly/engine 0.3.7-dev.888 → 0.3.7-dev.891

package/build/services/appStateBackupFile.js

@@ -0,0 +1,135 @@
+/**
+ * App state backup files: the share-sheet export and file-picker restore
+ * behind Settings > Profile > Backup. What goes in the file is decided in
+ * AppStateBackup.ts; this side reads and writes the live stores.
+ */
+import { File, Paths } from "expo-file-system";
+import { Platform } from "react-native";
+import Share from "react-native-share";
+import { SETTINGS, useSettingsStore } from "../stores/settings";
+import { useAppStatusStore } from "../stores/apps";
+import { storage } from "../utils/storage/storage";
+import appRegistry, { saveAlwaysOnOverride, saveWidgetExpandChoice } from "./AppRegistry";
+import { AppStateBackupError, collectAppStateBackup, miniappPrefs, miniappsWithStorage, parseAppStateBackup, restorableSettings, restoreMiniappStorage, } from "./AppStateBackup";
+import { cloudClientService } from "./CloudClientService";
+import { memoryStore } from "./memoryStoreInstance";
+import { respawnMiniapp, runningMiniappPackages, stopMiniapp } from "./MiniappEngine";
+const PICK_MIME_TYPES = Platform.OS === "android" ? ["application/json", "application/octet-stream"] : ["application/json"];
+const backend = {
+    get(key) {
+        const result = storage.load(key);
+        return result.is_ok() ? result.value : null;
+    },
+    set(key, value) {
+        const result = storage.save(key, value);
+        if (result.is_error())
+            throw result.error;
+    },
+    keys: () => storage.getAllKeys(),
+};
+export async function exportAppStateFile() {
+    const userId = await cloudClientService.resolveUserId();
+    const installed = [];
+    for (const app of await appRegistry.getInstalledMiniapps()) {
+        const version = await appRegistry.getActiveVersion(app.packageName);
+        if (!version)
+            continue;
+        installed.push({
+            packageName: app.packageName,
+            version,
+            source: appRegistry.getReleaseIdentity(app.packageName, version)?.source,
+        });
+    }
+    const backup = collectAppStateBackup({
+        backend,
+        userId,
+        settings: Object.values(SETTINGS),
+        installed,
+        memory: await memoryStore.exportBackup(),
+        now: Date.now(),
+    });
+    const filename = `glassly-backup-${localDate(backup.exportedAt)}.json`;
+    const file = new File(Paths.cache, filename);
+    file.writeSync(JSON.stringify(backup));
+    try {
+        await Share.open({ url: file.uri, type: "application/json", filename, title: "Glassly backup" });
+        return { success: true };
+    }
+    catch (error) {
+        // react-native-share rejects when the user dismisses the sheet.
+        if (error?.message?.includes("User did not share"))
+            return { success: false, cancelled: true };
+        throw error;
+    }
+}
+/** Resolves null when the user cancels the picker. */
+export async function importAppStateFile(opts = {}) {
+    const picked = await File.pickFileAsync({ mimeTypes: PICK_MIME_TYPES });
+    if (picked.canceled)
+        return null;
+    let data;
+    try {
+        data = JSON.parse(await picked.result.text());
+    }
+    catch {
+        throw new AppStateBackupError("Not a Glassly app state backup");
+    }
+    const backup = parseAppStateBackup(data);
+    const userId = await cloudClientService.resolveUserId();
+    // First, so a memory section this build rejects fails the restore before anything is written.
+    const memory = backup.memory ? await memoryStore.importBackup(backup.memory) : null;
+    const { plain, indexed } = restorableSettings(backup, Object.values(SETTINGS));
+    const written = await useSettingsStore.getState().setManyLocally(plain);
+    if (written.is_error())
+        throw written.error;
+    // setManyLocally only takes registry keys; `key:index` values go to storage and the store directly.
+    for (const [key, value] of Object.entries(indexed))
+        backend.set(key, value);
+    if (Object.keys(indexed).length > 0) {
+        useSettingsStore.setState((state) => ({ settings: { ...state.settings, ...indexed } }));
+    }
+    // A running miniapp holds its old values in memory and could write them back over the
+    // restore, so the ones getting storage stop now and start again at the end.
+    const running = new Set(runningMiniappPackages());
+    const restarting = miniappsWithStorage(backup).filter((packageName) => running.has(packageName));
+    for (const packageName of restarting)
+        await stopMiniapp(packageName);
+    try {
+        const restored = restoreMiniappStorage(backend, userId, backup);
+        const apps = useAppStatusStore.getState();
+        for (const [packageName, record] of Object.entries(backup.miniapps)) {
+            const prefs = miniappPrefs(record);
+            if (prefs.hidden !== undefined)
+                apps.setHiddenStatus(packageName, prefs.hidden);
+            if (prefs.alwaysOn !== undefined)
+                saveAlwaysOnOverride(packageName, prefs.alwaysOn);
+            for (const [widgetId, expand] of Object.entries(prefs.widgetExpand)) {
+                saveWidgetExpandChoice(packageName, widgetId, expand);
+            }
+        }
+        appRegistry.markRefreshNeeded();
+        await apps.refresh();
+        const installedNow = new Set((await appRegistry.getInstalledMiniapps()).map((app) => app.packageName));
+        const missing = Object.entries(backup.miniapps)
+            .filter(([packageName, record]) => record.installed && !installedNow.has(packageName))
+            .map(([packageName]) => packageName);
+        if (missing.length > 0)
+            await opts.reinstall?.(missing);
+        return {
+            settings: Object.keys(plain).length + Object.keys(indexed).length,
+            miniapps: restored.packages.length,
+            memory,
+            missing,
+        };
+    }
+    finally {
+        for (const packageName of restarting)
+            await respawnMiniapp(packageName);
+    }
+}
+function localDate(ms) {
+    const d = new Date(ms);
+    const pad = (n) => String(n).padStart(2, "0");
+    return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+}
+//# sourceMappingURL=appStateBackupFile.js.map

package/build/services/appStateBackupFile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"appStateBackupFile.js","sourceRoot":"","sources":["../../src/services/appStateBackupFile.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * App state backup files: the share-sheet export and file-picker restore\n * behind Settings > Profile > Backup. What goes in the file is decided in\n * AppStateBackup.ts; this side reads and writes the live stores.\n */\n\nimport type {MemoryImportResult} from \"@glassly/miniapp\"\nimport {File, Paths} from \"expo-file-system\"\nimport {Platform} from \"react-native\"\nimport Share from \"react-native-share\"\n\nimport {SETTINGS, useSettingsStore} from \"../stores/settings\"\nimport {useAppStatusStore} from \"../stores/apps\"\nimport {storage} from \"../utils/storage/storage\"\nimport appRegistry, {saveAlwaysOnOverride, saveWidgetExpandChoice} from \"./AppRegistry\"\nimport {\n  AppStateBackupError,\n  collectAppStateBackup,\n  miniappPrefs,\n  miniappsWithStorage,\n  parseAppStateBackup,\n  restorableSettings,\n  restoreMiniappStorage,\n  type AppStateBackupBackend,\n} from \"./AppStateBackup\"\nimport {cloudClientService} from \"./CloudClientService\"\nimport {memoryStore} from \"./memoryStoreInstance\"\nimport {respawnMiniapp, runningMiniappPackages, stopMiniapp} from \"./MiniappEngine\"\n\nexport interface AppStateExportResult {\n  success: boolean\n  cancelled?: boolean\n}\n\nexport interface AppStateRestoreResult {\n  /** Settings written. */\n  settings: number\n  /** Miniapps whose storage was restored. */\n  miniapps: number\n  memory: MemoryImportResult | null\n  /** Installed when the backup was made but not on this phone now. */\n  missing: string[]\n}\n\nexport interface AppStateRestoreOptions {\n  /**\n   * Install what the backup had installed and this phone lacks. Runs before\n   * the restored miniapps start again, so the dashboard comes back with every\n   * widget provider its saved layout names: it drops unknown widgets from the\n   * layout the next time it saves it.\n   */\n  reinstall?: (packageNames: string[]) => Promise<void>\n}\n\nconst PICK_MIME_TYPES =\n  Platform.OS === \"android\" ? [\"application/json\", \"application/octet-stream\"] : [\"application/json\"]\n\nconst backend: AppStateBackupBackend = {\n  get(key) {\n    const result = storage.load<unknown>(key)\n    return result.is_ok() ? result.value : null\n  },\n  set(key, value) {\n    const result = storage.save(key, value)\n    if (result.is_error()) throw result.error\n  },\n  keys: () => storage.getAllKeys(),\n}\n\nexport async function exportAppStateFile(): Promise<AppStateExportResult> {\n  const userId = await cloudClientService.resolveUserId()\n  const installed: Array<{packageName: string; version: string; source?: string}> = []\n  for (const app of await appRegistry.getInstalledMiniapps()) {\n    const version = await appRegistry.getActiveVersion(app.packageName)\n    if (!version) continue\n    installed.push({\n      packageName: app.packageName,\n      version,\n      source: appRegistry.getReleaseIdentity(app.packageName, version)?.source,\n    })\n  }\n  const backup = collectAppStateBackup({\n    backend,\n    userId,\n    settings: Object.values(SETTINGS),\n    installed,\n    memory: await memoryStore.exportBackup(),\n    now: Date.now(),\n  })\n\n  const filename = `glassly-backup-${localDate(backup.exportedAt)}.json`\n  const file = new File(Paths.cache, filename)\n  file.writeSync(JSON.stringify(backup))\n  try {\n    await Share.open({url: file.uri, type: \"application/json\", filename, title: \"Glassly backup\"})\n    return {success: true}\n  } catch (error: any) {\n    // react-native-share rejects when the user dismisses the sheet.\n    if (error?.message?.includes(\"User did not share\")) return {success: false, cancelled: true}\n    throw error\n  }\n}\n\n/** Resolves null when the user cancels the picker. */\nexport async function importAppStateFile(opts: AppStateRestoreOptions = {}): Promise<AppStateRestoreResult | null> {\n  const picked = await File.pickFileAsync({mimeTypes: PICK_MIME_TYPES})\n  if (picked.canceled) return null\n  let data: unknown\n  try {\n    data = JSON.parse(await picked.result.text())\n  } catch {\n    throw new AppStateBackupError(\"Not a Glassly app state backup\")\n  }\n  const backup = parseAppStateBackup(data)\n  const userId = await cloudClientService.resolveUserId()\n\n  // First, so a memory section this build rejects fails the restore before anything is written.\n  const memory = backup.memory ? await memoryStore.importBackup(backup.memory) : null\n\n  const {plain, indexed} = restorableSettings(backup, Object.values(SETTINGS))\n  const written = await useSettingsStore.getState().setManyLocally(plain)\n  if (written.is_error()) throw written.error\n  // setManyLocally only takes registry keys; `key:index` values go to storage and the store directly.\n  for (const [key, value] of Object.entries(indexed)) backend.set(key, value)\n  if (Object.keys(indexed).length > 0) {\n    useSettingsStore.setState((state) => ({settings: {...state.settings, ...indexed}}))\n  }\n\n  // A running miniapp holds its old values in memory and could write them back over the\n  // restore, so the ones getting storage stop now and start again at the end.\n  const running = new Set(runningMiniappPackages())\n  const restarting = miniappsWithStorage(backup).filter((packageName) => running.has(packageName))\n  for (const packageName of restarting) await stopMiniapp(packageName)\n\n  try {\n    const restored = restoreMiniappStorage(backend, userId, backup)\n\n    const apps = useAppStatusStore.getState()\n    for (const [packageName, record] of Object.entries(backup.miniapps)) {\n      const prefs = miniappPrefs(record)\n      if (prefs.hidden !== undefined) apps.setHiddenStatus(packageName, prefs.hidden)\n      if (prefs.alwaysOn !== undefined) saveAlwaysOnOverride(packageName, prefs.alwaysOn)\n      for (const [widgetId, expand] of Object.entries(prefs.widgetExpand)) {\n        saveWidgetExpandChoice(packageName, widgetId, expand)\n      }\n    }\n    appRegistry.markRefreshNeeded()\n    await apps.refresh()\n\n    const installedNow = new Set((await appRegistry.getInstalledMiniapps()).map((app) => app.packageName))\n    const missing = Object.entries(backup.miniapps)\n      .filter(([packageName, record]) => record.installed && !installedNow.has(packageName))\n      .map(([packageName]) => packageName)\n    if (missing.length > 0) await opts.reinstall?.(missing)\n\n    return {\n      settings: Object.keys(plain).length + Object.keys(indexed).length,\n      miniapps: restored.packages.length,\n      memory,\n      missing,\n    }\n  } finally {\n    for (const packageName of restarting) await respawnMiniapp(packageName)\n  }\n}\n\nfunction localDate(ms: number): string {\n  const d = new Date(ms)\n  const pad = (n: number) => String(n).padStart(2, \"0\")\n  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glassly/engine",
-  "version": "0.3.7-dev.888",
+  "version": "0.3.7-dev.891",
   "description": "Glassly Engine — miniapp registry, WebView bridge, and miniapp store",
   "main": "build/index.js",
   "react-native": "src/index.ts",
@@ -97,17 +97,17 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@glassly/bluetooth-sdk": "0.3.7-dev.888",
-    "@glassly/cloud-client": "0.3.7-dev.888",
-    "@glassly/cloud-protocol": "0.3.7-dev.888",
-    "@glassly/crust": "0.3.7-dev.888",
-    "@glassly/miniapp": "0.3.7-dev.888",
+    "@glassly/bluetooth-sdk": "0.3.7-dev.891",
+    "@glassly/cloud-client": "0.3.7-dev.891",
+    "@glassly/cloud-protocol": "0.3.7-dev.891",
+    "@glassly/crust": "0.3.7-dev.891",
+    "@glassly/miniapp": "0.3.7-dev.891",
     "buffer": "^6.0.3",
     "events": "^3.3.0",
     "react-native-marked": "8.3.2",
     "semver": "^7.7.4",
     "typesafe-ts": "^1.7.1",
-    "@glassly/llm-providers": "0.3.7-dev.888",
+    "@glassly/llm-providers": "0.3.7-dev.891",
     "@huggingface/jinja": "^0.5.9",
     "jsonrepair": "^3.12.0"
   },

package/src/engine.ts

@@ -49,6 +49,7 @@ import {permissions} from "./facades/permissions"
 import {notifications} from "./facades/notifications"
 import {maps} from "./facades/maps"
 import {memory} from "./facades/memory"
+import {backup} from "./facades/backup"
 import {speakers} from "./facades/speakers"
 import {providerKeys} from "./facades/providerKeys"
 import {logBuffer} from "./utils/devLogging"
@@ -232,6 +233,8 @@ export const engine = {
   maps,
   /** Shared user-scoped memory timeline (Settings > Memory + session.memory). */
   memory,
+  /** Whole-app backup file: settings, miniapp storage, installed list, memory (Settings > Profile). */
+  backup,
   /** Device-local voice profiles for on-device speaker ID (Settings > Speakers). */
   speakers,
   /** AI/voice provider key validation — user-supplied keys (Settings > API Keys). */

package/src/facades/backup.ts

@@ -0,0 +1,28 @@
+/**
+ * backup facade — `engine.backup`: the whole-app backup behind Settings >
+ * Profile > Backup. One JSON file carries system settings, every miniapp's
+ * storage (so their sign-ins survive a logout or reinstall), the installed
+ * miniapp list, and the memory timeline.
+ */
+import {AppStateBackupError} from "../services/AppStateBackup"
+import {
+  exportAppStateFile,
+  importAppStateFile,
+  type AppStateExportResult,
+  type AppStateRestoreOptions,
+  type AppStateRestoreResult,
+} from "../services/appStateBackupFile"
+import {MemoryBackupError} from "../services/MemoryStore"
+
+export const backup = {
+  /** Share the app state as a JSON backup file. */
+  exportFile: (): Promise<AppStateExportResult> => exportAppStateFile(),
+  /**
+   * Pick a backup file and restore it: backup values overwrite per key, and
+   * running miniapps whose storage changed restart after `opts.reinstall` has
+   * installed the ones this phone lacks. Resolves null on cancel.
+   */
+  importFile: (opts?: AppStateRestoreOptions): Promise<AppStateRestoreResult | null> => importAppStateFile(opts),
+  /** True for a file that isn't a backup this build can read. */
+  isBackupError: (err: unknown): boolean => err instanceof AppStateBackupError || err instanceof MemoryBackupError,
+}

package/src/generated/releaseMetadata.ts

@@ -12,9 +12,9 @@ export interface EngineReleaseMetadata {
 export const ENGINE_RELEASE_METADATA: Readonly<EngineReleaseMetadata> = Object.freeze({
   "schemaVersion": 1,
   "familyBaseVersion": "0.3.7",
-  "releaseIdentity": "0.3.7-dev.888",
-  "releaseSetId": "glassly-0.3.7-dev.888",
-  "sourceCommit": "b2a2c570c204c2ecc6e03a27128de74957148be5",
+  "releaseIdentity": "0.3.7-dev.891",
+  "releaseSetId": "glassly-0.3.7-dev.891",
+  "sourceCommit": "64f5b454fbb7786a307c1fe678c63f6f13f571a3",
   "otaManifestUrl": null,
   "otaManifestSha256": null
 })

package/src/index.ts

@@ -69,6 +69,7 @@ export {DEFAULT_LOCAL_LLM_MODEL, isLocalLlmModelId} from "./services/LocalLlmMod
 // session shapes are canonical in @glassly/miniapp (the session.memory
 // surface); the stats read model is engine-side.
 export type {MemoryStats} from "./services/MemoryStore"
+export type {AppStateExportResult, AppStateRestoreOptions, AppStateRestoreResult} from "./services/appStateBackupFile"
 export type {SpeakerProfile} from "./services/SpeakerProfileStore"
 export type {EnrollOutcome} from "./facades/speakers"
 export {MENTRA_LIVE_SETTING_KEYS, getBluetoothSettingKeysForDevice} from "./stores/bluetoothSettingKeys"

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> {