@glassly/engine 0.1.0-dev.0

package/src/services/cloudStreamApi.ts

@@ -0,0 +1,142 @@
+/**
+ * Managed-stream provisioning over the cloud-v2 runtime (cloud-client REST):
+ *
+ *   POST   /api/camera/stream      -> provision (Cloudflare live input)
+ *   GET    /api/camera/stream/:id  -> provider's ingest status
+ *   DELETE /api/camera/stream/:id  -> teardown
+ *
+ * Drop-in replacement for the legacy `v2StreamApi` (which hit the v1 cloud's
+ * /api/v2/client/streams/managed on backend_url): same exported shapes, so
+ * PhoneStreamCoordinator is unchanged apart from the import. Local miniapps
+ * use ONLY this path — no legacy V1 transport.
+ *
+ * Errors are tagged with stage "provision"/"status"/"teardown" and transport
+ * "cloud-rest" so a miniapp sees exactly where and on which leg it broke.
+ */
+
+import {cloudClientService as cloudClient} from "./CloudClientService"
+
+/**
+ * Restream destination. The full stream key is part of the URL — Cloudflare
+ * appends nothing on the publish side. `name` is a human label that surfaces
+ * in Cloudflare's dashboard but doesn't affect routing.
+ */
+export interface RestreamDestination {
+  url: string
+  name?: string
+}
+
+/** Caller-facing shape: either a bare URL string or the full object. */
+export type RestreamDestinationInput = string | RestreamDestination
+
+export interface ProvisionResult {
+  liveInputId: string
+  rtmpUrl: string
+  srtUrl?: string
+  hlsUrl: string
+  dashUrl: string
+  webrtcUrl?: string
+  webrtcPublishUrl?: string
+}
+
+export interface CloudflareStatus {
+  isConnected: boolean
+  state?: string | null
+  connectedAt?: string
+  lastSeenAt?: string
+  reason?: string
+}
+
+export type StreamApiStage = "provision" | "status" | "teardown"
+
+export class StreamApiError extends Error {
+  readonly transport = "cloud-rest" as const
+  constructor(
+    public readonly code: string,
+    message: string,
+    public readonly stage: StreamApiStage,
+  ) {
+    super(message)
+    this.name = "StreamApiError"
+  }
+}
+
+/** The cloud-v2 runtime's ManagedStream wire shape (open records, see protocol). */
+interface ManagedStreamWire {
+  streamId: string
+  ingest: {
+    url?: string
+    streamKey?: string
+    rtmpUrl?: string
+    srtUrl?: string
+    webrtcPublishUrl?: string
+  }
+  playback: {
+    hls?: string
+    dash?: string
+    webrtc?: string
+  }
+}
+
+/**
+ * Provision a managed stream on the cloud-v2 runtime. Returns ready-to-publish
+ * ingest URLs (credentials embedded) plus the playback URLs.
+ */
+export async function provisionManagedStream(
+  restreamDestinations?: RestreamDestinationInput[],
+): Promise<ProvisionResult> {
+  let wire: ManagedStreamWire
+  try {
+    wire = (await cloudClient.startManagedStream(
+      restreamDestinations && restreamDestinations.length > 0 ? {restreamDestinations} : {},
+    )) as ManagedStreamWire
+  } catch (err) {
+    throw new StreamApiError("STREAM_PROVISION_FAILED", err instanceof Error ? err.message : String(err), "provision")
+  }
+
+  const ingest = wire.ingest ?? {}
+  const playback = wire.playback ?? {}
+  const rtmpUrl = ingest.rtmpUrl ?? (ingest.url && ingest.streamKey ? `${ingest.url}${ingest.streamKey}` : "")
+  if (!playback.hls || !playback.dash) {
+    throw new StreamApiError(
+      "STREAM_PROVISION_INCOMPLETE",
+      `runtime returned no playback URLs for stream ${wire.streamId}`,
+      "provision",
+    )
+  }
+
+  return {
+    liveInputId: wire.streamId,
+    rtmpUrl,
+    srtUrl: ingest.srtUrl,
+    hlsUrl: playback.hls,
+    dashUrl: playback.dash,
+    webrtcUrl: playback.webrtc,
+    webrtcPublishUrl: ingest.webrtcPublishUrl,
+  }
+}
+
+/** The provider's view of the ingest: is the device's push arriving? */
+export async function getManagedStreamStatus(liveInputId: string): Promise<CloudflareStatus> {
+  try {
+    const s = await cloudClient.getManagedStreamStatus(liveInputId)
+    return {
+      isConnected: s.isConnected,
+      state: s.state,
+      connectedAt: s.connectedAt,
+      lastSeenAt: s.lastSeenAt,
+      reason: s.reason,
+    }
+  } catch (err) {
+    throw new StreamApiError("STREAM_STATUS_FAILED", err instanceof Error ? err.message : String(err), "status")
+  }
+}
+
+/** Tear down the provider stream. */
+export async function teardownManagedStream(liveInputId: string): Promise<void> {
+  try {
+    await cloudClient.stopManagedStream(liveInputId)
+  } catch (err) {
+    throw new StreamApiError("STREAM_TEARDOWN_FAILED", err instanceof Error ? err.message : String(err), "teardown")
+  }
+}

package/src/services/effectiveCapabilities.ts

@@ -0,0 +1,27 @@
+/**
+ * Effective device capabilities — the static model profile plus what the
+ * connected firmware reports at runtime. Today the only runtime override is
+ * the scene canvas: Glassly CFW on the G2 rasterizes scenes phone-side
+ * straight into the 640×480 panel, so the drawable canvas grows past stock's
+ * 576×288. Native publishes the canvas into the glasses status (0 = none).
+ */
+import {useGlassesStore} from "../stores/glasses"
+import {getModelCapabilities, type Capabilities, type DeviceTypes} from "../types"
+
+export interface SceneCanvasSize {
+  width: number
+  height: number
+}
+
+export function runtimeSceneCanvas(): SceneCanvasSize | null {
+  const {sceneCanvasWidth, sceneCanvasHeight} = useGlassesStore.getState()
+  if (!sceneCanvasWidth || !sceneCanvasHeight || sceneCanvasWidth <= 0 || sceneCanvasHeight <= 0) return null
+  return {width: sceneCanvasWidth, height: sceneCanvasHeight}
+}
+
+export function getEffectiveCapabilities(model: DeviceTypes): Capabilities {
+  const base = getModelCapabilities(model)
+  const canvas = runtimeSceneCanvas()
+  if (!base.display || !canvas) return base
+  return {...base, display: {...base.display, width: canvas.width, height: canvas.height}}
+}

package/src/services/gallerySyncClock.ts

@@ -0,0 +1,39 @@
+/**
+ * Clock skew detection for gallery sync (phone vs glasses).
+ * Phone pushes time to glasses only when skew is detected during sync.
+ */
+
+export const CLOCK_SKEW_TOLERANCE_MS = 60_000
+
+export type ClockSkewReason = "watermark_ahead_of_glasses" | "wall_clock_drift" | ""
+
+export interface ClockSkewResult {
+  skewed: boolean
+  reason: ClockSkewReason
+}
+
+export function detectClockSkew(
+  phoneNow: number,
+  glassesServerTime: number,
+  lastSyncTime: number,
+  toleranceMs: number = CLOCK_SKEW_TOLERANCE_MS,
+): ClockSkewResult {
+  if (lastSyncTime > glassesServerTime + toleranceMs) {
+    return {skewed: true, reason: "watermark_ahead_of_glasses"}
+  }
+  if (Math.abs(phoneNow - glassesServerTime) > toleranceMs) {
+    return {skewed: true, reason: "wall_clock_drift"}
+  }
+  return {skewed: false, reason: ""}
+}
+
+export function isSyncManifestEmpty(syncData: {
+  api_version?: number
+  captures?: unknown[]
+  changed_files?: unknown[]
+}): boolean {
+  if ((syncData.api_version || 0) >= 2 && syncData.captures && syncData.captures.length > 0) {
+    return false
+  }
+  return !syncData.changed_files || syncData.changed_files.length === 0
+}

package/src/services/glassesClockSync.ts

@@ -0,0 +1,115 @@
+/**
+ * Push phone time to glasses only when clock skew is detected (gallery sync, OTA, etc.).
+ */
+
+import BluetoothSdk from "@glassly/bluetooth-sdk/internal"
+import {BgTimer} from "../utils/timers"
+import {useGlassesStore} from "../stores/glasses"
+
+import {resolveOtaManifestUrl} from "./otaManifestUrl"
+import {detectClockSkew} from "./gallerySyncClock"
+
+export const CLOCK_SETTLE_MS = 500
+
+const OTA_CLOCK_FIX_COOLDOWN_MS = 30_000
+let lastOtaClockFixAt = 0
+// Coalesce concurrent OTA clock-fix attempts. Glasses can emit two clock_skew events
+// back-to-back during BLE handshake; without this guard both would await the BLE fix
+// + retry pair before either updated `lastOtaClockFixAt`.
+let inflightOtaClockFix: Promise<boolean> | null = null
+
+/** @internal test-only */
+export function resetOtaClockFixCooldownForTests(): void {
+  lastOtaClockFixAt = 0
+  inflightOtaClockFix = null
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => BgTimer.setTimeout(resolve, ms))
+}
+
+/**
+ * Set glasses system clock from phone when skew is detected.
+ */
+export async function fixGlassesClockIfSkewed(glassesServerTime: number, lastSyncTime = 0): Promise<boolean> {
+  const {skewed, reason} = detectClockSkew(Date.now(), glassesServerTime, lastSyncTime)
+  if (!skewed) {
+    return false
+  }
+  console.log(`[GlassesClockSync] ⏰ Clock skew detected (${reason}) — setting glasses time from phone`)
+  await BluetoothSdk.setSystemTime(Date.now())
+  await delay(CLOCK_SETTLE_MS)
+  return true
+}
+
+/**
+ * After glasses report OTA failure due to clock skew, fix time and restart
+ * through the normal phone-driven ota_start path.
+ */
+export async function handleOtaClockSkewFromGlasses(
+  errorCode: string | undefined,
+  glassesTimeMs?: number,
+): Promise<boolean> {
+  if (Date.now() - lastOtaClockFixAt < OTA_CLOCK_FIX_COOLDOWN_MS) {
+    return false
+  }
+
+  const hasGlassesTime = typeof glassesTimeMs === "number" && Number.isFinite(glassesTimeMs) && glassesTimeMs > 0
+
+  if (errorCode === "ssl_error") {
+    if (!hasGlassesTime) {
+      return false
+    }
+    const {skewed} = detectClockSkew(Date.now(), glassesTimeMs, 0)
+    if (!skewed) {
+      return false
+    }
+    console.log("[GlassesClockSync] ⏰ OTA ssl_error with wall-clock drift — treating as clock skew")
+  } else if (errorCode !== "clock_skew") {
+    return false
+  }
+
+  // Coalesce concurrent attempts: if a fix is already in flight, await its result instead
+  // of racing it through the cooldown guard.
+  if (inflightOtaClockFix) {
+    return inflightOtaClockFix
+  }
+
+  const glassesTime = hasGlassesTime ? glassesTimeMs : Date.now() - 86_400_000
+
+  inflightOtaClockFix = (async () => {
+    try {
+      const fixed = await fixGlassesClockIfSkewed(glassesTime, 0)
+      if (!fixed) {
+        return false
+      }
+
+      lastOtaClockFixAt = Date.now()
+      const {buildNumber, otaVersionUrl} = useGlassesStore.getState()
+      const manifestUrl = resolveOtaManifestUrl(otaVersionUrl, buildNumber)
+      console.log("[GlassesClockSync] ⏰ Restarting OTA with ota_start after clock fix")
+      await BluetoothSdk.startOtaUpdate(manifestUrl)
+      return true
+    } finally {
+      inflightOtaClockFix = null
+    }
+  })()
+
+  return inflightOtaClockFix
+}
+
+/**
+ * Proactive fix when version_info includes glasses system_time_ms before OTA manifest checks.
+ */
+export async function maybeFixGlassesClockFromVersionInfo(systemTimeMs: number | undefined): Promise<boolean> {
+  if (typeof systemTimeMs !== "number" || systemTimeMs <= 0) {
+    return false
+  }
+
+  const fixed = await fixGlassesClockIfSkewed(systemTimeMs, 0)
+  if (!fixed) {
+    return false
+  }
+
+  return true
+}

package/src/services/manifestActions.ts

@@ -0,0 +1,80 @@
+import type {DeclaredAction} from "../types/applet"
+
+/** The subset of ClientApp that action-listing needs (structural, no cycle on applet types). */
+export interface ActionListApp {
+  packageName: string
+  name: string
+  actions?: DeclaredAction[]
+  compatibility?: {isCompatible: boolean}
+}
+
+/** One row of `session.actions.list` — a flat, MCP-tool-shaped descriptor. */
+export interface ActionListRow {
+  packageName: string
+  appName: string
+  id: string
+  description: string
+  parameters?: Record<string, unknown>
+  outputSchema?: Record<string, unknown>
+}
+
+/**
+ * Project the installed-app set into the caller's invokable-action rows:
+ * excludes the caller's own actions, incompatible apps, and placeholder
+ * packages; `visibility: "system"` actions only surface for system callers.
+ */
+export function visibleActionRows(
+  apps: ActionListApp[],
+  callerPackageName: string,
+  callerIsSystem: boolean,
+): ActionListRow[] {
+  const rows: ActionListRow[] = []
+  for (const app of apps) {
+    if (!app.packageName || app.packageName === callerPackageName || app.packageName.includes("@empty")) continue
+    if (app.compatibility?.isCompatible === false) continue
+    for (const action of app.actions ?? []) {
+      if (action.visibility === "system" && !callerIsSystem) continue
+      rows.push({
+        packageName: app.packageName,
+        appName: app.name,
+        id: action.id,
+        description: action.description,
+        ...(action.parameters ? {parameters: action.parameters} : {}),
+        ...(action.outputSchema ? {outputSchema: action.outputSchema} : {}),
+      })
+    }
+  }
+  return rows
+}
+
+/**
+ * Normalize manifest actions defensively for installed and dev-sideloaded
+ * bundles. Input and output schemas are passed through as opaque JSON Schema.
+ */
+export function normalizeManifestActions(raw: unknown): DeclaredAction[] {
+  if (!Array.isArray(raw)) return []
+  const out: DeclaredAction[] = []
+  for (const a of raw as Array<{
+    id?: unknown
+    description?: unknown
+    parameters?: unknown
+    outputSchema?: unknown
+    visibility?: unknown
+  }>) {
+    if (a && typeof a.id === "string" && typeof a.description === "string") {
+      out.push({
+        id: a.id,
+        description: a.description,
+        ...(a.parameters && typeof a.parameters === "object" && !Array.isArray(a.parameters)
+          ? {parameters: a.parameters as Record<string, unknown>}
+          : {}),
+        ...(a.outputSchema && typeof a.outputSchema === "object" && !Array.isArray(a.outputSchema)
+          ? {outputSchema: a.outputSchema as Record<string, unknown>}
+          : {}),
+        // Unknown/absent values fall back to the default ("public") by omission.
+        ...(a.visibility === "system" || a.visibility === "public" ? {visibility: a.visibility} : {}),
+      })
+    }
+  }
+  return out
+}

package/src/services/manifestVersionGate.ts

@@ -0,0 +1,43 @@
+import semver from "semver"
+
+/**
+ * Pure helper extracted from `AppRegistry.checkManifestVersions` so it
+ * can be unit-tested without dragging in the `expo-file-system`
+ * transitively-React-Native dependency tree.
+ *
+ * Returns `{ok: true}` when the manifest is compatible with the host,
+ * or `{ok: false, reason}` with a user-facing string. Manifests missing
+ * either field pass through (legacy single-bundle bundles).
+ *
+ * `sdkVersion` is the SDK ABI the bundle targets; `minHostVersion` is
+ * the host floor the miniapp requires. Both must satisfy semver-coerce.
+ * Strings that don't coerce are treated as "unspecified" — the
+ * CLI's validateManifest catches malformed inputs at install time so
+ * this helper stays permissive at the policy layer.
+ */
+export function checkManifestVersions(
+  manifest: {sdkVersion?: string; minHostVersion?: string} | null,
+  options: {hostVersion: string; supportedSdkRange: string},
+): {ok: true} | {ok: false; reason: string} {
+  if (!manifest) return {ok: true}
+  if (manifest.minHostVersion) {
+    const cleanHost = semver.valid(semver.coerce(options.hostVersion) ?? options.hostVersion)
+    const cleanMin = semver.valid(semver.coerce(manifest.minHostVersion) ?? manifest.minHostVersion)
+    if (cleanHost && cleanMin && semver.lt(cleanHost, cleanMin)) {
+      return {
+        ok: false,
+        reason: `Requires Glassly ${manifest.minHostVersion}+; this host is ${options.hostVersion}.`,
+      }
+    }
+  }
+  if (manifest.sdkVersion) {
+    const cleanSdk = semver.valid(semver.coerce(manifest.sdkVersion) ?? manifest.sdkVersion)
+    if (cleanSdk && !semver.satisfies(cleanSdk, options.supportedSdkRange)) {
+      return {
+        ok: false,
+        reason: `Built for SDK ${manifest.sdkVersion}; host supports ${options.supportedSdkRange}.`,
+      }
+    }
+  }
+  return {ok: true}
+}

package/src/services/memoryStoreInstance.ts

@@ -0,0 +1,70 @@
+/**
+ * The engine's singleton MemoryStore — the shared user-scoped memory timeline
+ * behind LocalMiniappRuntime's MEMORY_* bridge handlers and engine.memory.
+ * Lives in its own module (not MemoryStore.ts) so the store class stays
+ * dependency-free for tests.
+ */
+
+import {AppState} from "react-native"
+
+import {storage as mmkvStorage} from "../utils/storage/storage"
+import {cloudClientService} from "./CloudClientService"
+import {EXTENDED_RETENTION, MemoryStore, STANDARD_RETENTION} from "./MemoryStore"
+
+/**
+ * Persisted "Plus/Pro memory retention" flag. Cached in MMKV so a paying user
+ * who relaunches offline keeps their full read window; only a DEFINITIVE
+ * subscription answer may change it (the RevenueCatSetup effect passes
+ * nothing on unknown/null customer info).
+ */
+const RETENTION_EXTENDED_KEY = "memory_retention_extended"
+
+let retentionExtended = ((): boolean => {
+  const result = mmkvStorage.load<boolean>(RETENTION_EXTENDED_KEY)
+  return result.is_ok() && result.value === true
+})()
+
+/** Whether the extended (Plus/Pro) retention window is active right now. */
+export function isMemoryRetentionExtended(): boolean {
+  return retentionExtended
+}
+
+/**
+ * Flip the visible retention window. Called by the host app when the
+ * subscription state resolves or changes. Downgrading freezes reads to the
+ * standard window but deletes nothing — the older timeline stays stored and
+ * reappears on re-upgrade (MemoryStore prunes at the extended bound for
+ * every tier).
+ */
+export function setMemoryRetentionExtended(extended: boolean): void {
+  if (retentionExtended === extended) return
+  retentionExtended = extended
+  mmkvStorage.save(RETENTION_EXTENDED_KEY, extended)
+}
+
+export const memoryStore = new MemoryStore({
+  getUserId: () => cloudClientService.resolveGlasslyUserId(),
+  getRetention: () => (retentionExtended ? EXTENDED_RETENTION : STANDARD_RETENTION),
+  backend: {
+    get(key: string): unknown | null {
+      const result = mmkvStorage.load<unknown>(key)
+      return result.is_ok() ? result.value : null
+    },
+    set(key: string, value: unknown): void {
+      mmkvStorage.save(key, value)
+    },
+    remove(key: string): void {
+      mmkvStorage.remove(key)
+    },
+  },
+})
+
+// Transcript writes are debounced (see MemoryStore.schedulePersistLog), so the
+// tail of a conversation can be in-memory only when the user leaves the app.
+// Losing it to a background kill would be silent data loss — flush on the way out.
+AppState.addEventListener("change", (state) => {
+  if (state === "active") return
+  void memoryStore.flush().catch((err) => {
+    console.warn("MemoryStore: flush on background failed:", err instanceof Error ? err.message : err)
+  })
+})

package/src/services/navigation/roadNameResolver.ts

@@ -0,0 +1,103 @@
+/**
+ * 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
+}