@mentra/engine 0.1.0-beta.0

package/build/services/mentraUiShim.d.ts

@@ -0,0 +1,38 @@
+/**
+ * window.mentra — WebView-side bridge to the per-miniapp background JSContext.
+ *
+ * Injected into every UI WebView via `injectedJavaScriptBeforeContentLoaded`
+ * (iOS) or `injectedJavaScriptObject` + a bundler-emitted inline `<script>`
+ * (Android, where the `BeforeContentLoaded` prop is documented unreliable
+ * per react-native-webview issues #1099 / #1609).
+ *
+ * The shim:
+ *   - Buffers `mentra.send(channel, payload)` calls until `mentra.ready()`
+ *     fires + the host acks the channel is open. WebView-side BUFFERS (the
+ *     WebView is the short-lived side and shouldn't drop user input).
+ *   - Installs `window.__mentra.recv(envelope)` for the host to push
+ *     background → WebView messages via `webview.injectJavaScript(...)`.
+ *   - Sends `__heartbeat__` every 5s; host considers the WebView gone
+ *     after 15s of silence.
+ *   - Maintains monotonic seq numbers; the host's per-WebView dedup window
+ *     drops replays during reconnect.
+ *
+ * This file exports a `buildMentraUiShim()` function returning the JS
+ * source as a string. The host's MentraUIRouter wraps it inside the
+ * existing WebView setup so a single bundler-time string emission covers
+ * both platforms.
+ *
+ * IMPORTANT: the shim runs in the WebView's bare ECMAScript scope before
+ * the miniapp's bundle. It must not import anything; the source is one
+ * IIFE. The only injected dependencies are
+ * `window.ReactNativeWebView.postMessage` (provided by react-native-webview)
+ * and (on Android) `window.ReactNativeWebView.injectedObjectJson()`
+ * (provided when the host sets `injectedJavaScriptObject`).
+ */
+export interface MentraUiShimOptions {
+    packageName: string;
+    /** @deprecated No longer used — heartbeat removed since WebViews are foreground-only. */
+    heartbeatIntervalMs?: number;
+}
+export declare function buildMentraUiShim(options: MentraUiShimOptions): string;
+//# sourceMappingURL=mentraUiShim.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mentraUiShim.d.ts","sourceRoot":"","sources":["../../src/services/mentraUiShim.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAA;IACnB,yFAAyF;IACzF,mBAAmB,CAAC,EAAE,MAAM,CAAA;CAC7B;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,CAuUtE"}

package/build/services/mentraUiShim.js

@@ -0,0 +1,360 @@
+/**
+ * window.mentra — WebView-side bridge to the per-miniapp background JSContext.
+ *
+ * Injected into every UI WebView via `injectedJavaScriptBeforeContentLoaded`
+ * (iOS) or `injectedJavaScriptObject` + a bundler-emitted inline `<script>`
+ * (Android, where the `BeforeContentLoaded` prop is documented unreliable
+ * per react-native-webview issues #1099 / #1609).
+ *
+ * The shim:
+ *   - Buffers `mentra.send(channel, payload)` calls until `mentra.ready()`
+ *     fires + the host acks the channel is open. WebView-side BUFFERS (the
+ *     WebView is the short-lived side and shouldn't drop user input).
+ *   - Installs `window.__mentra.recv(envelope)` for the host to push
+ *     background → WebView messages via `webview.injectJavaScript(...)`.
+ *   - Sends `__heartbeat__` every 5s; host considers the WebView gone
+ *     after 15s of silence.
+ *   - Maintains monotonic seq numbers; the host's per-WebView dedup window
+ *     drops replays during reconnect.
+ *
+ * This file exports a `buildMentraUiShim()` function returning the JS
+ * source as a string. The host's MentraUIRouter wraps it inside the
+ * existing WebView setup so a single bundler-time string emission covers
+ * both platforms.
+ *
+ * IMPORTANT: the shim runs in the WebView's bare ECMAScript scope before
+ * the miniapp's bundle. It must not import anything; the source is one
+ * IIFE. The only injected dependencies are
+ * `window.ReactNativeWebView.postMessage` (provided by react-native-webview)
+ * and (on Android) `window.ReactNativeWebView.injectedObjectJson()`
+ * (provided when the host sets `injectedJavaScriptObject`).
+ */
+export function buildMentraUiShim(options) {
+    const packageNameJson = JSON.stringify(options.packageName);
+    // The IIFE assembles a typed `mentra` global plus an internal
+    // `__mentra` for host inbound calls. Quoted strings are JSON-safe so
+    // direct injection inside another JS literal also works.
+    return `
+(function () {
+  if (typeof window === 'undefined') return;
+  if (window.mentra && window.__mentra) return;
+  var packageName = ${packageNameJson};
+  // Resolve window.ReactNativeWebView.postMessage LAZILY, not once at shim-eval.
+  // On Android the shim is injected as a WebViewCompat document-start script
+  // (so it beats the page bundle and the ready handshake can't be raced — see
+  // the react-native-webview patch). But the order in which that document-start
+  // script runs vs. the WebMessageListener that installs
+  // window.ReactNativeWebView is not contractually fixed on Android the way it
+  // is on iOS (postMessageScript is registered before atStartScript there). If
+  // we captured rnPost once and the bridge object wasn't installed yet, every
+  // postMessage — including {type:'ready'} — would be silently dropped and the
+  // splash would hang forever. Resolving per-call means we always pick up the
+  // bridge once it exists, which it reliably does by the time the bundle mounts
+  // and calls mentra.ready().
+  function getRnPost() {
+    try {
+      return window.ReactNativeWebView && typeof window.ReactNativeWebView.postMessage === 'function'
+        ? window.ReactNativeWebView.postMessage.bind(window.ReactNativeWebView)
+        : null;
+    } catch (e) { return null; }
+  }
+
+  // Outbound seq number — purely a log-correlation aid (the host's
+  // router doesn't dedup anymore since reconnect can't happen: one
+  // WebView, foreground-only, destroyed on close → fresh shim on
+  // next open).
+  var outboundSeq = 1;
+  var ready = false;
+  var channelHandlers = Object.create(null);
+  var openHandlers = [];
+  var closeHandlers = [];
+  // Queued mentra.send calls before mentra.ready() acks. FIFO drained
+  // on ack. Buffered so user input (button taps, etc.) isn't dropped
+  // when the WebView mounts faster than the host expects.
+  var outboundQueue = [];
+  // Inbound payloads that arrived before any mentra.on subscriber was
+  // registered for the channel. The background side fires
+  // session.ui.onOpen handlers as soon as the WebView posts {type:'ready'},
+  // and on a fast bridge the resulting ui.send round-trips back before
+  // React useEffects have had a chance to attach listeners. Without
+  // buffering, the very first snapshot (the one a controller pushes from
+  // its ui.onOpen handler to hydrate the fresh UI) is silently dropped.
+  //
+  // Drain policy: the queue for a channel is flushed into the FIRST
+  // mentra.on(channel, ...) subscriber, then discarded. Subsequent
+  // sends with no listener fall back to the old drop-on-floor behaviour
+  // — we don't want a re-subscribe to replay stale state.
+  //
+  // Cap: 32 entries per channel, oldest dropped on overflow. Bounds the
+  // memory cost when a controller pushes to a channel that no UI page
+  // ever subscribes to.
+  var pendingByChannel = Object.create(null);
+  var PENDING_CAP_PER_CHANNEL = 32;
+
+  function postEnvelope(envelope) {
+    var rnPost = getRnPost();
+    if (!rnPost) return;
+    try { rnPost(JSON.stringify(envelope)); } catch (_) {}
+  }
+
+  function send(channel, payload) {
+    var seq = outboundSeq++;
+    var envelope = { type: 'msg', seq: seq, channel: String(channel), payload: payload };
+    if (!ready) {
+      outboundQueue.push(envelope);
+      return;
+    }
+    postEnvelope(envelope);
+  }
+
+  function flushQueue() {
+    while (outboundQueue.length > 0) {
+      postEnvelope(outboundQueue.shift());
+    }
+  }
+
+  // NOTE: console.* tap lives in miniappGlobals.ts (injected alongside
+  // this shim for every UI WebView, two-layer or single-bundle). That
+  // shim posts {payload:{type:"dev_log", ...}} envelopes which
+  // LocalMiniappRuntime forwards to the dev sidecar tagged source:"ui".
+  // We don't re-wrap here to avoid double-delivery.
+
+  function on(channel, cb) {
+    if (typeof cb !== 'function') return function () {};
+    var list = channelHandlers[channel];
+    var firstSubscriber = !list || list.length === 0;
+    if (!list) { list = []; channelHandlers[channel] = list; }
+    list.push(cb);
+    // Drain any payloads buffered before this channel had a listener.
+    // Only fired on the first subscriber for the channel — a later
+    // re-subscribe (after an unsubscribe) does NOT replay history.
+    if (firstSubscriber) {
+      var pending = pendingByChannel[channel];
+      if (pending) {
+        delete pendingByChannel[channel];
+        for (var i = 0; i < pending.length; i++) {
+          try { cb(pending[i]); } catch (e) {}
+        }
+      }
+    }
+    return function () {
+      var idx = list.indexOf(cb);
+      if (idx >= 0) list.splice(idx, 1);
+    };
+  }
+
+  // ── RPC ─────────────────────────────────────────────────────────────
+  // Outbound RPC: every mentra.request() generates a request id, sends a
+  // 'msg' envelope tagged with requestId, and stashes a one-shot resolver
+  // keyed on the id. The background-side reply is a recv('msg') with the
+  // same channel + requestId; we route it directly to the resolver.
+  //
+  // Cancellation: caller's AbortSignal triggers a 'cancel' envelope to
+  // background and rejects the local promise with a DOM-standard
+  // AbortError. The background side's UI_CANCEL handler aborts the
+  // handler's ctx.signal and drops the reply.
+  var rpcCounter = 0;
+  var rpcInflight = Object.create(null);
+
+  function makeRequestId() {
+    rpcCounter += 1;
+    return 'r' + rpcCounter + '-' + Date.now().toString(36) + '-' + Math.random().toString(36).slice(2, 8);
+  }
+
+  function MentraRpcError(message, code, stage, transport) {
+    var e = new Error(message);
+    e.name = 'MentraRpcError';
+    if (code) {
+      try { e.cause = {code: code}; } catch (_) { /* old runtimes */ }
+      e.code = code;
+    }
+    // Diagnostic fields ride as own props so a miniapp can show exactly which
+    // pipeline stage and transport failed, not just a message string.
+    if (stage) e.stage = stage;
+    if (transport) e.transport = transport;
+    return e;
+  }
+
+  function MentraRpcTimeoutError(message) {
+    var e = new Error(message || 'RPC timed out');
+    e.name = 'MentraRpcTimeoutError';
+    return e;
+  }
+
+  function MentraAbortError() {
+    var e;
+    try { e = new DOMException('aborted', 'AbortError'); } catch (_) {
+      e = new Error('aborted');
+      e.name = 'AbortError';
+    }
+    return e;
+  }
+
+  function request(channel, payload, options) {
+    var opts = options || {};
+    var signal = opts.signal;
+    var timeoutMs = typeof opts.timeout === 'number' ? opts.timeout : null;
+    var id = makeRequestId();
+
+    return new Promise(function (resolve, reject) {
+      var done = false;
+      var timeoutHandle = null;
+      var abortListener = null;
+
+      function cleanup() {
+        if (done) return;
+        done = true;
+        delete rpcInflight[id];
+        if (timeoutHandle != null) { clearTimeout(timeoutHandle); timeoutHandle = null; }
+        if (signal && abortListener) {
+          try { signal.removeEventListener('abort', abortListener); } catch (_) {}
+        }
+      }
+
+      function settle(envelope) {
+        if (done) return;
+        cleanup();
+        if (envelope && envelope.ok === true) {
+          resolve(envelope.result);
+        } else if (envelope && envelope.ok === false) {
+          reject(MentraRpcError(envelope.error && envelope.error.message || 'RPC failed', envelope.error && envelope.error.code, envelope.error && envelope.error.stage, envelope.error && envelope.error.transport));
+        } else {
+          reject(MentraRpcError('malformed RPC reply'));
+        }
+      }
+
+      rpcInflight[id] = settle;
+
+      if (signal) {
+        if (signal.aborted) {
+          cleanup();
+          reject(MentraAbortError());
+          return;
+        }
+        abortListener = function () {
+          if (done) return;
+          cleanup();
+          postEnvelope({type: 'cancel', requestId: id});
+          reject(MentraAbortError());
+        };
+        try { signal.addEventListener('abort', abortListener); } catch (_) {}
+      }
+
+      if (timeoutMs != null) {
+        timeoutHandle = setTimeout(function () {
+          if (done) return;
+          cleanup();
+          postEnvelope({type: 'cancel', requestId: id});
+          reject(MentraRpcTimeoutError());
+        }, timeoutMs);
+      }
+
+      var envelope = {type: 'msg', seq: outboundSeq++, channel: String(channel), payload: payload, requestId: id};
+      if (!ready) {
+        outboundQueue.push(envelope);
+        return;
+      }
+      postEnvelope(envelope);
+    });
+  }
+
+  function onOpen(cb) {
+    if (typeof cb !== 'function') return function () {};
+    openHandlers.push(cb);
+    if (ready) {
+      try { cb(); } catch (e) {}
+    }
+    return function () {
+      var idx = openHandlers.indexOf(cb);
+      if (idx >= 0) openHandlers.splice(idx, 1);
+    };
+  }
+
+  function onClose(cb) {
+    if (typeof cb !== 'function') return function () {};
+    closeHandlers.push(cb);
+    return function () {
+      var idx = closeHandlers.indexOf(cb);
+      if (idx >= 0) closeHandlers.splice(idx, 1);
+    };
+  }
+
+  function readyFn() {
+    if (ready) return;
+    ready = true;
+    postEnvelope({ type: 'ready' });
+    flushQueue();
+    for (var i = 0; i < openHandlers.length; i++) {
+      try { openHandlers[i](); } catch (e) {}
+    }
+  }
+
+  function fireChannel(channel, payload) {
+    var list = channelHandlers[channel];
+    if (!list || list.length === 0) {
+      // No subscriber yet — stash for the first mentra.on(channel, ...).
+      // Bounded FIFO: drop the oldest when capped so a stuck channel
+      // can't grow unbounded.
+      var q = pendingByChannel[channel];
+      if (!q) { q = []; pendingByChannel[channel] = q; }
+      q.push(payload);
+      if (q.length > PENDING_CAP_PER_CHANNEL) q.shift();
+      return;
+    }
+    for (var i = 0; i < list.length; i++) {
+      try { list[i](payload); } catch (e) {}
+    }
+  }
+
+  function recv(envelope) {
+    if (!envelope || typeof envelope !== 'object') return;
+    var type = envelope.type;
+    if (type === 'msg' && typeof envelope.channel === 'string') {
+      // RPC frames carry a requestId; broadcast frames don't. Treat them
+      // as disjoint — never fall through from RPC to broadcast. An orphan
+      // RPC reply (caller already aborted/timed out) is silently dropped.
+      if (typeof envelope.requestId === 'string') {
+        var settle = rpcInflight[envelope.requestId];
+        if (settle) settle(envelope.payload);
+        return;
+      }
+      fireChannel(envelope.channel, envelope.payload);
+      return;
+    }
+    if (type === 'open') {
+      for (var j = 0; j < openHandlers.length; j++) {
+        try { openHandlers[j](); } catch (e) {}
+      }
+      return;
+    }
+    if (type === 'close') {
+      for (var k = 0; k < closeHandlers.length; k++) {
+        try { closeHandlers[k](); } catch (e) {}
+      }
+      return;
+    }
+    if (type === 'cancel' && typeof envelope.requestId === 'string') {
+      // Background-side cancel (reserved; currently unused). If we had a
+      // future bidirectional RPC this would abort an in-flight UI handler.
+      return;
+    }
+    if (type === 'ack') {
+      return;
+    }
+  }
+
+  window.mentra = {
+    send: send,
+    on: on,
+    request: request,
+    onOpen: onOpen,
+    onClose: onClose,
+    ready: readyFn,
+    /** @internal — packageName for diagnostic logs only. */
+    _packageName: packageName,
+  };
+  window.__mentra = { recv: recv };
+})();
+`.trim();
+}
+//# sourceMappingURL=mentraUiShim.js.map

package/build/services/mentraUiShim.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mentraUiShim.js","sourceRoot":"","sources":["../../src/services/mentraUiShim.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAQH,MAAM,UAAU,iBAAiB,CAAC,OAA4B;IAC5D,MAAM,eAAe,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,WAAW,CAAC,CAAA;IAC3D,8DAA8D;IAC9D,qEAAqE;IACrE,yDAAyD;IACzD,OAAO;;;;sBAIa,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6TpC,CAAC,IAAI,EAAE,CAAA;AACR,CAAC","sourcesContent":["/**\n * window.mentra — WebView-side bridge to the per-miniapp background JSContext.\n *\n * Injected into every UI WebView via `injectedJavaScriptBeforeContentLoaded`\n * (iOS) or `injectedJavaScriptObject` + a bundler-emitted inline `<script>`\n * (Android, where the `BeforeContentLoaded` prop is documented unreliable\n * per react-native-webview issues #1099 / #1609).\n *\n * The shim:\n *   - Buffers `mentra.send(channel, payload)` calls until `mentra.ready()`\n *     fires + the host acks the channel is open. WebView-side BUFFERS (the\n *     WebView is the short-lived side and shouldn't drop user input).\n *   - Installs `window.__mentra.recv(envelope)` for the host to push\n *     background → WebView messages via `webview.injectJavaScript(...)`.\n *   - Sends `__heartbeat__` every 5s; host considers the WebView gone\n *     after 15s of silence.\n *   - Maintains monotonic seq numbers; the host's per-WebView dedup window\n *     drops replays during reconnect.\n *\n * This file exports a `buildMentraUiShim()` function returning the JS\n * source as a string. The host's MentraUIRouter wraps it inside the\n * existing WebView setup so a single bundler-time string emission covers\n * both platforms.\n *\n * IMPORTANT: the shim runs in the WebView's bare ECMAScript scope before\n * the miniapp's bundle. It must not import anything; the source is one\n * IIFE. The only injected dependencies are\n * `window.ReactNativeWebView.postMessage` (provided by react-native-webview)\n * and (on Android) `window.ReactNativeWebView.injectedObjectJson()`\n * (provided when the host sets `injectedJavaScriptObject`).\n */\n\nexport interface MentraUiShimOptions {\n  packageName: string\n  /** @deprecated No longer used — heartbeat removed since WebViews are foreground-only. */\n  heartbeatIntervalMs?: number\n}\n\nexport function buildMentraUiShim(options: MentraUiShimOptions): string {\n  const packageNameJson = JSON.stringify(options.packageName)\n  // The IIFE assembles a typed `mentra` global plus an internal\n  // `__mentra` for host inbound calls. Quoted strings are JSON-safe so\n  // direct injection inside another JS literal also works.\n  return `\n(function () {\n  if (typeof window === 'undefined') return;\n  if (window.mentra && window.__mentra) return;\n  var packageName = ${packageNameJson};\n  // Resolve window.ReactNativeWebView.postMessage LAZILY, not once at shim-eval.\n  // On Android the shim is injected as a WebViewCompat document-start script\n  // (so it beats the page bundle and the ready handshake can't be raced — see\n  // the react-native-webview patch). But the order in which that document-start\n  // script runs vs. the WebMessageListener that installs\n  // window.ReactNativeWebView is not contractually fixed on Android the way it\n  // is on iOS (postMessageScript is registered before atStartScript there). If\n  // we captured rnPost once and the bridge object wasn't installed yet, every\n  // postMessage — including {type:'ready'} — would be silently dropped and the\n  // splash would hang forever. Resolving per-call means we always pick up the\n  // bridge once it exists, which it reliably does by the time the bundle mounts\n  // and calls mentra.ready().\n  function getRnPost() {\n    try {\n      return window.ReactNativeWebView && typeof window.ReactNativeWebView.postMessage === 'function'\n        ? window.ReactNativeWebView.postMessage.bind(window.ReactNativeWebView)\n        : null;\n    } catch (e) { return null; }\n  }\n\n  // Outbound seq number — purely a log-correlation aid (the host's\n  // router doesn't dedup anymore since reconnect can't happen: one\n  // WebView, foreground-only, destroyed on close → fresh shim on\n  // next open).\n  var outboundSeq = 1;\n  var ready = false;\n  var channelHandlers = Object.create(null);\n  var openHandlers = [];\n  var closeHandlers = [];\n  // Queued mentra.send calls before mentra.ready() acks. FIFO drained\n  // on ack. Buffered so user input (button taps, etc.) isn't dropped\n  // when the WebView mounts faster than the host expects.\n  var outboundQueue = [];\n  // Inbound payloads that arrived before any mentra.on subscriber was\n  // registered for the channel. The background side fires\n  // session.ui.onOpen handlers as soon as the WebView posts {type:'ready'},\n  // and on a fast bridge the resulting ui.send round-trips back before\n  // React useEffects have had a chance to attach listeners. Without\n  // buffering, the very first snapshot (the one a controller pushes from\n  // its ui.onOpen handler to hydrate the fresh UI) is silently dropped.\n  //\n  // Drain policy: the queue for a channel is flushed into the FIRST\n  // mentra.on(channel, ...) subscriber, then discarded. Subsequent\n  // sends with no listener fall back to the old drop-on-floor behaviour\n  // — we don't want a re-subscribe to replay stale state.\n  //\n  // Cap: 32 entries per channel, oldest dropped on overflow. Bounds the\n  // memory cost when a controller pushes to a channel that no UI page\n  // ever subscribes to.\n  var pendingByChannel = Object.create(null);\n  var PENDING_CAP_PER_CHANNEL = 32;\n\n  function postEnvelope(envelope) {\n    var rnPost = getRnPost();\n    if (!rnPost) return;\n    try { rnPost(JSON.stringify(envelope)); } catch (_) {}\n  }\n\n  function send(channel, payload) {\n    var seq = outboundSeq++;\n    var envelope = { type: 'msg', seq: seq, channel: String(channel), payload: payload };\n    if (!ready) {\n      outboundQueue.push(envelope);\n      return;\n    }\n    postEnvelope(envelope);\n  }\n\n  function flushQueue() {\n    while (outboundQueue.length > 0) {\n      postEnvelope(outboundQueue.shift());\n    }\n  }\n\n  // NOTE: console.* tap lives in miniappGlobals.ts (injected alongside\n  // this shim for every UI WebView, two-layer or single-bundle). That\n  // shim posts {payload:{type:\"dev_log\", ...}} envelopes which\n  // LocalMiniappRuntime forwards to the dev sidecar tagged source:\"ui\".\n  // We don't re-wrap here to avoid double-delivery.\n\n  function on(channel, cb) {\n    if (typeof cb !== 'function') return function () {};\n    var list = channelHandlers[channel];\n    var firstSubscriber = !list || list.length === 0;\n    if (!list) { list = []; channelHandlers[channel] = list; }\n    list.push(cb);\n    // Drain any payloads buffered before this channel had a listener.\n    // Only fired on the first subscriber for the channel — a later\n    // re-subscribe (after an unsubscribe) does NOT replay history.\n    if (firstSubscriber) {\n      var pending = pendingByChannel[channel];\n      if (pending) {\n        delete pendingByChannel[channel];\n        for (var i = 0; i < pending.length; i++) {\n          try { cb(pending[i]); } catch (e) {}\n        }\n      }\n    }\n    return function () {\n      var idx = list.indexOf(cb);\n      if (idx >= 0) list.splice(idx, 1);\n    };\n  }\n\n  // ── RPC ─────────────────────────────────────────────────────────────\n  // Outbound RPC: every mentra.request() generates a request id, sends a\n  // 'msg' envelope tagged with requestId, and stashes a one-shot resolver\n  // keyed on the id. The background-side reply is a recv('msg') with the\n  // same channel + requestId; we route it directly to the resolver.\n  //\n  // Cancellation: caller's AbortSignal triggers a 'cancel' envelope to\n  // background and rejects the local promise with a DOM-standard\n  // AbortError. The background side's UI_CANCEL handler aborts the\n  // handler's ctx.signal and drops the reply.\n  var rpcCounter = 0;\n  var rpcInflight = Object.create(null);\n\n  function makeRequestId() {\n    rpcCounter += 1;\n    return 'r' + rpcCounter + '-' + Date.now().toString(36) + '-' + Math.random().toString(36).slice(2, 8);\n  }\n\n  function MentraRpcError(message, code, stage, transport) {\n    var e = new Error(message);\n    e.name = 'MentraRpcError';\n    if (code) {\n      try { e.cause = {code: code}; } catch (_) { /* old runtimes */ }\n      e.code = code;\n    }\n    // Diagnostic fields ride as own props so a miniapp can show exactly which\n    // pipeline stage and transport failed, not just a message string.\n    if (stage) e.stage = stage;\n    if (transport) e.transport = transport;\n    return e;\n  }\n\n  function MentraRpcTimeoutError(message) {\n    var e = new Error(message || 'RPC timed out');\n    e.name = 'MentraRpcTimeoutError';\n    return e;\n  }\n\n  function MentraAbortError() {\n    var e;\n    try { e = new DOMException('aborted', 'AbortError'); } catch (_) {\n      e = new Error('aborted');\n      e.name = 'AbortError';\n    }\n    return e;\n  }\n\n  function request(channel, payload, options) {\n    var opts = options || {};\n    var signal = opts.signal;\n    var timeoutMs = typeof opts.timeout === 'number' ? opts.timeout : null;\n    var id = makeRequestId();\n\n    return new Promise(function (resolve, reject) {\n      var done = false;\n      var timeoutHandle = null;\n      var abortListener = null;\n\n      function cleanup() {\n        if (done) return;\n        done = true;\n        delete rpcInflight[id];\n        if (timeoutHandle != null) { clearTimeout(timeoutHandle); timeoutHandle = null; }\n        if (signal && abortListener) {\n          try { signal.removeEventListener('abort', abortListener); } catch (_) {}\n        }\n      }\n\n      function settle(envelope) {\n        if (done) return;\n        cleanup();\n        if (envelope && envelope.ok === true) {\n          resolve(envelope.result);\n        } else if (envelope && envelope.ok === false) {\n          reject(MentraRpcError(envelope.error && envelope.error.message || 'RPC failed', envelope.error && envelope.error.code, envelope.error && envelope.error.stage, envelope.error && envelope.error.transport));\n        } else {\n          reject(MentraRpcError('malformed RPC reply'));\n        }\n      }\n\n      rpcInflight[id] = settle;\n\n      if (signal) {\n        if (signal.aborted) {\n          cleanup();\n          reject(MentraAbortError());\n          return;\n        }\n        abortListener = function () {\n          if (done) return;\n          cleanup();\n          postEnvelope({type: 'cancel', requestId: id});\n          reject(MentraAbortError());\n        };\n        try { signal.addEventListener('abort', abortListener); } catch (_) {}\n      }\n\n      if (timeoutMs != null) {\n        timeoutHandle = setTimeout(function () {\n          if (done) return;\n          cleanup();\n          postEnvelope({type: 'cancel', requestId: id});\n          reject(MentraRpcTimeoutError());\n        }, timeoutMs);\n      }\n\n      var envelope = {type: 'msg', seq: outboundSeq++, channel: String(channel), payload: payload, requestId: id};\n      if (!ready) {\n        outboundQueue.push(envelope);\n        return;\n      }\n      postEnvelope(envelope);\n    });\n  }\n\n  function onOpen(cb) {\n    if (typeof cb !== 'function') return function () {};\n    openHandlers.push(cb);\n    if (ready) {\n      try { cb(); } catch (e) {}\n    }\n    return function () {\n      var idx = openHandlers.indexOf(cb);\n      if (idx >= 0) openHandlers.splice(idx, 1);\n    };\n  }\n\n  function onClose(cb) {\n    if (typeof cb !== 'function') return function () {};\n    closeHandlers.push(cb);\n    return function () {\n      var idx = closeHandlers.indexOf(cb);\n      if (idx >= 0) closeHandlers.splice(idx, 1);\n    };\n  }\n\n  function readyFn() {\n    if (ready) return;\n    ready = true;\n    postEnvelope({ type: 'ready' });\n    flushQueue();\n    for (var i = 0; i < openHandlers.length; i++) {\n      try { openHandlers[i](); } catch (e) {}\n    }\n  }\n\n  function fireChannel(channel, payload) {\n    var list = channelHandlers[channel];\n    if (!list || list.length === 0) {\n      // No subscriber yet — stash for the first mentra.on(channel, ...).\n      // Bounded FIFO: drop the oldest when capped so a stuck channel\n      // can't grow unbounded.\n      var q = pendingByChannel[channel];\n      if (!q) { q = []; pendingByChannel[channel] = q; }\n      q.push(payload);\n      if (q.length > PENDING_CAP_PER_CHANNEL) q.shift();\n      return;\n    }\n    for (var i = 0; i < list.length; i++) {\n      try { list[i](payload); } catch (e) {}\n    }\n  }\n\n  function recv(envelope) {\n    if (!envelope || typeof envelope !== 'object') return;\n    var type = envelope.type;\n    if (type === 'msg' && typeof envelope.channel === 'string') {\n      // RPC frames carry a requestId; broadcast frames don't. Treat them\n      // as disjoint — never fall through from RPC to broadcast. An orphan\n      // RPC reply (caller already aborted/timed out) is silently dropped.\n      if (typeof envelope.requestId === 'string') {\n        var settle = rpcInflight[envelope.requestId];\n        if (settle) settle(envelope.payload);\n        return;\n      }\n      fireChannel(envelope.channel, envelope.payload);\n      return;\n    }\n    if (type === 'open') {\n      for (var j = 0; j < openHandlers.length; j++) {\n        try { openHandlers[j](); } catch (e) {}\n      }\n      return;\n    }\n    if (type === 'close') {\n      for (var k = 0; k < closeHandlers.length; k++) {\n        try { closeHandlers[k](); } catch (e) {}\n      }\n      return;\n    }\n    if (type === 'cancel' && typeof envelope.requestId === 'string') {\n      // Background-side cancel (reserved; currently unused). If we had a\n      // future bidirectional RPC this would abort an in-flight UI handler.\n      return;\n    }\n    if (type === 'ack') {\n      return;\n    }\n  }\n\n  window.mentra = {\n    send: send,\n    on: on,\n    request: request,\n    onOpen: onOpen,\n    onClose: onClose,\n    ready: readyFn,\n    /** @internal — packageName for diagnostic logs only. */\n    _packageName: packageName,\n  };\n  window.__mentra = { recv: recv };\n})();\n`.trim()\n}\n"]}

package/build/services/navigation/roadNameResolver.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Hybrid road-name resolver for Routes-API steps. Used to fill
+ * `ComputedRouteStep.road` so miniapps don't have to parse instruction
+ * prose or geocode themselves — every miniapp talking to the SDK sees
+ * the same accurate names for preview AND live trip.
+ *
+ * Strategy per step:
+ *   1. Parse "onto X" from the Routes-API instruction when present
+ *      (the API literally tells us the road; no second-guessing).
+ *   2. Fall back to reverse-geocoding the step MIDPOINT when the
+ *      instruction has no road name ("Slight right", "Turn left toward
+ *      …", "Destination will be on the right", bare depart steps).
+ *
+ * Endpoints get rejected as fallback probe points: they sit on
+ * junctions and snap to whichever cross-street has higher weight;
+ * the midpoint sits on the step's own road.
+ *
+ * This is a direct port of the resolver that used to live in the Nav
+ * miniapp's NavigationPage.tsx. Lives on the host so all miniapps
+ * benefit and so preview + live can share a single implementation.
+ */
+type StepLike = {
+    lat: number;
+    lng: number;
+    endLat: number;
+    endLng: number;
+    instruction?: string;
+};
+type ReverseGeocode = (coord: {
+    lat: number;
+    lng: number;
+}) => Promise<{
+    ok: boolean;
+    road?: string | null;
+    error?: string;
+}>;
+/**
+ * Pull a short road name out of a Routes-API instruction. Instructions
+ * look like:
+ *   "Turn left onto Octavia Blvd"
+ *   "Head northeast on Market St toward Octavia St"
+ *   "Turn right onto Haight St\nDestination will be on the right"
+ *
+ * Pitfalls this guards against (seen in real data):
+ *   - Multi-line: API appends "Destination will be on the right" etc.
+ *     Only the first line is parsed, otherwise the greedy "on" match
+ *     grabs "on the right" → "the right".
+ *   - Trailing clauses ("… toward Octavia St", "… and continue"):
+ *     cut at the first such keyword.
+ *   - Unit suffixes: "Hayes St #116" → "Hayes St".
+ *   - Bare direction words slipping through: rejected so the resolver
+ *     falls back to geocoding instead of labeling a step "left".
+ */
+export declare function roadNameFromInstruction(instruction?: string): string | null;
+/**
+ * Resolve `road` for every step in a Routes-API step list. The
+ * `reverseGeocode` callback is injected so this module stays free of
+ * the host's network plumbing (and is unit-testable).
+ *
+ * Steps are resolved in parallel: parsed names land synchronously,
+ * geocoded fallbacks fire concurrently. Order is preserved.
+ */
+export declare function resolveStepRoads<S extends StepLike>(steps: S[], reverseGeocode: ReverseGeocode): Promise<Array<S & {
+    road: string | null;
+}>>;
+export {};
+//# sourceMappingURL=roadNameResolver.d.ts.map

package/build/services/navigation/roadNameResolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roadNameResolver.d.ts","sourceRoot":"","sources":["../../../src/services/navigation/roadNameResolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,KAAK,QAAQ,GAAG;IACd,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,CAAA;AAED,KAAK,cAAc,GAAG,CAAC,KAAK,EAAE;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAC,KAAK,OAAO,CAAC;IACnE,EAAE,EAAE,OAAO,CAAA;IACX,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAAC,CAAA;AAaF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAe3E;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,SAAS,QAAQ,EACvD,KAAK,EAAE,CAAC,EAAE,EACV,cAAc,EAAE,cAAc,GAC7B,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG;IAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CAAC,CAAC,CAAC,CAmB3C"}

package/build/services/navigation/roadNameResolver.js

@@ -0,0 +1,96 @@
+/**
+ * Hybrid road-name resolver for Routes-API steps. Used to fill
+ * `ComputedRouteStep.road` so miniapps don't have to parse instruction
+ * prose or geocode themselves — every miniapp talking to the SDK sees
+ * the same accurate names for preview AND live trip.
+ *
+ * Strategy per step:
+ *   1. Parse "onto X" from the Routes-API instruction when present
+ *      (the API literally tells us the road; no second-guessing).
+ *   2. Fall back to reverse-geocoding the step MIDPOINT when the
+ *      instruction has no road name ("Slight right", "Turn left toward
+ *      …", "Destination will be on the right", bare depart steps).
+ *
+ * Endpoints get rejected as fallback probe points: they sit on
+ * junctions and snap to whichever cross-street has higher weight;
+ * the midpoint sits on the step's own road.
+ *
+ * This is a direct port of the resolver that used to live in the Nav
+ * miniapp's NavigationPage.tsx. Lives on the host so all miniapps
+ * benefit and so preview + live can share a single implementation.
+ */
+const DIRECTION_WORDS = new Set([
+    "right",
+    "left",
+    "the right",
+    "the left",
+    "north",
+    "south",
+    "east",
+    "west",
+]);
+/**
+ * Pull a short road name out of a Routes-API instruction. Instructions
+ * look like:
+ *   "Turn left onto Octavia Blvd"
+ *   "Head northeast on Market St toward Octavia St"
+ *   "Turn right onto Haight St\nDestination will be on the right"
+ *
+ * Pitfalls this guards against (seen in real data):
+ *   - Multi-line: API appends "Destination will be on the right" etc.
+ *     Only the first line is parsed, otherwise the greedy "on" match
+ *     grabs "on the right" → "the right".
+ *   - Trailing clauses ("… toward Octavia St", "… and continue"):
+ *     cut at the first such keyword.
+ *   - Unit suffixes: "Hayes St #116" → "Hayes St".
+ *   - Bare direction words slipping through: rejected so the resolver
+ *     falls back to geocoding instead of labeling a step "left".
+ */
+export function roadNameFromInstruction(instruction) {
+    if (!instruction)
+        return null;
+    const firstLine = instruction.split("\n")[0] ?? "";
+    // Prefer "onto" (always immediately precedes the road); fall back to
+    // "on" for depart steps ("Head north on Market St").
+    const m = firstLine.match(/\bonto\s+(.+)$/i) ?? firstLine.match(/\bon\s+(.+)$/i);
+    let raw = (m ? m[1] : "").trim();
+    if (!raw)
+        return null;
+    // Cut trailing direction/continuation clauses the API appends.
+    raw = raw.split(/\s+(?:toward|towards|to|and|then|for)\b/i)[0]?.trim() ?? "";
+    // Strip a unit/suite suffix.
+    raw = raw.replace(/\s+#.*$/, "").trim();
+    if (!raw)
+        return null;
+    if (DIRECTION_WORDS.has(raw.toLowerCase()))
+        return null;
+    return raw;
+}
+/**
+ * Resolve `road` for every step in a Routes-API step list. The
+ * `reverseGeocode` callback is injected so this module stays free of
+ * the host's network plumbing (and is unit-testable).
+ *
+ * Steps are resolved in parallel: parsed names land synchronously,
+ * geocoded fallbacks fire concurrently. Order is preserved.
+ */
+export async function resolveStepRoads(steps, reverseGeocode) {
+    const probes = steps.map((s) => {
+        const parsed = roadNameFromInstruction(s.instruction);
+        if (parsed)
+            return Promise.resolve(parsed);
+        if (!Number.isFinite(s.lat) ||
+            !Number.isFinite(s.lng) ||
+            !Number.isFinite(s.endLat) ||
+            !Number.isFinite(s.endLng)) {
+            return Promise.resolve(null);
+        }
+        const mid = { lat: (s.lat + s.endLat) / 2, lng: (s.lng + s.endLng) / 2 };
+        return reverseGeocode(mid)
+            .then((r) => (r.ok ? r.road ?? null : null))
+            .catch(() => null);
+    });
+    const roads = await Promise.all(probes);
+    return steps.map((s, i) => ({ ...s, road: roads[i] }));
+}
+//# sourceMappingURL=roadNameResolver.js.map

package/build/services/navigation/roadNameResolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"roadNameResolver.js","sourceRoot":"","sources":["../../../src/services/navigation/roadNameResolver.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Hybrid road-name resolver for Routes-API steps. Used to fill\n * `ComputedRouteStep.road` so miniapps don't have to parse instruction\n * prose or geocode themselves — every miniapp talking to the SDK sees\n * the same accurate names for preview AND live trip.\n *\n * Strategy per step:\n *   1. Parse \"onto X\" from the Routes-API instruction when present\n *      (the API literally tells us the road; no second-guessing).\n *   2. Fall back to reverse-geocoding the step MIDPOINT when the\n *      instruction has no road name (\"Slight right\", \"Turn left toward\n *      …\", \"Destination will be on the right\", bare depart steps).\n *\n * Endpoints get rejected as fallback probe points: they sit on\n * junctions and snap to whichever cross-street has higher weight;\n * the midpoint sits on the step's own road.\n *\n * This is a direct port of the resolver that used to live in the Nav\n * miniapp's NavigationPage.tsx. Lives on the host so all miniapps\n * benefit and so preview + live can share a single implementation.\n */\n\ntype StepLike = {\n  lat: number\n  lng: number\n  endLat: number\n  endLng: number\n  instruction?: string\n}\n\ntype ReverseGeocode = (coord: {lat: number; lng: number}) => Promise<{\n  ok: boolean\n  road?: string | null\n  error?: string\n}>\n\nconst DIRECTION_WORDS = new Set([\n  \"right\",\n  \"left\",\n  \"the right\",\n  \"the left\",\n  \"north\",\n  \"south\",\n  \"east\",\n  \"west\",\n])\n\n/**\n * Pull a short road name out of a Routes-API instruction. Instructions\n * look like:\n *   \"Turn left onto Octavia Blvd\"\n *   \"Head northeast on Market St toward Octavia St\"\n *   \"Turn right onto Haight St\\nDestination will be on the right\"\n *\n * Pitfalls this guards against (seen in real data):\n *   - Multi-line: API appends \"Destination will be on the right\" etc.\n *     Only the first line is parsed, otherwise the greedy \"on\" match\n *     grabs \"on the right\" → \"the right\".\n *   - Trailing clauses (\"… toward Octavia St\", \"… and continue\"):\n *     cut at the first such keyword.\n *   - Unit suffixes: \"Hayes St #116\" → \"Hayes St\".\n *   - Bare direction words slipping through: rejected so the resolver\n *     falls back to geocoding instead of labeling a step \"left\".\n */\nexport function roadNameFromInstruction(instruction?: string): string | null {\n  if (!instruction) return null\n  const firstLine = instruction.split(\"\\n\")[0] ?? \"\"\n  // Prefer \"onto\" (always immediately precedes the road); fall back to\n  // \"on\" for depart steps (\"Head north on Market St\").\n  const m = firstLine.match(/\\bonto\\s+(.+)$/i) ?? firstLine.match(/\\bon\\s+(.+)$/i)\n  let raw = (m ? m[1] : \"\").trim()\n  if (!raw) return null\n  // Cut trailing direction/continuation clauses the API appends.\n  raw = raw.split(/\\s+(?:toward|towards|to|and|then|for)\\b/i)[0]?.trim() ?? \"\"\n  // Strip a unit/suite suffix.\n  raw = raw.replace(/\\s+#.*$/, \"\").trim()\n  if (!raw) return null\n  if (DIRECTION_WORDS.has(raw.toLowerCase())) return null\n  return raw\n}\n\n/**\n * Resolve `road` for every step in a Routes-API step list. The\n * `reverseGeocode` callback is injected so this module stays free of\n * the host's network plumbing (and is unit-testable).\n *\n * Steps are resolved in parallel: parsed names land synchronously,\n * geocoded fallbacks fire concurrently. Order is preserved.\n */\nexport async function resolveStepRoads<S extends StepLike>(\n  steps: S[],\n  reverseGeocode: ReverseGeocode,\n): Promise<Array<S & {road: string | null}>> {\n  const probes = steps.map<Promise<string | null>>((s) => {\n    const parsed = roadNameFromInstruction(s.instruction)\n    if (parsed) return Promise.resolve(parsed)\n    if (\n      !Number.isFinite(s.lat) ||\n      !Number.isFinite(s.lng) ||\n      !Number.isFinite(s.endLat) ||\n      !Number.isFinite(s.endLng)\n    ) {\n      return Promise.resolve(null)\n    }\n    const mid = {lat: (s.lat + s.endLat) / 2, lng: (s.lng + s.endLng) / 2}\n    return reverseGeocode(mid)\n      .then((r) => (r.ok ? r.road ?? null : null))\n      .catch(() => null)\n  })\n  const roads = await Promise.all(probes)\n  return steps.map((s, i) => ({...s, road: roads[i]}))\n}\n"]}

package/build/services/navigation/routesApiCodec.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Pure decoders used by `NavigationService.computeRoute` when talking to
+ * Mapbox's Directions API directly (no native dependency).
+ *
+ * Kept in their own module so unit tests don't have to bring up the
+ * `crust` native module to exercise them. The algorithms are unit
+ * testable; the surrounding service is not.
+ *
+ * Migrated from Google Routes API: Mapbox returns numeric `distance`
+ * (meters) / `duration` (seconds) rather than Google's `"123s"` protobuf
+ * strings, and `polyline6` (precision-6) geometry rather than Google's
+ * precision-5 encoded polyline. `parseDurationSeconds` is retained for
+ * back-compat but Mapbox callers pass the numeric value through directly.
+ */
+export type LatLng = {
+    lat: number;
+    lng: number;
+};
+/**
+ * Back-compat: Google Routes API encoded durations as protobuf strings
+ * ("123s"). Mapbox returns a number, so new callers should not need this.
+ * Accepts a number (passed through) or a "123s" string.
+ */
+export declare function parseDurationSeconds(s: string | number): number;
+/**
+ * Decode an encoded polyline. The standard Google/Mapbox polyline
+ * algorithm, parameterized by coordinate precision:
+ *   - precision 5 (Google Routes, Mapbox `polyline`): factor 1e5
+ *   - precision 6 (Mapbox `polyline6`): factor 1e6
+ *
+ * We request `geometries=polyline6` from Mapbox Directions for the extra
+ * precision (tighter road-centerline tracing keeps the turn-pivot dots on
+ * the visible road), so the default precision here is 6.
+ *
+ * Reference: https://docs.mapbox.com/api/navigation/directions/#route-object
+ */
+export declare function decodePolyline(encoded: string, precision?: number): LatLng[];
+//# sourceMappingURL=routesApiCodec.d.ts.map

package/build/services/navigation/routesApiCodec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routesApiCodec.d.ts","sourceRoot":"","sources":["../../../src/services/navigation/routesApiCodec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,MAAM,MAAM,GAAG;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAC,CAAA;AAE/C;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAI/D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,GAAE,MAAU,GAAG,MAAM,EAAE,CA4B/E"}