@glassly/engine 0.3.7 → 0.3.8-dev.977

package/src/services/JSRouter.ts

@@ -146,6 +146,9 @@ export class JSRouter {
    */
   uiRouter: UIRouter | null = null
 
+  /** Teardowns in progress, so a stop and a racing start or stop see the same one. */
+  private readonly unregistering = new Map<string, Promise<void>>()
+
   constructor(
     private readonly runtime: LocalMiniappRuntime,
     private readonly crust: JSCrustBinding,
@@ -351,12 +354,26 @@ export class JSRouter {
   }
 
   /**
-   * Tear down a JSContext and unregister from the runtime. Synchronous
-   * teardown — the spec drops the 50ms WILL_DISCONNECT grace window
-   * because there's no transport handshake to flush in the JSC world.
+   * Tear down a JSContext and unregister from the runtime. The session's
+   * `onBeforeDisconnect` handlers get a short grace window first, so a
+   * miniapp can clear what it drew and end its own work while its messages
+   * still reach the host. Concurrent calls share one teardown.
    */
-  async unregister(packageName: string): Promise<void> {
-    if (!this.registered.has(packageName)) return
+  unregister(packageName: string): Promise<void> {
+    if (!this.registered.has(packageName)) return Promise.resolve()
+    const inFlight = this.unregistering.get(packageName)
+    if (inFlight) return inFlight
+    const teardown = this.teardown(packageName).finally(() => this.unregistering.delete(packageName))
+    this.unregistering.set(packageName, teardown)
+    return teardown
+  }
+
+  /** Resolves once an in-flight {@link unregister} of this package has finished. */
+  async whenUnregistered(packageName: string): Promise<void> {
+    await this.unregistering.get(packageName)
+  }
+
+  private async teardown(packageName: string): Promise<void> {
     // Cancel any pending crash-respawn before tearing down — we don't
     // want a stale timer to re-spawn a miniapp the user just disabled.
     const pending = this.respawnTimers.get(packageName)
@@ -364,6 +381,7 @@ export class JSRouter {
       BgTimer.clearTimeout(pending)
       this.respawnTimers.delete(packageName)
     }
+    await this.runtime.notifyWillDisconnect(packageName, "stopped")
     this.spawnCache.delete(packageName)
     this.crashController?.onKill(packageName)
     // User-initiated close/disable: end any active nav trip so the glasses
@@ -382,6 +400,14 @@ export class JSRouter {
   }
 
   /** List packages the router has registered. */
+  /** The user opened a running miniapp again; the source rides the next respawn too. */
+  notifyLaunch(packageName: string, launchSource: MiniappLaunchSource): void {
+    if (!this.registered.has(packageName)) return
+    const cached = this.spawnCache.get(packageName)
+    if (cached) cached.launchSource = launchSource
+    this.runtime.sendLaunchChange(packageName, launchSource)
+  }
+
   registeredPackages(): string[] {
     return Array.from(this.registered)
   }
@@ -483,13 +509,18 @@ export class JSRouter {
     if (iface === "__error") {
       const payload = this.tryParseArgs(msg.argsJson)
       this.logger.error(`[${packageName}] ${method}`, payload)
+      // Crashes reach the `glassly dev` terminal too, not only console calls.
+      const summary = this.summarizeReason(payload, method)
+      const stack = (payload as {stack?: unknown} | null)?.stack
+      const errorArgs = typeof stack === "string" && stack ? [summary, stack] : [summary]
+      devServerBridge.forwardLog(packageName, "error", errorArgs, Date.now(), "background")
       if (this.crashController) {
         // Only treat "exception" + "unhandledRejection" + "uncaught" as
         // crash signals. `console.error` calls also flow through the
         // log path — those don't end the JSContext.
         const isCrash = method === "exception" || method === "unhandledRejection" || method === "uncaught"
         if (isCrash) {
-          this.handleCrash(packageName, this.summarizeReason(payload, method))
+          this.handleCrash(packageName, summary)
         }
       }
       return

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
@@ -326,6 +340,8 @@ const SYSTEM_MINIAPP_PACKAGES = new Set([
   "com.glassly.miniappdev",
 ])
 const PING_INTERVAL_MS = 5_000
+/** How long a stopping miniapp's `beforeDisconnect` handlers get before teardown. */
+const WILL_DISCONNECT_GRACE_MS = 100
 // Min gap between "transcription limit reached" notices on the glasses. A
 // debounce, not a cooldown: the cloud re-announces the block per refused
 // subscribe, and miniapps retry in bursts — this only coalesces those bursts
@@ -1235,21 +1251,26 @@ class LocalMiniappRuntime {
    * undeliverable anyway.
    */
   public async gracefullyUnregisterApp(packageName: string, reason = "unregistering"): Promise<void> {
-    const app = this.connectedApps.get(packageName)
-    if (!app) return
-
-    console.log(`${LOG_TAG}: gracefullyUnregisterApp(${packageName}) — sending WILL_DISCONNECT`)
-    this.sendToMiniapp(packageName, {
-      type: MiniappResponseType.WILL_DISCONNECT,
-      reason,
-    })
-    // 50 ms: imperceptible to the user, plenty of time for the SDK's
-    // synchronous `beforeDisconnect` handlers to flush a final
-    // sendOneShot through the still-open transport.
-    await new Promise<void>((resolve) => BgTimer.setTimeout(resolve, 50))
+    if (!this.connectedApps.has(packageName)) return
+    await this.notifyWillDisconnect(packageName, reason)
     this.unregisterApp(packageName)
   }
 
+  /**
+   * Send `WILL_DISCONNECT` and wait out the grace window, so the session's
+   * `beforeDisconnect` handlers run (Navigation clears its HUD and ends its
+   * trip) and their last messages land before teardown. No-op unless the
+   * app finished its handshake.
+   */
+  public async notifyWillDisconnect(packageName: string, reason: string): Promise<void> {
+    if (!this.connectedApps.has(packageName) || !this.handshookApps.has(packageName)) return
+    console.log(`${LOG_TAG}: ${packageName} — sending WILL_DISCONNECT (${reason})`)
+    this.sendToMiniapp(packageName, {type: MiniappResponseType.WILL_DISCONNECT, reason})
+    // The message and the replies it triggers each cross a JSContext hop;
+    // short enough not to slow an app switch noticeably.
+    await new Promise<void>((resolve) => BgTimer.setTimeout(resolve, WILL_DISCONNECT_GRACE_MS))
+  }
+
   public unregisterApp(packageName: string, opts?: {endNavigation?: boolean}): void {
     console.log(`${LOG_TAG}: unregisterApp(${packageName})`)
     const releasedMicGateOverride = micStateCoordinator.clearMiniappGateOverrides(packageName)
@@ -3450,7 +3471,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 +6092,16 @@ class LocalMiniappRuntime {
   private async startInteropApp(packageName: string): Promise<boolean> {
     const app = this.interopApps().find((a) => a.packageName === packageName)
     if (!app) return false
-    // 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.local) {
-      await miniappLauncher.ensureConnected(packageName)
-      return true
-    }
-    return useAppStatusStore.getState().start(app, {skipNavigation: true})
+    // 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.
+    // The full start, as a phone open runs it: the standard peer stops so this
+    // app owns the display, and an app already running hears the new launch.
+    const launchSource = "glasses" as const
+    const started = await useAppStatusStore.getState().start(app, {skipNavigation: true, launchSource})
+    if (!started) return false
+    // The caller may message the app next; start() resolves at spawn.
+    if (app.local) await miniappLauncher.ensureConnected(packageName, undefined, {launchSource})
+    return true
   }
 
   private stopInteropApp(packageName: string): Promise<void> {
@@ -6851,6 +6875,17 @@ class LocalMiniappRuntime {
     this.sendToMiniapp(packageName, {type: MiniappResponseType.LINK, params})
   }
 
+  /**
+   * Tell a running miniapp the user opened it again and from where. The
+   * CONNECT_ACK only carries the source of the spawn, which is stale for a
+   * background app that keeps running between opens.
+   */
+  public sendLaunchChange(packageName: string, launchSource: MiniappLaunchSource): void {
+    const existing = this.connectedApps.get(packageName)
+    if (existing) existing.launchSource = launchSource
+    this.sendToMiniapp(packageName, {type: MiniappResponseType.LAUNCH_CHANGE, launchSource})
+  }
+
   /**
    * Send a VISIBILITY_CHANGE push to a miniapp.
    */

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/MiniappLauncher.ts

@@ -91,6 +91,11 @@ class MiniappLauncher {
   }
 
   /** True iff the package's background JS context is currently spawned. */
+  /** Tell an already-running miniapp the user opened it again and from where. */
+  notifyLaunch(packageName: string, launchSource: MiniappLaunchSource): void {
+    this.deps?.router.notifyLaunch(packageName, launchSource)
+  }
+
   isRunning(packageName: string): boolean {
     return this.deps?.router.registeredPackages().includes(packageName) ?? false
   }
@@ -228,6 +233,8 @@ class MiniappLauncher {
    */
   async ensureRunning(packageName: string, hints?: LaunchHints): Promise<LaunchResult> {
     const router = this.requireRouter()
+    // A context still tearing down from a stop is not one to reuse.
+    await router.whenUnregistered(packageName)
 
     // Already spawned: best-effort resolve for the UI entry, never throw —
     // a headless caller that doesn't need UI gets {null, null} fast even if

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

package/src/services/PhoneCalendarService.ts

@@ -49,9 +49,16 @@ export async function listPhoneCalendarEvents(request: CalendarListRequest): Pro
   if (calendars.length === 0) return {events: [], truncated: false}
 
   const rawEvents = await Calendar.listEvents(calendars, startsAt, endsAt)
+  const seen = new Set<string>()
   const events = rawEvents
     .map(normalizeCalendarEvent)
     .filter((event) => calendarEventOverlapsWindow(event, startsAt, endsAt))
+    .filter((event) => {
+      const key = `${event.title}\n${event.startsAt}\n${event.endsAt}\n${event.allDay}`
+      if (seen.has(key)) return false
+      seen.add(key)
+      return true
+    })
     .sort((a, b) => Date.parse(a.startsAt) - Date.parse(b.startsAt) || Date.parse(a.endsAt) - Date.parse(b.endsAt))
 
   return {

package/src/services/PhoneNotificationsSync.ts

@@ -91,6 +91,11 @@ export function nativeNotificationsSupported(): boolean {
   return getModelCapabilities(model).hasNativeNotifications === true
 }
 
+function notificationRelaySupported(): boolean {
+  const model = useGlassesStore.getState().deviceModel as DeviceTypes
+  return Platform.OS === "ios" && getModelCapabilities(model).hasNotificationRelay === true
+}
+
 /** Popup durations the firmware accepts, or an empty list when it takes any. */
 export function nativeNotificationPopupSeconds(): number[] {
   const model = useGlassesStore.getState().deviceModel as DeviceTypes
@@ -141,10 +146,10 @@ export function currentPresentationOwner(hostActive: boolean): PresentationOwner
  */
 export function captureAuthorization(): "granted" | "denied" | "unknown" | "not_needed" {
   if (Platform.OS !== "ios") return "not_needed"
-  if (!nativeNotificationsSupported()) return "not_needed"
+  if (!nativeNotificationsSupported() && !notificationRelaySupported()) return "not_needed"
   const glasses = useGlassesStore.getState()
   if (!isGlassesConnected(glasses.connection)) return "unknown"
-  return glasses.ancsAuthorized ? "granted" : "denied"
+  return glasses.ancsAuthorized ? "granted" : notificationRelaySupported() ? "unknown" : "denied"
 }
 
 /**
@@ -178,7 +183,7 @@ function pushListenerConfig(): void {
 }
 
 function pushGlassesConfig(): void {
-  if (!nativeNotificationsSupported()) return
+  if (!nativeNotificationsSupported() && !notificationRelaySupported()) return
   if (!isGlassesConnected(useGlassesStore.getState().connection)) return
   void Promise.resolve(BluetoothSdk.setGlassesNotificationConfig(desiredGlassesNotificationConfig())).catch(
     (err: unknown) =>

package/src/services/SceneRenderer.ts

@@ -250,7 +250,7 @@ class SceneRenderer {
       return {kind: "legacy", layout, degraded, dropped}
     }
 
-    const processed = processScene(elements, caps, displayProcessor.getProfile())
+    const processed = processScene(elements, caps, displayProcessor.getSceneProfile())
     // A stale baseline means the glasses were cleared since the last commit —
     // diff from empty so everything repaints (the retained frame stays valid
     // as the replay source only).

package/src/services/appStateBackupFile.ts

@@ -0,0 +1,171 @@
+/**
+ * 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 type {MemoryImportResult} from "@glassly/miniapp"
+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,
+  type AppStateBackupBackend,
+} from "./AppStateBackup"
+import {cloudClientService} from "./CloudClientService"
+import {memoryStore} from "./memoryStoreInstance"
+import {respawnMiniapp, runningMiniappPackages, stopMiniapp} from "./MiniappEngine"
+
+export interface AppStateExportResult {
+  success: boolean
+  cancelled?: boolean
+}
+
+export interface AppStateRestoreResult {
+  /** Settings written. */
+  settings: number
+  /** Miniapps whose storage was restored. */
+  miniapps: number
+  memory: MemoryImportResult | null
+  /** Installed when the backup was made but not on this phone now. */
+  missing: string[]
+}
+
+export interface AppStateRestoreOptions {
+  /**
+   * Install what the backup had installed and this phone lacks. Runs before
+   * the restored miniapps start again, so the dashboard comes back with every
+   * widget provider its saved layout names: it drops unknown widgets from the
+   * layout the next time it saves it.
+   */
+  reinstall?: (packageNames: string[]) => Promise<void>
+}
+
+const PICK_MIME_TYPES =
+  Platform.OS === "android" ? ["application/json", "application/octet-stream"] : ["application/json"]
+
+const backend: AppStateBackupBackend = {
+  get(key) {
+    const result = storage.load<unknown>(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(): Promise<AppStateExportResult> {
+  const userId = await cloudClientService.resolveUserId()
+  const installed: Array<{packageName: string; version: string; source?: string}> = []
+  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: any) {
+    // 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: AppStateRestoreOptions = {}): Promise<AppStateRestoreResult | null> {
+  const picked = await File.pickFileAsync({mimeTypes: PICK_MIME_TYPES})
+  if (picked.canceled) return null
+  let data: unknown
+  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: number): string {
+  const d = new Date(ms)
+  const pad = (n: number) => String(n).padStart(2, "0")
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`
+}