@glassly/engine 0.1.0-dev.0

package/src/facades/speech.ts

@@ -0,0 +1,49 @@
+/**
+ * speech facade — `engine.speech.{stt,tts}`: on-device STT/TTS model management,
+ * wrapping the in-engine model managers. Thin passthrough (args forwarded with
+ * exact types via Parameters<>), so the facade never drifts from the managers.
+ * STT additionally exposes the auto-download status stream (the TTS path has none).
+ */
+import BluetoothSdk from "@glassly/bluetooth-sdk/internal"
+import sttModelManager from "../services/STTModelManager"
+import ttsModelManager from "../services/TTSModelManager"
+import offlineSpeechModelService from "../services/OfflineSpeechModelService"
+import sonioxDirectService from "../services/soniox/SonioxDirectService"
+
+export const speech = {
+  /** Restart the glasses' on-device transcriber (e.g. after switching STT language). */
+  restartTranscriber: (): Promise<void> => BluetoothSdk.restartTranscriber(),
+  stt: {
+    currentLanguage: () => sttModelManager.getCurrentLanguage(),
+    languages: () => sttModelManager.getAvailableLanguages(),
+    languageInfo: () => sttModelManager.getAllLanguageInfo(),
+    download: (...args: Parameters<typeof sttModelManager.downloadModel>) => sttModelManager.downloadModel(...args),
+    activate: (code: string) => sttModelManager.setCurrentLanguage(code),
+    cancelDownload: () => sttModelManager.cancelDownload(),
+    deleteModel: (...args: Parameters<typeof sttModelManager.deleteModel>) => sttModelManager.deleteModel(...args),
+    /** Current auto-download status of the offline STT model. */
+    status: () => offlineSpeechModelService.getStatus(),
+    /** Subscribe to auto-download status changes; returns an unsubscribe. */
+    onStatusChanged: (...args: Parameters<typeof offlineSpeechModelService.subscribe>) =>
+      offlineSpeechModelService.subscribe(...args),
+  },
+  /** Phone → Soniox direct transcription (user-supplied API key, Settings > Keys). */
+  sonioxDirect: {
+    getStatus: () => sonioxDirectService.getStatus(),
+    /** Subscribe to status changes; returns an unsubscribe. */
+    onStatusChanged: (...args: Parameters<typeof sonioxDirectService.onStatusChanged>) =>
+      sonioxDirectService.onStatusChanged(...args),
+    /** Probe a key against the Soniox API without saving it. */
+    validateKey: (...args: Parameters<typeof sonioxDirectService.validateApiKey>) =>
+      sonioxDirectService.validateApiKey(...args),
+  },
+  tts: {
+    currentLanguage: () => ttsModelManager.getCurrentLanguage(),
+    languages: () => ttsModelManager.getAvailableLanguages(),
+    languageInfo: () => ttsModelManager.getAllLanguageInfo(),
+    download: (...args: Parameters<typeof ttsModelManager.downloadModel>) => ttsModelManager.downloadModel(...args),
+    activate: (code: string) => ttsModelManager.setCurrentLanguage(code),
+    cancelDownload: () => ttsModelManager.cancelDownload(),
+    deleteModel: (...args: Parameters<typeof ttsModelManager.deleteModel>) => ttsModelManager.deleteModel(...args),
+  },
+}

package/src/index.ts

@@ -0,0 +1,214 @@
+/**
+ * `@glassly/engine` — the OEM-facing main entry.
+ *
+ * The `engine` namespace (configure/start/stop + typed domain facades), the
+ * public contract/read-model types, and the pure helpers host UI legitimately
+ * renders with (decision functions, sort/order helpers, policy constants,
+ * capability tables, timers). Judgment rule: read models, commands, pure
+ * functions and types belong here; anything that mutates runtime state or
+ * exposes a raw store/service lives on `@glassly/engine/internal`
+ * (migration-era surface) or `@glassly/engine/devtools` (debug-only) instead.
+ * See cloud-v2/docs/issues/020-glasses-status-boundary/integration-review.md §D.
+ */
+
+// The namespaced OEM-facing engine API (the "(A) host API"). See ./engine.
+export {engine} from "./engine"
+export type {
+  ReportAttachmentInput,
+  ReportContext,
+  ReportDetails,
+  ReportStatus,
+  ReportTrigger,
+  ReportSubmitResult,
+  EngineSubmitReportInput,
+} from "./facades/reports"
+export type {IslandNotification, IslandNotificationKind} from "./facades/notifications"
+export type {WifiSearchResult} from "./facades/glassesWifi"
+export type {IdentitySnapshot} from "./services/PairingIdentity"
+export type {DisplayMirrorEvent} from "./facades/displayMirror"
+export type {
+  IslandConfigureOptions,
+  IslandAuth,
+  IslandConfigValues,
+  IslandAnalytics,
+  IslandUiSeams,
+  ScanQrOptions,
+  ScanQrResult,
+  SubjectTokenType,
+} from "./runtime/bootstrap"
+
+// Settings contract: the typed key registry (schema descriptors — the same
+// surface engine.settings.descriptor()/keys() reads), the per-key React hook
+// (the hook layer, same precedent as the apps hooks below), and the pure
+// device-model key helpers. The raw useSettingsStore stays internal;
+// imperative access goes through engine.settings.
+export {SETTINGS, useSetting} from "./stores/settings"
+
+// AI tier registry: the curated per-tier model dropdown options and helpers
+// the Settings > AI Models screen renders. Resolution itself runs inside
+// LocalMiniappRuntime; the screen only reads/writes the ai_model_* settings.
+export {AI_TIERS, TIER_MODEL_OPTIONS, parseTierSetting} from "./services/AiTierResolution"
+export type {AiTier, AiTierProvider, TierModelOption} from "./services/AiTierResolution"
+
+// Shared user memory timeline (engine.memory / Settings > Memory). Entry and
+// session shapes are canonical in @glassly/miniapp (the session.memory
+// surface); the stats read model is engine-side.
+export type {MemoryStats} from "./services/MemoryStore"
+export type {SpeakerProfile} from "./services/SpeakerProfileStore"
+export type {EnrollOutcome} from "./facades/speakers"
+export {MENTRA_LIVE_SETTING_KEYS, getBluetoothSettingKeysForDevice} from "./stores/bluetoothSettingKeys"
+
+// Runtime-shared constants and contract DTOs.
+export {ISLAND_SETTINGS_KEYS} from "./runtime/config"
+export type {CloudClientStatusSnapshot, MiniappAuthToken, InteropAuditEvent, TtsSynthesisResult} from "./runtime/config"
+
+// Pure readiness predicates over glasses connection state.
+export {
+  isGlassesConnected,
+  isGlassesReady,
+  isGlassesLinkLayerBusy,
+  waitForGlassesReady,
+  type GlassesConnectionStatus,
+  type WaitForGlassesReadyOptions,
+} from "./services/GlassesReadiness"
+// Pure connect/reconnect decision helpers (host UI renders the outcome).
+export {
+  decideReconnect,
+  decideConnectButtonAction,
+  type ReconnectDecision,
+  type ReconnectDecisionInput,
+  type ConnectButtonAction,
+} from "./services/ConnectionCoordinator"
+
+// OTA read-model types for host OTA UI (progress screen, error mapping,
+// progress section) — the check/install machinery itself is internal.
+export type {
+  VersionInfo,
+  MtkPatch,
+  BesFirmware,
+  VersionJson,
+  OtaCheckResult,
+  OtaCheckCurrentGlassesResult,
+  OtaCheckCurrentGlassesOptions,
+} from "./services/OtaUpdateCheckService"
+// OTA install policy (watchdog timings + failure copy) + display-state
+// derivation, consumed by the OTA screens and their tests.
+export {
+  MINIMUM_OTA_STATUS_BUILD,
+  MAX_RETRIES,
+  RETRY_INTERVAL_MS,
+  PROGRESS_TIMEOUT_MS,
+  DOWNLOAD_STUCK_TIMEOUT_MS,
+  MTK_INSTALL_TIMEOUT_MS,
+  GLOBAL_OTA_TIMEOUT_MS,
+  PING_INTERVAL_MS,
+  QUERY_REPLY_TIMEOUT_MS,
+  OtaProgressMessages,
+} from "./services/otaInstallPolicy"
+export {deriveDisplayState} from "./services/otaDisplayState"
+export type {DisplayState} from "./services/otaDisplayState"
+export type {
+  OtaProgress,
+  OtaProgressStatus,
+  OtaStatus,
+  OtaUpdateInfo,
+  OtaSnapshot,
+  OtaInstallSnapshot,
+} from "./facades/ota"
+
+// Gallery read models: engine.gallery.onNotice payload types, the media
+// permission helper + display-name derivation host gallery UI uses, and the
+// glasses-camera DTO types (re-exported through the host @/types/asg shim).
+export type {GalleryNotice, GalleryNoticeCode} from "./services/asg/galleryNotices"
+export {MediaLibraryPermissions} from "./utils/permissions/MediaLibraryPermissions"
+export {deriveGalleryDisplayName} from "./utils/permissions/galleryDisplayName"
+export type {
+  PhotoInfo,
+  CaptureFile,
+  CaptureGroup,
+  GalleryResponse,
+  ServerStatus,
+  HealthResponse,
+  GalleryEvent,
+} from "./types/asg"
+
+// Bluetooth SDK event types host UI subscribes to via engine facades (the
+// BluetoothSdk singleton passthrough itself is internal).
+export type {PairFailureEvent, GlassesNotReadyEvent} from "@glassly/bluetooth-sdk/internal"
+
+// Cloud connection status enum (read model; the connection store is internal).
+export {WebSocketStatus} from "./stores/connection"
+
+// App-list hook layer + pure list helpers (the raw useAppStatusStore and
+// installAppStoreHooks wiring are internal).
+export {
+  DUMMY_APPLET,
+  saveAppsOrder,
+  getAppsOrder,
+  sortAppsByPackageNamePriority,
+  saveLastOpenTime,
+  getLastOpenTime,
+  sortAppsByLastOpenTime,
+  useApps,
+  useStart,
+  useStop,
+  useSetForeground,
+  useClearForeground,
+  useRefresh,
+  useStopAll,
+  useInstall,
+  useUninstall,
+  useActiveApps,
+  useActiveBackgroundApps,
+  useBackgroundApps,
+  useActiveForegroundApp,
+  useForegroundApp,
+  useActiveBackgroundAppsCount,
+  useLocalMiniApps,
+  type StartOptions,
+  type OrderMap,
+} from "./stores/apps"
+
+// Pure dev-miniapp launch-route decision (registration itself is internal).
+export {
+  decideDevLaunchRoute,
+  type DecideDevLaunchOptions,
+  type DevLaunchResult,
+  type DevManifest,
+} from "./utils/devMiniappLaunch"
+export {HardwareCompatibility, type CompatibilityResult} from "./utils/hardware"
+export {BgTimer, throttle, debounce} from "./utils/timers"
+
+// Types (hardware requirement types are canonical in @glassly/miniapp; the rest are engine-owned)
+export {
+  HardwareType,
+  HardwareRequirementLevel,
+  DeviceTypes,
+  ControllerTypes,
+  HARDWARE_CAPABILITIES,
+  getModelCapabilities,
+  simulatedGlasses,
+  evenRealitiesG1,
+  evenRealitiesG2,
+  mentraLive,
+  vuzixZ100,
+  mentraDisplay,
+  nimo,
+} from "./types"
+export type {
+  HardwareRequirement,
+  CameraCapabilities,
+  DisplayCapabilities,
+  MicrophoneCapabilities,
+  SpeakerCapabilities,
+  IMUCapabilities,
+  ButtonCapabilities,
+  LightCapabilities,
+  PowerCapabilities,
+  Capabilities,
+  AppletType,
+  AppPermissionType,
+  AppletPermission,
+  AppletInterface,
+  ClientApp,
+} from "./types"

package/src/internal.ts

@@ -0,0 +1,155 @@
+/**
+ * `@glassly/engine/internal` — the migration-era runtime surface.
+ *
+ * Raw zustand stores and service singletons that the Glassly app's host-side
+ * services (and the `@/stores/*` / `@/utils/*` shims) still reach into while
+ * the typed `engine` facades grow. Everything here either mutates runtime
+ * state or exposes a store/service directly, so none of it belongs on the
+ * OEM-facing `@glassly/engine` main entry: new host code should read/act
+ * through `engine.*` instead.
+ *
+ * Every `/internal` import in mobile/src is counted (report-only) by
+ * scripts/check-mobile-runtime-boundary.sh; the burn-down plan is
+ * cloud-v2/docs/issues/020-glasses-status-boundary/integration-review.md §D.
+ * Types that only describe these internal surfaces live here with them;
+ * types host UI renders with stay on the main entry.
+ */
+
+// Miniapp runtime plumbing: WebView bridge, registry, launcher, engine.
+export {default as webviewBridge} from "./services/WebviewBridge"
+export {
+  default as appRegistry,
+  normalizeManifestPermissions,
+  normalizeManifestActions,
+  buildHardwareRequirements,
+  saveLocalAppRunningState,
+  deriveDevPackageId,
+  registerDevApp,
+  unregisterDevApp,
+  getDevAppRecords,
+  getDevAppSourcePackage,
+  getDevAppAttestation,
+  DEV_APP_PACKAGE_NAME,
+  type DevAppRecord,
+  type MiniappReleaseIdentity,
+} from "./services/AppRegistry"
+export {default as displayProcessor} from "./services/DisplayProcessor"
+export {default as localDisplayManager, type DisplayPayload} from "./services/LocalDisplayManager"
+export {default as localMiniappRuntime, type InstalledMiniappManifest} from "./services/LocalMiniappRuntime"
+export {miniappLauncher, type LaunchHints, type LaunchResult, type ResolvedBundle} from "./services/MiniappLauncher"
+export {
+  JSRouter,
+  type JSCrustBinding,
+  type OutboundMessagePayload as JSOutboundMessage,
+  type RouterLogger as JSRouterLogger,
+} from "./services/JSRouter"
+export {buildUiShim, type UiShimOptions} from "./services/uiShim"
+export {UIRouter, type UICrustBinding} from "./services/UIRouter"
+export {
+  JSCrashController,
+  type CrashState,
+  type CrashOutcome,
+  type CrashControllerOptions,
+} from "./services/JSCrashController"
+export {ensureMiniappEngine, getMiniappEngine, type MiniappEngine} from "./services/MiniappEngine"
+export {redactSecrets, JSLogThrottle, JSLogRingBuffer, type ThrottleOptions} from "./services/JSLogPipeline"
+// WebView-injection script builders (miniapp globals + glassly-ui shim).
+export {
+  buildMiniappGlobalsScript,
+  getCapsuleMenuRect,
+  type BuildMiniappGlobalsOptions,
+  type CapsuleMenuRect,
+  type MiniappColorScheme,
+  type MiniappSafeArea,
+} from "./utils/miniappGlobals"
+
+// Speech/audio coordinators and model managers.
+export {default as localSttFallbackCoordinator} from "./services/LocalSttFallbackCoordinator"
+export {default as micStateCoordinator} from "./services/MicStateCoordinator"
+export {default as audioPlaybackService} from "./services/AudioPlaybackService"
+export {
+  default as sttModelManager,
+  STTModelManager,
+  type LanguageInfo as SttLanguageInfo,
+  type LanguageConfig as SttLanguageConfig,
+  type DownloadProgress as SttDownloadProgress,
+  type ExtractionProgress as SttExtractionProgress,
+} from "./services/STTModelManager"
+export {default as ttsModelManager, TTSModelManager} from "./services/TTSModelManager"
+export {
+  default as offlineSpeechModelService,
+  type DownloadStatus as OfflineModelDownloadStatus,
+  type DownloadStage as OfflineModelDownloadStage,
+} from "./services/OfflineSpeechModelService"
+
+export {default as navigationService} from "./services/NavigationService"
+// Phone GPS — the background location task + tier control. Importing this
+// module registers the background task, so the entry that MantleManager loads
+// must keep re-exporting it (was: the main barrel).
+export {phoneLocationService, stopPhoneLocation} from "./services/PhoneLocationService"
+// Clock-skew fix commands (BLE writes) used by OTA + gallery sync.
+export {fixGlassesClockIfSkewed, maybeFixGlassesClockFromVersionInfo} from "./services/glassesClockSync"
+// OTA manifest-URL resolution (dev-override/legacy-build/env/prod).
+export {resolveOtaManifestUrl} from "./services/otaManifestUrl"
+// Flat OTA check helpers (network + BLE state). Host usage is a tracked
+// burn-down surface (§F); the sanctioned path is engine.ota.checkForUpdates().
+export {
+  fetchVersionInfo,
+  checkVersionUpdateAvailable,
+  getLatestVersionInfo,
+  findMatchingMtkPatch,
+  checkBesUpdate,
+  checkForOtaUpdate,
+  checkCurrentGlassesForUpdate,
+} from "./services/OtaUpdateCheckService"
+
+// Gallery cluster — sync orchestrator, glasses-camera HTTP API, media/storage,
+// settings, validation and the service-to-service notice bus. Host gallery UI
+// renders engine.gallery; these are the underlying services.
+export {detectClockSkew, isSyncManifestEmpty, CLOCK_SKEW_TOLERANCE_MS} from "./services/gallerySyncClock"
+export {gallerySyncService} from "./services/asg/gallerySyncService"
+export {asgCameraApi} from "./services/asg/asgCameraApi"
+export {localStorageService} from "./services/asg/localStorageService"
+export {mediaProcessingQueue} from "./services/asg/mediaProcessingQueue"
+export {gallerySettingsService} from "./services/asg/gallerySettingsService"
+export {cameraRollExportCoordinator, type CameraRollExportSummary} from "./services/asg/cameraRollExportCoordinator"
+export {
+  INVALID_DOWNLOADED_MEDIA,
+  validateCaptureMetadataForDownload,
+  validateDownloadedMediaFile,
+} from "./services/asg/galleryMediaValidation"
+export {emitGalleryNotice, onGalleryNotice} from "./services/asg/galleryNotices"
+
+// Phone-side capture coordinators.
+export {phonePhotoCoordinator} from "./services/PhonePhotoCoordinator"
+export {phoneStreamCoordinator} from "./services/PhoneStreamCoordinator"
+
+// Raw runtime stores (re-exported via the host @/stores/* shims). Read models
+// live on the engine facades; these are the migration escape hatch.
+export {useDisplayStore, flushDisplayCoalesceForTests} from "./stores/display"
+export {useCoreStore} from "./stores/core"
+export {useConnectionStore} from "./stores/connection"
+export {useCloudClientStatusStore} from "./stores/cloudClientStatus"
+export type {RuntimeAudioTransport, RuntimeSnapshot, RuntimeStatus} from "./stores/cloudClientStatus"
+export {SETTINGS, OFFLINE_APPLETS, useSettingsStore, useSetting} from "./stores/settings"
+export {MENTRA_LIVE_SETTING_KEYS, getBluetoothSettingKeysForDevice} from "./stores/bluetoothSettingKeys"
+export {useAppStatusStore, installAppStoreHooks, type AppStoreHooks} from "./stores/apps"
+
+// Cloud client + credentials + v1 comms.
+export {cloudSecureStore} from "./utils/cloudClient/cloudSecureStore"
+export {cloudClientService} from "./services/CloudClientService"
+export {createCloudUdpSocket} from "./utils/cloudClient/RnUdpAdapter"
+
+// Log ring buffer + console interception (bug-report attachments).
+export {logBuffer, type LogEntry} from "./utils/devLogging"
+
+// Bluetooth SDK internal compatibility passthrough. Prefer an engine facade
+// when one exists; this remains an escape hatch for app-only compatibility
+// needs (its event TYPES stay on the main entry).
+export {default as BluetoothSdk} from "@glassly/bluetooth-sdk/internal"
+
+// Engine-owned MMKV instance + debug helper.
+export {storage, printDirectory} from "./utils/storage"
+// Process-wide event bus — one shared instance for engine services + host
+// (re-exported via the @/utils/GlobalEventEmitter shim).
+export {default as GlobalEventEmitter} from "./utils/GlobalEventEmitter"

package/src/runtime/bootstrap.ts

@@ -0,0 +1,159 @@
+/**
+ * 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
+  /**
+   * Optional dead-session hook. Fired when the cloud client's credentials are
+   * unrecoverable (refresh AND subject-token exchange both failed — e.g. the
+   * backend rejected tokens minted by a different environment, or the session
+   * was revoked). The host should sign the user out and route back to login;
+   * without this the app keeps looking signed-in while every cloud feature
+   * silently fails.
+   */
+  onSessionExpired?: () => void
+}
+
+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 (Glassly 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, packageName?: string) => Promise<void> | void
+  /**
+   * `session.system.scanQr` — open a phone-camera QR scanner overlay. Must NOT
+   * clear miniapp foreground: UI_CLOSE on a live call hangs it up. Absent ⇒
+   * miniapps get NOT_IMPLEMENTED.
+   */
+  scanQr?: (options?: ScanQrOptions) => Promise<ScanQrResult>
+}
+
+export interface ScanQrOptions {
+  title?: string
+  hint?: string
+}
+
+export type ScanQrResult = {data: string} | {cancelled: true}
+
+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
+}
+
+/**
+ * Merge host-UI seams after configure/start. UI capabilities (scan overlay,
+ * wifi setup) are looked up per request, so this is safe on a running runtime.
+ * Used so Metro reloads can attach seams that missed the original configure().
+ */
+export function updateUiSeams(ui: IslandUiSeams): void {
+  if (!options) {
+    console.warn("engine.updateUiSeams() called before engine.configure(); ignored")
+    return
+  }
+  options = {...options, ui: {...options.ui, ...ui}}
+}
+
+/** 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
+}
+
+/** Test-only: wipe configure state so suites can start from a cold host. */
+export function resetForTests(): void {
+  options = null
+  started = false
+}
+
+/** 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 ?? {}
+}