@mentra/engine 0.1.0-beta.0

package/build/services/MentraUIRouter.d.ts

@@ -0,0 +1,137 @@
+/**
+ * MentraUIRouter — bidirectional bus between a per-miniapp UI WebView
+ * and its bound background JSContext.
+ *
+ * The flow:
+ *
+ *   WebView (mentra.send/on)                Background (session.ui.send/on)
+ *      │                                       │
+ *      │   window.ReactNativeWebView          │
+ *      │   .postMessage(jsonEnvelope)         │  session.sendOneShot({
+ *      │                                      │     type: "UI_SEND", channel, payload, seq
+ *      │                                      │  })
+ *      │                                      │
+ *      ▼                                      ▼
+ *   MiniappHost.onMessage              MentraJSRouter (recognises payload.type==="UI_SEND")
+ *      │                                      │
+ *      ▼                                      ▼
+ *      ──── MentraUIRouter.routeFromWebView   ──── MentraUIRouter.routeFromBackground
+ *           ──► Crust.mentraJsDispatchToJs        ──► webView.injectJavaScript("window.__mentra.recv(...)")
+ *                {kind:"bridge", raw: JSON({
+ *                  payload:{
+ *                    type:"EVENT", streamType:"_ui",
+ *                    data:{type:"UI_MESSAGE", channel, payload, seq}
+ *                  }})}
+ *
+ * The router is a singleton — one instance for the whole host process —
+ * because only one WebView is allowed open at a time per spec. The
+ * binding map is therefore N entries (one per "currently has a UI
+ * WebView mounted" miniapp), but in practice it's 0 or 1.
+ *
+ * UI_OPEN / UI_CLOSE lifecycle envelopes are pushed by the WebView's
+ * `mentra.ready()` and the host's WebView teardown handler; the router
+ * forwards them to background via the same EVENT/_ui envelope shape.
+ */
+interface MentraUIInjectFn {
+    (jsSource: string): void;
+}
+/**
+ * Subset of the Crust native module that MentraUIRouter touches.
+ * Loose binding keeps tests free of Expo imports.
+ */
+export interface MentraUICrustBinding {
+    mentraJsDispatchToJs(packageName: string, envelope: Record<string, unknown>): Promise<void> | void;
+}
+/**
+ * NOTE: the WebView ↔ host heartbeat was removed when the lifecycle
+ * inversion landed. The current model is **at most one WebView at a
+ * time, foreground UI with an always-on background JSContext** (same
+ * shape as the cloud-WebView miniapps). User navigation closes it
+ * explicitly and `onContentProcessDidTerminate` catches OS-level
+ * crashes, but the host may still re-announce UI_OPEN for an already
+ * mounted WebView after app resume/dev respawn so the background can
+ * push a fresh authoritative snapshot.
+ */
+export declare class MentraUIRouter {
+    private readonly bindings;
+    private readonly crust;
+    constructor(crust: MentraUICrustBinding);
+    /**
+     * Called when a UI WebView mounts. `injectFn` wraps
+     * `webView.injectJavaScript` — the router calls it with prebuilt
+     * `window.__mentra.recv(...)` strings to deliver background-side
+     * frames into the WebView's mentra global.
+     *
+     * The router also pushes a UI_OPEN envelope to the background side
+     * once the WebView signals ready (see {@link routeFromWebView}).
+     * Calling bindWebView on a packageName that already has a binding
+     * replaces the previous one (defensive — should not happen in
+     * practice because only one WebView is open at a time).
+     */
+    bindWebView(packageName: string, injectFn: MentraUIInjectFn): void;
+    /**
+     * Called when the WebView unmounts (user navigated away or the host
+     * tore it down on heartbeat timeout). Pushes UI_CLOSE to background
+     * so handlers can flush state, then drops the binding.
+     */
+    unbindWebView(packageName: string): void;
+    /** True iff a WebView is currently bound to the named package. */
+    isBound(packageName: string): boolean;
+    /**
+     * Re-announce the already-mounted WebView to the background JSContext.
+     * This covers dev background hot-reload, app resume, and thawed WebViews
+     * whose injected UI_SEND frames may have been missed while the host was
+     * suspended. Re-emitting UI_OPEN flips `ui.bound` back to true if needed
+     * and lets background code push a fresh snapshot via session.ui.onOpen.
+     *
+     * No-op if no WebView is currently bound for the package.
+     */
+    notifyReopen(packageName: string): void;
+    /**
+     * Forward a WebView-originated postMessage envelope to the JSContext.
+     * `rawJson` is the raw string from `event.nativeEvent.data` — the
+     * caller hasn't parsed it yet so the router controls the wire format
+     * end-to-end.
+     *
+     * Recognised envelope types from the WebView shim:
+     *   - {type: "ready"}                              → fire UI_OPEN
+     *   - {type: "msg", seq, channel, payload}         → fire UI_MESSAGE
+     *   - {type: "heartbeat", seq}                     → silently ack
+     */
+    routeFromWebView(packageName: string, rawJson: string): void;
+    /**
+     * Called by MentraJSRouter when it sees a `__bridge.send` outbound
+     * frame whose parsed payload is a UI_SEND envelope. The router
+     * forwards it as a `msg` frame to the bound WebView (or drops if no
+     * WebView is currently mounted).
+     *
+     * `uiSendPayload` is the raw `{type:"UI_SEND", channel, payload, seq}`
+     * shape produced by `session.ui.send` on the background side.
+     */
+    routeFromBackground(packageName: string, uiSendPayload: {
+        type: string;
+        channel?: string;
+        payload?: unknown;
+        seq?: number;
+        requestId?: string;
+    }): void;
+    /**
+     * Send a synthetic frame to the WebView. Used for host-initiated
+     * lifecycle events (`open`, `close`, `ack`). The wire shape is the
+     * same as the WebView shim's recv handler expects.
+     */
+    pushLifecycleFrame(packageName: string, frame: {
+        type: "open" | "close" | "ack";
+        seq?: number;
+    }): void;
+    /**
+     * Wrap an EVENT envelope and push it to background via the bridge.
+     * Background's UIModule listens for stream `_ui`. The `type` is the
+     * wire value `miniapp_event` — must match `MiniappResponseType.EVENT`
+     * exactly, otherwise the SDK's session switch falls through and the
+     * `_ui` fan-out never fires (bound stays false; `ui.send` drops).
+     */
+    private deliverToBackground;
+}
+export {};
+//# sourceMappingURL=MentraUIRouter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"MentraUIRouter.d.ts","sourceRoot":"","sources":["../../src/services/MentraUIRouter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,UAAU,gBAAgB;IACxB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,oBAAoB,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;CACnG;AAMD;;;;;;;;;GASG;AAEH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuC;IAChE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAsB;gBAEhC,KAAK,EAAE,oBAAoB;IAIvC;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,GAAG,IAAI;IAIlE;;;;OAIG;IACH,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAMxC,kEAAkE;IAClE,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO;IAIrC;;;;;;;;OAQG;IACH,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAKvC;;;;;;;;;;OAUG;IACH,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IA2C5D;;;;;;;;OAQG;IACH,mBAAmB,CACjB,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE;QACb,IAAI,EAAE,MAAM,CAAA;QACZ,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,OAAO,CAAC,EAAE,OAAO,CAAA;QACjB,GAAG,CAAC,EAAE,MAAM,CAAA;QACZ,SAAS,CAAC,EAAE,MAAM,CAAA;KACnB,GACA,IAAI;IAsBP;;;;OAIG;IACH,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE;QAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,KAAK,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAC,GAAG,IAAI;IAQpG;;;;;;OAMG;IACH,OAAO,CAAC,mBAAmB;CAa5B"}

package/build/services/MentraUIRouter.js

@@ -0,0 +1,210 @@
+/**
+ * MentraUIRouter — bidirectional bus between a per-miniapp UI WebView
+ * and its bound background JSContext.
+ *
+ * The flow:
+ *
+ *   WebView (mentra.send/on)                Background (session.ui.send/on)
+ *      │                                       │
+ *      │   window.ReactNativeWebView          │
+ *      │   .postMessage(jsonEnvelope)         │  session.sendOneShot({
+ *      │                                      │     type: "UI_SEND", channel, payload, seq
+ *      │                                      │  })
+ *      │                                      │
+ *      ▼                                      ▼
+ *   MiniappHost.onMessage              MentraJSRouter (recognises payload.type==="UI_SEND")
+ *      │                                      │
+ *      ▼                                      ▼
+ *      ──── MentraUIRouter.routeFromWebView   ──── MentraUIRouter.routeFromBackground
+ *           ──► Crust.mentraJsDispatchToJs        ──► webView.injectJavaScript("window.__mentra.recv(...)")
+ *                {kind:"bridge", raw: JSON({
+ *                  payload:{
+ *                    type:"EVENT", streamType:"_ui",
+ *                    data:{type:"UI_MESSAGE", channel, payload, seq}
+ *                  }})}
+ *
+ * The router is a singleton — one instance for the whole host process —
+ * because only one WebView is allowed open at a time per spec. The
+ * binding map is therefore N entries (one per "currently has a UI
+ * WebView mounted" miniapp), but in practice it's 0 or 1.
+ *
+ * UI_OPEN / UI_CLOSE lifecycle envelopes are pushed by the WebView's
+ * `mentra.ready()` and the host's WebView teardown handler; the router
+ * forwards them to background via the same EVENT/_ui envelope shape.
+ */
+/**
+ * NOTE: the WebView ↔ host heartbeat was removed when the lifecycle
+ * inversion landed. The current model is **at most one WebView at a
+ * time, foreground UI with an always-on background JSContext** (same
+ * shape as the cloud-WebView miniapps). User navigation closes it
+ * explicitly and `onContentProcessDidTerminate` catches OS-level
+ * crashes, but the host may still re-announce UI_OPEN for an already
+ * mounted WebView after app resume/dev respawn so the background can
+ * push a fresh authoritative snapshot.
+ */
+export class MentraUIRouter {
+    bindings = new Map();
+    crust;
+    constructor(crust) {
+        this.crust = crust;
+    }
+    /**
+     * Called when a UI WebView mounts. `injectFn` wraps
+     * `webView.injectJavaScript` — the router calls it with prebuilt
+     * `window.__mentra.recv(...)` strings to deliver background-side
+     * frames into the WebView's mentra global.
+     *
+     * The router also pushes a UI_OPEN envelope to the background side
+     * once the WebView signals ready (see {@link routeFromWebView}).
+     * Calling bindWebView on a packageName that already has a binding
+     * replaces the previous one (defensive — should not happen in
+     * practice because only one WebView is open at a time).
+     */
+    bindWebView(packageName, injectFn) {
+        this.bindings.set(packageName, { inject: injectFn });
+    }
+    /**
+     * Called when the WebView unmounts (user navigated away or the host
+     * tore it down on heartbeat timeout). Pushes UI_CLOSE to background
+     * so handlers can flush state, then drops the binding.
+     */
+    unbindWebView(packageName) {
+        if (!this.bindings.has(packageName))
+            return;
+        this.bindings.delete(packageName);
+        this.deliverToBackground(packageName, { type: "UI_CLOSE" });
+    }
+    /** True iff a WebView is currently bound to the named package. */
+    isBound(packageName) {
+        return this.bindings.has(packageName);
+    }
+    /**
+     * Re-announce the already-mounted WebView to the background JSContext.
+     * This covers dev background hot-reload, app resume, and thawed WebViews
+     * whose injected UI_SEND frames may have been missed while the host was
+     * suspended. Re-emitting UI_OPEN flips `ui.bound` back to true if needed
+     * and lets background code push a fresh snapshot via session.ui.onOpen.
+     *
+     * No-op if no WebView is currently bound for the package.
+     */
+    notifyReopen(packageName) {
+        if (!this.bindings.has(packageName))
+            return;
+        this.deliverToBackground(packageName, { type: "UI_OPEN" });
+    }
+    /**
+     * Forward a WebView-originated postMessage envelope to the JSContext.
+     * `rawJson` is the raw string from `event.nativeEvent.data` — the
+     * caller hasn't parsed it yet so the router controls the wire format
+     * end-to-end.
+     *
+     * Recognised envelope types from the WebView shim:
+     *   - {type: "ready"}                              → fire UI_OPEN
+     *   - {type: "msg", seq, channel, payload}         → fire UI_MESSAGE
+     *   - {type: "heartbeat", seq}                     → silently ack
+     */
+    routeFromWebView(packageName, rawJson) {
+        let env;
+        try {
+            env = JSON.parse(rawJson);
+        }
+        catch {
+            return;
+        }
+        if (typeof env.type !== "string")
+            return;
+        if (env.type === "ready") {
+            this.deliverToBackground(packageName, { type: "UI_OPEN" });
+            return;
+        }
+        if (env.type === "msg" && typeof env.channel === "string") {
+            const out = {
+                type: "UI_MESSAGE",
+                channel: env.channel,
+                payload: env.payload,
+                seq: env.seq,
+            };
+            if (typeof env.requestId === "string")
+                out.requestId = env.requestId;
+            this.deliverToBackground(packageName, out);
+            return;
+        }
+        if (env.type === "cancel" && typeof env.requestId === "string") {
+            this.deliverToBackground(packageName, { type: "UI_CANCEL", requestId: env.requestId });
+            return;
+        }
+        // NOTE: console.* logs do NOT come through this router. The
+        // miniappGlobals console-tap shim posts {payload:{type:"dev_log"}}
+        // envelopes which LocalMiniappRuntime handles and forwards to the
+        // dev sidecar tagged source:"ui". Keeping that path one-way means
+        // we don't have two console-capture pipelines competing.
+        //
+        // Unknown envelope — drop silently.
+    }
+    /**
+     * Called by MentraJSRouter when it sees a `__bridge.send` outbound
+     * frame whose parsed payload is a UI_SEND envelope. The router
+     * forwards it as a `msg` frame to the bound WebView (or drops if no
+     * WebView is currently mounted).
+     *
+     * `uiSendPayload` is the raw `{type:"UI_SEND", channel, payload, seq}`
+     * shape produced by `session.ui.send` on the background side.
+     */
+    routeFromBackground(packageName, uiSendPayload) {
+        const binding = this.bindings.get(packageName);
+        if (!binding)
+            return;
+        if (uiSendPayload.type === "UI_CANCEL" && typeof uiSendPayload.requestId === "string") {
+            const cancel = { type: "cancel", requestId: uiSendPayload.requestId };
+            const literal = JSON.stringify(cancel);
+            const escaped = JSON.stringify(literal);
+            binding.inject(`if (window.__mentra && window.__mentra.recv) window.__mentra.recv(JSON.parse(${escaped})); true;`);
+            return;
+        }
+        const outbound = {
+            type: "msg",
+            seq: uiSendPayload.seq ?? 0,
+            channel: uiSendPayload.channel,
+            payload: uiSendPayload.payload,
+        };
+        if (typeof uiSendPayload.requestId === "string")
+            outbound.requestId = uiSendPayload.requestId;
+        const literal = JSON.stringify(outbound);
+        const escaped = JSON.stringify(literal);
+        binding.inject(`if (window.__mentra && window.__mentra.recv) window.__mentra.recv(JSON.parse(${escaped})); true;`);
+    }
+    /**
+     * Send a synthetic frame to the WebView. Used for host-initiated
+     * lifecycle events (`open`, `close`, `ack`). The wire shape is the
+     * same as the WebView shim's recv handler expects.
+     */
+    pushLifecycleFrame(packageName, frame) {
+        const binding = this.bindings.get(packageName);
+        if (!binding)
+            return;
+        const literal = JSON.stringify(frame);
+        const escaped = JSON.stringify(literal);
+        binding.inject(`if (window.__mentra && window.__mentra.recv) window.__mentra.recv(JSON.parse(${escaped})); true;`);
+    }
+    /**
+     * Wrap an EVENT envelope and push it to background via the bridge.
+     * Background's UIModule listens for stream `_ui`. The `type` is the
+     * wire value `miniapp_event` — must match `MiniappResponseType.EVENT`
+     * exactly, otherwise the SDK's session switch falls through and the
+     * `_ui` fan-out never fires (bound stays false; `ui.send` drops).
+     */
+    deliverToBackground(packageName, data) {
+        const innerEnvelope = {
+            payload: {
+                type: "miniapp_event",
+                streamType: "_ui",
+                data,
+            },
+        };
+        void this.crust.mentraJsDispatchToJs(packageName, {
+            kind: "bridge",
+            raw: JSON.stringify(innerEnvelope),
+        });
+    }
+}
+//# sourceMappingURL=MentraUIRouter.js.map

package/build/services/MentraUIRouter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MentraUIRouter.js","sourceRoot":"","sources":["../../src/services/MentraUIRouter.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * MentraUIRouter — bidirectional bus between a per-miniapp UI WebView\n * and its bound background JSContext.\n *\n * The flow:\n *\n *   WebView (mentra.send/on)                Background (session.ui.send/on)\n *      │                                       │\n *      │   window.ReactNativeWebView          │\n *      │   .postMessage(jsonEnvelope)         │  session.sendOneShot({\n *      │                                      │     type: \"UI_SEND\", channel, payload, seq\n *      │                                      │  })\n *      │                                      │\n *      ▼                                      ▼\n *   MiniappHost.onMessage              MentraJSRouter (recognises payload.type===\"UI_SEND\")\n *      │                                      │\n *      ▼                                      ▼\n *      ──── MentraUIRouter.routeFromWebView   ──── MentraUIRouter.routeFromBackground\n *           ──► Crust.mentraJsDispatchToJs        ──► webView.injectJavaScript(\"window.__mentra.recv(...)\")\n *                {kind:\"bridge\", raw: JSON({\n *                  payload:{\n *                    type:\"EVENT\", streamType:\"_ui\",\n *                    data:{type:\"UI_MESSAGE\", channel, payload, seq}\n *                  }})}\n *\n * The router is a singleton — one instance for the whole host process —\n * because only one WebView is allowed open at a time per spec. The\n * binding map is therefore N entries (one per \"currently has a UI\n * WebView mounted\" miniapp), but in practice it's 0 or 1.\n *\n * UI_OPEN / UI_CLOSE lifecycle envelopes are pushed by the WebView's\n * `mentra.ready()` and the host's WebView teardown handler; the router\n * forwards them to background via the same EVENT/_ui envelope shape.\n */\n\ninterface MentraUIInjectFn {\n  (jsSource: string): void\n}\n\n/**\n * Subset of the Crust native module that MentraUIRouter touches.\n * Loose binding keeps tests free of Expo imports.\n */\nexport interface MentraUICrustBinding {\n  mentraJsDispatchToJs(packageName: string, envelope: Record<string, unknown>): Promise<void> | void\n}\n\ninterface BoundWebView {\n  inject: MentraUIInjectFn\n}\n\n/**\n * NOTE: the WebView ↔ host heartbeat was removed when the lifecycle\n * inversion landed. The current model is **at most one WebView at a\n * time, foreground UI with an always-on background JSContext** (same\n * shape as the cloud-WebView miniapps). User navigation closes it\n * explicitly and `onContentProcessDidTerminate` catches OS-level\n * crashes, but the host may still re-announce UI_OPEN for an already\n * mounted WebView after app resume/dev respawn so the background can\n * push a fresh authoritative snapshot.\n */\n\nexport class MentraUIRouter {\n  private readonly bindings: Map<string, BoundWebView> = new Map()\n  private readonly crust: MentraUICrustBinding\n\n  constructor(crust: MentraUICrustBinding) {\n    this.crust = crust\n  }\n\n  /**\n   * Called when a UI WebView mounts. `injectFn` wraps\n   * `webView.injectJavaScript` — the router calls it with prebuilt\n   * `window.__mentra.recv(...)` strings to deliver background-side\n   * frames into the WebView's mentra global.\n   *\n   * The router also pushes a UI_OPEN envelope to the background side\n   * once the WebView signals ready (see {@link routeFromWebView}).\n   * Calling bindWebView on a packageName that already has a binding\n   * replaces the previous one (defensive — should not happen in\n   * practice because only one WebView is open at a time).\n   */\n  bindWebView(packageName: string, injectFn: MentraUIInjectFn): void {\n    this.bindings.set(packageName, {inject: injectFn})\n  }\n\n  /**\n   * Called when the WebView unmounts (user navigated away or the host\n   * tore it down on heartbeat timeout). Pushes UI_CLOSE to background\n   * so handlers can flush state, then drops the binding.\n   */\n  unbindWebView(packageName: string): void {\n    if (!this.bindings.has(packageName)) return\n    this.bindings.delete(packageName)\n    this.deliverToBackground(packageName, {type: \"UI_CLOSE\"})\n  }\n\n  /** True iff a WebView is currently bound to the named package. */\n  isBound(packageName: string): boolean {\n    return this.bindings.has(packageName)\n  }\n\n  /**\n   * Re-announce the already-mounted WebView to the background JSContext.\n   * This covers dev background hot-reload, app resume, and thawed WebViews\n   * whose injected UI_SEND frames may have been missed while the host was\n   * suspended. Re-emitting UI_OPEN flips `ui.bound` back to true if needed\n   * and lets background code push a fresh snapshot via session.ui.onOpen.\n   *\n   * No-op if no WebView is currently bound for the package.\n   */\n  notifyReopen(packageName: string): void {\n    if (!this.bindings.has(packageName)) return\n    this.deliverToBackground(packageName, {type: \"UI_OPEN\"})\n  }\n\n  /**\n   * Forward a WebView-originated postMessage envelope to the JSContext.\n   * `rawJson` is the raw string from `event.nativeEvent.data` — the\n   * caller hasn't parsed it yet so the router controls the wire format\n   * end-to-end.\n   *\n   * Recognised envelope types from the WebView shim:\n   *   - {type: \"ready\"}                              → fire UI_OPEN\n   *   - {type: \"msg\", seq, channel, payload}         → fire UI_MESSAGE\n   *   - {type: \"heartbeat\", seq}                     → silently ack\n   */\n  routeFromWebView(packageName: string, rawJson: string): void {\n    let env: {\n      type?: string\n      seq?: number\n      channel?: string\n      payload?: unknown\n      requestId?: string\n    }\n    try {\n      env = JSON.parse(rawJson)\n    } catch {\n      return\n    }\n    if (typeof env.type !== \"string\") return\n\n    if (env.type === \"ready\") {\n      this.deliverToBackground(packageName, {type: \"UI_OPEN\"})\n      return\n    }\n    if (env.type === \"msg\" && typeof env.channel === \"string\") {\n      const out: Record<string, unknown> = {\n        type: \"UI_MESSAGE\",\n        channel: env.channel,\n        payload: env.payload,\n        seq: env.seq,\n      }\n      if (typeof env.requestId === \"string\") out.requestId = env.requestId\n      this.deliverToBackground(packageName, out)\n      return\n    }\n    if (env.type === \"cancel\" && typeof env.requestId === \"string\") {\n      this.deliverToBackground(packageName, {type: \"UI_CANCEL\", requestId: env.requestId})\n      return\n    }\n    // NOTE: console.* logs do NOT come through this router. The\n    // miniappGlobals console-tap shim posts {payload:{type:\"dev_log\"}}\n    // envelopes which LocalMiniappRuntime handles and forwards to the\n    // dev sidecar tagged source:\"ui\". Keeping that path one-way means\n    // we don't have two console-capture pipelines competing.\n    //\n    // Unknown envelope — drop silently.\n  }\n\n  /**\n   * Called by MentraJSRouter when it sees a `__bridge.send` outbound\n   * frame whose parsed payload is a UI_SEND envelope. The router\n   * forwards it as a `msg` frame to the bound WebView (or drops if no\n   * WebView is currently mounted).\n   *\n   * `uiSendPayload` is the raw `{type:\"UI_SEND\", channel, payload, seq}`\n   * shape produced by `session.ui.send` on the background side.\n   */\n  routeFromBackground(\n    packageName: string,\n    uiSendPayload: {\n      type: string\n      channel?: string\n      payload?: unknown\n      seq?: number\n      requestId?: string\n    },\n  ): void {\n    const binding = this.bindings.get(packageName)\n    if (!binding) return\n    if (uiSendPayload.type === \"UI_CANCEL\" && typeof uiSendPayload.requestId === \"string\") {\n      const cancel = {type: \"cancel\", requestId: uiSendPayload.requestId}\n      const literal = JSON.stringify(cancel)\n      const escaped = JSON.stringify(literal)\n      binding.inject(`if (window.__mentra && window.__mentra.recv) window.__mentra.recv(JSON.parse(${escaped})); true;`)\n      return\n    }\n    const outbound: Record<string, unknown> = {\n      type: \"msg\",\n      seq: uiSendPayload.seq ?? 0,\n      channel: uiSendPayload.channel,\n      payload: uiSendPayload.payload,\n    }\n    if (typeof uiSendPayload.requestId === \"string\") outbound.requestId = uiSendPayload.requestId\n    const literal = JSON.stringify(outbound)\n    const escaped = JSON.stringify(literal)\n    binding.inject(`if (window.__mentra && window.__mentra.recv) window.__mentra.recv(JSON.parse(${escaped})); true;`)\n  }\n\n  /**\n   * Send a synthetic frame to the WebView. Used for host-initiated\n   * lifecycle events (`open`, `close`, `ack`). The wire shape is the\n   * same as the WebView shim's recv handler expects.\n   */\n  pushLifecycleFrame(packageName: string, frame: {type: \"open\" | \"close\" | \"ack\"; seq?: number}): void {\n    const binding = this.bindings.get(packageName)\n    if (!binding) return\n    const literal = JSON.stringify(frame)\n    const escaped = JSON.stringify(literal)\n    binding.inject(`if (window.__mentra && window.__mentra.recv) window.__mentra.recv(JSON.parse(${escaped})); true;`)\n  }\n\n  /**\n   * Wrap an EVENT envelope and push it to background via the bridge.\n   * Background's UIModule listens for stream `_ui`. The `type` is the\n   * wire value `miniapp_event` — must match `MiniappResponseType.EVENT`\n   * exactly, otherwise the SDK's session switch falls through and the\n   * `_ui` fan-out never fires (bound stays false; `ui.send` drops).\n   */\n  private deliverToBackground(packageName: string, data: Record<string, unknown>): void {\n    const innerEnvelope = {\n      payload: {\n        type: \"miniapp_event\",\n        streamType: \"_ui\",\n        data,\n      },\n    }\n    void this.crust.mentraJsDispatchToJs(packageName, {\n      kind: \"bridge\",\n      raw: JSON.stringify(innerEnvelope),\n    })\n  }\n}\n"]}

package/build/services/MicStateCoordinator.d.ts

@@ -0,0 +1,37 @@
+/**
+ * MicStateCoordinator
+ *
+ * Owns local-miniapp-driven microphone requirements.
+ *
+ * Local miniapps subscribe to audio_chunk / transcription streams.
+ * This coordinator pushes the aggregate local requirement set to BluetoothSdk
+ * so the mic runs whenever at least one local consumer needs it.
+ */
+declare class MicStateCoordinator {
+    private static instance;
+    private localWantsPcm;
+    private localWantsLc3;
+    private constructor();
+    static getInstance(): MicStateCoordinator;
+    /**
+     * Update local miniapp requirements. Called by LocalMiniappRuntime when
+     * the aggregated set of local subscriptions changes.
+     */
+    setLocalRequirements(req: {
+        pcm: boolean;
+        lc3: boolean;
+    }): void;
+    /**
+     * Push local requirements to BluetoothSdk. `should_send_pcm` is strictly for
+     * on-device PCM consumers; cloud audio uses LC3 through AudioCloudUplink.
+     */
+    private applyUnion;
+    /**
+     * Reset all requirements to off. Called during cleanup.
+     */
+    reset(): void;
+    cleanup(): void;
+}
+declare const micStateCoordinator: MicStateCoordinator;
+export default micStateCoordinator;
+//# sourceMappingURL=MicStateCoordinator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"MicStateCoordinator.d.ts","sourceRoot":"","sources":["../../src/services/MicStateCoordinator.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAoBH,cAAM,mBAAmB;IACvB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAmC;IAG1D,OAAO,CAAC,aAAa,CAAQ;IAC7B,OAAO,CAAC,aAAa,CAAQ;IAE7B,OAAO;WAEO,WAAW,IAAI,mBAAmB;IAOhD;;;OAGG;IACI,oBAAoB,CAAC,GAAG,EAAE;QAAC,GAAG,EAAE,OAAO,CAAC;QAAC,GAAG,EAAE,OAAO,CAAA;KAAC,GAAG,IAAI;IAOpE;;;OAGG;IACH,OAAO,CAAC,UAAU;IAiBlB;;OAEG;IACI,KAAK,IAAI,IAAI;IAMb,OAAO,IAAI,IAAI;CAKvB;AAED,QAAA,MAAM,mBAAmB,qBAAoC,CAAA;AAC7D,eAAe,mBAAmB,CAAA"}

package/build/services/MicStateCoordinator.js

@@ -0,0 +1,81 @@
+/**
+ * MicStateCoordinator
+ *
+ * Owns local-miniapp-driven microphone requirements.
+ *
+ * Local miniapps subscribe to audio_chunk / transcription streams.
+ * This coordinator pushes the aggregate local requirement set to BluetoothSdk
+ * so the mic runs whenever at least one local consumer needs it.
+ */
+import BluetoothSdk from "@mentra/bluetooth-sdk/internal";
+import { createDebouncedPatchFlusher } from "../utils/debouncedPatch";
+const LOG_TAG = "MIC_COORDINATOR";
+/** Mic-requirement flips are debounced (300ms) and merged into one BLE write
+ *  (wire v2 keeps BLE JSON small and infrequent). */
+const flushMicRequirementsPatch = createDebouncedPatchFlusher((patch) => {
+    try {
+        void Promise.resolve(BluetoothSdk.updateBluetoothSettings(patch)).catch((err) => {
+            console.error(`${LOG_TAG}: failed to apply mic requirements:`, err);
+        });
+    }
+    catch (err) {
+        console.error(`${LOG_TAG}: failed to apply mic requirements:`, err);
+    }
+}, 300);
+class MicStateCoordinator {
+    static instance = null;
+    // Local miniapp requirements (set when miniapps subscribe to audio streams)
+    localWantsPcm = false;
+    localWantsLc3 = false;
+    constructor() { }
+    static getInstance() {
+        if (!MicStateCoordinator.instance) {
+            MicStateCoordinator.instance = new MicStateCoordinator();
+        }
+        return MicStateCoordinator.instance;
+    }
+    /**
+     * Update local miniapp requirements. Called by LocalMiniappRuntime when
+     * the aggregated set of local subscriptions changes.
+     */
+    setLocalRequirements(req) {
+        this.localWantsPcm = req.pcm;
+        this.localWantsLc3 = req.lc3;
+        console.log(`${LOG_TAG}: local requirements updated — pcm=${req.pcm} lc3=${req.lc3}`);
+        this.applyUnion();
+    }
+    /**
+     * Push local requirements to BluetoothSdk. `should_send_pcm` is strictly for
+     * on-device PCM consumers; cloud audio uses LC3 through AudioCloudUplink.
+     */
+    applyUnion() {
+        const shouldSendPcm = this.localWantsPcm;
+        const shouldSendLc3 = this.localWantsLc3;
+        // console.log(
+        //   `${LOG_TAG}: applying requirements — pcm=${shouldSendPcm} lc3=${shouldSendLc3}`,
+        // )
+        // The mic control plane is a direct btsdk call now (was a host setMicRequirements
+        // hook) so a bare OEM streams audio without wiring it.
+        flushMicRequirementsPatch({
+            should_send_pcm: shouldSendPcm,
+            should_send_lc3: shouldSendLc3,
+            should_send_transcript: false,
+        });
+    }
+    /**
+     * Reset all requirements to off. Called during cleanup.
+     */
+    reset() {
+        this.localWantsPcm = false;
+        this.localWantsLc3 = false;
+        this.applyUnion();
+    }
+    cleanup() {
+        console.log(`${LOG_TAG}: cleanup()`);
+        this.reset();
+        MicStateCoordinator.instance = null;
+    }
+}
+const micStateCoordinator = MicStateCoordinator.getInstance();
+export default micStateCoordinator;
+//# sourceMappingURL=MicStateCoordinator.js.map

package/build/services/MicStateCoordinator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MicStateCoordinator.js","sourceRoot":"","sources":["../../src/services/MicStateCoordinator.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,YAAY,MAAM,gCAAgC,CAAA;AAEzD,OAAO,EAAC,2BAA2B,EAAC,MAAM,yBAAyB,CAAA;AAEnE,MAAM,OAAO,GAAG,iBAAiB,CAAA;AAEjC;qDACqD;AACrD,MAAM,yBAAyB,GAAG,2BAA2B,CAA0B,CAAC,KAAK,EAAE,EAAE;IAC/F,IAAI,CAAC;QACH,KAAK,OAAO,CAAC,OAAO,CAAC,YAAY,CAAC,uBAAuB,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;YAC9E,OAAO,CAAC,KAAK,CAAC,GAAG,OAAO,qCAAqC,EAAE,GAAG,CAAC,CAAA;QACrE,CAAC,CAAC,CAAA;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,KAAK,CAAC,GAAG,OAAO,qCAAqC,EAAE,GAAG,CAAC,CAAA;IACrE,CAAC;AACH,CAAC,EAAE,GAAG,CAAC,CAAA;AAEP,MAAM,mBAAmB;IACf,MAAM,CAAC,QAAQ,GAA+B,IAAI,CAAA;IAE1D,4EAA4E;IACpE,aAAa,GAAG,KAAK,CAAA;IACrB,aAAa,GAAG,KAAK,CAAA;IAE7B,gBAAuB,CAAC;IAEjB,MAAM,CAAC,WAAW;QACvB,IAAI,CAAC,mBAAmB,CAAC,QAAQ,EAAE,CAAC;YAClC,mBAAmB,CAAC,QAAQ,GAAG,IAAI,mBAAmB,EAAE,CAAA;QAC1D,CAAC;QACD,OAAO,mBAAmB,CAAC,QAAQ,CAAA;IACrC,CAAC;IAED;;;OAGG;IACI,oBAAoB,CAAC,GAAiC;QAC3D,IAAI,CAAC,aAAa,GAAG,GAAG,CAAC,GAAG,CAAA;QAC5B,IAAI,CAAC,aAAa,GAAG,GAAG,CAAC,GAAG,CAAA;QAC5B,OAAO,CAAC,GAAG,CAAC,GAAG,OAAO,sCAAsC,GAAG,CAAC,GAAG,QAAQ,GAAG,CAAC,GAAG,EAAE,CAAC,CAAA;QACrF,IAAI,CAAC,UAAU,EAAE,CAAA;IACnB,CAAC;IAED;;;OAGG;IACK,UAAU;QAChB,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,CAAA;QACxC,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,CAAA;QAExC,eAAe;QACf,qFAAqF;QACrF,IAAI;QAEJ,kFAAkF;QAClF,uDAAuD;QACvD,yBAAyB,CAAC;YACxB,eAAe,EAAE,aAAa;YAC9B,eAAe,EAAE,aAAa;YAC9B,sBAAsB,EAAE,KAAK;SAC9B,CAAC,CAAA;IACJ,CAAC;IAED;;OAEG;IACI,KAAK;QACV,IAAI,CAAC,aAAa,GAAG,KAAK,CAAA;QAC1B,IAAI,CAAC,aAAa,GAAG,KAAK,CAAA;QAC1B,IAAI,CAAC,UAAU,EAAE,CAAA;IACnB,CAAC;IAEM,OAAO;QACZ,OAAO,CAAC,GAAG,CAAC,GAAG,OAAO,aAAa,CAAC,CAAA;QACpC,IAAI,CAAC,KAAK,EAAE,CAAA;QACZ,mBAAmB,CAAC,QAAQ,GAAG,IAAI,CAAA;IACrC,CAAC;;AAGH,MAAM,mBAAmB,GAAG,mBAAmB,CAAC,WAAW,EAAE,CAAA;AAC7D,eAAe,mBAAmB,CAAA","sourcesContent":["/**\n * MicStateCoordinator\n *\n * Owns local-miniapp-driven microphone requirements.\n *\n * Local miniapps subscribe to audio_chunk / transcription streams.\n * This coordinator pushes the aggregate local requirement set to BluetoothSdk\n * so the mic runs whenever at least one local consumer needs it.\n */\n\nimport BluetoothSdk from \"@mentra/bluetooth-sdk/internal\"\n\nimport {createDebouncedPatchFlusher} from \"../utils/debouncedPatch\"\n\nconst LOG_TAG = \"MIC_COORDINATOR\"\n\n/** Mic-requirement flips are debounced (300ms) and merged into one BLE write\n *  (wire v2 keeps BLE JSON small and infrequent). */\nconst flushMicRequirementsPatch = createDebouncedPatchFlusher<Record<string, unknown>>((patch) => {\n  try {\n    void Promise.resolve(BluetoothSdk.updateBluetoothSettings(patch)).catch((err) => {\n      console.error(`${LOG_TAG}: failed to apply mic requirements:`, err)\n    })\n  } catch (err) {\n    console.error(`${LOG_TAG}: failed to apply mic requirements:`, err)\n  }\n}, 300)\n\nclass MicStateCoordinator {\n  private static instance: MicStateCoordinator | null = null\n\n  // Local miniapp requirements (set when miniapps subscribe to audio streams)\n  private localWantsPcm = false\n  private localWantsLc3 = false\n\n  private constructor() {}\n\n  public static getInstance(): MicStateCoordinator {\n    if (!MicStateCoordinator.instance) {\n      MicStateCoordinator.instance = new MicStateCoordinator()\n    }\n    return MicStateCoordinator.instance\n  }\n\n  /**\n   * Update local miniapp requirements. Called by LocalMiniappRuntime when\n   * the aggregated set of local subscriptions changes.\n   */\n  public setLocalRequirements(req: {pcm: boolean; lc3: boolean}): void {\n    this.localWantsPcm = req.pcm\n    this.localWantsLc3 = req.lc3\n    console.log(`${LOG_TAG}: local requirements updated — pcm=${req.pcm} lc3=${req.lc3}`)\n    this.applyUnion()\n  }\n\n  /**\n   * Push local requirements to BluetoothSdk. `should_send_pcm` is strictly for\n   * on-device PCM consumers; cloud audio uses LC3 through AudioCloudUplink.\n   */\n  private applyUnion(): void {\n    const shouldSendPcm = this.localWantsPcm\n    const shouldSendLc3 = this.localWantsLc3\n\n    // console.log(\n    //   `${LOG_TAG}: applying requirements — pcm=${shouldSendPcm} lc3=${shouldSendLc3}`,\n    // )\n\n    // The mic control plane is a direct btsdk call now (was a host setMicRequirements\n    // hook) so a bare OEM streams audio without wiring it.\n    flushMicRequirementsPatch({\n      should_send_pcm: shouldSendPcm,\n      should_send_lc3: shouldSendLc3,\n      should_send_transcript: false,\n    })\n  }\n\n  /**\n   * Reset all requirements to off. Called during cleanup.\n   */\n  public reset(): void {\n    this.localWantsPcm = false\n    this.localWantsLc3 = false\n    this.applyUnion()\n  }\n\n  public cleanup(): void {\n    console.log(`${LOG_TAG}: cleanup()`)\n    this.reset()\n    MicStateCoordinator.instance = null\n  }\n}\n\nconst micStateCoordinator = MicStateCoordinator.getInstance()\nexport default micStateCoordinator\n"]}

package/build/services/MiniappEngine.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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 { MentraJSCrashController } from "./MentraJSCrashController";
+import { MentraJSRouter } from "./MentraJSRouter";
+import { MentraUIRouter } from "./MentraUIRouter";
+export interface MiniappEngine {
+    router: MentraJSRouter;
+    uiRouter: MentraUIRouter;
+    crashController: MentraJSCrashController;
+}
+/**
+ * Construct (once) and return the MentraJS engine singletons. Starts the router's
+ * message pump on first call. Subsequent calls return the same instances.
+ */
+export declare function ensureMiniappEngine(): MiniappEngine;
+/** Stop the MentraJS message pump and tear down router-managed JSContexts. */
+export declare function stopMiniappEngine(): Promise<void>;
+/** Returns the engine singletons if already constructed, else null. */
+export declare function getMiniappEngine(): MiniappEngine | null;
+//# sourceMappingURL=MiniappEngine.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"MiniappEngine.d.ts","sourceRoot":"","sources":["../../src/services/MiniappEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAOH,OAAO,EAAC,uBAAuB,EAAC,MAAM,2BAA2B,CAAA;AACjE,OAAO,EAAC,cAAc,EAA4B,MAAM,kBAAkB,CAAA;AAC1E,OAAO,EAAC,cAAc,EAAC,MAAM,kBAAkB,CAAA;AAE/C,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,cAAc,CAAA;IACtB,QAAQ,EAAE,cAAc,CAAA;IACxB,eAAe,EAAE,uBAAuB,CAAA;CACzC;AAwCD;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,aAAa,CAyCnD;AAED,8EAA8E;AAC9E,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAsBvD;AAED,uEAAuE;AACvE,wBAAgB,gBAAgB,IAAI,aAAa,GAAG,IAAI,CAEvD"}