@mentra/engine 0.1.0-beta.0

package/build/services/MiniappEngine.js

@@ -0,0 +1,119 @@
+/**
+ * MiniappEngine — constructs the MentraJS router singletons (crash controller,
+ * UI router, JS router), binds them to the native Crust module + the launcher,
+ * wires the dev-server background-respawn signal, and starts the message pump.
+ *
+ * Engine owns this so a bare OEM's `engine.start()` brings up the local-miniapp
+ * engine with no host construction step. Host-only concerns that remain outside
+ * engine, such as Mentra-app crashloop telemetry, are attached by the host after
+ * this returns via `router.onCrashloop` / `router.onRestartToast`.
+ *
+ * Idempotent — `ensureMiniappEngine()` returns the same singletons on every call,
+ * so it's safe to call from both `engine.start()` and the host bootstrap.
+ */
+import CrustModule from "@mentra/crust";
+import devServerBridge from "./DevServerBridge";
+import localMiniappRuntime from "./LocalMiniappRuntime";
+import { miniappLauncher } from "./MiniappLauncher";
+import { MentraJSCrashController } from "./MentraJSCrashController";
+import { MentraJSRouter } from "./MentraJSRouter";
+import { MentraUIRouter } from "./MentraUIRouter";
+let engine = null;
+function wireDevServerRespawnBackground(router, uiRouter) {
+    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(`MentraJS: 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(`MentraJS: respawn-bg failed for ${packageName}`);
+                return;
+            }
+            // The respawned JSContext is a fresh MiniappSession with ui.bound false.
+            // The mounted WebView won't re-fire mentra.ready() (it's latched), so
+            // re-announce it so RPC replies (mentra.request) reach the UI again
+            // instead of being dropped while unbound.
+            uiRouter.notifyReopen(packageName);
+        }
+        catch (e) {
+            console.warn(`MentraJS: respawn-bg threw for ${packageName}:`, e);
+        }
+    });
+}
+/**
+ * Construct (once) and return the MentraJS engine singletons. Starts the router's
+ * message pump on first call. Subsequent calls return the same instances.
+ */
+export function ensureMiniappEngine() {
+    if (engine) {
+        wireDevServerRespawnBackground(engine.router, engine.uiRouter);
+        engine.router.start();
+        return engine;
+    }
+    // The Crust native module's published TS typing doesn't include the new
+    // mentraJs* functions until expo prebuild regenerates it; cast to the binding
+    // shapes the routers expect.
+    const crust = CrustModule;
+    const crashController = new MentraJSCrashController({
+        maxRetries: 3,
+    });
+    const uiRouter = new MentraUIRouter({
+        mentraJsDispatchToJs: (packageName, envelope) => CrustModule.mentraJsDispatchToJs(packageName, envelope),
+    });
+    const router = new MentraJSRouter(localMiniappRuntime, crust);
+    router.crashController = crashController;
+    router.uiRouter = uiRouter;
+    // Hand the router to the engine MiniappLauncher so headless launch/teardown
+    // (apps.ts start/stop, the action broker, the WebView mount path) all spawn
+    // through one place.
+    miniappLauncher.configure({ router });
+    // Wire up the dev server's "respawn-bg" signal so a touch under
+    // src/background/ kills + re-spawns the JSContext with the latest bundle.
+    // The WebView reload path stays separate (devServerBridge.onReload).
+    wireDevServerRespawnBackground(router, uiRouter);
+    router.start();
+    engine = { router, uiRouter, crashController };
+    return engine;
+}
+/** Stop the MentraJS message pump and tear down router-managed JSContexts. */
+export async function stopMiniappEngine() {
+    const current = engine;
+    if (!current)
+        return;
+    // Null the singleton BEFORE the async teardown below: a concurrent
+    // ensureMiniappEngine() must construct fresh instead of re-starting (and
+    // re-subscribing) the router that is mid-teardown, which would leak a zombie
+    // Crust subscription once this function finishes.
+    engine = null;
+    devServerBridge.clearRespawnBackgroundHandler();
+    current.router.stop();
+    const packages = current.router.registeredPackages();
+    await Promise.all(packages.map(async (packageName) => {
+        try {
+            await current.router.unregister(packageName);
+        }
+        catch (err) {
+            console.warn(`MentraJS: failed to unregister ${packageName} during stop:`, err);
+        }
+    }));
+}
+/** Returns the engine singletons if already constructed, else null. */
+export function getMiniappEngine() {
+    return engine;
+}
+//# sourceMappingURL=MiniappEngine.js.map

package/build/services/MiniappEngine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MiniappEngine.js","sourceRoot":"","sources":["../../src/services/MiniappEngine.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * MiniappEngine — constructs the MentraJS router singletons (crash controller,\n * UI router, JS router), binds them to the native Crust module + the launcher,\n * wires the dev-server background-respawn signal, and starts the message pump.\n *\n * Engine owns this so a bare OEM's `engine.start()` brings up the local-miniapp\n * engine with no host construction step. Host-only concerns that remain outside\n * engine, such as Mentra-app crashloop telemetry, are attached by the host after\n * this returns via `router.onCrashloop` / `router.onRestartToast`.\n *\n * Idempotent — `ensureMiniappEngine()` returns the same singletons on every call,\n * so it's safe to call from both `engine.start()` and the host bootstrap.\n */\n\nimport CrustModule from \"@mentra/crust\"\n\nimport devServerBridge from \"./DevServerBridge\"\nimport localMiniappRuntime from \"./LocalMiniappRuntime\"\nimport {miniappLauncher} from \"./MiniappLauncher\"\nimport {MentraJSCrashController} from \"./MentraJSCrashController\"\nimport {MentraJSRouter, type MentraJSCrustBinding} from \"./MentraJSRouter\"\nimport {MentraUIRouter} from \"./MentraUIRouter\"\n\nexport interface MiniappEngine {\n  router: MentraJSRouter\n  uiRouter: MentraUIRouter\n  crashController: MentraJSCrashController\n}\n\nlet engine: MiniappEngine | null = null\n\nfunction wireDevServerRespawnBackground(router: MentraJSRouter, uiRouter: MentraUIRouter): void {\n  devServerBridge.onRespawnBackground(async (packageName) => {\n    try {\n      // Re-resolve the freshly built bundle (dev: HTTP off the dev server;\n      // released: file:// snapshot) via the launcher's shared recipe. Carries\n      // the declared permissions + manifest across the respawn — omitting them\n      // would respawn the JSContext with no permissions, so SUBSCRIBE gates and\n      // per-call dispatch checks would start rejecting after a background\n      // hot-reload.\n      const resolved = await miniappLauncher.resolveBundle(packageName)\n      if (!resolved) {\n        console.warn(`MentraJS: respawn-bg could not resolve bundle for ${packageName}`)\n        return\n      }\n      // Force a respawn (kill + spawn) rather than launcher.ensureRunning,\n      // which is idempotent and would no-op an already-registered context.\n      await router.unregister(packageName)\n      const ok = await router.spawnAndRegister(packageName, resolved.bgSource, {\n        permissions: resolved.declaredPermissions,\n        installedManifest: resolved.installedManifest,\n      })\n      if (!ok) {\n        console.warn(`MentraJS: respawn-bg failed for ${packageName}`)\n        return\n      }\n      // The respawned JSContext is a fresh MiniappSession with ui.bound false.\n      // The mounted WebView won't re-fire mentra.ready() (it's latched), so\n      // re-announce it so RPC replies (mentra.request) reach the UI again\n      // instead of being dropped while unbound.\n      uiRouter.notifyReopen(packageName)\n    } catch (e) {\n      console.warn(`MentraJS: respawn-bg threw for ${packageName}:`, e)\n    }\n  })\n}\n\n/**\n * Construct (once) and return the MentraJS engine singletons. Starts the router's\n * message pump on first call. Subsequent calls return the same instances.\n */\nexport function ensureMiniappEngine(): MiniappEngine {\n  if (engine) {\n    wireDevServerRespawnBackground(engine.router, engine.uiRouter)\n    engine.router.start()\n    return engine\n  }\n\n  // The Crust native module's published TS typing doesn't include the new\n  // mentraJs* functions until expo prebuild regenerates it; cast to the binding\n  // shapes the routers expect.\n  const crust = CrustModule as unknown as MentraJSCrustBinding\n\n  const crashController = new MentraJSCrashController({\n    maxRetries: 3,\n  })\n  const uiRouter = new MentraUIRouter({\n    mentraJsDispatchToJs: (packageName: string, envelope: Record<string, unknown>) =>\n      (\n        CrustModule as unknown as {\n          mentraJsDispatchToJs: (p: string, e: Record<string, unknown>) => Promise<void>\n        }\n      ).mentraJsDispatchToJs(packageName, envelope),\n  })\n  const router = new MentraJSRouter(localMiniappRuntime, crust)\n  router.crashController = crashController\n  router.uiRouter = uiRouter\n\n  // Hand the router to the engine MiniappLauncher so headless launch/teardown\n  // (apps.ts start/stop, the action broker, the WebView mount path) all spawn\n  // through one place.\n  miniappLauncher.configure({router})\n\n  // Wire up the dev server's \"respawn-bg\" signal so a touch under\n  // src/background/ kills + re-spawns the JSContext with the latest bundle.\n  // The WebView reload path stays separate (devServerBridge.onReload).\n  wireDevServerRespawnBackground(router, uiRouter)\n\n  router.start()\n\n  engine = {router, uiRouter, crashController}\n  return engine\n}\n\n/** Stop the MentraJS message pump and tear down router-managed JSContexts. */\nexport async function stopMiniappEngine(): Promise<void> {\n  const current = engine\n  if (!current) return\n  // Null the singleton BEFORE the async teardown below: a concurrent\n  // ensureMiniappEngine() must construct fresh instead of re-starting (and\n  // re-subscribing) the router that is mid-teardown, which would leak a zombie\n  // Crust subscription once this function finishes.\n  engine = null\n\n  devServerBridge.clearRespawnBackgroundHandler()\n  current.router.stop()\n\n  const packages = current.router.registeredPackages()\n  await Promise.all(\n    packages.map(async (packageName) => {\n      try {\n        await current.router.unregister(packageName)\n      } catch (err) {\n        console.warn(`MentraJS: failed to unregister ${packageName} during stop:`, err)\n      }\n    }),\n  )\n}\n\n/** Returns the engine singletons if already constructed, else null. */\nexport function getMiniappEngine(): MiniappEngine | null {\n  return engine\n}\n"]}

package/build/services/MiniappLauncher.d.ts

@@ -0,0 +1,129 @@
+/**
+ * MiniappLauncher — headless launch/teardown of a local miniapp's background
+ * JS context.
+ *
+ * This is the one piece of "run a miniapp" that used to live inside the
+ * `LocalMiniappView` React component (resolve the bundle → read the manifest →
+ * `spawnAndRegister`), triggered only when the Compositor mounted that
+ * component on foreground. Pulling it into the runtime means:
+ *
+ *   - `start()` can actually spawn an app even when nothing foregrounds it
+ *     (e.g. a system app launching another miniapp via `session.miniapps`).
+ *   - the action broker can wake a stopped target headlessly — no UI at all.
+ *   - the dev hot-reload respawn path and the WebView mount path share one
+ *     resolve+spawn recipe instead of three copies.
+ *
+ * The launcher is **headless**: no React, no RN components. The engine-owned
+ * MiniappEngine hands it the {@link MentraJSRouter} instance once during
+ * engine construction. OEMs embedding the runtime drive miniapp lifecycle
+ * through the engine facade and stores, not a separate launcher configure API.
+ *
+ * Boundary: the launcher owns the **background** context. WebView *rendering*
+ * (the UI layer) stays with the host — the launcher just hands back the
+ * resolved UI entry so the host can mount its `<WebView>`.
+ */
+import { type InstalledMiniappManifest } from "./LocalMiniappRuntime";
+import type { MentraJSRouter } from "./MentraJSRouter";
+interface LauncherDeps {
+    /** The host-constructed router (needs the native Crust binding). */
+    router: MentraJSRouter;
+}
+/** Hints the host may pass from a view's props to avoid re-deriving them. */
+export interface LaunchHints {
+    devUrl?: string;
+    version?: string;
+    devPort?: string;
+}
+/** Everything the launcher resolved for a package — bg source + UI entry. */
+export interface ResolvedBundle {
+    bgSource: string;
+    uiUri: string | null;
+    uiBaseDir: string | null;
+    declaredPermissions: string[];
+    installedManifest?: InstalledMiniappManifest;
+    /** Set for dev miniapps (HTTP off the dev server); null for released. */
+    devUrl: string | null;
+    devPort: number | null;
+}
+/** What the host needs back to render the UI layer. */
+export interface LaunchResult {
+    uiUri: string | null;
+    uiBaseDir: string | null;
+}
+declare class MiniappLauncher {
+    private deps;
+    /**
+     * In-flight launches keyed by packageName. Both apps.ts start() and the
+     * WebView mount call ensureRunning() before the first spawnAndRegister
+     * resolves — without this, neither sees the package in registeredPackages()
+     * yet and both spawn the same context (a clobber/double-spawn). Concurrent
+     * callers share the same promise.
+     */
+    private readonly inFlight;
+    /** Wire the router in. Called once from MiniappEngine construction. */
+    configure(deps: LauncherDeps): void;
+    private requireRouter;
+    /** True iff the package's background JS context is currently spawned. */
+    isRunning(packageName: string): boolean;
+    /**
+     * Resolve the background JS source + UI entry + declared permissions for a
+     * package. Handles both dev (HTTP off the running dev server) and released
+     * (file:// from the installed snapshot). Reads disk/network/storage; does
+     * NOT spawn. Returns null when the bundle can't be resolved (dev server
+     * unreachable, missing entry, no installed version).
+     */
+    resolveBundle(packageName: string, hints?: LaunchHints): Promise<ResolvedBundle | null>;
+    /**
+     * Ensure a miniapp's background JS context is spawned. Idempotent — if the
+     * context is already alive this is a no-op spawn-wise (it still resolves the
+     * UI entry so a re-mounting host gets its `<WebView>` source back).
+     *
+     * Resolves once the context is SPAWNED. It does NOT block on the context's
+     * CONNECT handshake — the host's WebView mount shouldn't wait on background
+     * JS. Callers that need the context to be connected and ready to receive
+     * messages (the action broker) follow up with
+     * {@link LocalMiniappRuntime.waitForConnect}.
+     */
+    ensureRunning(packageName: string, hints?: LaunchHints): Promise<LaunchResult>;
+    /** Resolve the bundle and spawn the context. Serialized via {@link inFlight}. */
+    private spawn;
+    /**
+     * Re-spawn local miniapps that were running when the app was last killed.
+     *
+     * Cloud apps run on a remote server: the cloud persists which ones are
+     * running and resurrects them when the phone reconnects, so a host-app
+     * restart brings them back on its own. Local (phone-hosted) miniapps run in
+     * the phone's own JS engine — a host-process kill tears down their JSContext
+     * and there is no server to resurrect them, so without this they silently
+     * stay stopped on the next launch even though the user left them running.
+     *
+     * Each local miniapp persists its running flag to disk on start/stop
+     * (`saveLocalAppRunningState`, via the applet's `onStart`/`onStop`). We read
+     * those flags back and re-spawn the background context headlessly (no
+     * foreground, no navigation) — the spawn registers the package so the home
+     * tray/switcher project it as running, exactly as a normal start would. The
+     * WebView, if any, re-attaches lazily when the user opens the app.
+     *
+     * Idempotent and best-effort: skips already-spawned contexts, and clears the
+     * persisted flag for any app whose bundle can no longer be resolved
+     * (uninstalled, or dev server gone) so a dead entry doesn't retry every boot.
+     * Not compatibility-gated: a previously-running background app shouldn't be
+     * dropped just because glasses are momentarily disconnected at boot — it
+     * resumes when they reconnect, same as mid-session.
+     */
+    autostartLocalMiniapps(): Promise<void>;
+    /**
+     * Ensure the context is running AND has completed its CONNECT handshake.
+     * Used by the action broker, which must not deliver to a context that hasn't
+     * come up yet. Throws on spawn failure or connect timeout.
+     */
+    ensureConnected(packageName: string, connectTimeoutMs?: number, hints?: LaunchHints): Promise<void>;
+    /** Tear down a miniapp's background JS context. */
+    stop(packageName: string): Promise<void>;
+    private storedDevUrl;
+    /** resolveDevPort — moved verbatim from the old LocalMiniappView helper. */
+    private resolveDevPort;
+}
+export declare const miniappLauncher: MiniappLauncher;
+export {};
+//# sourceMappingURL=MiniappLauncher.d.ts.map

package/build/services/MiniappLauncher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MiniappLauncher.d.ts","sourceRoot":"","sources":["../../src/services/MiniappLauncher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAQH,OAA4B,EAAC,KAAK,wBAAwB,EAAC,MAAM,uBAAuB,CAAA;AACxF,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,kBAAkB,CAAA;AAEpD,UAAU,YAAY;IACpB,oEAAoE;IACpE,MAAM,EAAE,cAAc,CAAA;CACvB;AAED,6EAA6E;AAC7E,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,6EAA6E;AAC7E,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,mBAAmB,EAAE,MAAM,EAAE,CAAA;IAC7B,iBAAiB,CAAC,EAAE,wBAAwB,CAAA;IAC5C,yEAAyE;IACzE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB;AAED,uDAAuD;AACvD,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CACzB;AAED,cAAM,eAAe;IACnB,OAAO,CAAC,IAAI,CAA4B;IAExC;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA2C;IAEpE,uEAAuE;IACvE,SAAS,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI;IAInC,OAAO,CAAC,aAAa;IAOrB,yEAAyE;IACzE,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO;IAIvC;;;;;;OAMG;IACG,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAmF7F;;;;;;;;;;OAUG;IACG,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;IAwBpF,iFAAiF;YACnE,KAAK;IAiCnB;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;IAkB7C;;;;OAIG;IACG,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,gBAAgB,SAAS,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAKzG,mDAAmD;IAC7C,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiB9C,OAAO,CAAC,YAAY;IAKpB,4EAA4E;IAC5E,OAAO,CAAC,cAAc;CASvB;AAED,eAAO,MAAM,eAAe,iBAAwB,CAAA"}

package/build/services/MiniappLauncher.js

@@ -0,0 +1,291 @@
+/**
+ * MiniappLauncher — headless launch/teardown of a local miniapp's background
+ * JS context.
+ *
+ * This is the one piece of "run a miniapp" that used to live inside the
+ * `LocalMiniappView` React component (resolve the bundle → read the manifest →
+ * `spawnAndRegister`), triggered only when the Compositor mounted that
+ * component on foreground. Pulling it into the runtime means:
+ *
+ *   - `start()` can actually spawn an app even when nothing foregrounds it
+ *     (e.g. a system app launching another miniapp via `session.miniapps`).
+ *   - the action broker can wake a stopped target headlessly — no UI at all.
+ *   - the dev hot-reload respawn path and the WebView mount path share one
+ *     resolve+spawn recipe instead of three copies.
+ *
+ * The launcher is **headless**: no React, no RN components. The engine-owned
+ * MiniappEngine hands it the {@link MentraJSRouter} instance once during
+ * engine construction. OEMs embedding the runtime drive miniapp lifecycle
+ * through the engine facade and stores, not a separate launcher configure API.
+ *
+ * Boundary: the launcher owns the **background** context. WebView *rendering*
+ * (the UI layer) stays with the host — the launcher just hands back the
+ * resolved UI entry so the host can mount its `<WebView>`.
+ */
+import { File } from "expo-file-system";
+import { decideDevLaunchRoute } from "../utils/devMiniappLaunch";
+import { storage } from "../utils/storage/storage";
+import appRegistry, { getLocalAppRunningState, saveLocalAppRunningState } from "./AppRegistry";
+import devServerBridge from "./DevServerBridge";
+import localMiniappRuntime from "./LocalMiniappRuntime";
+class MiniappLauncher {
+    deps = null;
+    /**
+     * In-flight launches keyed by packageName. Both apps.ts start() and the
+     * WebView mount call ensureRunning() before the first spawnAndRegister
+     * resolves — without this, neither sees the package in registeredPackages()
+     * yet and both spawn the same context (a clobber/double-spawn). Concurrent
+     * callers share the same promise.
+     */
+    inFlight = new Map();
+    /** Wire the router in. Called once from MiniappEngine construction. */
+    configure(deps) {
+        this.deps = deps;
+    }
+    requireRouter() {
+        if (!this.deps) {
+            throw new Error("MiniappLauncher not configured — ensureMiniappEngine() has not run");
+        }
+        return this.deps.router;
+    }
+    /** True iff the package's background JS context is currently spawned. */
+    isRunning(packageName) {
+        return this.deps?.router.registeredPackages().includes(packageName) ?? false;
+    }
+    /**
+     * Resolve the background JS source + UI entry + declared permissions for a
+     * package. Handles both dev (HTTP off the running dev server) and released
+     * (file:// from the installed snapshot). Reads disk/network/storage; does
+     * NOT spawn. Returns null when the bundle can't be resolved (dev server
+     * unreachable, missing entry, no installed version).
+     */
+    async resolveBundle(packageName, hints) {
+        const devUrl = hints?.devUrl ?? this.storedDevUrl(packageName);
+        // --- Dev: load directly off the local dev server over HTTP. ---
+        if (devUrl) {
+            const route = await decideDevLaunchRoute(packageName, devUrl);
+            if (route.decision === "offline" || !route.manifest)
+                return null;
+            const manifest = route.manifest;
+            const entry = manifest.entry;
+            if (!entry?.background)
+                return null;
+            const base = devUrl.replace(/\/$/, "");
+            // entry.* are bundle-root paths (dist/ stripped); the dev server serves
+            // files relative to cwd, so prepend dist/.
+            const bgUrl = `${base}/dist/${entry.background.replace(/^\.?\/+/, "")}`;
+            const uiUri = entry.ui ? `${base}/dist/${entry.ui.replace(/^\.?\/+/, "")}` : null;
+            const perms = manifest.permissions;
+            const declaredPermissions = (perms ?? [])
+                .map((p) => (typeof p === "string" ? p : p?.type))
+                .filter((t) => typeof t === "string");
+            const installedManifest = {
+                name: manifest.name,
+                permissions: manifest.permissions,
+                hardwareRequirements: manifest.hardwareRequirements,
+            };
+            let bgSource;
+            try {
+                const res = await fetch(bgUrl);
+                if (!res.ok)
+                    return null;
+                bgSource = await res.text();
+            }
+            catch {
+                return null;
+            }
+            return {
+                bgSource,
+                uiUri,
+                uiBaseDir: uiUri ? uiUri.replace(/\/[^/]+$/, "/") : null,
+                declaredPermissions,
+                installedManifest,
+                devUrl,
+                devPort: this.resolveDevPort(hints?.devPort, packageName),
+            };
+        }
+        // --- Released: resolve from the installed file:// snapshot. ---
+        const version = hints?.version ?? (await appRegistry.getActiveVersion(packageName));
+        if (!version)
+            return null;
+        const entryPaths = appRegistry.getMiniappEntryPaths(packageName, version);
+        if (!entryPaths?.background)
+            return null;
+        const manifest = appRegistry.getMiniappManifest(packageName, version);
+        const declaredPermissions = (manifest?.permissions ?? [])
+            .map((p) => p.type)
+            .filter((t) => typeof t === "string");
+        const installedManifest = manifest
+            ? { name: manifest.name, permissions: manifest.permissions, hardwareRequirements: manifest.hardwareRequirements }
+            : undefined;
+        let bgSource;
+        try {
+            bgSource = new File(entryPaths.background).textSync();
+        }
+        catch {
+            return null;
+        }
+        return {
+            bgSource,
+            uiUri: entryPaths.ui ?? null,
+            uiBaseDir: entryPaths.ui ? entryPaths.ui.replace(/\/[^/]+$/, "/") : null,
+            declaredPermissions,
+            installedManifest,
+            devUrl: null,
+            devPort: null,
+        };
+    }
+    /**
+     * Ensure a miniapp's background JS context is spawned. Idempotent — if the
+     * context is already alive this is a no-op spawn-wise (it still resolves the
+     * UI entry so a re-mounting host gets its `<WebView>` source back).
+     *
+     * Resolves once the context is SPAWNED. It does NOT block on the context's
+     * CONNECT handshake — the host's WebView mount shouldn't wait on background
+     * JS. Callers that need the context to be connected and ready to receive
+     * messages (the action broker) follow up with
+     * {@link LocalMiniappRuntime.waitForConnect}.
+     */
+    async ensureRunning(packageName, hints) {
+        const router = this.requireRouter();
+        // 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
+        // the dev server has since dropped.
+        if (router.registeredPackages().includes(packageName)) {
+            const existing = await this.resolveBundle(packageName, hints).catch(() => null);
+            return { uiUri: existing?.uiUri ?? null, uiBaseDir: existing?.uiBaseDir ?? null };
+        }
+        // Coalesce concurrent launches of the same package onto one promise.
+        const pending = this.inFlight.get(packageName);
+        if (pending)
+            return pending;
+        const launch = this.spawn(packageName, hints);
+        this.inFlight.set(packageName, launch);
+        try {
+            return await launch;
+        }
+        finally {
+            this.inFlight.delete(packageName);
+        }
+    }
+    /** Resolve the bundle and spawn the context. Serialized via {@link inFlight}. */
+    async spawn(packageName, hints) {
+        const router = this.requireRouter();
+        const resolved = await this.resolveBundle(packageName, hints);
+        if (!resolved) {
+            throw new Error(`MiniappLauncher: cannot resolve bundle for ${packageName}`);
+        }
+        // Re-check after the async resolve: a different path may have spawned it
+        // while we were fetching/reading the bundle.
+        if (!router.registeredPackages().includes(packageName)) {
+            const ok = await router.spawnAndRegister(packageName, resolved.bgSource, {
+                permissions: resolved.declaredPermissions,
+                installedManifest: resolved.installedManifest,
+            });
+            if (!ok) {
+                throw new Error(`MiniappLauncher: spawn failed for ${packageName}`);
+            }
+            // Dev: wire the hot-reload + log-forwarding sidecar. No-op in prod
+            // (devServerBridge silently drops when no sidecar is up).
+            if (resolved.devUrl && resolved.devPort != null) {
+                devServerBridge.connect(packageName, resolved.devUrl, resolved.devPort);
+            }
+            else if (resolved.devUrl) {
+                // Dev miniapp with no resolvable port — it still launches, but hot
+                // reload + log forwarding won't connect. Surface it instead of failing
+                // silently (the old inline path hard-failed with "no dev port").
+                console.warn(`MiniappLauncher: ${packageName} has no dev port — hot reload + log forwarding disabled`);
+            }
+        }
+        return { uiUri: resolved.uiUri, uiBaseDir: resolved.uiBaseDir };
+    }
+    /**
+     * Re-spawn local miniapps that were running when the app was last killed.
+     *
+     * Cloud apps run on a remote server: the cloud persists which ones are
+     * running and resurrects them when the phone reconnects, so a host-app
+     * restart brings them back on its own. Local (phone-hosted) miniapps run in
+     * the phone's own JS engine — a host-process kill tears down their JSContext
+     * and there is no server to resurrect them, so without this they silently
+     * stay stopped on the next launch even though the user left them running.
+     *
+     * Each local miniapp persists its running flag to disk on start/stop
+     * (`saveLocalAppRunningState`, via the applet's `onStart`/`onStop`). We read
+     * those flags back and re-spawn the background context headlessly (no
+     * foreground, no navigation) — the spawn registers the package so the home
+     * tray/switcher project it as running, exactly as a normal start would. The
+     * WebView, if any, re-attaches lazily when the user opens the app.
+     *
+     * Idempotent and best-effort: skips already-spawned contexts, and clears the
+     * persisted flag for any app whose bundle can no longer be resolved
+     * (uninstalled, or dev server gone) so a dead entry doesn't retry every boot.
+     * Not compatibility-gated: a previously-running background app shouldn't be
+     * dropped just because glasses are momentarily disconnected at boot — it
+     * resumes when they reconnect, same as mid-session.
+     */
+    async autostartLocalMiniapps() {
+        const apps = await appRegistry.getInstalledMiniapps();
+        for (const app of apps) {
+            // Only phone-hosted miniapps have a JSContext to re-spawn. Offline
+            // built-ins (`local:false, offline:true`) restore their native running
+            // state elsewhere and have no bundle to launch.
+            if (!app.local)
+                continue;
+            if (!getLocalAppRunningState(app.packageName))
+                continue;
+            if (this.isRunning(app.packageName))
+                continue;
+            try {
+                await this.ensureRunning(app.packageName);
+            }
+            catch (e) {
+                console.warn(`MiniappLauncher: autostart failed for ${app.packageName} — clearing stale running flag`, e);
+                saveLocalAppRunningState(app.packageName, false);
+            }
+        }
+    }
+    /**
+     * Ensure the context is running AND has completed its CONNECT handshake.
+     * Used by the action broker, which must not deliver to a context that hasn't
+     * come up yet. Throws on spawn failure or connect timeout.
+     */
+    async ensureConnected(packageName, connectTimeoutMs = 10_000, hints) {
+        await this.ensureRunning(packageName, hints);
+        await localMiniappRuntime.waitForConnect(packageName, connectTimeoutMs);
+    }
+    /** Tear down a miniapp's background JS context. */
+    async stop(packageName) {
+        // If a launch is in flight, let it finish first. Otherwise unregister()
+        // no-ops on the not-yet-registered package and the pending spawn then
+        // re-registers the context — leaving it running despite the stop.
+        const pending = this.inFlight.get(packageName);
+        if (pending) {
+            try {
+                await pending;
+            }
+            catch {
+                // Launch failed — nothing got registered, so nothing to tear down.
+            }
+        }
+        await this.deps?.router.unregister(packageName);
+    }
+    // --- internals -----------------------------------------------------------
+    storedDevUrl(packageName) {
+        const r = storage.load(`${packageName}_dev_url`);
+        return r.is_ok() ? r.value : undefined;
+    }
+    /** resolveDevPort — moved verbatim from the old LocalMiniappView helper. */
+    resolveDevPort(searchParam, packageName) {
+        if (searchParam) {
+            const n = parseInt(searchParam, 10);
+            if (Number.isFinite(n))
+                return n;
+        }
+        const stored = storage.load(`${packageName}_dev_port`);
+        if (stored.is_ok())
+            return stored.value;
+        return null;
+    }
+}
+export const miniappLauncher = new MiniappLauncher();
+//# sourceMappingURL=MiniappLauncher.js.map

package/build/services/MiniappLauncher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MiniappLauncher.js","sourceRoot":"","sources":["../../src/services/MiniappLauncher.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * MiniappLauncher — headless launch/teardown of a local miniapp's background\n * JS context.\n *\n * This is the one piece of \"run a miniapp\" that used to live inside the\n * `LocalMiniappView` React component (resolve the bundle → read the manifest →\n * `spawnAndRegister`), triggered only when the Compositor mounted that\n * component on foreground. Pulling it into the runtime means:\n *\n *   - `start()` can actually spawn an app even when nothing foregrounds it\n *     (e.g. a system app launching another miniapp via `session.miniapps`).\n *   - the action broker can wake a stopped target headlessly — no UI at all.\n *   - the dev hot-reload respawn path and the WebView mount path share one\n *     resolve+spawn recipe instead of three copies.\n *\n * The launcher is **headless**: no React, no RN components. The engine-owned\n * MiniappEngine hands it the {@link MentraJSRouter} instance once during\n * engine construction. OEMs embedding the runtime drive miniapp lifecycle\n * through the engine facade and stores, not a separate launcher configure API.\n *\n * Boundary: the launcher owns the **background** context. WebView *rendering*\n * (the UI layer) stays with the host — the launcher just hands back the\n * resolved UI entry so the host can mount its `<WebView>`.\n */\n\nimport {File} from \"expo-file-system\"\n\nimport {decideDevLaunchRoute} from \"../utils/devMiniappLaunch\"\nimport {storage} from \"../utils/storage/storage\"\nimport appRegistry, {getLocalAppRunningState, saveLocalAppRunningState} from \"./AppRegistry\"\nimport devServerBridge from \"./DevServerBridge\"\nimport localMiniappRuntime, {type InstalledMiniappManifest} from \"./LocalMiniappRuntime\"\nimport type {MentraJSRouter} from \"./MentraJSRouter\"\n\ninterface LauncherDeps {\n  /** The host-constructed router (needs the native Crust binding). */\n  router: MentraJSRouter\n}\n\n/** Hints the host may pass from a view's props to avoid re-deriving them. */\nexport interface LaunchHints {\n  devUrl?: string\n  version?: string\n  devPort?: string\n}\n\n/** Everything the launcher resolved for a package — bg source + UI entry. */\nexport interface ResolvedBundle {\n  bgSource: string\n  uiUri: string | null\n  uiBaseDir: string | null\n  declaredPermissions: string[]\n  installedManifest?: InstalledMiniappManifest\n  /** Set for dev miniapps (HTTP off the dev server); null for released. */\n  devUrl: string | null\n  devPort: number | null\n}\n\n/** What the host needs back to render the UI layer. */\nexport interface LaunchResult {\n  uiUri: string | null\n  uiBaseDir: string | null\n}\n\nclass MiniappLauncher {\n  private deps: LauncherDeps | null = null\n\n  /**\n   * In-flight launches keyed by packageName. Both apps.ts start() and the\n   * WebView mount call ensureRunning() before the first spawnAndRegister\n   * resolves — without this, neither sees the package in registeredPackages()\n   * yet and both spawn the same context (a clobber/double-spawn). Concurrent\n   * callers share the same promise.\n   */\n  private readonly inFlight = new Map<string, Promise<LaunchResult>>()\n\n  /** Wire the router in. Called once from MiniappEngine construction. */\n  configure(deps: LauncherDeps): void {\n    this.deps = deps\n  }\n\n  private requireRouter(): MentraJSRouter {\n    if (!this.deps) {\n      throw new Error(\"MiniappLauncher not configured — ensureMiniappEngine() has not run\")\n    }\n    return this.deps.router\n  }\n\n  /** True iff the package's background JS context is currently spawned. */\n  isRunning(packageName: string): boolean {\n    return this.deps?.router.registeredPackages().includes(packageName) ?? false\n  }\n\n  /**\n   * Resolve the background JS source + UI entry + declared permissions for a\n   * package. Handles both dev (HTTP off the running dev server) and released\n   * (file:// from the installed snapshot). Reads disk/network/storage; does\n   * NOT spawn. Returns null when the bundle can't be resolved (dev server\n   * unreachable, missing entry, no installed version).\n   */\n  async resolveBundle(packageName: string, hints?: LaunchHints): Promise<ResolvedBundle | null> {\n    const devUrl = hints?.devUrl ?? this.storedDevUrl(packageName)\n\n    // --- Dev: load directly off the local dev server over HTTP. ---\n    if (devUrl) {\n      const route = await decideDevLaunchRoute(packageName, devUrl)\n      if (route.decision === \"offline\" || !route.manifest) return null\n      const manifest = route.manifest\n      const entry = manifest.entry as {background?: string; ui?: string} | undefined\n      if (!entry?.background) return null\n\n      const base = devUrl.replace(/\\/$/, \"\")\n      // entry.* are bundle-root paths (dist/ stripped); the dev server serves\n      // files relative to cwd, so prepend dist/.\n      const bgUrl = `${base}/dist/${entry.background.replace(/^\\.?\\/+/, \"\")}`\n      const uiUri = entry.ui ? `${base}/dist/${entry.ui.replace(/^\\.?\\/+/, \"\")}` : null\n\n      const perms = manifest.permissions as Array<{type?: string} | string> | undefined\n      const declaredPermissions = (perms ?? [])\n        .map((p) => (typeof p === \"string\" ? p : p?.type))\n        .filter((t): t is string => typeof t === \"string\")\n      const installedManifest: InstalledMiniappManifest = {\n        name: manifest.name,\n        permissions: manifest.permissions as InstalledMiniappManifest[\"permissions\"],\n        hardwareRequirements: manifest.hardwareRequirements as InstalledMiniappManifest[\"hardwareRequirements\"],\n      }\n\n      let bgSource: string\n      try {\n        const res = await fetch(bgUrl)\n        if (!res.ok) return null\n        bgSource = await res.text()\n      } catch {\n        return null\n      }\n\n      return {\n        bgSource,\n        uiUri,\n        uiBaseDir: uiUri ? uiUri.replace(/\\/[^/]+$/, \"/\") : null,\n        declaredPermissions,\n        installedManifest,\n        devUrl,\n        devPort: this.resolveDevPort(hints?.devPort, packageName),\n      }\n    }\n\n    // --- Released: resolve from the installed file:// snapshot. ---\n    const version = hints?.version ?? (await appRegistry.getActiveVersion(packageName))\n    if (!version) return null\n    const entryPaths = appRegistry.getMiniappEntryPaths(packageName, version)\n    if (!entryPaths?.background) return null\n\n    const manifest = appRegistry.getMiniappManifest(packageName, version) as {\n      name?: string\n      permissions?: Array<{type: string; required?: boolean; description?: string}>\n      hardwareRequirements?: Array<{type: string; level: string; description?: string}>\n    } | null\n    const declaredPermissions = (manifest?.permissions ?? [])\n      .map((p) => p.type)\n      .filter((t): t is string => typeof t === \"string\")\n    const installedManifest: InstalledMiniappManifest | undefined = manifest\n      ? {name: manifest.name, permissions: manifest.permissions, hardwareRequirements: manifest.hardwareRequirements}\n      : undefined\n\n    let bgSource: string\n    try {\n      bgSource = new File(entryPaths.background).textSync()\n    } catch {\n      return null\n    }\n\n    return {\n      bgSource,\n      uiUri: entryPaths.ui ?? null,\n      uiBaseDir: entryPaths.ui ? entryPaths.ui.replace(/\\/[^/]+$/, \"/\") : null,\n      declaredPermissions,\n      installedManifest,\n      devUrl: null,\n      devPort: null,\n    }\n  }\n\n  /**\n   * Ensure a miniapp's background JS context is spawned. Idempotent — if the\n   * context is already alive this is a no-op spawn-wise (it still resolves the\n   * UI entry so a re-mounting host gets its `<WebView>` source back).\n   *\n   * Resolves once the context is SPAWNED. It does NOT block on the context's\n   * CONNECT handshake — the host's WebView mount shouldn't wait on background\n   * JS. Callers that need the context to be connected and ready to receive\n   * messages (the action broker) follow up with\n   * {@link LocalMiniappRuntime.waitForConnect}.\n   */\n  async ensureRunning(packageName: string, hints?: LaunchHints): Promise<LaunchResult> {\n    const router = this.requireRouter()\n\n    // Already spawned: best-effort resolve for the UI entry, never throw —\n    // a headless caller that doesn't need UI gets {null, null} fast even if\n    // the dev server has since dropped.\n    if (router.registeredPackages().includes(packageName)) {\n      const existing = await this.resolveBundle(packageName, hints).catch(() => null)\n      return {uiUri: existing?.uiUri ?? null, uiBaseDir: existing?.uiBaseDir ?? null}\n    }\n\n    // Coalesce concurrent launches of the same package onto one promise.\n    const pending = this.inFlight.get(packageName)\n    if (pending) return pending\n\n    const launch = this.spawn(packageName, hints)\n    this.inFlight.set(packageName, launch)\n    try {\n      return await launch\n    } finally {\n      this.inFlight.delete(packageName)\n    }\n  }\n\n  /** Resolve the bundle and spawn the context. Serialized via {@link inFlight}. */\n  private async spawn(packageName: string, hints?: LaunchHints): Promise<LaunchResult> {\n    const router = this.requireRouter()\n    const resolved = await this.resolveBundle(packageName, hints)\n    if (!resolved) {\n      throw new Error(`MiniappLauncher: cannot resolve bundle for ${packageName}`)\n    }\n\n    // Re-check after the async resolve: a different path may have spawned it\n    // while we were fetching/reading the bundle.\n    if (!router.registeredPackages().includes(packageName)) {\n      const ok = await router.spawnAndRegister(packageName, resolved.bgSource, {\n        permissions: resolved.declaredPermissions,\n        installedManifest: resolved.installedManifest,\n      })\n      if (!ok) {\n        throw new Error(`MiniappLauncher: spawn failed for ${packageName}`)\n      }\n\n      // Dev: wire the hot-reload + log-forwarding sidecar. No-op in prod\n      // (devServerBridge silently drops when no sidecar is up).\n      if (resolved.devUrl && resolved.devPort != null) {\n        devServerBridge.connect(packageName, resolved.devUrl, resolved.devPort)\n      } else if (resolved.devUrl) {\n        // Dev miniapp with no resolvable port — it still launches, but hot\n        // reload + log forwarding won't connect. Surface it instead of failing\n        // silently (the old inline path hard-failed with \"no dev port\").\n        console.warn(`MiniappLauncher: ${packageName} has no dev port — hot reload + log forwarding disabled`)\n      }\n    }\n\n    return {uiUri: resolved.uiUri, uiBaseDir: resolved.uiBaseDir}\n  }\n\n  /**\n   * Re-spawn local miniapps that were running when the app was last killed.\n   *\n   * Cloud apps run on a remote server: the cloud persists which ones are\n   * running and resurrects them when the phone reconnects, so a host-app\n   * restart brings them back on its own. Local (phone-hosted) miniapps run in\n   * the phone's own JS engine — a host-process kill tears down their JSContext\n   * and there is no server to resurrect them, so without this they silently\n   * stay stopped on the next launch even though the user left them running.\n   *\n   * Each local miniapp persists its running flag to disk on start/stop\n   * (`saveLocalAppRunningState`, via the applet's `onStart`/`onStop`). We read\n   * those flags back and re-spawn the background context headlessly (no\n   * foreground, no navigation) — the spawn registers the package so the home\n   * tray/switcher project it as running, exactly as a normal start would. The\n   * WebView, if any, re-attaches lazily when the user opens the app.\n   *\n   * Idempotent and best-effort: skips already-spawned contexts, and clears the\n   * persisted flag for any app whose bundle can no longer be resolved\n   * (uninstalled, or dev server gone) so a dead entry doesn't retry every boot.\n   * Not compatibility-gated: a previously-running background app shouldn't be\n   * dropped just because glasses are momentarily disconnected at boot — it\n   * resumes when they reconnect, same as mid-session.\n   */\n  async autostartLocalMiniapps(): Promise<void> {\n    const apps = await appRegistry.getInstalledMiniapps()\n    for (const app of apps) {\n      // Only phone-hosted miniapps have a JSContext to re-spawn. Offline\n      // built-ins (`local:false, offline:true`) restore their native running\n      // state elsewhere and have no bundle to launch.\n      if (!app.local) continue\n      if (!getLocalAppRunningState(app.packageName)) continue\n      if (this.isRunning(app.packageName)) continue\n      try {\n        await this.ensureRunning(app.packageName)\n      } catch (e) {\n        console.warn(`MiniappLauncher: autostart failed for ${app.packageName} — clearing stale running flag`, e)\n        saveLocalAppRunningState(app.packageName, false)\n      }\n    }\n  }\n\n  /**\n   * Ensure the context is running AND has completed its CONNECT handshake.\n   * Used by the action broker, which must not deliver to a context that hasn't\n   * come up yet. Throws on spawn failure or connect timeout.\n   */\n  async ensureConnected(packageName: string, connectTimeoutMs = 10_000, hints?: LaunchHints): Promise<void> {\n    await this.ensureRunning(packageName, hints)\n    await localMiniappRuntime.waitForConnect(packageName, connectTimeoutMs)\n  }\n\n  /** Tear down a miniapp's background JS context. */\n  async stop(packageName: string): Promise<void> {\n    // If a launch is in flight, let it finish first. Otherwise unregister()\n    // no-ops on the not-yet-registered package and the pending spawn then\n    // re-registers the context — leaving it running despite the stop.\n    const pending = this.inFlight.get(packageName)\n    if (pending) {\n      try {\n        await pending\n      } catch {\n        // Launch failed — nothing got registered, so nothing to tear down.\n      }\n    }\n    await this.deps?.router.unregister(packageName)\n  }\n\n  // --- internals -----------------------------------------------------------\n\n  private storedDevUrl(packageName: string): string | undefined {\n    const r = storage.load<string>(`${packageName}_dev_url`)\n    return r.is_ok() ? r.value : undefined\n  }\n\n  /** resolveDevPort — moved verbatim from the old LocalMiniappView helper. */\n  private resolveDevPort(searchParam: string | undefined, packageName: string): number | null {\n    if (searchParam) {\n      const n = parseInt(searchParam, 10)\n      if (Number.isFinite(n)) return n\n    }\n    const stored = storage.load<number>(`${packageName}_dev_port`)\n    if (stored.is_ok()) return stored.value\n    return null\n  }\n}\n\nexport const miniappLauncher = new MiniappLauncher()\n"]}

package/build/services/MiniappRunningRegistry.d.ts

@@ -0,0 +1,24 @@
+/**
+ * MiniappRunningRegistry — module-level set of currently-running miniapp
+ * packageNames.
+ *
+ * "Running" means the miniapp's **background JSContext is alive** in the
+ * host process. The UI WebView open/close state is separate — that's
+ * tracked by MentraUIRouter.isBound(). A miniapp can be "running"
+ * (JSContext alive, processing glasses events) without any WebView
+ * mounted, which is the steady-state.
+ *
+ * MentraJSRouter is the single writer: `spawnAndRegister` adds,
+ * `unregister` removes. Home tile / tray reads from here to project the
+ * `running` field on local applets.
+ */
+type Listener = () => void;
+export declare const miniappRunningRegistry: {
+    add(packageName: string): void;
+    remove(packageName: string): void;
+    has(packageName: string): boolean;
+    getAll(): string[];
+    subscribe(fn: Listener): () => void;
+};
+export {};
+//# sourceMappingURL=MiniappRunningRegistry.d.ts.map

package/build/services/MiniappRunningRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MiniappRunningRegistry.d.ts","sourceRoot":"","sources":["../../src/services/MiniappRunningRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,KAAK,QAAQ,GAAG,MAAM,IAAI,CAAA;AAe1B,eAAO,MAAM,sBAAsB;qBAChB,MAAM,GAAG,IAAI;wBAMV,MAAM,GAAG,IAAI;qBAKhB,MAAM,GAAG,OAAO;cAIvB,MAAM,EAAE;kBAIJ,QAAQ,GAAG,MAAM,IAAI;CAMpC,CAAA"}