@mentra/engine 0.1.0-beta.0

package/src/runtime/bootstrap.ts

@@ -0,0 +1,118 @@
+/**
+ * Bootstrap — the engine's single front door (`engine.configure` / `start` / `stop`).
+ *
+ * The host hands engine auth + config + analytics in one call; engine owns the
+ * runtime construction behind `start()`. Internal services read this holder
+ * directly instead of exposing host-facing adapter bags.
+ */
+
+export type SubjectTokenType = "supabase" | "authing" | (string & {})
+
+export interface IslandAuth {
+  /** Returns the host's current (auto-refreshed) subject token for the backend. */
+  getSubjectToken: () => Promise<{token: string; type: SubjectTokenType}>
+  /**
+   * Optional auth-session listener. Hosts that can emit auth changes should
+   * wire this so engine can reconnect backend sessions after restored login
+   * state lands post-boot.
+   */
+  onStateChange?: (callback: (event: string, session: {token?: string | null} | null) => void) => unknown
+}
+
+export interface IslandConfigValues {
+  /** cloud-v2 core service base URL (defaults resolved by the cloud client). */
+  coreUrl?: string
+  /** cloud-v2 runtime service base URL. */
+  runtimeUrl?: string
+  /** OEM identifier (Mentra is OEM #0); reserved for OEM auth/telemetry. */
+  oemId?: string
+  /**
+   * LC3 frame size (bytes) the phone's mic encoder emits — announced to the
+   * cloud on connect (20 for G1, 40 for G2, …). Defaults to 20 if unset.
+   */
+  audioFrameSizeBytes?: number
+  /**
+   * Dev-only live Metro/LAN host used to repair persisted local-miniapp dev URLs
+   * after the laptop changes networks. Omitted in production/OEM builds.
+   */
+  devServerHost?: () => string | undefined
+}
+
+export type IslandAnalytics = (event: string, props?: Record<string, unknown>) => void
+
+/**
+ * Named host-UI seams: engine dispatches the runtime request, the host owns the
+ * screen/navigation/branding. Keep each entry a single narrow purpose — this is
+ * a contract of specific UI capabilities, not a generic runtime-hook bag.
+ */
+export interface IslandUiSeams {
+  /**
+   * `session.glasses.requestWifiSetup` — open the host's glasses Wi-Fi setup
+   * flow. Absent ⇒ miniapps get NOT_IMPLEMENTED for the request.
+   */
+  requestWifiSetup?: (reason?: string) => Promise<void> | void
+}
+
+export interface IslandConfigureOptions {
+  /** REQUIRED — the only must-have seam. The host owns login; engine owns the rest. */
+  auth: IslandAuth
+  config?: IslandConfigValues
+  analytics?: IslandAnalytics
+  ui?: IslandUiSeams
+}
+
+let options: IslandConfigureOptions | null = null
+let started = false
+
+/**
+ * Hand engine its auth + config + analytics. Call once, before `start()`.
+ *
+ * Reconfiguring a RUNNING runtime is not supported: services capture pieces of
+ * this config as they build (e.g. the cloud client's endpoints), so swapping the
+ * options mid-run would split-brain the runtime (`getAuth()`/`getConfigValues()`
+ * report values the running services never consumed). Ignored with a warning
+ * while started; after `stop()`, `configure()` + `start()` begin a fresh cycle.
+ */
+export function configure(opts: IslandConfigureOptions): void {
+  if (started) {
+    console.warn("engine.configure() called after engine.start(); ignored — stop() the runtime before reconfiguring")
+    return
+  }
+  options = opts
+}
+
+/** Mark the runtime started. Idempotent. */
+export async function start(): Promise<void> {
+  if (started) return
+  if (!options) {
+    throw new Error("engine.start() called before engine.configure()")
+  }
+  started = true
+}
+
+/** Tear down. Idempotent. */
+export async function stop(): Promise<void> {
+  started = false
+}
+
+export function isStarted(): boolean {
+  return started
+}
+
+/** The host-supplied auth provider, or null if not configured yet. */
+export function getAuth(): IslandAuth | null {
+  return options?.auth ?? null
+}
+
+export function getConfigValues(): IslandConfigValues {
+  return options?.config ?? {}
+}
+
+export function getAnalytics(): IslandAnalytics | null {
+  return options?.analytics ?? null
+}
+
+/** The host-supplied UI seams ({} until configure() provides them). */
+export function getUiSeams(): IslandUiSeams {
+  return options?.ui ?? {}
+}

package/src/runtime/config.ts

@@ -0,0 +1,147 @@
+/**
+ * Runtime-shared constants and DTOs.
+ *
+ * The old host-injected runtime adapter surface has moved behind engine-owned
+ * services and `engine.configure({auth, config, analytics})`. Keep this file
+ * limited to stable types that are shared across those services.
+ */
+
+export type CloudClientConnectionStatus = "connected" | "connecting" | "reconnecting" | "disconnected"
+export type CloudClientAudioTransport = "udp" | "ws" | "offline" | "none"
+
+export interface CloudClientStatusSnapshot {
+  status: CloudClientConnectionStatus
+  audioTransport: CloudClientAudioTransport
+}
+
+export interface MiniappAuthToken {
+  mentraUserId: string
+  tenantId?: string
+  token: string
+  expiresAt: number
+}
+
+/**
+ * Result of an offline TTS synthesis. The engine's TTSModelManager produces
+ * this directly; the type is kept exported for hosts that wrap it.
+ */
+export interface TtsSynthesisResult {
+  audioUrl: string
+  cleanup?: () => Promise<void> | void
+}
+
+/**
+ * Stable settings keys read by engine services. Hosts must wire their own
+ * settings store keys to these names. Mobile already uses these strings.
+ */
+export const ISLAND_SETTINGS_KEYS = {
+  localSttFallbackActive: "local_stt_fallback_active",
+  defaultWearable: "default_wearable",
+  coreToken: "core_token",
+  cameraFov: "camera_fov",
+} as const
+
+/**
+ * Navigation event payloads. Mirror the host's NavigationService types but are
+ * duplicated here so the engine module does not import host types.
+ */
+export type NavManeuverEvent = {
+  kind: "maneuver"
+  maneuverType: string
+  distanceMeters: number
+  fromRoad?: string | null
+  toRoad?: string | null
+  nextStepRoad?: string | null
+  distanceToDestinationMeters?: number
+  timeToDestinationSeconds?: number
+  currentSpeedMps?: number | null
+  speedLimitMps?: number | null
+  routeHeadingDeg?: number | null
+}
+export type NavOffRouteEvent = {kind: "off_route"; offRouteDistanceMeters: number}
+export type NavReroutingEvent = {kind: "rerouting"}
+export type NavArrivedEvent = {kind: "arrived"}
+export type NavErrorEvent = {kind: "error"; message: string}
+export type NavUpdate = NavManeuverEvent | NavOffRouteEvent | NavReroutingEvent | NavArrivedEvent | NavErrorEvent
+
+export type NavLocation = {
+  lat: number
+  lng: number
+  accuracy: number | null
+  timestamp: number
+}
+
+export type NavRouteStep = {
+  lat: number
+  lng: number
+  routeIndex: number
+  road: string | null
+  maneuver: string
+  distanceMeters: number
+}
+export type NavRoute = {
+  points: Array<{lat: number; lng: number}>
+  steps?: NavRouteStep[]
+}
+
+export type NavTripSnapshot = {
+  active: boolean
+  mode?: string
+  stops?: Array<{lat: number; lng: number}>
+  currentStopIndex?: number
+  route?: NavRoute
+  maneuver?: NavManeuverEvent
+  distanceToDestinationMeters?: number
+  timeToDestinationSeconds?: number
+  currentSpeedMps?: number | null
+  speedLimitMps?: number | null
+}
+
+export interface StreamVideoConfig {
+  width?: number
+  height?: number
+  bitrate?: number
+  fps?: number
+}
+
+export interface StreamAudioConfig {
+  bitrate?: number
+  sampleRate?: number
+  echoCancellation?: boolean
+  noiseSuppression?: boolean
+}
+
+export type CameraRoiPosition = "center" | "bottom" | "top"
+export type CameraFovPreset = "narrow" | "standard" | "wide"
+
+export type CameraFovRequest =
+  | {
+      fov: number
+      roiPosition?: CameraRoiPosition
+    }
+  | {
+      preset: CameraFovPreset
+    }
+
+export interface CameraFovResult {
+  requestId: string
+  fov: number
+  roiPosition: CameraRoiPosition
+  timestamp: number
+}
+
+/** One audited inter-miniapp call. */
+export interface InteropAuditEvent {
+  /** The system app that made the call. */
+  caller: string
+  op: "list" | "start" | "stop" | "invoke"
+  /** Target miniapp (start/stop/invoke). */
+  target?: string
+  /** Action id (invoke only). */
+  actionId?: string
+  /** True if the call was permitted and accepted; false on denial / pre-flight failure. */
+  ok: boolean
+  /** MiniappErrorCode when ok is false. */
+  errorCode?: string
+}
+

package/src/runtime/streamConfig.ts

@@ -0,0 +1,34 @@
+import type {StreamAudioConfig, StreamVideoConfig} from "./config"
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value)
+
+const finiteNumber = (value: unknown): number | undefined =>
+  typeof value === "number" && Number.isFinite(value) ? value : undefined
+
+export const normalizeStreamVideoConfig = (value: unknown): StreamVideoConfig | undefined => {
+  if (!isRecord(value)) return undefined
+  const config: StreamVideoConfig = {}
+  const width = finiteNumber(value.width)
+  const height = finiteNumber(value.height)
+  const bitrate = finiteNumber(value.bitrate)
+  const frameRate = finiteNumber(value.frameRate)
+  const fps = frameRate ?? finiteNumber(value.fps)
+  if (width !== undefined) config.width = width
+  if (height !== undefined) config.height = height
+  if (bitrate !== undefined) config.bitrate = bitrate
+  if (fps !== undefined) config.fps = fps
+  return Object.keys(config).length > 0 ? config : undefined
+}
+
+export const normalizeStreamAudioConfig = (value: unknown): StreamAudioConfig | undefined => {
+  if (!isRecord(value)) return undefined
+  const config: StreamAudioConfig = {}
+  const bitrate = finiteNumber(value.bitrate)
+  const sampleRate = finiteNumber(value.sampleRate)
+  if (bitrate !== undefined) config.bitrate = bitrate
+  if (sampleRate !== undefined) config.sampleRate = sampleRate
+  if (typeof value.echoCancellation === "boolean") config.echoCancellation = value.echoCancellation
+  if (typeof value.noiseSuppression === "boolean") config.noiseSuppression = value.noiseSuppression
+  return Object.keys(config).length > 0 ? config : undefined
+}