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

package/build/services/AppRegistry.js

@@ -21,11 +21,13 @@ import { unzip } from "react-native-zip-archive";
 import semver from "semver";
 import { result as Res } from "typesafe-ts";
 import { 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 = new Set([
     "MICROPHONE",
     "CAMERA",
@@ -66,29 +68,6 @@ export function normalizeManifestPermissions(raw) {
 function normalizeManifestType(raw) {
     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) {
-    if (!Array.isArray(raw))
-        return [];
-    const out = [];
-    for (const a of raw) {
-        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 }
-                    : {}),
-            });
-        }
-    }
-    return out;
-}
 /**
  * Convert declared hardwareRequirements from a miniapp.json manifest into
  * runtime `HardwareRequirement[]`, always appending `{EXIST, REQUIRED}` so
@@ -132,6 +111,9 @@ export function buildHardwareRequirements(raw, packageName) {
     out.push({ type: HardwareType.EXIST, level: HardwareRequirementLevel.REQUIRED });
     return out;
 }
+function releaseIdentityKey(packageName, version) {
+    return `miniapp_release_identity:${packageName}:${version}`;
+}
 /**
  * Download a miniapp zip from `url` into the cache and return its local path.
  *
@@ -408,7 +390,7 @@ class AppRegistry {
         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" });
         });
     }
     /**
@@ -422,7 +404,7 @@ class AppRegistry {
         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 };
         });
     }
@@ -431,7 +413,7 @@ class AppRegistry {
      * artifacts on release installs, point the active-version at the just-
      * installed bundle, and notify subscribers to refresh.
      */
-    finalizeInstall(packageName, version) {
+    finalizeInstall(packageName, version, releaseIdentity) {
         // 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
@@ -442,9 +424,14 @@ class AppRegistry {
             this.clearDevArtifacts(packageName);
         }
         this.setActiveVersion(packageName, version);
+        storage.save(releaseIdentityKey(packageName, version), releaseIdentity);
         this.refreshNeeded = true;
         this.notify();
     }
+    getReleaseIdentity(packageName, version) {
+        const result = storage.load(releaseIdentityKey(packageName, version));
+        return result.is_ok() ? result.value : null;
+    }
     installFromJsonUrl(baseUrl) {
         return Res.try_async(async () => {
             const trimmed = baseUrl.replace(/\/$/, "");
@@ -479,6 +466,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) {
@@ -493,17 +481,13 @@ 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);
     }
     /**
      * Garbage-collect older `dev-*` version directories for this package,
@@ -544,6 +528,7 @@ class AppRegistry {
                 // 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) {
@@ -551,6 +536,9 @@ class AppRegistry {
                 }
             }
             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();
@@ -646,26 +634,19 @@ 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.
      */
     mergeProjectedApps(diskApps) {
-        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];
     }
     async getInstalledMiniapps() {
         if (!this.refreshNeeded && this.cachedApps.length > 0) {
@@ -799,6 +780,21 @@ class AppRegistry {
         this.refreshNeeded = true;
         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.
+     */
+    setOfflineAppHidden(packageName, hidden) {
+        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).
@@ -849,24 +845,7 @@ export function getLocalAppScreenshot(packageName) {
     return uri;
 }
 const DEV_APPS_INDEX_KEY = "dev_apps_index";
-function configuredDevHost() {
-    // 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?.();
-}
+const DEV_APP_ICONS_DIR = "dev-miniapp-icons";
 function isPrivateLanHost(hostname) {
     return (hostname === "localhost" ||
         hostname.startsWith("192.168.") ||
@@ -895,71 +874,173 @@ function normalizeDevAppRecord(record) {
     const iconUrl = rewriteStaleDevUrl(record.iconUrl);
     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.
+ */
+async function cacheDevAppIcon(packageName, iconUrl) {
+    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) {
+    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) {
+    const res = storage.load(`${packageName}_dev_meta`);
+    if (!res.is_ok())
+        return null;
+    try {
+        return JSON.parse(res.value);
+    }
+    catch {
+        return null;
+    }
+}
+/** Move the historical `com.dev` record onto its real manifest package key. */
+function migrateLegacyDevSlot() {
+    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 = existingTarget ?? {
+        ...legacy,
+        packageName: targetPackage,
+        sourcePackageName: targetPackage,
+    };
+    if (!existingTarget)
+        storage.save(`${targetPackage}_dev_meta`, JSON.stringify(migrated));
+    const legacyUrl = storage.load(`${DEV_APP_PACKAGE_NAME}_dev_url`);
+    const targetUrl = storage.load(`${targetPackage}_dev_url`);
+    if (!targetUrl.is_ok()) {
+        storage.save(`${targetPackage}_dev_url`, legacyUrl.is_ok() ? legacyUrl.value : migrated.devUrl);
+    }
+    const legacyPort = storage.load(`${DEV_APP_PACKAGE_NAME}_dev_port`);
+    const targetPort = storage.load(`${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(`${DEV_APP_PACKAGE_NAME}_dev_mdns`);
+    const targetMdns = storage.load(`${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) {
+    const res = storage.load(`${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 function registerDevApp(record) {
+export async function registerDevApp(record) {
+    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 = {
         ...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(`${DEV_APP_PACKAGE_NAME}_dev_port`);
+        storage.remove(`${packageName}_dev_port`);
+    }
+    if (mdnsHost) {
+        storage.save(`${packageName}_dev_mdns`, mdnsHost);
+    }
+    else {
+        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() {
-    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) {
+    removeDevRecordKeys(packageName);
+    const idx = getDevAppIndex().filter((p) => p !== packageName);
     storage.save(DEV_APPS_INDEX_KEY, JSON.stringify(idx));
     appRegistry.markRefreshNeeded();
 }
@@ -975,35 +1056,18 @@ function getDevAppIndex() {
         return [];
     }
 }
-/**
- * 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() {
-    const res = storage.load(`${DEV_APP_PACKAGE_NAME}_dev_meta`);
-    if (!res.is_ok())
-        return null;
-    try {
-        const rec = JSON.parse(res.value);
-        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) {
+    migrateLegacyDevSlot();
+    const rec = readDevAppRecord(packageName);
+    return rec?.sourcePackageName ?? rec?.packageName ?? null;
 }
-export function getDevAppAttestation() {
-    const res = storage.load(`${DEV_APP_PACKAGE_NAME}_dev_meta`);
-    if (!res.is_ok())
-        return null;
-    try {
-        const rec = JSON.parse(res.value);
-        return rec.devAttestation ?? null;
-    }
-    catch {
-        return null;
-    }
+export function getDevAppAttestation(packageName = DEV_APP_PACKAGE_NAME) {
+    migrateLegacyDevSlot();
+    return readDevAppRecord(packageName)?.devAttestation ?? null;
 }
 export function getDevAppRecords() {
+    migrateLegacyDevSlot();
     const out = [];
     for (const pkg of getDevAppIndex()) {
         const res = storage.load(`${pkg}_dev_meta`);