@mentra/engine 0.1.0-beta.0 → 0.1.0-dev.1

package/src/services/PhoneStreamCoordinator.ts

@@ -58,6 +58,9 @@ const DEFAULT_TIMINGS = {
   ackTimeoutMs: 10_000,
   maxMissedAcks: 3,
   cloudflareStatusPollMs: 5_000,
+  // During WHIP startup, probe quickly so readiness is not quantized to the
+  // steady-state 5s monitoring cadence. The delay backs off on each miss.
+  cloudflareStartupPollInitialMs: 500,
   // Cloudflare typically needs ~5-10s after first frame before HLS is live.
   hlsReadinessInitialDelayMs: 5_000,
   hlsReadinessPollMs: 2_000,
@@ -85,6 +88,8 @@ export interface StartUnmanagedOptions {
   video?: StreamStartRequest["video"]
   audio?: StreamStartRequest["audio"]
   sound?: boolean
+  /** Optional Bearer token for WHIP Authorization (custom authenticated endpoints). */
+  authToken?: string
 }
 
 export interface StartManagedOptions {
@@ -99,8 +104,10 @@ export interface StartManagedOptions {
    *   - "whip": WebRTC ingest -> WHEP playback (<1s glass-to-screen), but NO
    *     HLS/DASH playback and NO recording (Cloudflare limitation; the returned
    *     hlsUrl will serve 204 forever).
+   *   - "rtmp": RTMPS ingest over TCP 443 -> HLS playback. Survives networks
+   *     that drop WHIP/SRT UDP.
    */
-  ingest?: "srt" | "whip"
+  ingest?: "srt" | "whip" | "rtmp"
 }
 
 export interface StreamPublisherStartResult {
@@ -152,11 +159,13 @@ interface ManagedEntry {
   hlsReady: boolean
   hlsReadyResolvers: Array<(result: ManagedStartResult) => void>
   hlsReadyRejecters: Array<(err: Error) => void>
-  cloudflareTimer?: ReturnType<typeof setInterval>
+  cloudflareTimer?: ReturnType<typeof setTimeout>
   hlsTimer?: ReturnType<typeof setInterval>
   hlsAttempts: number
-  /** webrtc mode: CF status polls seen while waiting for first "connected". */
-  connectAttempts: number
+  /** Cloudflare status probes made during this stream session. */
+  cloudflareAttempts: number
+  /** Wall-clock origin for end-to-end managed startup diagnostics. */
+  startupStartedAtMs: number
 }
 
 type Entry = UnmanagedEntry | ManagedEntry
@@ -250,6 +259,26 @@ export class PhoneStreamCoordinator {
     return this.current !== null && this.current.streamId === streamId
   }
 
+  /** Report-safe stream ownership snapshot for incident diagnostics. */
+  getDiagnosticSnapshot(): Record<string, unknown> {
+    if (!this.current) return {active: false}
+    return this.current.kind === "managed"
+      ? {
+          active: true,
+          kind: this.current.kind,
+          streamId: this.current.streamId,
+          subscribers: [...this.current.subscribers].sort(),
+          mode: this.current.mode,
+          playbackReady: this.current.hlsReady,
+        }
+      : {
+          active: true,
+          kind: this.current.kind,
+          streamId: this.current.streamId,
+          ownerPackageName: this.current.packageName,
+        }
+  }
+
   async startUnmanaged(
     packageName: string,
     opts: StartUnmanagedOptions,
@@ -289,6 +318,7 @@ export class PhoneStreamCoordinator {
           // undefined, expected an Object") — only include what was provided.
           ...(opts.video !== undefined ? {video: opts.video} : {}),
           ...(opts.audio !== undefined ? {audio: opts.audio} : {}),
+          ...(opts.authToken ? {authToken: opts.authToken} : {}),
         })
         const result = publisherStartResult(streamId, event)
         this.startLifecycle(streamId)
@@ -304,6 +334,15 @@ export class PhoneStreamCoordinator {
     packageName: string,
     opts: StartManagedOptions,
   ): Promise<ManagedStartResult> {
+    const startupStartedAtMs = Date.now()
+    // streamId doesn't exist yet — it's minted a few lines below, once we
+    // know this is a fresh provision rather than a join onto an existing one.
+    console.info("[STREAM_STARTUP]", {
+      stage: "requested",
+      packageName,
+      ingest: opts.ingest,
+      elapsedMs: 0,
+    })
     // Two-phase: the entry-claim runs under the transition lock; the wait for
     // HLS readiness happens AFTER the lock releases so a long warm-up doesn't
     // block subsequent start/stop transitions on this coordinator.
@@ -362,10 +401,18 @@ export class PhoneStreamCoordinator {
         hlsReadyResolvers: [],
         hlsReadyRejecters: [],
         hlsAttempts: 0,
-        connectAttempts: 0,
+        cloudflareAttempts: 0,
+        startupStartedAtMs,
       }
       this.current = entry
 
+      console.info("[STREAM_STARTUP]", {
+        streamId,
+        stage: "provisioned",
+        mode,
+        elapsedMs: Date.now() - startupStartedAtMs,
+      })
+
       try {
         const event = await BluetoothSdk.startExternallyManagedStream({
           type: "start_stream",
@@ -377,6 +424,12 @@ export class PhoneStreamCoordinator {
           ...(opts.audio !== undefined ? {audio: opts.audio} : {}),
         })
         entry.publisherStart = publisherStartResult(streamId, event)
+        console.info("[STREAM_STARTUP]", {
+          streamId,
+          stage: "publisher_ready",
+          mode,
+          elapsedMs: Date.now() - startupStartedAtMs,
+        })
       } catch (err) {
         this.current = null
         await teardownManagedStream(provision.liveInputId).catch(() => undefined)
@@ -398,6 +451,13 @@ export class PhoneStreamCoordinator {
       return decision.immediate
     }
 
+    // The first Cloudflare probe runs immediately and can complete before the
+    // transition lock releases. Avoid stranding this caller after readiness
+    // resolvers have already been drained.
+    if (decision.entry.hlsReady) {
+      return managedStartResult(decision.entry)
+    }
+
     // Wait for playback readiness OUTSIDE the lock — readiness can take ~10s
     // and we don't want to block other transitions for that long.
     return new Promise<ManagedStartResult>((resolve, reject) => {
@@ -530,20 +590,41 @@ export class PhoneStreamCoordinator {
   }
 
   private startCloudflareStatusPoll(entry: ManagedEntry): void {
-    // webrtc mode: how many polls to wait for the first "connected" before
-    // declaring the publisher never reached Cloudflare. Mirrors the HLS
-    // readiness budget (~60s at the default 5s cadence).
-    const maxConnectAttempts = Math.max(
-      1,
-      Math.ceil(
-        (this.timings.hlsReadinessMaxAttempts * this.timings.hlsReadinessPollMs) /
-          this.timings.cloudflareStatusPollMs,
-      ),
-    )
+    // Keep the existing ~60s readiness budget while decoupling it from probe
+    // count. Startup probes begin immediately and back off to the normal 5s
+    // monitoring cadence, so a just-connected publisher is noticed quickly
+    // without increasing steady-state traffic.
+    const connectTimeoutMs = Math.max(1, this.timings.hlsReadinessMaxAttempts * this.timings.hlsReadinessPollMs)
+    const pollingStartedAtMs = Date.now()
+
+    const scheduleNext = () => {
+      if (this.current !== entry) return
+      const waitingForWebRtc = entry.mode === "webrtc" && !entry.hlsReady
+      const elapsedMs = Date.now() - pollingStartedAtMs
+      const remainingMs = Math.max(0, connectTimeoutMs - elapsedMs)
+      const startupDelayMs = Math.min(
+        this.timings.cloudflareStatusPollMs,
+        this.timings.cloudflareStartupPollInitialMs * 2 ** Math.min(Math.max(0, entry.cloudflareAttempts - 1), 10),
+      )
+      const delayMs = waitingForWebRtc ? Math.min(startupDelayMs, remainingMs) : this.timings.cloudflareStatusPollMs
+      entry.cloudflareTimer = setTimeout(() => void poll(), delayMs)
+    }
+
     const poll = async () => {
       if (this.current !== entry) return
+      const requestStartedAtMs = Date.now()
+      let keepPolling = true
+      entry.cloudflareAttempts += 1
       try {
         const status: CloudflareStatus = await getManagedStreamStatus(entry.liveInputId)
+        console.debug("[STREAM_STARTUP]", {
+          streamId: entry.streamId,
+          stage: "cloudflare_probe",
+          connected: status.isConnected,
+          attempt: entry.cloudflareAttempts,
+          requestMs: Date.now() - requestStartedAtMs,
+          elapsedMs: Date.now() - entry.startupStartedAtMs,
+        })
         this.fanout({
           streamId: entry.streamId,
           source: "cloudflare",
@@ -556,6 +637,13 @@ export class PhoneStreamCoordinator {
         if (entry.mode === "webrtc" && !entry.hlsReady) {
           if (status.isConnected) {
             entry.hlsReady = true
+            console.info("[STREAM_STARTUP]", {
+              streamId: entry.streamId,
+              stage: "playback_ready",
+              mode: entry.mode,
+              probes: entry.cloudflareAttempts,
+              elapsedMs: Date.now() - entry.startupStartedAtMs,
+            })
             const result = managedStartResult(entry)
             for (const r of entry.hlsReadyResolvers) r(result)
             entry.hlsReadyResolvers = []
@@ -567,11 +655,8 @@ export class PhoneStreamCoordinator {
               data: result as unknown as Record<string, unknown>,
             })
           } else {
-            entry.connectAttempts += 1
-            if (entry.connectAttempts >= maxConnectAttempts) {
-              const err = new Error(
-                `WebRTC ingest never reached Cloudflare after ${entry.connectAttempts} status polls`,
-              )
+            if (Date.now() - pollingStartedAtMs >= connectTimeoutMs) {
+              const err = new Error(`WebRTC ingest never reached Cloudflare after ${connectTimeoutMs}ms`)
               for (const reject of entry.hlsReadyRejecters) reject(err)
               entry.hlsReadyResolvers = []
               entry.hlsReadyRejecters = []
@@ -586,15 +671,32 @@ export class PhoneStreamCoordinator {
                 if (this.current?.streamId !== targetStreamId) return
                 await this.teardownLocked("webrtc_not_connected")
               })
+              keepPolling = false
             }
           }
         }
       } catch (err) {
         console.warn("[STREAM] cloudflare status poll failed:", err)
+        if (entry.mode === "webrtc" && !entry.hlsReady && Date.now() - pollingStartedAtMs >= connectTimeoutMs) {
+          const timeoutErr = new Error(`WebRTC ingest status could not be confirmed after ${connectTimeoutMs}ms`)
+          for (const reject of entry.hlsReadyRejecters) reject(timeoutErr)
+          entry.hlsReadyResolvers = []
+          entry.hlsReadyRejecters = []
+          const targetStreamId = entry.streamId
+          void this.runExclusive(async () => {
+            if (this.current?.streamId !== targetStreamId) return
+            await this.teardownLocked("webrtc_status_unavailable")
+          })
+          keepPolling = false
+        }
+      } finally {
+        if (keepPolling) scheduleNext()
       }
     }
-    entry.cloudflareTimer = setInterval(poll, this.timings.cloudflareStatusPollMs)
-    // Don't fire immediately — Cloudflare wouldn't have first-frame yet.
+
+    // The glasses publisher has already reported streaming, so the first
+    // status request is useful now. Most starts avoid the old blind 5s wait.
+    void poll()
   }
 
   private startHlsReadinessPoll(entry: ManagedEntry): void {
@@ -610,6 +712,13 @@ export class PhoneStreamCoordinator {
         const res = await fetch(entry.hlsUrl, {method: "HEAD"})
         if (res.status === 200) {
           entry.hlsReady = true
+          console.info("[STREAM_STARTUP]", {
+            streamId: entry.streamId,
+            stage: "playback_ready",
+            mode: entry.mode,
+            probes: entry.hlsAttempts,
+            elapsedMs: Date.now() - entry.startupStartedAtMs,
+          })
           if (entry.hlsTimer) {
             clearInterval(entry.hlsTimer)
             entry.hlsTimer = undefined
@@ -697,7 +806,7 @@ export class PhoneStreamCoordinator {
     this.lifecycle = null
 
     if (entry.kind === "managed") {
-      if (entry.cloudflareTimer) clearInterval(entry.cloudflareTimer)
+      if (entry.cloudflareTimer) clearTimeout(entry.cloudflareTimer)
       if (entry.hlsTimer) clearInterval(entry.hlsTimer)
       // Reject any still-pending HLS readiness waiters.
       const pendingErr = new Error(`Stream torn down: ${reason}`)
@@ -728,7 +837,7 @@ export class PhoneStreamCoordinator {
   }
 }
 
-function pickIngestUrl(p: ProvisionResult, preference?: "srt" | "whip"): string {
+function pickIngestUrl(p: ProvisionResult, preference?: "srt" | "whip" | "rtmp"): string {
   // Glasses' StreamCommandHandler detects protocol from URL prefix.
   //
   // Default priority: SRT > RTMP > WHIP. SRT first: Cloudflare's WebRTC (WHIP)
@@ -739,13 +848,18 @@ function pickIngestUrl(p: ProvisionResult, preference?: "srt" | "whip"): string
   //
   // "whip" preference flips the trade: sub-second WHEP playback for
   // live-monitor use cases, accepting no HLS and no recording.
+  // "rtmp" prefers TCP 443 ingest so networks that drop WHIP/SRT UDP still
+  // get HLS playback. Callers must request it explicitly; WHIP starts do not
+  // fall back to RTMP.
   //
   // Throw if none resolved so the caller's Promise rejects with a clear
   // message rather than the glasses' "unknown protocol" error.
   const url =
     preference === "whip"
       ? p.webrtcPublishUrl || p.srtUrl || p.rtmpUrl
-      : p.srtUrl || p.rtmpUrl || p.webrtcPublishUrl
+      : preference === "rtmp"
+        ? p.rtmpUrl || p.srtUrl || p.webrtcPublishUrl
+        : p.srtUrl || p.rtmpUrl || p.webrtcPublishUrl
   if (!url) {
     throw new Error("Cloudflare provision returned no usable ingest URL")
   }

package/src/services/PhoneVideoCoordinator.ts

@@ -55,6 +55,17 @@ export class PhoneVideoCoordinator {
   // second start that races the first is still rejected.
   private starting = false
 
+  /** Report-safe recording ownership snapshot for incident diagnostics. */
+  getDiagnosticSnapshot(): Record<string, unknown> {
+    return {
+      recordingOwners: [
+        ...new Set([...this.activeRecordings.values()].map((recording) => recording.packageName)),
+      ].sort(),
+      activeRecordingCount: this.activeRecordings.size,
+      startInProgress: this.starting,
+    }
+  }
+
   async startRecording(packageName: string, opts: VideoRecordingOpts): Promise<VideoRecordingStarted> {
     // Fail fast if glasses aren't connected — the BLE command would otherwise
     // be sent into the void.

package/src/services/SceneRenderer.ts

@@ -13,6 +13,7 @@
 
 import displayProcessor from "./DisplayProcessor"
 import BluetoothSdk from "@mentra/bluetooth-sdk/internal"
+import {useDisplayStore} from "../stores/display"
 import {SETTINGS, useSettingsStore} from "../stores/settings"
 import {useGlassesStore} from "../stores/glasses"
 import {DeviceTypes, getModelCapabilities} from "../types"
@@ -269,6 +270,21 @@ class SceneRenderer {
       void Promise.resolve(BluetoothSdk.displayEvent({view: frame.view, scene: frame})).catch((err) => {
         console.error(`${LOG_TAG}: native scene send failed:`, err)
       })
+
+      // Keep the phone-side glasses mirror on the same frame as native. Legacy
+      // layouts update this store in LocalDisplayManager.sendToNative; scene
+      // frames bypass that method, so without an explicit write every
+      // positioning device (including G2) leaves the mirror blank/stale.
+      const caps = this.currentCapabilities()
+      useDisplayStore.getState().setDisplayEvent({
+        view: frame.view,
+        layout: {
+          layoutType: "scene",
+          width: caps?.width,
+          height: caps?.height,
+          elements: frame.elements,
+        },
+      })
     } catch (err) {
       console.error(`${LOG_TAG}: native scene send failed:`, err)
     }

package/src/services/SupportProfileSync.ts

@@ -0,0 +1,218 @@
+import Constants from "expo-constants"
+import * as Device from "expo-device"
+import {Platform} from "react-native"
+import type {SupportStateInput} from "@mentra/cloud-client"
+
+import {useGlassesStore} from "../stores/glasses"
+import {BgTimer} from "../utils/timers"
+import {cloudClientService} from "./CloudClientService"
+
+const ENGINE_VERSION = (require("../../package.json") as {version?: string}).version
+const BLUETOOTH_SDK_VERSION = (require("@mentra/bluetooth-sdk/package.json") as {version?: string}).version
+const DEBOUNCE_MS = 2_000
+const RETRY_MS = 30_000
+const HEARTBEAT_MS = 6 * 60 * 60_000
+
+let unsubscribe: (() => void) | null = null
+let debounceTimer: number | null = null
+let retryTimer: number | null = null
+let heartbeatTimer: number | null = null
+let lastSentFingerprint: string | null = null
+let queuedFingerprint: string | null = null
+let sendingGeneration: number | null = null
+let syncGeneration = 0
+let consecutiveSendFailures = 0
+let lastFailure: {code: string; stage: string} | null = null
+let lastConnectionState: string | null = null
+
+/**
+ * Keep Cloud V2's canonical support snapshot current without creating an event
+ * stream from noisy store updates. Only the explicitly selected fields below
+ * leave the phone; Wi-Fi, Bluetooth addresses, location and diagnostics do not.
+ */
+export function startSupportProfileSync(): void {
+  if (unsubscribe) return
+  const generation = ++syncGeneration
+  lastConnectionState = useGlassesStore.getState().connection.state
+  unsubscribe = useGlassesStore.subscribe(() => handleGlassesStoreChange(generation))
+  heartbeatTimer = BgTimer.setInterval(() => void sendCurrentSnapshot(true, generation), HEARTBEAT_MS)
+  void sendCurrentSnapshot(true, generation)
+}
+
+export function stopSupportProfileSync(): void {
+  syncGeneration += 1
+  unsubscribe?.()
+  unsubscribe = null
+  if (debounceTimer !== null) BgTimer.clearTimeout(debounceTimer)
+  if (retryTimer !== null) BgTimer.clearTimeout(retryTimer)
+  if (heartbeatTimer !== null) BgTimer.clearInterval(heartbeatTimer)
+  debounceTimer = null
+  retryTimer = null
+  heartbeatTimer = null
+  lastSentFingerprint = null
+  queuedFingerprint = null
+  sendingGeneration = null
+  consecutiveSendFailures = 0
+  lastFailure = null
+  lastConnectionState = null
+}
+
+function handleGlassesStoreChange(generation: number): void {
+  if (!unsubscribe || generation !== syncGeneration) return
+  const connectionState = useGlassesStore.getState().connection.state
+  if (connectionState === "connected" && lastConnectionState !== "connected") lastFailure = null
+  lastConnectionState = connectionState
+  scheduleMeaningfulUpdate(generation)
+}
+
+function scheduleMeaningfulUpdate(generation = syncGeneration): void {
+  if (!unsubscribe || generation !== syncGeneration) return
+  const fingerprint = snapshotFingerprint(buildSnapshot())
+  if (fingerprint === lastSentFingerprint) return
+  queuedFingerprint = fingerprint
+  armDebounce(generation)
+}
+
+function armDebounce(generation: number): void {
+  if (debounceTimer !== null) BgTimer.clearTimeout(debounceTimer)
+  debounceTimer = BgTimer.setTimeout(() => {
+    debounceTimer = null
+    void sendCurrentSnapshot(false, generation)
+  }, DEBOUNCE_MS)
+}
+
+async function sendCurrentSnapshot(force: boolean, generation = syncGeneration): Promise<void> {
+  if (!unsubscribe || generation !== syncGeneration) return
+  if (sendingGeneration === generation) {
+    const fingerprint = snapshotFingerprint(buildSnapshot())
+    if (fingerprint !== lastSentFingerprint) queuedFingerprint = fingerprint
+    return
+  }
+  const snapshot = buildSnapshot()
+  const fingerprint = snapshotFingerprint(snapshot)
+  if (!force && fingerprint === lastSentFingerprint) return
+
+  sendingGeneration = generation
+  let retryDelayMs: number | null = null
+  try {
+    const result = await cloudClientService.core.supportProfile.update(snapshot)
+    if (generation !== syncGeneration || !unsubscribe) return
+    consecutiveSendFailures = 0
+    retryDelayMs = retryDelayForSupportProfileResult(result)
+    if (retryDelayMs === null) {
+      lastSentFingerprint = fingerprint
+      if (queuedFingerprint === fingerprint) queuedFingerprint = null
+      if (retryTimer !== null) BgTimer.clearTimeout(retryTimer)
+      retryTimer = null
+    }
+  } catch (error) {
+    if (generation !== syncGeneration || !unsubscribe) return
+    consecutiveSendFailures += 1
+    retryDelayMs = retryDelayForSendFailure(consecutiveSendFailures)
+    console.warn(
+      `supportProfile: Cloud V2 update failed (retry in ${Math.round(retryDelayMs / 1_000)}s):`,
+      error instanceof Error ? error.message : error,
+    )
+  } finally {
+    const generationIsActive = generation === syncGeneration && sendingGeneration === generation && Boolean(unsubscribe)
+    if (generationIsActive) {
+      sendingGeneration = null
+      if (retryDelayMs !== null) {
+        if (retryTimer !== null) BgTimer.clearTimeout(retryTimer)
+        retryTimer = BgTimer.setTimeout(() => {
+          retryTimer = null
+          void sendCurrentSnapshot(true, generation)
+        }, retryDelayMs)
+      } else {
+        const currentFingerprint = snapshotFingerprint(buildSnapshot())
+        if (currentFingerprint !== lastSentFingerprint) {
+          queuedFingerprint = currentFingerprint
+          if (retryTimer === null) armDebounce(generation)
+        }
+      }
+    }
+  }
+}
+
+export function retryDelayForSupportProfileResult(result: {
+  status: "accepted" | "deduplicated" | "stale"
+}): number | null {
+  if (result.status === "accepted" || result.status === "deduplicated") return null
+  return RETRY_MS
+}
+
+/**
+ * Support freshness is not worth an aggressive retry loop. A snapshot the
+ * server keeps rejecting (skewed clock, deleted account, signed-out host)
+ * backs off exponentially until it converges on the heartbeat cadence.
+ */
+export function retryDelayForSendFailure(consecutiveFailures: number): number {
+  return Math.min(HEARTBEAT_MS, RETRY_MS * 2 ** Math.min(Math.max(consecutiveFailures, 1) - 1, 10))
+}
+
+export function buildSnapshot(observedAt = new Date()): SupportStateInput {
+  const glasses = useGlassesStore.getState()
+  const device = {
+    hardwareId: optional(glasses.serialNumber),
+    model: optional(glasses.deviceModel),
+    androidVersion: optional(glasses.androidVersion),
+    firmwareVersion: optional(glasses.firmwareVersion),
+    mtkFirmwareVersion: optional(glasses.mtkFirmwareVersion),
+    besFirmwareVersion: optional(glasses.besFirmwareVersion),
+    appVersion: optional(glasses.appVersion),
+    buildNumber: optional(glasses.buildNumber),
+  }
+  const hasDevice = Object.values(device).some(Boolean)
+  const constants = Constants as typeof Constants & {
+    nativeAppVersion?: string | null
+    nativeBuildVersion?: string | null
+  }
+  return {
+    observedAt: observedAt.toISOString(),
+    host: {
+      appVersion: optional(constants.nativeAppVersion ?? Constants.expoConfig?.version),
+      appBuild: optional(constants.nativeBuildVersion),
+      engineVersion: optional(ENGINE_VERSION),
+      bluetoothSdkVersion: optional(BLUETOOTH_SDK_VERSION),
+      phonePlatform: Platform.OS === "ios" || Platform.OS === "android" ? Platform.OS : "unknown",
+      phoneModel: optional(Device.modelName),
+      phoneOsVersion: optional(
+        Platform.OS === "android"
+          ? String((Platform.constants as {Release?: string} | undefined)?.Release ?? Platform.Version)
+          : String(Platform.Version),
+      ),
+      connectionState: glasses.connection.state,
+      ...(lastFailure ? {failureCode: lastFailure.code, failureStage: lastFailure.stage} : {}),
+    },
+    ...(hasDevice ? {device} : {}),
+  }
+}
+
+/** Record only normalized connection failures; arbitrary exception messages never leave the phone. */
+export function recordSupportProfileConnectionFailure(error: unknown, stage: string): void {
+  const rawCode =
+    typeof error === "object" && error && "code" in error ? String((error as {code?: unknown}).code ?? "") : ""
+  const message = error instanceof Error ? `${error.name} ${error.message}`.toLowerCase() : ""
+  const code = /^[a-zA-Z0-9_.-]{1,64}$/.test(rawCode)
+    ? rawCode.toLowerCase()
+    : message.includes("permission")
+      ? "permission_denied"
+      : message.includes("bluetooth") && (message.includes("off") || message.includes("unavailable"))
+        ? "bluetooth_unavailable"
+        : message.includes("not found") || message.includes("no default")
+          ? "device_not_found"
+          : message.includes("timeout")
+            ? "connect_timeout"
+            : "connect_failed"
+  lastFailure = {code, stage: stage.replace(/[^a-zA-Z0-9_.-]/g, "_").slice(0, 64)}
+  scheduleMeaningfulUpdate()
+}
+
+export function snapshotFingerprint(snapshot: SupportStateInput): string {
+  return JSON.stringify({host: snapshot.host, device: snapshot.device})
+}
+
+function optional(value: string | null | undefined): string | undefined {
+  const trimmed = value?.trim()
+  return trimmed ? trimmed.slice(0, 128) : undefined
+}

package/src/services/TtsTextSanitizer.ts

@@ -0,0 +1,66 @@
+const HTML_ENTITIES: Record<string, string> = {
+  "&amp;": "&",
+  "&lt;": "<",
+  "&gt;": ">",
+  "&quot;": '"',
+  "&#39;": "'",
+}
+
+/** Convert display-oriented text into plain words before TTS synthesis. */
+export function sanitizeTtsText(text: string): string {
+  let speech = text.replace(/&(amp|lt|gt|quot|#39);/gi, (entity) => HTML_ENTITIES[entity.toLowerCase()] ?? entity)
+
+  speech = speech
+    .replace(/<say-as\b[^>]*>(.*?)<\/say-as>/gis, "$1")
+    .replace(/<\/?[a-z][a-z0-9-]*(?:\s[^<>]*?)?\s*\/?>/gi, " ")
+    .replace(/\[([^\]]+)]\([^)]+\)/g, "$1")
+    .replace(/`([^`]*)`/g, "$1")
+    .replace(/(-?\d+(?:[.,]\d+)?)\s*(?:°\s*f\b|℉)/gi, "$1 degrees Fahrenheit")
+    .replace(/(-?\d+(?:[.,]\d+)?)\s*(?:°\s*c\b|℃)/gi, "$1 degrees Celsius")
+    .replace(/(-?\d+(?:[.,]\d+)?)\s*°/g, "$1 degrees")
+    .replace(/<=/g, " less than or equal to ")
+    .replace(/>=/g, " greater than or equal to ")
+    .replace(/</g, " less than ")
+    .replace(/>/g, " greater than ")
+    .replace(/[[\]{}()]/g, " ")
+    .replace(/(degrees Fahrenheit)\s+(-?\d+(?:[.,]\d+)? degrees Celsius)\b/gi, "$1 or $2")
+    .replace(/(degrees Celsius)\s+(-?\d+(?:[.,]\d+)? degrees Fahrenheit)\b/gi, "$1 or $2")
+    .replace(/&/g, " and ")
+    .replace(/\+/g, " plus ")
+    .replace(/=/g, " equals ")
+    .replace(/#/g, " hash ")
+    .replace(/@/g, " at ")
+    .replace(/%/g, " percent ")
+    .replace(/\\/g, " backslash ")
+    .replace(/\//g, (slash, offset, source) => {
+      const numericSeparator = /\d/.test(source[offset - 1] ?? "") && /\d/.test(source[offset + 1] ?? "")
+      return numericSeparator ? slash : " slash "
+    })
+    .replace(/\*/g, " star ")
+
+  return speech
+    .replace(/\s+([,.;:!?])/g, "$1")
+    .replace(/\s+/g, " ")
+    .trim()
+}
+
+/** Prepare an already-trimmed sentence list while preserving the exact-text opt-out. */
+export function prepareTtsSentences(sentences: string[], enableSanitization = true): string[] {
+  if (!enableSanitization) return sentences
+
+  const sanitized = sentences.map((sentence) => sanitizeTtsText(sentence)).filter(Boolean)
+
+  return sanitized.map((sentence, index) => {
+    const previous = sanitized[index - 1]
+    if (!previous) return sentence
+
+    const followsFahrenheit = /degrees Fahrenheit[,.;:!?]?$/i.test(previous)
+    const followsCelsius = /degrees Celsius[,.;:!?]?$/i.test(previous)
+    const startsWithFahrenheit = /^-?\d+(?:[.,]\d+)? degrees Fahrenheit\b/i.test(sentence)
+    const startsWithCelsius = /^-?\d+(?:[.,]\d+)? degrees Celsius\b/i.test(sentence)
+
+    return (followsFahrenheit && startsWithCelsius) || (followsCelsius && startsWithFahrenheit)
+      ? `or ${sentence}`
+      : sentence
+  })
+}