@mentra/engine 0.1.0-dev.0 → 3.1.0-dev.10

package/src/react/index.ts

@@ -0,0 +1,7 @@
+export {
+  MentraLiveOtaFlow,
+  type MentraLiveOtaFlowPage,
+  type MentraLiveOtaFlowProps,
+  type MentraLiveOtaFlowTheme,
+  type MentraLiveOtaFlowTranslate,
+} from "./MentraLiveOtaFlow"

package/src/react/useEngineSnapshot.ts

@@ -0,0 +1,16 @@
+import {useEffect, useRef, useState} from "react"
+
+export function useEngineSnapshot<T>(getSnapshot: () => T, subscribe: (onChange: () => void) => () => void): T {
+  const getSnapshotRef = useRef(getSnapshot)
+  const subscribeRef = useRef(subscribe)
+  getSnapshotRef.current = getSnapshot
+  subscribeRef.current = subscribe
+  const [snapshot, setSnapshot] = useState(() => getSnapshot())
+
+  useEffect(() => {
+    setSnapshot(getSnapshotRef.current())
+    return subscribeRef.current(() => setSnapshot(getSnapshotRef.current()))
+  }, [])
+
+  return snapshot
+}

package/src/runtime/bootstrap.ts

@@ -50,9 +50,22 @@ export interface IslandUiSeams {
    * `session.glasses.requestWifiSetup` — open the host's glasses Wi-Fi setup
    * flow. Absent ⇒ miniapps get NOT_IMPLEMENTED for the request.
    */
-  requestWifiSetup?: (reason?: string) => Promise<void> | void
+  requestWifiSetup?: (reason?: string, packageName?: string) => Promise<void> | void
+  /**
+   * `session.system.scanQr` — open a phone-camera QR scanner overlay. Must NOT
+   * clear miniapp foreground: UI_CLOSE on a live call hangs it up. Absent ⇒
+   * miniapps get NOT_IMPLEMENTED.
+   */
+  scanQr?: (options?: ScanQrOptions) => Promise<ScanQrResult>
+}
+
+export interface ScanQrOptions {
+  title?: string
+  hint?: string
 }
 
+export type ScanQrResult = {data: string} | {cancelled: true}
+
 export interface IslandConfigureOptions {
   /** REQUIRED — the only must-have seam. The host owns login; engine owns the rest. */
   auth: IslandAuth
@@ -81,6 +94,19 @@ export function configure(opts: IslandConfigureOptions): void {
   options = opts
 }
 
+/**
+ * Merge host-UI seams after configure/start. UI capabilities (scan overlay,
+ * wifi setup) are looked up per request, so this is safe on a running runtime.
+ * Used so Metro reloads can attach seams that missed the original configure().
+ */
+export function updateUiSeams(ui: IslandUiSeams): void {
+  if (!options) {
+    console.warn("engine.updateUiSeams() called before engine.configure(); ignored")
+    return
+  }
+  options = {...options, ui: {...options.ui, ...ui}}
+}
+
 /** Mark the runtime started. Idempotent. */
 export async function start(): Promise<void> {
   if (started) return
@@ -99,6 +125,12 @@ export function isStarted(): boolean {
   return started
 }
 
+/** Test-only: wipe configure state so suites can start from a cold host. */
+export function resetForTests(): void {
+  options = null
+  started = false
+}
+
 /** The host-supplied auth provider, or null if not configured yet. */
 export function getAuth(): IslandAuth | null {
   return options?.auth ?? null

package/src/runtime/scanQrSeam.ts

@@ -0,0 +1,20 @@
+import type {ScanQrOptions, ScanQrResult} from "./bootstrap"
+
+export class ScanQrNotConfiguredError extends Error {
+  readonly code = "NOT_IMPLEMENTED"
+  constructor() {
+    super("QR scanning is not configured on this host. Reload the Mentra App and try again.")
+    this.name = "ScanQrNotConfiguredError"
+  }
+}
+
+export async function invokeScanQrSeam(
+  scanQr: ((options?: ScanQrOptions) => Promise<ScanQrResult>) | undefined,
+  payload: Record<string, unknown> = {},
+): Promise<ScanQrResult> {
+  if (!scanQr) throw new ScanQrNotConfiguredError()
+  return scanQr({
+    title: typeof payload.title === "string" ? payload.title : undefined,
+    hint: typeof payload.hint === "string" ? payload.hint : undefined,
+  })
+}

package/src/services/AppRegistry.ts

@@ -22,14 +22,17 @@ import {unzip} from "react-native-zip-archive"
 import semver from "semver"
 import {AsyncResult, Result, result as Res} from "typesafe-ts"
 
-import type {AppletPermission, AppPermissionType, AppletType, ClientApp, DeclaredAction} from "../types/applet"
+import type {AppletPermission, AppPermissionType, AppletType, ClientApp} from "../types/applet"
 import {HardwareRequirement, HardwareRequirementLevel, HardwareType} from "../types"
-import {getConfigValues} from "../runtime/bootstrap"
+import {configuredDevHost} from "../utils/configuredDevHost"
 import {storage} from "../utils/storage/storage"
 import {printDirectory} from "../utils/storage/zip"
 import {checkManifestVersions} from "./manifestVersionGate"
+import {normalizeManifestActions} from "./manifestActions"
 import {miniappRunningRegistry} from "./MiniappRunningRegistry"
 
+export {normalizeManifestActions} from "./manifestActions"
+
 const ALLOWED_PERMISSION_TYPES: ReadonlySet<AppPermissionType> = new Set<AppPermissionType>([
   "MICROPHONE",
   "CAMERA",
@@ -73,29 +76,6 @@ function normalizeManifestType(raw: unknown): AppletType {
   return raw === "background" || raw === "system_dashboard" || raw === "standard" ? raw : "standard"
 }
 
-/**
- * Normalize a manifest's `actions` into DeclaredAction[]. Defensive — keeps only
- * well-formed `{id, description}` entries (installed/dev bundles may be
- * malformed). Shared by installed (disk) and dev-sideload projection so both
- * surface declared actions to session.miniapps.list + the invoke gate.
- */
-export function normalizeManifestActions(raw: unknown): DeclaredAction[] {
-  if (!Array.isArray(raw)) return []
-  const out: DeclaredAction[] = []
-  for (const a of raw as Array<{id?: unknown; description?: unknown; parameters?: unknown}>) {
-    if (a && typeof a.id === "string" && typeof a.description === "string") {
-      out.push({
-        id: a.id,
-        description: a.description,
-        ...(a.parameters && typeof a.parameters === "object"
-          ? {parameters: a.parameters as Record<string, unknown>}
-          : {}),
-      })
-    }
-  }
-  return out
-}
-
 /**
  * Convert declared hardwareRequirements from a miniapp.json manifest into
  * runtime `HardwareRequirement[]`, always appending `{EXIST, REQUIRED}` so
@@ -159,6 +139,17 @@ interface InstalledLma {
   versions: Record<string, InstalledInfo>
 }
 
+export interface MiniappReleaseIdentity {
+  source: "direct_download" | "bundled_asset" | "preinstalled_registry" | "dev_snapshot"
+  releaseId?: string
+  bundleSha256?: string
+  channel?: string
+}
+
+function releaseIdentityKey(packageName: string, version: string): string {
+  return `miniapp_release_identity:${packageName}:${version}`
+}
+
 /**
  * Download a miniapp zip from `url` into the cache and return its local path.
  *
@@ -451,11 +442,18 @@ class AppRegistry {
    *   of `manifest.version`. The dev caching path uses `dev-<ms>` so multiple
    *   snapshots can coexist alongside semver-installed versions.
    */
-  public installFromUrl(url: string, opts?: {versionOverride?: string}): AsyncResult<void, Error> {
+  public installFromUrl(
+    url: string,
+    opts?: {versionOverride?: string; releaseIdentity?: MiniappReleaseIdentity},
+  ): AsyncResult<void, Error> {
     return Res.try_async(async () => {
       const {packageName, version} = await downloadAndInstallMiniApp(url, opts?.versionOverride)
       console.log("APP_REGISTRY: Downloaded and installed mini app")
-      this.finalizeInstall(packageName, version)
+      this.finalizeInstall(
+        packageName,
+        version,
+        opts?.releaseIdentity ?? {source: version.startsWith("dev-") ? "dev_snapshot" : "direct_download"},
+      )
     })
   }
 
@@ -468,12 +466,12 @@ class AppRegistry {
    */
   public installFromLocalZip(
     zipPath: string,
-    opts?: {versionOverride?: string},
+    opts?: {versionOverride?: string; releaseIdentity?: MiniappReleaseIdentity},
   ): AsyncResult<{packageName: string; version: string}, Error> {
     return Res.try_async(async () => {
       const {packageName, version} = await unpackMiniApp(zipPath, opts?.versionOverride)
       console.log("APP_REGISTRY: Installed mini app from local zip")
-      this.finalizeInstall(packageName, version)
+      this.finalizeInstall(packageName, version, opts?.releaseIdentity ?? {source: "bundled_asset"})
       return {packageName, version}
     })
   }
@@ -483,7 +481,7 @@ class AppRegistry {
    * artifacts on release installs, point the active-version at the just-
    * installed bundle, and notify subscribers to refresh.
    */
-  private finalizeInstall(packageName: string, version: string): void {
+  private finalizeInstall(packageName: string, version: string, releaseIdentity: MiniappReleaseIdentity): void {
     // If this is a release install (semver, not dev-*) of a package that
     // currently has dev-* snapshots, clear the dev state so the swap to
     // "released" is clean. Otherwise the dev version would keep winning
@@ -495,10 +493,16 @@ class AppRegistry {
     }
 
     this.setActiveVersion(packageName, version)
+    storage.save(releaseIdentityKey(packageName, version), releaseIdentity)
     this.refreshNeeded = true
     this.notify()
   }
 
+  public getReleaseIdentity(packageName: string, version: string): MiniappReleaseIdentity | null {
+    const result = storage.load<MiniappReleaseIdentity>(releaseIdentityKey(packageName, version))
+    return result.is_ok() ? result.value : null
+  }
+
   public installFromJsonUrl(baseUrl: string): AsyncResult<{packageName: string; version: string; name: string}, Error> {
     return Res.try_async(async () => {
       const trimmed = baseUrl.replace(/\/$/, "")
@@ -534,6 +538,7 @@ class AppRegistry {
         for (const item of pkgDir.list()) {
           if (item instanceof Directory && item.name.startsWith("dev-")) {
             try {
+              storage.remove(releaseIdentityKey(packageName, item.name))
               item.delete()
             } catch (e) {
               console.warn(`APP_REGISTRY: failed to delete ${item.name}:`, e)
@@ -546,17 +551,12 @@ class AppRegistry {
     }
     storage.remove(`${packageName}_dev_url`)
     storage.remove(`${packageName}_dev_port`)
+    storage.remove(`${packageName}_dev_mdns`)
     storage.remove(`${packageName}_dev_last_reachable`)
-    // Drop the single dev slot's home-tile metadata + dev URL/port keys (all stored under
-    // DEV_APP_PACKAGE_NAME, not `packageName`). Dev miniapps load over HTTP and aren't on disk,
-    // so without this the projected tile would reappear on the next getInstalledMiniapps() refresh.
-    //
-    // Only do this when we're actually touching the dev slot: either the dev package itself, or the
-    // real manifest package currently occupying the slot. Otherwise a release install/uninstall of
-    // an UNRELATED package would wipe the active dev tile.
-    if (packageName === DEV_APP_PACKAGE_NAME || packageName === getDevAppSourcePackage()) {
-      unregisterDevApp()
-    }
+    // HTTP-direct dev miniapps are indexed by their real package name. A
+    // release install/uninstall of that same package should remove only its
+    // dev tile; unrelated dev miniapps must remain available.
+    if (readDevAppRecord(packageName)) unregisterDevApp(packageName)
   }
 
   /**
@@ -594,12 +594,16 @@ class AppRegistry {
         // Guard exists: a dev miniapp loads over HTTP and has no on-disk dir,
         // so an unconditional delete() would throw and abort the cleanup below.
         if (lmaDir.exists) lmaDir.delete()
+        storage.remove(releaseIdentityKey(packageName, version))
         console.log("APP_REGISTRY: Uninstalled mini app version", version)
         const packageDir = new Directory(Paths.document, "lmas", packageName)
         if (packageDir.exists && packageDir.list().length === 0) {
           packageDir.delete()
         }
       } else {
+        for (const installedVersion of this.getInstalledVersions(packageName)) {
+          storage.remove(releaseIdentityKey(packageName, installedVersion))
+        }
         const packageDir = new Directory(Paths.document, "lmas", packageName)
         if (packageDir.exists) {
           packageDir.delete()
@@ -698,25 +702,21 @@ class AppRegistry {
     return out
   }
 
-  /**
-   * Read the lmas/ tree and return one ClientApp per installed package,
-   * picking each package's active version. The store/host overlays runtime
-   * state (loading, hidden, compatibility) on top of these.
-   *
-   * `running` reflects MiniappHost mount state via miniappRunningRegistry.
-   */
   /**
    * Merge disk-derived apps with the projected dev + offline layers,
-   * de-duping by packageName. A real on-disk install (or offline app) wins
-   * over a dev tile of the same package — a dev record is just a launcher
-   * stub that an actual install supersedes.
+   * de-duping by packageName. An active dev registration wins over an older
+   * disk install of the same package; installing a release clears that dev
+   * registration in finalizeInstall. Native offline apps keep top priority.
    */
   private mergeProjectedApps(diskApps: ClientApp[]): ClientApp[] {
-    const seen = new Set(diskApps.map((a) => a.packageName))
     const offline = this.projectOfflineApps()
-    for (const a of offline) seen.add(a.packageName)
-    const dev = this.projectDevApps().filter((a) => !seen.has(a.packageName))
-    return [...diskApps, ...dev, ...offline]
+    const offlinePackages = new Set(offline.map((app) => app.packageName))
+    const dev = this.projectDevApps().filter((app) => !offlinePackages.has(app.packageName))
+    const devPackages = new Set(dev.map((app) => app.packageName))
+    const installed = diskApps.filter(
+      (app) => !offlinePackages.has(app.packageName) && !devPackages.has(app.packageName),
+    )
+    return [...installed, ...dev, ...offline]
   }
 
   public async getInstalledMiniapps(): Promise<ClientApp[]> {
@@ -742,7 +742,7 @@ class AppRegistry {
           permissions?: Array<string | {type: string; required?: boolean; description?: string}>
           hardwareRequirements?: Array<{type: string; level: string; description?: string}>
           type?: string
-          actions?: Array<{id?: unknown; description?: unknown; parameters?: unknown}>
+          actions?: Array<{id?: unknown; description?: unknown; parameters?: unknown; outputSchema?: unknown}>
         } | null
 
         const permissions = normalizeManifestPermissions(manifest?.permissions)
@@ -871,6 +871,22 @@ class AppRegistry {
     this.notify()
   }
 
+  /**
+   * Update whether a registered offline app is projected into launcher UIs.
+   *
+   * Offline apps are registered once at host startup, so settings-backed
+   * visibility changes need to update the projection without reinstalling or
+   * duplicating the app. No-op when the app is missing or already matches.
+   */
+  public setOfflineAppHidden(packageName: string, hidden: boolean): void {
+    const app = this.offlineApps.find((candidate) => candidate.packageName === packageName)
+    if (!app || app.hidden === hidden) return
+
+    app.hidden = hidden
+    this.refreshNeeded = true
+    this.notify()
+  }
+
   /**
    * Registered as needing the on-device STT model before it can start (the
    * host declares this per offline app; the apps store gates start() on it).
@@ -940,43 +956,30 @@ export interface DevAppRecord {
   iconUrl: string
   devUrl: string
   devPort?: number
+  /**
+   * Bonjour / mDNS hostname from the QR (`ComputerName.local`). Used as a
+   * failover host when the raw LAN IP in `devUrl` goes stale after a Wi-Fi
+   * change — phones that resolve `.local` can relaunch without re-scanning.
+   */
+  mdnsHost?: string
   type?: AppletType
   permissions?: Array<string | {type: string; required?: boolean; description?: string}>
   hardwareRequirements?: Array<{type: string; level: string; description?: string}>
   /** Manifest-declared actions — so dev-sideloaded miniapps can be invoked too. */
-  actions?: Array<{id?: unknown; description?: unknown; parameters?: unknown}>
-  /**
-   * The dev miniapp's real manifest package name. `packageName` is overwritten to
-   * {@link DEV_APP_PACKAGE_NAME} so the launch chain routes consistently, so this field
-   * preserves the original so install/uninstall of OTHER packages don't wipe the dev slot.
-   */
+  actions?: Array<{id?: unknown; description?: unknown; parameters?: unknown; outputSchema?: unknown}>
+  /** Legacy single-slot migration field. New records use the real packageName directly. */
   sourcePackageName?: string
   /**
    * Short-lived Core-verifiable proof emitted by `mentra dev`. This lets the
-   * single `com.dev` slot request auto-auth for the real package without
-   * letting arbitrary dev URLs claim any package name.
+   * dev runtime request auto-auth for the manifest package without letting
+   * arbitrary dev URLs claim any package name.
    */
   devAttestation?: string
 }
 
 const DEV_APPS_INDEX_KEY = "dev_apps_index"
+const DEV_APP_ICONS_DIR = "dev-miniapp-icons"
 
-function configuredDevHost(): string | undefined {
-  // Explicit escape hatch first; otherwise the host-injected Metro host (the
-  // address this dev bundle was served from — always current for the network
-  // the phone is on). Deliberately NOT the EXPO_PUBLIC_CLOUD_* URLs: those are
-  // cloud endpoints, a different machine entirely from the laptop running the
-  // miniapp dev server, and rewriting a dev URL to a cloud host would break it.
-  const explicit = process.env.EXPO_PUBLIC_LOCAL_MINIAPP_HOST
-  if (explicit) {
-    try {
-      return new URL(explicit).hostname
-    } catch {
-      if (/^[\w.-]+$/.test(explicit)) return explicit
-    }
-  }
-  return getConfigValues().devServerHost?.()
-}
 
 function isPrivateLanHost(hostname: string): boolean {
   return (
@@ -1008,72 +1011,173 @@ function normalizeDevAppRecord(record: DevAppRecord): DevAppRecord {
   return devUrl === record.devUrl && iconUrl === record.iconUrl ? record : {...record, devUrl, iconUrl}
 }
 
-/**
- * The one and only package name a dev miniapp is registered under.
- *
- * There is a SINGLE dev slot: scanning a new QR (or entering a new dev URL)
- * replaces the previous dev app rather than adding a second tile. Because the
- * whole launch chain — JSContext registration, UI-router binding,
- * setForeground, dev_url/dev_port storage keys, respawn-bg lookup — keys on
- * this package name, every consumer MUST use `DEV_APP_PACKAGE_NAME` (not the
- * manifest's real packageName) so messages route consistently. Mixing the two
- * was the cause of the "CONNECT_ACK timeout" — the tile said `com.dev` while
- * the dev URL/port and foreground target used the manifest name.
- */
+/** Legacy package used by builds that supported only one dev miniapp. */
 export const DEV_APP_PACKAGE_NAME = "com.dev"
 export const DEV_APP_NAME = "Dev"
 
 /**
- * Register (or replace) THE dev miniapp. Persists the home-tile metadata AND
- * the dev_url/dev_port keyed on {@link DEV_APP_PACKAGE_NAME}, so this function
- * is the single source of truth for the dev slot — callers must not write the
- * `*_dev_url` / `*_dev_port` keys under the manifest's real package name.
- *
- * Callers pass the manifest's REAL packageName/name. Only the packageName is
- * forced to {@link DEV_APP_PACKAGE_NAME} so the home tile and launch chain key
- * on the single dev slot (the real package survives in `sourcePackageName` for
- * clearDevArtifacts). The name + icon are kept as-is so the home tile reflects
- * the actual dev miniapp — marked as dev by the {@link DevMiniappBadge} dot
- * rather than renamed to a generic "Dev" tile.
+ * Copy a dev-server icon into Documents so the tile remains branded after the
+ * laptop/server disappears. A failed download is non-fatal: the remote URL is
+ * retained and can still render while the server is reachable.
  */
-export function registerDevApp(record: DevAppRecord): void {
+async function cacheDevAppIcon(packageName: string, iconUrl: string): Promise<string> {
+  if (!/^https?:\/\//.test(iconUrl)) return iconUrl
+
+  try {
+    const dir = new Directory(Paths.document, DEV_APP_ICONS_DIR)
+    if (!dir.exists) dir.create({intermediates: true})
+
+    const safePackageName = packageName.replace(/[^a-zA-Z0-9._-]/g, "_")
+    let extension = ".png"
+    try {
+      const match = new URL(iconUrl).pathname.match(/\.(png|jpe?g|webp|gif|svg)$/i)
+      if (match) extension = `.${match[1].toLowerCase()}`
+    } catch {
+      // Keep the decoder-friendly .png fallback; image loaders sniff content.
+    }
+
+    const target = new File(dir, `${safePackageName}${extension}`)
+    const downloaded = await File.downloadFileAsync(iconUrl, target, {idempotent: true})
+
+    // Only remove older extensions AFTER the replacement is safely on disk;
+    // a broken icon URL must not destroy the last known-good cached logo.
+    for (const item of dir.list()) {
+      if (item instanceof File && item.uri !== downloaded.uri && item.name.startsWith(`${safePackageName}.`)) {
+        try {
+          item.delete()
+        } catch {
+          // Best effort; the current icon has already been persisted.
+        }
+      }
+    }
+    return downloaded.uri
+  } catch (error) {
+    console.warn(`APP_REGISTRY: failed to cache dev icon for ${packageName}:`, error)
+    return readDevAppRecord(packageName)?.iconUrl ?? iconUrl
+  }
+}
+
+function removeDevRecordKeys(packageName: string): void {
+  const existing = readDevAppRecord(packageName)
+  if (existing?.iconUrl.startsWith("file://")) {
+    try {
+      const icon = new File(existing.iconUrl)
+      if (icon.exists) icon.delete()
+    } catch (error) {
+      console.warn(`APP_REGISTRY: failed to delete dev icon for ${packageName}:`, error)
+    }
+  }
+  storage.remove(`${packageName}_dev_meta`)
+  storage.remove(`${packageName}_dev_url`)
+  storage.remove(`${packageName}_dev_port`)
+  storage.remove(`${packageName}_dev_mdns`)
+  storage.remove(`${packageName}_dev_last_reachable`)
+}
+
+function readDevAppRecord(packageName: string): DevAppRecord | null {
+  const res = storage.load<string>(`${packageName}_dev_meta`)
+  if (!res.is_ok()) return null
+  try {
+    return JSON.parse(res.value) as DevAppRecord
+  } catch {
+    return null
+  }
+}
+
+/** Move the historical `com.dev` record onto its real manifest package key. */
+function migrateLegacyDevSlot(): void {
+  const legacy = readDevAppRecord(DEV_APP_PACKAGE_NAME)
+  const targetPackage = legacy?.sourcePackageName?.trim()
+  if (!legacy || !targetPackage || targetPackage === DEV_APP_PACKAGE_NAME) return
+
+  const existingTarget = readDevAppRecord(targetPackage)
+  const migrated: DevAppRecord = existingTarget ?? {
+    ...legacy,
+    packageName: targetPackage,
+    sourcePackageName: targetPackage,
+  }
+  if (!existingTarget) storage.save(`${targetPackage}_dev_meta`, JSON.stringify(migrated))
+
+  const legacyUrl = storage.load<string>(`${DEV_APP_PACKAGE_NAME}_dev_url`)
+  const targetUrl = storage.load<string>(`${targetPackage}_dev_url`)
+  if (!targetUrl.is_ok()) {
+    storage.save(`${targetPackage}_dev_url`, legacyUrl.is_ok() ? legacyUrl.value : migrated.devUrl)
+  }
+  const legacyPort = storage.load<number>(`${DEV_APP_PACKAGE_NAME}_dev_port`)
+  const targetPort = storage.load<number>(`${targetPackage}_dev_port`)
+  if (!targetPort.is_ok()) {
+    const port = migrated.devPort ?? (legacyPort.is_ok() ? legacyPort.value : undefined)
+    if (typeof port === "number" && Number.isFinite(port)) storage.save(`${targetPackage}_dev_port`, port)
+  }
+  const legacyMdns = storage.load<string>(`${DEV_APP_PACKAGE_NAME}_dev_mdns`)
+  const targetMdns = storage.load<string>(`${targetPackage}_dev_mdns`)
+  if (!targetMdns.is_ok() && legacyMdns.is_ok() && legacyMdns.value.trim()) {
+    storage.save(`${targetPackage}_dev_mdns`, legacyMdns.value.trim())
+  }
+
+  storage.remove(`${DEV_APP_PACKAGE_NAME}_dev_meta`)
+  storage.remove(`${DEV_APP_PACKAGE_NAME}_dev_url`)
+  storage.remove(`${DEV_APP_PACKAGE_NAME}_dev_port`)
+  storage.remove(`${DEV_APP_PACKAGE_NAME}_dev_mdns`)
+  storage.remove(`${DEV_APP_PACKAGE_NAME}_dev_last_reachable`)
+
+  const index = Array.from(new Set(getDevAppIndex().map((pkg) => (pkg === DEV_APP_PACKAGE_NAME ? targetPackage : pkg))))
+  storage.save(DEV_APPS_INDEX_KEY, JSON.stringify(index))
+}
+
+function readStoredMdnsHost(packageName: string): string | undefined {
+  const res = storage.load<string>(`${packageName}_dev_mdns`)
+  if (!res.is_ok()) return undefined
+  return res.value.trim() || undefined
+}
+
+/**
+ * Register or update one dev miniapp under its real manifest package. Different
+ * package names coexist; rescanning the same package updates that package only.
+ */
+export async function registerDevApp(record: DevAppRecord): Promise<void> {
+  migrateLegacyDevSlot()
+  const packageName = record.packageName.trim()
+  if (!packageName) throw new Error("Dev miniapp manifest is missing packageName")
+
+  const iconUrl = await cacheDevAppIcon(packageName, record.iconUrl)
+  // Relaunch paths (developer-URL screen, loadDevMiniapp) omit mdnsHost, so an
+  // omitted field keeps whatever the QR scan stored instead of wiping the
+  // `.local` failover host.
+  const mdnsHost =
+    record.mdnsHost !== undefined ? record.mdnsHost.trim() || undefined : readStoredMdnsHost(packageName)
   const devRecord: DevAppRecord = {
     ...record,
-    // Preserve the real manifest package before overwriting packageName with the
-    // single dev-slot name, so clearDevArtifacts can tell whether an install/uninstall
-    // actually targets the dev slot.
-    sourcePackageName: record.sourcePackageName ?? record.packageName,
-    packageName: DEV_APP_PACKAGE_NAME,
-    // Keep the manifest's real name + icon (display-only; routing keys on
-    // packageName). Fall back to DEV_APP_NAME only if a caller omitted the name.
+    packageName,
+    sourcePackageName: packageName,
     name: record.name || DEV_APP_NAME,
-    iconUrl: record.iconUrl,
+    iconUrl,
+    mdnsHost,
   }
-  storage.save(`${DEV_APP_PACKAGE_NAME}_dev_meta`, JSON.stringify(devRecord))
-  // The launch chain (LocalMiniappView.resolveDevPort, mentraJsBootstrap
-  // respawn-bg) reads these keys under DEV_APP_PACKAGE_NAME — persist them
-  // here so callers can't key them on the wrong (real) package name.
-  storage.save(`${DEV_APP_PACKAGE_NAME}_dev_url`, record.devUrl)
+  storage.save(`${packageName}_dev_meta`, JSON.stringify(devRecord))
+  storage.save(`${packageName}_dev_url`, record.devUrl)
   if (typeof record.devPort === "number" && Number.isFinite(record.devPort)) {
-    storage.save(`${DEV_APP_PACKAGE_NAME}_dev_port`, record.devPort)
+    storage.save(`${packageName}_dev_port`, record.devPort)
+  } else {
+    storage.remove(`${packageName}_dev_port`)
+  }
+  if (mdnsHost) {
+    storage.save(`${packageName}_dev_mdns`, mdnsHost)
   } else {
-    storage.remove(`${DEV_APP_PACKAGE_NAME}_dev_port`)
+    storage.remove(`${packageName}_dev_mdns`)
   }
   const idx = getDevAppIndex()
-  if (!idx.includes(DEV_APP_PACKAGE_NAME)) {
-    idx.push(DEV_APP_PACKAGE_NAME)
+  if (!idx.includes(packageName)) {
+    idx.push(packageName)
     storage.save(DEV_APPS_INDEX_KEY, JSON.stringify(idx))
   }
   appRegistry.markRefreshNeeded()
 }
 
-/** Drop the dev miniapp's home-tile metadata + dev URL/port keys. */
-export function unregisterDevApp(): void {
-  storage.remove(`${DEV_APP_PACKAGE_NAME}_dev_meta`)
-  storage.remove(`${DEV_APP_PACKAGE_NAME}_dev_url`)
-  storage.remove(`${DEV_APP_PACKAGE_NAME}_dev_port`)
-  storage.remove(`${DEV_APP_PACKAGE_NAME}_dev_last_reachable`)
-  const idx = getDevAppIndex().filter((p) => p !== DEV_APP_PACKAGE_NAME)
+/** Drop one dev miniapp's metadata, routing keys, and cached icon. */
+export function unregisterDevApp(packageName = DEV_APP_PACKAGE_NAME): void {
+  removeDevRecordKeys(packageName)
+  const idx = getDevAppIndex().filter((p) => p !== packageName)
   storage.save(DEV_APPS_INDEX_KEY, JSON.stringify(idx))
   appRegistry.markRefreshNeeded()
 }
@@ -1089,33 +1193,20 @@ function getDevAppIndex(): string[] {
   }
 }
 
-/**
- * The real manifest package name currently occupying the dev slot, or null if no dev app is
- * registered. Used to decide whether clearing a package's artifacts should also drop the dev slot.
- */
-export function getDevAppSourcePackage(): string | null {
-  const res = storage.load<string>(`${DEV_APP_PACKAGE_NAME}_dev_meta`)
-  if (!res.is_ok()) return null
-  try {
-    const rec = JSON.parse(res.value) as DevAppRecord
-    return rec.sourcePackageName ?? null
-  } catch {
-    return null
-  }
+/** Resolve the manifest package for a dev runtime (including the legacy slot). */
+export function getDevAppSourcePackage(packageName = DEV_APP_PACKAGE_NAME): string | null {
+  migrateLegacyDevSlot()
+  const rec = readDevAppRecord(packageName)
+  return rec?.sourcePackageName ?? rec?.packageName ?? null
 }
 
-export function getDevAppAttestation(): string | null {
-  const res = storage.load<string>(`${DEV_APP_PACKAGE_NAME}_dev_meta`)
-  if (!res.is_ok()) return null
-  try {
-    const rec = JSON.parse(res.value) as DevAppRecord
-    return rec.devAttestation ?? null
-  } catch {
-    return null
-  }
+export function getDevAppAttestation(packageName = DEV_APP_PACKAGE_NAME): string | null {
+  migrateLegacyDevSlot()
+  return readDevAppRecord(packageName)?.devAttestation ?? null
 }
 
 export function getDevAppRecords(): DevAppRecord[] {
+  migrateLegacyDevSlot()
   const out: DevAppRecord[] = []
   for (const pkg of getDevAppIndex()) {
     const res = storage.load<string>(`${pkg}_dev_meta`)