@mentra/engine 0.1.0-beta.0

package/src/services/mentraUiShim.ts

@@ -0,0 +1,366 @@
+/**
+ * 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 function buildMentraUiShim(options: MentraUiShimOptions): string {
+  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()
+}

package/src/services/navigation/roadNameResolver.ts

@@ -0,0 +1,112 @@
+/**
+ * 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
+}>
+
+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?: string): string | null {
+  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<S extends StepLike>(
+  steps: S[],
+  reverseGeocode: ReverseGeocode,
+): Promise<Array<S & {road: string | null}>> {
+  const probes = steps.map<Promise<string | null>>((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]}))
+}

package/src/services/navigation/routesApiCodec.ts

@@ -0,0 +1,69 @@
+/**
+ * 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 function parseDurationSeconds(s: string | number): number {
+  if (typeof s === "number") return Number.isFinite(s) ? Math.round(s) : 0
+  const match = s.match(/^(\d+)/)
+  return match ? Number(match[1]) : 0
+}
+
+/**
+ * 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 function decodePolyline(encoded: string, precision: number = 6): LatLng[] {
+  if (!encoded) return []
+  const factor = Math.pow(10, precision)
+  const points: LatLng[] = []
+  let index = 0
+  let lat = 0
+  let lng = 0
+  while (index < encoded.length) {
+    let result = 0
+    let shift = 0
+    let b: number
+    do {
+      b = encoded.charCodeAt(index++) - 63
+      result |= (b & 0x1f) << shift
+      shift += 5
+    } while (b >= 0x20)
+    lat += result & 1 ? ~(result >> 1) : result >> 1
+    result = 0
+    shift = 0
+    do {
+      b = encoded.charCodeAt(index++) - 63
+      result |= (b & 0x1f) << shift
+      shift += 5
+    } while (b >= 0x20)
+    lng += result & 1 ? ~(result >> 1) : result >> 1
+    points.push({lat: lat / factor, lng: lng / factor})
+  }
+  return points
+}

package/src/services/otaDisplayState.ts

@@ -0,0 +1,115 @@
+import type {OtaProgress, OtaStatus} from "@mentra/bluetooth-sdk/internal"
+
+import {isLegacyShapedOtaStatus} from "./otaInstallPolicy"
+
+export type DisplayState = "starting" | "updating" | "complete" | "failed" | "disconnected" | "restarting"
+
+/**
+ * Pure derivation of the OTA progress UI state from the glasses data in the
+ * Zustand store plus a couple of genuinely-local inputs. See
+ * OtaInstallCoordinator.ts for the state machine that consumes this (the host
+ * progress screen renders its snapshot).
+ *
+ * Legacy shape (WP 8C): old (< 37) ASG builds send `ota_progress`, which the SDK
+ * maps to ota_status with sessionId "" and FINISHED→"complete" at ANY phase. For
+ * those statuses a download-phase "complete" only means the download finished
+ * (the install is still ahead), and an apk install "complete" may be held by the
+ * coordinator's settle window — both stay "updating" instead of terminal.
+ *
+ * Priority-ordered rules (first match wins):
+ *   1. errorMsg !== ""                                          -> "failed"
+ *   2. BES terminal + connected + sawReconnectEdge             -> "complete"
+ *   3. BES terminal (any connection state)                     -> "restarting"
+ *      (legacy-shaped BES "complete" counts only in install phase)
+ *   4. apkCompletedViaBuildIncrease (legacy build-number port) -> "complete"
+ *   5. otaStatus.status === "failed"                           -> "failed"
+ *   6. otaStatus.status === "complete" (non-BES)               -> "complete"
+ *      (unless legacy-shaped download-complete or held apk settle -> in flight)
+ *   7. !connected + legacy in-flight complete (held apk)       -> "updating"
+ *   8. !connected + APK step_complete with totalSteps > 1      -> "starting"   (expected reboot)
+ *   9. !connected + BES in flight                              -> "restarting" (defensive)
+ *   10. !connected                                             -> "disconnected"
+ *   11. connected + in_progress | step_complete | legacy in-flight complete -> "updating"
+ *   12. fallback                                               -> "starting"
+ */
+export function deriveDisplayState(args: {
+  otaStatus: OtaStatus | null
+  otaProgress: OtaProgress | null
+  connected: boolean
+  errorMsg: string
+  sawReconnectEdge: boolean
+  /** Coordinator is holding a legacy apk install "complete" for the settle window (WP 8C). */
+  legacyApkSettleHold?: boolean
+  /** Legacy APK completion detected by build-number increase (WP 8C). */
+  apkCompletedViaBuildIncrease?: boolean
+}): DisplayState {
+  const {otaStatus, otaProgress, connected, errorMsg, sawReconnectEdge, legacyApkSettleHold, apkCompletedViaBuildIncrease} =
+    args
+
+  if (errorMsg) return "failed"
+
+  const besTerminal = isBesTerminal(otaStatus, otaProgress)
+  if (besTerminal && connected && sawReconnectEdge) return "complete"
+  if (besTerminal) return "restarting"
+
+  // Legacy build-number APK completion: the coordinator clears errorMsg when it fires,
+  // and the flag outranks whatever stale legacy status is still in the store (the old
+  // screen's last-write-wins completion from starting/failed/installing).
+  if (apkCompletedViaBuildIncrease) return "complete"
+
+  if (otaStatus?.status === "failed") return "failed"
+
+  // Legacy-shaped "complete" that is still in flight: a download-phase FINISHED (the
+  // install is still ahead), or an apk install FINISHED held by the settle window.
+  const legacyInFlightComplete =
+    isLegacyShapedOtaStatus(otaStatus) &&
+    otaStatus?.status === "complete" &&
+    (otaStatus.phase === "download" ||
+      (!!legacyApkSettleHold && otaStatus.stepType === "apk" && otaStatus.phase === "install"))
+
+  if (otaStatus?.status === "complete" && !legacyInFlightComplete) return "complete"
+
+  if (!connected) {
+    // The held apk install complete means the glasses are restarting into the new
+    // build — the legacy screen kept showing "installing" through that restart.
+    if (legacyInFlightComplete && otaStatus?.phase === "install") return "updating"
+
+    // By here, the failed/complete rules already returned for terminal statuses.
+    // For APK multi-step, "step_complete" means the current step ended and the
+    // glasses are rebooting to start the next one.
+    const apkRebootExpected =
+      otaStatus?.stepType === "apk" && (otaStatus?.totalSteps ?? 0) > 1 && otaStatus.status === "step_complete"
+    if (apkRebootExpected) return "starting"
+
+    // Legacy-shaped BES download events do not mean a reboot is coming (the flash
+    // has not started); the legacy screen treated that drop as a plain disconnect.
+    const besStatusInFlight =
+      otaStatus?.stepType === "bes" && !(isLegacyShapedOtaStatus(otaStatus) && otaStatus.phase === "download")
+    const besInFlight =
+      besStatusInFlight || (otaProgress?.currentUpdate === "bes" && otaProgress?.stage === "install")
+    if (besInFlight) return "restarting"
+
+    return "disconnected"
+  }
+
+  if (otaStatus?.status === "in_progress" || otaStatus?.status === "step_complete" || legacyInFlightComplete) {
+    return "updating"
+  }
+
+  return "starting"
+}
+
+function isBesTerminal(otaStatus: OtaStatus | null, otaProgress: OtaProgress | null): boolean {
+  if (otaStatus?.stepType === "bes" && (otaStatus.status === "step_complete" || otaStatus.status === "complete")) {
+    // Legacy-shaped statuses map download FINISHED to "complete" too; only an
+    // install-phase terminal means the BES flash actually ran (WP 8C).
+    if (isLegacyShapedOtaStatus(otaStatus) && otaStatus.phase !== "install") {
+      return false
+    }
+    return true
+  }
+  if (otaProgress?.currentUpdate === "bes" && otaProgress.stage === "install" && otaProgress.status === "FINISHED") {
+    return true
+  }
+  return false
+}